| Index: third_party/sqlite/src/src/sqlite.h.in
|
| diff --git a/third_party/sqlite/src/src/sqlite.h.in b/third_party/sqlite/src/src/sqlite.h.in
|
| index f736ca5af225ab02289edc92f71f367b7bcab231..6829bcbdb993d90adf90782f3ad4a42bac3c646f 100644
|
| --- a/third_party/sqlite/src/src/sqlite.h.in
|
| +++ b/third_party/sqlite/src/src/sqlite.h.in
|
| @@ -23,7 +23,7 @@
|
| **
|
| ** The official C-language API documentation for SQLite is derived
|
| ** from comments in this file. This file is the authoritative source
|
| -** on how SQLite interfaces are suppose to operate.
|
| +** on how SQLite interfaces are supposed to operate.
|
| **
|
| ** The name of this file under configuration management is "sqlite.h.in".
|
| ** The makefile makes some minor changes to this file (such as inserting
|
| @@ -43,16 +43,25 @@ extern "C" {
|
|
|
|
|
| /*
|
| -** Add the ability to override 'extern'
|
| +** Provide the ability to override linkage features of the interface.
|
| */
|
| #ifndef SQLITE_EXTERN
|
| # define SQLITE_EXTERN extern
|
| #endif
|
| +#ifndef SQLITE_API
|
| +# define SQLITE_API
|
| +#endif
|
| +#ifndef SQLITE_CDECL
|
| +# define SQLITE_CDECL
|
| +#endif
|
| +#ifndef SQLITE_STDCALL
|
| +# define SQLITE_STDCALL
|
| +#endif
|
|
|
| /*
|
| ** 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 interfaces - they are support for backwards
|
| +** should not use deprecated interfaces - they are supported for backwards
|
| ** compatibility only. Application writers should be aware that
|
| ** experimental interfaces are subject to change in point releases.
|
| **
|
| @@ -115,7 +124,7 @@ extern "C" {
|
| ** but are associated with the library instead of the header file. ^(Cautious
|
| ** programmers might include assert() statements in their application to
|
| ** verify that values returned by these interfaces match the macros in
|
| -** the header, and thus insure that the application is
|
| +** the header, and thus ensure that the application is
|
| ** compiled with matching library and header files.
|
| **
|
| ** <blockquote><pre>
|
| @@ -196,7 +205,7 @@ const char *sqlite3_compileoption_get(int N);
|
| ** SQLITE_THREADSAFE=1 or =2 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 the
|
| +** or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the
|
| ** sqlite3_threadsafe() function shows only the compile-time setting of
|
| ** thread safety, not any run-time changes to that setting made by
|
| ** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
|
| @@ -261,6 +270,7 @@ typedef sqlite_uint64 sqlite3_uint64;
|
|
|
| /*
|
| ** CAPI3REF: Closing A Database Connection
|
| +** DESTRUCTOR: sqlite3
|
| **
|
| ** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
|
| ** for the [sqlite3] object.
|
| @@ -312,6 +322,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
|
|
|
| /*
|
| ** CAPI3REF: One-Step Query Execution Interface
|
| +** METHOD: sqlite3
|
| **
|
| ** The sqlite3_exec() interface is a convenience wrapper around
|
| ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
|
| @@ -363,7 +374,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
|
| ** Restrictions:
|
| **
|
| ** <ul>
|
| -** <li> The application must insure that the 1st parameter to sqlite3_exec()
|
| +** <li> The application must ensure that the 1st parameter to sqlite3_exec()
|
| ** is a valid and open [database connection].
|
| ** <li> The application must not close the [database connection] specified by
|
| ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
|
| @@ -466,6 +477,8 @@ int sqlite3_exec(
|
| #define SQLITE_IOERR_MMAP (SQLITE_IOERR | (24<<8))
|
| #define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25<<8))
|
| #define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8))
|
| +#define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27<<8))
|
| +#define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8))
|
| #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
|
| #define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
|
| #define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8))
|
| @@ -751,14 +764,16 @@ struct sqlite3_io_methods {
|
| ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
|
| ** interface.
|
| **
|
| +** <ul>
|
| +** <li>[[SQLITE_FCNTL_LOCKSTATE]]
|
| ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
|
| ** opcode causes the xFileControl method to write the current state of
|
| ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
|
| ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
|
| ** into an integer that the pArg argument points to. This capability
|
| -** is used during testing and only needs to be supported when SQLITE_TEST
|
| -** is defined.
|
| -** <ul>
|
| +** is used during testing and is only available when the SQLITE_TEST
|
| +** compile-time option is used.
|
| +**
|
| ** <li>[[SQLITE_FCNTL_SIZE_HINT]]
|
| ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
|
| ** layer a hint of how large the database file will grow to be during the
|
| @@ -779,8 +794,13 @@ struct sqlite3_io_methods {
|
| ** <li>[[SQLITE_FCNTL_FILE_POINTER]]
|
| ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
|
| ** to the [sqlite3_file] object associated with a particular database
|
| -** connection. See the [sqlite3_file_control()] documentation for
|
| -** additional information.
|
| +** connection. See also [SQLITE_FCNTL_JOURNAL_POINTER].
|
| +**
|
| +** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]
|
| +** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
|
| +** to the [sqlite3_file] object associated with the journal file (either
|
| +** the [rollback journal] or the [write-ahead log]) for a particular database
|
| +** connection. See also [SQLITE_FCNTL_FILE_POINTER].
|
| **
|
| ** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
|
| ** No longer in use.
|
| @@ -867,6 +887,15 @@ struct sqlite3_io_methods {
|
| ** pointer in case this file-control is not implemented. This file-control
|
| ** is intended for diagnostic use only.
|
| **
|
| +** <li>[[SQLITE_FCNTL_VFS_POINTER]]
|
| +** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
|
| +** [VFSes] currently in use. ^(The argument X in
|
| +** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
|
| +** of type "[sqlite3_vfs] **". This opcodes will set *X
|
| +** to a pointer to the top-level VFS.)^
|
| +** ^When there are multiple VFS shims in the stack, this opcode finds the
|
| +** upper-most shim only.
|
| +**
|
| ** <li>[[SQLITE_FCNTL_PRAGMA]]
|
| ** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
|
| ** file control is sent to the open [sqlite3_file] object corresponding
|
| @@ -883,7 +912,9 @@ struct sqlite3_io_methods {
|
| ** [PRAGMA] processing continues. ^If the [SQLITE_FCNTL_PRAGMA]
|
| ** file control returns [SQLITE_OK], then the parser assumes that the
|
| ** VFS has handled the PRAGMA itself and the parser generates a no-op
|
| -** prepared statement. ^If the [SQLITE_FCNTL_PRAGMA] file control returns
|
| +** prepared statement if result string is NULL, or that returns a copy
|
| +** of the result string if the string is non-NULL.
|
| +** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
|
| ** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
|
| ** that the VFS encountered an error while handling the [PRAGMA] and the
|
| ** compilation of the PRAGMA fails with an error. ^The [SQLITE_FCNTL_PRAGMA]
|
| @@ -941,12 +972,27 @@ struct sqlite3_io_methods {
|
| ** pointed to by the pArg argument. This capability is used during testing
|
| ** and only needs to be supported when SQLITE_TEST is defined.
|
| **
|
| +** <li>[[SQLITE_FCNTL_WAL_BLOCK]]
|
| +** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
|
| +** be advantageous to block on the next WAL lock if the lock is not immediately
|
| +** available. The WAL subsystem issues this signal during rare
|
| +** circumstances in order to fix a problem with priority inversion.
|
| +** Applications should <em>not</em> use this file-control.
|
| +**
|
| +** <li>[[SQLITE_FCNTL_ZIPVFS]]
|
| +** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
|
| +** VFS should return SQLITE_NOTFOUND for this opcode.
|
| +**
|
| +** <li>[[SQLITE_FCNTL_RBU]]
|
| +** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
|
| +** the RBU extension only. All other VFS should return SQLITE_NOTFOUND for
|
| +** this opcode.
|
| ** </ul>
|
| */
|
| #define SQLITE_FCNTL_LOCKSTATE 1
|
| -#define SQLITE_GET_LOCKPROXYFILE 2
|
| -#define SQLITE_SET_LOCKPROXYFILE 3
|
| -#define SQLITE_LAST_ERRNO 4
|
| +#define SQLITE_FCNTL_GET_LOCKPROXYFILE 2
|
| +#define SQLITE_FCNTL_SET_LOCKPROXYFILE 3
|
| +#define SQLITE_FCNTL_LAST_ERRNO 4
|
| #define SQLITE_FCNTL_SIZE_HINT 5
|
| #define SQLITE_FCNTL_CHUNK_SIZE 6
|
| #define SQLITE_FCNTL_FILE_POINTER 7
|
| @@ -965,6 +1011,17 @@ struct sqlite3_io_methods {
|
| #define SQLITE_FCNTL_SYNC 21
|
| #define SQLITE_FCNTL_COMMIT_PHASETWO 22
|
| #define SQLITE_FCNTL_WIN32_SET_HANDLE 23
|
| +#define SQLITE_FCNTL_WAL_BLOCK 24
|
| +#define SQLITE_FCNTL_ZIPVFS 25
|
| +#define SQLITE_FCNTL_RBU 26
|
| +#define SQLITE_FCNTL_VFS_POINTER 27
|
| +#define SQLITE_FCNTL_JOURNAL_POINTER 28
|
| +
|
| +/* deprecated names */
|
| +#define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE
|
| +#define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE
|
| +#define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO
|
| +
|
|
|
| /*
|
| ** CAPI3REF: Mutex Handle
|
| @@ -1216,7 +1273,7 @@ struct sqlite3_vfs {
|
| ** </ul>
|
| **
|
| ** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
|
| -** was given no the corresponding lock.
|
| +** was given on the corresponding lock.
|
| **
|
| ** The xShmLock method can transition between unlocked and SHARED or
|
| ** between unlocked and EXCLUSIVE. It cannot transition between SHARED
|
| @@ -1327,9 +1384,11 @@ int sqlite3_os_end(void);
|
| ** 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()
|
| +** <b>The sqlite3_config() interface is not threadsafe. The application
|
| +** must ensure that no other SQLite interfaces are invoked by other
|
| +** threads while sqlite3_config() is running.</b>
|
| +**
|
| +** The sqlite3_config() interface
|
| ** may only be invoked prior to library initialization using
|
| ** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
|
| ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
|
| @@ -1351,6 +1410,7 @@ int sqlite3_config(int, ...);
|
|
|
| /*
|
| ** CAPI3REF: Configure database connections
|
| +** METHOD: sqlite3
|
| **
|
| ** The sqlite3_db_config() interface is used to make configuration
|
| ** changes to a [database connection]. The interface is similar to
|
| @@ -1499,31 +1559,33 @@ struct sqlite3_mem_methods {
|
| ** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
|
| **
|
| ** [[SQLITE_CONFIG_MALLOC]] <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
|
| +** <dd> ^(The SQLITE_CONFIG_MALLOC 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.)^ ^SQLite makes
|
| ** its own private copy of the content of the [sqlite3_mem_methods] structure
|
| ** before the [sqlite3_config()] call returns.</dd>
|
| **
|
| ** [[SQLITE_CONFIG_GETMALLOC]] <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]
|
| +** <dd> ^(The SQLITE_CONFIG_GETMALLOC 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>
|
| **
|
| ** [[SQLITE_CONFIG_MEMSTATUS]] <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 memory allocation statistics are disabled, the
|
| -** following SQLite interfaces become non-operational:
|
| +** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
|
| +** interpreted as a boolean, which enables or disables the collection of
|
| +** memory allocation statistics. ^(When memory allocation statistics are
|
| +** disabled, the following SQLite interfaces become non-operational:
|
| ** <ul>
|
| ** <li> [sqlite3_memory_used()]
|
| ** <li> [sqlite3_memory_highwater()]
|
| ** <li> [sqlite3_soft_heap_limit64()]
|
| -** <li> [sqlite3_status()]
|
| +** <li> [sqlite3_status64()]
|
| ** </ul>)^
|
| ** ^Memory allocation statistics are enabled by default unless SQLite is
|
| ** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
|
| @@ -1531,53 +1593,72 @@ struct sqlite3_mem_methods {
|
| ** </dd>
|
| **
|
| ** [[SQLITE_CONFIG_SCRATCH]] <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 an 8-byte
|
| +** <dd> ^The SQLITE_CONFIG_SCRATCH option specifies a static memory buffer
|
| +** that SQLite can use for scratch memory. ^(There are three arguments
|
| +** to SQLITE_CONFIG_SCRATCH: A pointer an 8-byte
|
| ** aligned memory buffer from which the scratch allocations will be
|
| ** drawn, the size of each scratch allocation (sz),
|
| -** and the maximum number of scratch allocations (N). The sz
|
| -** argument must be a multiple of 16.
|
| +** and the maximum number of scratch allocations (N).)^
|
| ** The first argument must be a pointer to an 8-byte aligned buffer
|
| ** of at least sz*N bytes of memory.
|
| -** ^SQLite will use no more than two scratch buffers per thread. So
|
| -** N should be set to twice the expected maximum number of threads.
|
| -** ^SQLite will never require a scratch buffer that is more than 6
|
| -** times the database page size. ^If SQLite needs needs additional
|
| +** ^SQLite will not use more than one scratch buffers per thread.
|
| +** ^SQLite will never request a scratch buffer that is more than 6
|
| +** times the database page size.
|
| +** ^If SQLite needs needs additional
|
| ** scratch memory beyond what is provided by this configuration option, then
|
| -** [sqlite3_malloc()] will be used to obtain the memory needed.</dd>
|
| +** [sqlite3_malloc()] will be used to obtain the memory needed.<p>
|
| +** ^When the application provides any amount of scratch memory using
|
| +** SQLITE_CONFIG_SCRATCH, SQLite avoids unnecessary large
|
| +** [sqlite3_malloc|heap allocations].
|
| +** This can help [Robson proof|prevent memory allocation failures] due to heap
|
| +** fragmentation in low-memory embedded systems.
|
| +** </dd>
|
| **
|
| ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
|
| -** <dd> ^This option specifies a static memory buffer that SQLite can use for
|
| -** the database page cache with the default page cache implementation.
|
| -** This configuration should not be used if an application-define page
|
| -** cache implementation is loaded using the SQLITE_CONFIG_PCACHE2 option.
|
| -** There are three arguments to this option: A pointer to 8-byte aligned
|
| -** memory, the size of each page buffer (sz), and the number of pages (N).
|
| +** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
|
| +** that SQLite can use for the database page cache with the default page
|
| +** cache implementation.
|
| +** This configuration option is a no-op if an application-define page
|
| +** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
|
| +** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
|
| +** 8-byte aligned memory (pMem), the size of each page cache line (sz),
|
| +** and the number of cache lines (N).
|
| ** The sz argument should be the size of the largest database page
|
| -** (a power of two between 512 and 32768) plus a little extra for each
|
| -** page header. ^The page header size is 20 to 40 bytes depending on
|
| -** the host architecture. ^It is harmless, apart from the wasted memory,
|
| -** to make sz a little too large. 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 pointer in the first argument must
|
| -** be aligned to an 8-byte boundary or subsequent behavior of SQLite
|
| -** will be undefined.</dd>
|
| +** (a power of two between 512 and 65536) plus some extra bytes for each
|
| +** page header. ^The number of extra bytes needed by the page header
|
| +** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
|
| +** ^It is harmless, apart from the wasted memory,
|
| +** for the sz parameter to be larger than necessary. The pMem
|
| +** argument must be either a NULL pointer or a pointer to an 8-byte
|
| +** aligned block of memory of at least sz*N bytes, otherwise
|
| +** subsequent behavior is undefined.
|
| +** ^When pMem is not NULL, SQLite will strive to use the memory provided
|
| +** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
|
| +** a page cache line is larger than sz bytes or if all of the pMem buffer
|
| +** is exhausted.
|
| +** ^If pMem is NULL and N is non-zero, then each database connection
|
| +** does an initial bulk allocation for page cache memory
|
| +** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
|
| +** of -1024*N bytes if N is negative, . ^If additional
|
| +** page cache memory is needed beyond what is provided by the initial
|
| +** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
|
| +** additional cache line. </dd>
|
| **
|
| ** [[SQLITE_CONFIG_HEAP]] <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: An 8-byte aligned pointer to the memory,
|
| +** <dd> ^The SQLITE_CONFIG_HEAP 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].
|
| +** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
|
| +** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
|
| +** [SQLITE_ERROR] if invoked otherwise.
|
| +** ^There are three arguments to SQLITE_CONFIG_HEAP:
|
| +** An 8-byte aligned 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
|
| +** memory pointer is not NULL then the alternative memory
|
| ** allocator is engaged to handle all of SQLites memory allocation needs.
|
| ** The first pointer (the memory pointer) must be aligned to an 8-byte
|
| ** boundary or subsequent behavior of SQLite will be undefined.
|
| @@ -1585,11 +1666,11 @@ struct sqlite3_mem_methods {
|
| ** for the minimum allocation size are 2**5 through 2**8.</dd>
|
| **
|
| ** [[SQLITE_CONFIG_MUTEX]] <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.)^ ^SQLite makes a copy of the
|
| -** content of the [sqlite3_mutex_methods] structure before the call to
|
| +** <dd> ^(The SQLITE_CONFIG_MUTEX 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.)^ ^SQLite makes a copy of
|
| +** the content of the [sqlite3_mutex_methods] structure before the call to
|
| ** [sqlite3_config()] returns. ^If SQLite is compiled with
|
| ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
|
| ** the entire mutexing subsystem is omitted from the build and hence calls to
|
| @@ -1597,8 +1678,8 @@ struct sqlite3_mem_methods {
|
| ** return [SQLITE_ERROR].</dd>
|
| **
|
| ** [[SQLITE_CONFIG_GETMUTEX]] <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
|
| +** <dd> ^(The SQLITE_CONFIG_GETMUTEX 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
|
| @@ -1610,25 +1691,25 @@ struct sqlite3_mem_methods {
|
| ** return [SQLITE_ERROR].</dd>
|
| **
|
| ** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
|
| -** <dd> ^(This option takes two arguments that determine the default
|
| -** memory allocation for the lookaside memory allocator on each
|
| -** [database connection]. The first argument is the
|
| +** <dd> ^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
|
| +** the default size of lookaside memory on each [database connection].
|
| +** The first argument is the
|
| ** size of each lookaside buffer slot and the second is the number of
|
| -** slots allocated to each database connection.)^ ^(This option sets the
|
| -** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
|
| -** verb to [sqlite3_db_config()] can be used to change the lookaside
|
| +** slots allocated to each database connection.)^ ^(SQLITE_CONFIG_LOOKASIDE
|
| +** sets the <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
|
| +** option to [sqlite3_db_config()] can be used to change the lookaside
|
| ** configuration on individual connections.)^ </dd>
|
| **
|
| ** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
|
| -** <dd> ^(This option takes a single argument which is a pointer to
|
| -** an [sqlite3_pcache_methods2] object. This object specifies the interface
|
| -** to a custom page cache implementation.)^ ^SQLite makes a copy of the
|
| -** object and uses it for page cache memory allocations.</dd>
|
| +** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
|
| +** a pointer to an [sqlite3_pcache_methods2] object. This object specifies
|
| +** the interface to a custom page cache implementation.)^
|
| +** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
|
| **
|
| ** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
|
| -** <dd> ^(This option takes a single argument which is a pointer to an
|
| -** [sqlite3_pcache_methods2] object. SQLite copies of the current
|
| -** page cache implementation into that object.)^ </dd>
|
| +** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
|
| +** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of
|
| +** the current page cache implementation into that object.)^ </dd>
|
| **
|
| ** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
|
| ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
|
| @@ -1651,10 +1732,11 @@ struct sqlite3_mem_methods {
|
| ** function must be threadsafe. </dd>
|
| **
|
| ** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
|
| -** <dd>^(This option takes a single argument of type int. If non-zero, then
|
| -** URI handling is globally enabled. If the parameter is zero, then URI handling
|
| -** is globally disabled.)^ ^If URI handling is globally enabled, all filenames
|
| -** passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or
|
| +** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
|
| +** If non-zero, then URI handling is globally enabled. If the parameter is zero,
|
| +** then URI handling is globally disabled.)^ ^If URI handling is globally
|
| +** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
|
| +** [sqlite3_open16()] or
|
| ** specified as part of [ATTACH] commands are interpreted as URIs, regardless
|
| ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
|
| ** connection is opened. ^If it is globally disabled, filenames are
|
| @@ -1664,9 +1746,10 @@ struct sqlite3_mem_methods {
|
| ** [SQLITE_USE_URI] symbol defined.)^
|
| **
|
| ** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
|
| -** <dd>^This option takes a single integer argument which is interpreted as
|
| -** a boolean in order to enable or disable the use of covering indices for
|
| -** full table scans in the query optimizer. ^The default setting is determined
|
| +** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
|
| +** argument which is interpreted as a boolean in order to enable or disable
|
| +** the use of covering indices for full table scans in the query optimizer.
|
| +** ^The default setting is determined
|
| ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
|
| ** if that compile-time option is omitted.
|
| ** The ability to disable the use of covering indices for full table scans
|
| @@ -1706,18 +1789,37 @@ struct sqlite3_mem_methods {
|
| ** ^The default setting can be overridden by each database connection using
|
| ** either the [PRAGMA mmap_size] command, or by using the
|
| ** [SQLITE_FCNTL_MMAP_SIZE] file control. ^(The maximum allowed mmap size
|
| -** cannot be changed at run-time. Nor may the maximum allowed mmap size
|
| -** exceed the compile-time maximum mmap size set by the
|
| +** will be silently truncated if necessary so that it does not exceed the
|
| +** compile-time maximum mmap size set by the
|
| ** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
|
| ** ^If either argument to this option is negative, then that argument is
|
| ** changed to its compile-time default.
|
| **
|
| ** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
|
| ** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
|
| -** <dd>^This option is only available if SQLite is compiled for Windows
|
| -** with the [SQLITE_WIN32_MALLOC] pre-processor macro defined.
|
| -** SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
|
| +** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
|
| +** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
|
| +** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
|
| ** that specifies the maximum size of the created heap.
|
| +**
|
| +** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
|
| +** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
|
| +** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
|
| +** is a pointer to an integer and writes into that integer the number of extra
|
| +** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].
|
| +** The amount of extra space required can change depending on the compiler,
|
| +** target platform, and SQLite version.
|
| +**
|
| +** [[SQLITE_CONFIG_PMASZ]]
|
| +** <dt>SQLITE_CONFIG_PMASZ
|
| +** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which
|
| +** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
|
| +** sorter to that integer. The default minimum PMA Size is set by the
|
| +** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched
|
| +** to help with sort operations when multithreaded sorting
|
| +** is enabled (using the [PRAGMA threads] command) and the amount of content
|
| +** to be sorted exceeds the page size times the minimum of the
|
| +** [PRAGMA cache_size] setting and this value.
|
| ** </dl>
|
| */
|
| #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
|
| @@ -1743,6 +1845,8 @@ struct sqlite3_mem_methods {
|
| #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
|
| #define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
|
| #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
|
| +#define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
|
| +#define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
|
|
|
| /*
|
| ** CAPI3REF: Database Connection Configuration Options
|
| @@ -1809,6 +1913,7 @@ struct sqlite3_mem_methods {
|
|
|
| /*
|
| ** CAPI3REF: Enable Or Disable Extended Result Codes
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_extended_result_codes() routine enables or disables the
|
| ** [extended result codes] feature of SQLite. ^The extended result
|
| @@ -1818,6 +1923,7 @@ int sqlite3_extended_result_codes(sqlite3*, int onoff);
|
|
|
| /*
|
| ** CAPI3REF: Last Insert Rowid
|
| +** METHOD: sqlite3
|
| **
|
| ** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
|
| ** has a unique 64-bit signed
|
| @@ -1869,48 +1975,47 @@ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
|
|
|
| /*
|
| ** CAPI3REF: Count The Number Of Rows Modified
|
| +** METHOD: 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
|
| -** triggers or [foreign key actions] are not counted.)^ Use the
|
| -** [sqlite3_total_changes()] function to find the total number of changes
|
| -** including changes caused by triggers and foreign key actions.
|
| -**
|
| -** ^Changes to a view that are simulated by an [INSTEAD OF trigger]
|
| -** are not counted. Only real table changes are counted.
|
| -**
|
| -** ^(A "row change" is a change to a single row of a single table
|
| -** caused by an INSERT, DELETE, or UPDATE statement. Rows that
|
| -** are changed as side effects of [REPLACE] constraint resolution,
|
| -** rollback, ABORT processing, [DROP TABLE], or by any other
|
| -** mechanisms do not count as direct row changes.)^
|
| -**
|
| -** A "trigger context" is a scope of execution that begins and
|
| -** ends with the script of a [CREATE TRIGGER | trigger].
|
| -** Most SQL statements are
|
| -** evaluated outside of any trigger. This is the "top level"
|
| -** trigger context. If a trigger fires from the top level, a
|
| -** new trigger context is entered for the duration of that one
|
| -** trigger. Subtriggers create subcontexts for their duration.
|
| -**
|
| -** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
|
| -** not create a new trigger context.
|
| -**
|
| -** ^This function returns the number of direct row changes in the
|
| -** most recent INSERT, UPDATE, or DELETE statement within the same
|
| -** trigger context.
|
| -**
|
| -** ^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
|
| -** 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 changes
|
| -** caused by subtriggers since those have their own context.)^
|
| +** ^This function returns the number of rows modified, inserted or
|
| +** deleted by the most recently completed INSERT, UPDATE or DELETE
|
| +** statement on the database connection specified by the only parameter.
|
| +** ^Executing any other type of SQL statement does not modify the value
|
| +** returned by this function.
|
| +**
|
| +** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
|
| +** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
|
| +** [foreign key actions] or [REPLACE] constraint resolution are not counted.
|
| +**
|
| +** Changes to a view that are intercepted by
|
| +** [INSTEAD OF trigger | INSTEAD OF triggers] are not counted. ^The value
|
| +** returned by sqlite3_changes() immediately after an INSERT, UPDATE or
|
| +** DELETE statement run on a view is always zero. Only changes made to real
|
| +** tables are counted.
|
| +**
|
| +** Things are more complicated if the sqlite3_changes() function is
|
| +** executed while a trigger program is running. This may happen if the
|
| +** program uses the [changes() SQL function], or if some other callback
|
| +** function invokes sqlite3_changes() directly. Essentially:
|
| +**
|
| +** <ul>
|
| +** <li> ^(Before entering a trigger program the value returned by
|
| +** sqlite3_changes() function is saved. After the trigger program
|
| +** has finished, the original value is restored.)^
|
| +**
|
| +** <li> ^(Within a trigger program each INSERT, UPDATE and DELETE
|
| +** statement sets the value returned by sqlite3_changes()
|
| +** upon completion as normal. Of course, this value will not include
|
| +** any changes performed by sub-triggers, as the sqlite3_changes()
|
| +** value will be saved and restored after each sub-trigger has run.)^
|
| +** </ul>
|
| +**
|
| +** ^This means that if the changes() SQL function (or similar) is used
|
| +** by the first INSERT, UPDATE or DELETE statement within a trigger, it
|
| +** returns the value as set when the calling statement began executing.
|
| +** ^If it is used by the second or subsequent such statement within a trigger
|
| +** program, the value returned reflects the number of rows modified by the
|
| +** previous INSERT, UPDATE or DELETE statement within the same trigger.
|
| **
|
| ** See also the [sqlite3_total_changes()] interface, the
|
| ** [count_changes pragma], and the [changes() SQL function].
|
| @@ -1923,21 +2028,19 @@ int sqlite3_changes(sqlite3*);
|
|
|
| /*
|
| ** CAPI3REF: Total Number Of Rows Modified
|
| +** METHOD: sqlite3
|
| **
|
| -** ^This function returns the number of row changes caused by [INSERT],
|
| -** [UPDATE] or [DELETE] statements since the [database connection] was opened.
|
| -** ^(The count returned by sqlite3_total_changes() includes all changes
|
| -** from all [CREATE TRIGGER | trigger] contexts and changes made by
|
| -** [foreign key actions]. However,
|
| -** the count does not include changes used to implement [REPLACE] constraints,
|
| -** do rollbacks or ABORT processing, or [DROP TABLE] processing. The
|
| -** count does not include rows of views that fire an [INSTEAD OF trigger],
|
| -** though if the INSTEAD OF trigger makes changes of its own, those changes
|
| -** are counted.)^
|
| -** ^The sqlite3_total_changes() function counts the changes as soon as
|
| -** the statement that makes them is completed (when the statement handle
|
| -** is passed to [sqlite3_reset()] or [sqlite3_finalize()]).
|
| -**
|
| +** ^This function returns the total number of rows inserted, modified or
|
| +** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed
|
| +** since the database connection was opened, including those executed as
|
| +** part of trigger programs. ^Executing any other type of SQL statement
|
| +** does not affect the value returned by sqlite3_total_changes().
|
| +**
|
| +** ^Changes made as part of [foreign key actions] are included in the
|
| +** count, but those made as part of REPLACE constraint resolution are
|
| +** not. ^Changes to a view that are intercepted by INSTEAD OF triggers
|
| +** are not counted.
|
| +**
|
| ** See also the [sqlite3_changes()] interface, the
|
| ** [count_changes pragma], and the [total_changes() SQL function].
|
| **
|
| @@ -1949,6 +2052,7 @@ int sqlite3_total_changes(sqlite3*);
|
|
|
| /*
|
| ** CAPI3REF: Interrupt A Long-Running Query
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This function causes any pending database operation to abort and
|
| ** return at its earliest opportunity. This routine is typically
|
| @@ -2024,6 +2128,8 @@ int sqlite3_complete16(const void *sql);
|
|
|
| /*
|
| ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
|
| +** KEYWORDS: {busy-handler callback} {busy handler}
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
|
| ** that might be invoked with argument P whenever
|
| @@ -2040,7 +2146,7 @@ int sqlite3_complete16(const void *sql);
|
| ** ^The first argument to the busy handler is a copy of the void* pointer which
|
| ** is the third argument to sqlite3_busy_handler(). ^The second argument to
|
| ** the busy handler callback is the number of times that the busy handler has
|
| -** been invoked for the same locking event. ^If the
|
| +** been invoked previously for the same locking event. ^If the
|
| ** busy callback returns 0, then no additional attempts are made to
|
| ** access the database and [SQLITE_BUSY] is returned
|
| ** to the application.
|
| @@ -2083,6 +2189,7 @@ int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
|
|
|
| /*
|
| ** CAPI3REF: Set A Busy Timeout
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
|
| ** for a specified amount of time when a table is locked. ^The handler
|
| @@ -2105,6 +2212,7 @@ int sqlite3_busy_timeout(sqlite3*, int ms);
|
|
|
| /*
|
| ** CAPI3REF: Convenience Routines For Running Queries
|
| +** METHOD: sqlite3
|
| **
|
| ** This is a legacy interface that is preserved for backwards compatibility.
|
| ** Use of this interface is not recommended.
|
| @@ -2190,6 +2298,10 @@ void sqlite3_free_table(char **result);
|
| **
|
| ** These routines are work-alikes of the "printf()" family of functions
|
| ** from the standard C library.
|
| +** These routines understand most of the common K&R formatting options,
|
| +** plus some additional non-standard formats, detailed below.
|
| +** Note that some of the more obscure formatting options from recent
|
| +** C-library standards are omitted from this implementation.
|
| **
|
| ** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
|
| ** results into memory obtained from [sqlite3_malloc()].
|
| @@ -2222,7 +2334,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
|
| -** is are "%q", "%Q", and "%z" options.
|
| +** is are "%q", "%Q", "%w" and "%z" options.
|
| **
|
| ** ^(The %q option works like %s in that it substitutes a nul-terminated
|
| ** string from the argument list. But %q also doubles every '\'' character.
|
| @@ -2275,6 +2387,12 @@ void sqlite3_free_table(char **result);
|
| ** The code above will render a correct SQL statement in the zSQL
|
| ** variable even if the zText variable is a NULL pointer.
|
| **
|
| +** ^(The "%w" formatting option is like "%q" except that it expects to
|
| +** be contained within double-quotes instead of single quotes, and it
|
| +** escapes the double-quote character instead of the single-quote
|
| +** character.)^ The "%w" formatting option is intended for safely inserting
|
| +** table and column names into a constructed SQL statement.
|
| +**
|
| ** ^(The "%z" formatting option works like "%s" but with the
|
| ** addition that after the string has been read and copied into
|
| ** the result, [sqlite3_free()] is called on the input string.)^
|
| @@ -2415,13 +2533,14 @@ sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
|
| ** applications to access the same PRNG for other purposes.
|
| **
|
| ** ^A call to this routine stores N bytes of randomness into buffer P.
|
| -** ^If N is less than one, then P can be a NULL pointer.
|
| +** ^The P parameter can be a NULL pointer.
|
| **
|
| ** ^If this routine has not been previously called or if the previous
|
| -** call had N less than one, then the PRNG is seeded using randomness
|
| -** obtained from the xRandomness method of the default [sqlite3_vfs] object.
|
| -** ^If the previous call to this routine had an N of 1 or more then
|
| -** the pseudo-randomness is generated
|
| +** call had N less than one or a NULL pointer for P, then the PRNG is
|
| +** seeded using randomness obtained from the xRandomness method of
|
| +** the default [sqlite3_vfs] object.
|
| +** ^If the previous call to this routine had an N of 1 or more and a
|
| +** non-NULL P then the pseudo-randomness is generated
|
| ** internally and without recourse to the [sqlite3_vfs] xRandomness
|
| ** method.
|
| */
|
| @@ -2429,6 +2548,7 @@ void sqlite3_randomness(int N, void *P);
|
|
|
| /*
|
| ** CAPI3REF: Compile-Time Authorization Callbacks
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This routine registers an authorizer callback with a particular
|
| ** [database connection], supplied in the first argument.
|
| @@ -2585,6 +2705,7 @@ int sqlite3_set_authorizer(
|
|
|
| /*
|
| ** CAPI3REF: Tracing And Profiling Functions
|
| +** METHOD: sqlite3
|
| **
|
| ** These routines register callback functions that can be used for
|
| ** tracing and profiling the execution of SQL statements.
|
| @@ -2617,6 +2738,7 @@ SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
|
|
|
| /*
|
| ** CAPI3REF: Query Progress Callbacks
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
|
| ** function X to be invoked periodically during long running calls to
|
| @@ -2650,6 +2772,7 @@ void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
|
|
|
| /*
|
| ** CAPI3REF: Opening A New Database Connection
|
| +** CONSTRUCTOR: sqlite3
|
| **
|
| ** ^These routines open an SQLite database file as specified by the
|
| ** filename argument. ^The filename argument is interpreted as UTF-8 for
|
| @@ -2935,12 +3058,15 @@ sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
|
|
|
| /*
|
| ** CAPI3REF: Error Codes And Messages
|
| -**
|
| -** ^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_extended_errcode()
|
| +** METHOD: sqlite3
|
| +**
|
| +** ^If the most recent sqlite3_* API call associated with
|
| +** [database connection] D failed, then the sqlite3_errcode(D) interface
|
| +** returns the numeric [result code] or [extended result code] for that
|
| +** API call.
|
| +** If the most recent API call was successful,
|
| +** then the return value from 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.
|
| @@ -2978,33 +3104,34 @@ const void *sqlite3_errmsg16(sqlite3*);
|
| const char *sqlite3_errstr(int);
|
|
|
| /*
|
| -** CAPI3REF: SQL Statement Object
|
| +** CAPI3REF: Prepared Statement Object
|
| ** KEYWORDS: {prepared statement} {prepared statements}
|
| **
|
| -** 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".
|
| +** An instance of this object represents a single SQL statement that
|
| +** has been compiled into binary form and is ready to be evaluated.
|
| +**
|
| +** Think of each SQL statement as a separate computer program. The
|
| +** original SQL text is source code. A prepared statement object
|
| +** is the compiled object code. All SQL must be converted into a
|
| +** prepared statement before it can be run.
|
| **
|
| -** The life of a statement object goes something like this:
|
| +** The life-cycle of a prepared statement object usually goes like this:
|
| **
|
| ** <ol>
|
| -** <li> Create the object using [sqlite3_prepare_v2()] or a related
|
| -** function.
|
| -** <li> Bind values to [host parameters] using the sqlite3_bind_*()
|
| +** <li> Create the prepared statement object using [sqlite3_prepare_v2()].
|
| +** <li> Bind values to [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
|
| +** <li> Reset the prepared statement using [sqlite3_reset()] then go back
|
| ** to step 2. Do this zero or more times.
|
| ** <li> Destroy the object using [sqlite3_finalize()].
|
| ** </ol>
|
| -**
|
| -** Refer to documentation on individual methods above for additional
|
| -** information.
|
| */
|
| typedef struct sqlite3_stmt sqlite3_stmt;
|
|
|
| /*
|
| ** CAPI3REF: Run-time Limits
|
| +** METHOD: sqlite3
|
| **
|
| ** ^(This interface allows the size of various constructs to be limited
|
| ** on a connection by connection basis. The first parameter is the
|
| @@ -3116,6 +3243,8 @@ int sqlite3_limit(sqlite3*, int id, int newVal);
|
| /*
|
| ** CAPI3REF: Compiling An SQL Statement
|
| ** KEYWORDS: {SQL statement compiler}
|
| +** METHOD: sqlite3
|
| +** CONSTRUCTOR: sqlite3_stmt
|
| **
|
| ** To execute an SQL query, it must first be compiled into a byte-code
|
| ** program using one of these routines.
|
| @@ -3129,16 +3258,14 @@ int sqlite3_limit(sqlite3*, int id, int newVal);
|
| ** 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 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 as this saves SQLite from having to
|
| -** make a copy of the input string.
|
| +** ^If the nByte argument is negative, then zSql is read up to the
|
| +** first zero terminator. ^If nByte is positive, then it is the
|
| +** number of bytes read from zSql. ^If nByte is zero, then no prepared
|
| +** statement is generated.
|
| +** If the caller knows that the supplied string is nul-terminated, then
|
| +** there is a small performance advantage to passing an nByte parameter that
|
| +** is the number of bytes in the input string <i>including</i>
|
| +** the nul-terminator.
|
| **
|
| ** ^If pzTail is not NULL then *pzTail is made to point to the first byte
|
| ** past the end of the first SQL statement in zSql. These routines only
|
| @@ -3225,6 +3352,7 @@ int sqlite3_prepare16_v2(
|
|
|
| /*
|
| ** CAPI3REF: Retrieving Statement SQL
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^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
|
| @@ -3234,6 +3362,7 @@ const char *sqlite3_sql(sqlite3_stmt *pStmt);
|
|
|
| /*
|
| ** CAPI3REF: Determine If An SQL Statement Writes The Database
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
|
| ** and only if the [prepared statement] X makes no direct changes to
|
| @@ -3265,10 +3394,12 @@ int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
|
|
|
| /*
|
| ** CAPI3REF: Determine If A Prepared Statement Has Been Reset
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
|
| ** [prepared statement] S has been stepped at least once using
|
| -** [sqlite3_step(S)] but has not run to completion and/or has not
|
| +** [sqlite3_step(S)] but has neither run to completion (returned
|
| +** [SQLITE_DONE] from [sqlite3_step(S)]) nor
|
| ** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S)
|
| ** interface returns false if S is a NULL pointer. If S is not a
|
| ** NULL pointer and is not a pointer to a valid [prepared statement]
|
| @@ -3295,7 +3426,9 @@ int sqlite3_stmt_busy(sqlite3_stmt*);
|
| ** 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
|
| -** whether or not it requires a protected sqlite3_value.
|
| +** whether or not it requires a protected sqlite3_value. The
|
| +** [sqlite3_value_dup()] interface can be used to construct a new
|
| +** protected sqlite3_value from an unprotected sqlite3_value.
|
| **
|
| ** The terms "protected" and "unprotected" refer to whether or not
|
| ** a mutex is held. An internal mutex is held for a protected
|
| @@ -3339,6 +3472,7 @@ typedef struct sqlite3_context sqlite3_context;
|
| ** CAPI3REF: Binding Values To Prepared Statements
|
| ** KEYWORDS: {host parameter} {host parameters} {host parameter name}
|
| ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
|
| ** literals may be replaced by a [parameter] that matches one of following
|
| @@ -3454,9 +3588,11 @@ int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
|
| void(*)(void*), unsigned char encoding);
|
| int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
|
| int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
|
| +int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
|
|
|
| /*
|
| ** CAPI3REF: Number Of SQL Parameters
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^This routine can be used to find the number of [SQL parameters]
|
| ** in a [prepared statement]. SQL parameters are tokens of the
|
| @@ -3477,6 +3613,7 @@ int sqlite3_bind_parameter_count(sqlite3_stmt*);
|
|
|
| /*
|
| ** CAPI3REF: Name Of A Host Parameter
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^The sqlite3_bind_parameter_name(P,N) interface returns
|
| ** the name of the N-th [SQL parameter] in the [prepared statement] P.
|
| @@ -3504,6 +3641,7 @@ const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
|
|
|
| /*
|
| ** CAPI3REF: Index Of A Parameter With A Given Name
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^Return the index of an SQL parameter given its name. ^The
|
| ** index value returned is suitable for use as the second
|
| @@ -3514,12 +3652,13 @@ const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
|
| **
|
| ** See also: [sqlite3_bind_blob|sqlite3_bind()],
|
| ** [sqlite3_bind_parameter_count()], and
|
| -** [sqlite3_bind_parameter_index()].
|
| +** [sqlite3_bind_parameter_name()].
|
| */
|
| int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
|
|
|
| /*
|
| ** CAPI3REF: Reset All Bindings On A Prepared Statement
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
|
| ** the [sqlite3_bind_blob | bindings] on a [prepared statement].
|
| @@ -3529,6 +3668,7 @@ int sqlite3_clear_bindings(sqlite3_stmt*);
|
|
|
| /*
|
| ** CAPI3REF: Number Of Columns In A Result Set
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^Return the number of columns in the result set returned by the
|
| ** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
|
| @@ -3540,6 +3680,7 @@ int sqlite3_column_count(sqlite3_stmt *pStmt);
|
|
|
| /*
|
| ** CAPI3REF: Column Names In A Result Set
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^These routines return the name assigned to a particular column
|
| ** in the result set of a [SELECT] statement. ^The sqlite3_column_name()
|
| @@ -3569,6 +3710,7 @@ const void *sqlite3_column_name16(sqlite3_stmt*, int N);
|
|
|
| /*
|
| ** CAPI3REF: Source Of Data In A Query Result
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^These routines provide a means to determine the database, table, and
|
| ** table column that is the origin of a particular result column in
|
| @@ -3621,6 +3763,7 @@ const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
|
|
|
| /*
|
| ** CAPI3REF: Declared Datatype Of A Query Result
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^(The first parameter is a [prepared statement].
|
| ** If this statement is a [SELECT] statement and the Nth column of the
|
| @@ -3653,6 +3796,7 @@ const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
|
|
|
| /*
|
| ** CAPI3REF: Evaluate An SQL Statement
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** After a [prepared statement] has been prepared using either
|
| ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
|
| @@ -3732,6 +3876,7 @@ int sqlite3_step(sqlite3_stmt*);
|
|
|
| /*
|
| ** CAPI3REF: Number of columns in a result set
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^The sqlite3_data_count(P) interface returns the number of columns in the
|
| ** current row of the result set of [prepared statement] P.
|
| @@ -3785,8 +3930,7 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
|
| /*
|
| ** CAPI3REF: Result Values From A Query
|
| ** KEYWORDS: {column access functions}
|
| -**
|
| -** These routines form the "result set" interface.
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^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
|
| @@ -3847,13 +3991,14 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
|
| ** even empty strings, are always zero-terminated. ^The return
|
| ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
|
| **
|
| -** ^The object returned by [sqlite3_column_value()] is an
|
| -** [unprotected sqlite3_value] object. An unprotected sqlite3_value object
|
| -** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
|
| +** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
|
| +** [unprotected sqlite3_value] object. In a multithreaded environment,
|
| +** an unprotected sqlite3_value object may only be used safely 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.
|
| +** or [sqlite3_value_bytes()], the behavior is not threadsafe.
|
| **
|
| ** These routines attempt to convert the value where appropriate. ^For
|
| ** example, if the internal representation is FLOAT and a text result
|
| @@ -3884,12 +4029,6 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
|
| ** </table>
|
| ** </blockquote>)^
|
| **
|
| -** The table above makes reference to standard C library functions atoi()
|
| -** and atof(). SQLite does not really use these functions. It has its
|
| -** 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.
|
| @@ -3914,7 +4053,7 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
|
| ** 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
|
| +** The safest policy is to invoke these routines
|
| ** in one of the following ways:
|
| **
|
| ** <ul>
|
| @@ -3934,7 +4073,7 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
|
| ** ^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
|
| +** and BLOBs is freed automatically. Do <em>not</em> pass the pointers returned
|
| ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
|
| ** [sqlite3_free()].
|
| **
|
| @@ -3957,6 +4096,7 @@ sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
|
|
|
| /*
|
| ** CAPI3REF: Destroy A Prepared Statement Object
|
| +** DESTRUCTOR: sqlite3_stmt
|
| **
|
| ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
|
| ** ^If the most recent evaluation of the statement encountered no errors
|
| @@ -3984,6 +4124,7 @@ int sqlite3_finalize(sqlite3_stmt *pStmt);
|
|
|
| /*
|
| ** CAPI3REF: Reset A Prepared Statement Object
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** The sqlite3_reset() function is called to reset a [prepared statement]
|
| ** object back to its initial state, ready to be re-executed.
|
| @@ -4013,6 +4154,7 @@ int sqlite3_reset(sqlite3_stmt *pStmt);
|
| ** KEYWORDS: {function creation routines}
|
| ** KEYWORDS: {application-defined SQL function}
|
| ** KEYWORDS: {application-defined SQL functions}
|
| +** METHOD: sqlite3
|
| **
|
| ** ^These functions (collectively known as "function creation routines")
|
| ** are used to add SQL functions or aggregates or to redefine the behavior
|
| @@ -4143,9 +4285,9 @@ int sqlite3_create_function_v2(
|
| ** These constant define integer codes that represent the various
|
| ** text encodings supported by SQLite.
|
| */
|
| -#define SQLITE_UTF8 1
|
| -#define SQLITE_UTF16LE 2
|
| -#define SQLITE_UTF16BE 3
|
| +#define SQLITE_UTF8 1 /* IMP: R-37514-35566 */
|
| +#define SQLITE_UTF16LE 2 /* IMP: R-03371-37637 */
|
| +#define SQLITE_UTF16BE 3 /* IMP: R-51971-34154 */
|
| #define SQLITE_UTF16 4 /* Use native byte order */
|
| #define SQLITE_ANY 5 /* Deprecated */
|
| #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
|
| @@ -4167,8 +4309,8 @@ int sqlite3_create_function_v2(
|
| ** 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 what they do.
|
| +** the use of these functions. To encourage programmers to avoid
|
| +** these functions, we will not explain what they do.
|
| */
|
| #ifndef SQLITE_OMIT_DEPRECATED
|
| SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
|
| @@ -4181,11 +4323,12 @@ SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
|
| #endif
|
|
|
| /*
|
| -** CAPI3REF: Obtaining SQL Function Parameter Values
|
| +** CAPI3REF: Obtaining SQL Values
|
| +** METHOD: sqlite3_value
|
| **
|
| ** The C-language implementation of SQL functions and aggregates uses
|
| ** this set of interface routines to access the parameter values on
|
| -** the function or aggregate.
|
| +** the function or aggregate.
|
| **
|
| ** The xFunc (for scalar functions) or xStep (for aggregates) parameters
|
| ** to [sqlite3_create_function()] and [sqlite3_create_function16()]
|
| @@ -4239,7 +4382,41 @@ int sqlite3_value_type(sqlite3_value*);
|
| int sqlite3_value_numeric_type(sqlite3_value*);
|
|
|
| /*
|
| +** CAPI3REF: Finding The Subtype Of SQL Values
|
| +** METHOD: sqlite3_value
|
| +**
|
| +** The sqlite3_value_subtype(V) function returns the subtype for
|
| +** an [application-defined SQL function] argument V. The subtype
|
| +** information can be used to pass a limited amount of context from
|
| +** one SQL function to another. Use the [sqlite3_result_subtype()]
|
| +** routine to set the subtype for the return value of an SQL function.
|
| +**
|
| +** SQLite makes no use of subtype itself. It merely passes the subtype
|
| +** from the result of one [application-defined SQL function] into the
|
| +** input of another.
|
| +*/
|
| +unsigned int sqlite3_value_subtype(sqlite3_value*);
|
| +
|
| +/*
|
| +** CAPI3REF: Copy And Free SQL Values
|
| +** METHOD: sqlite3_value
|
| +**
|
| +** ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value]
|
| +** object D and returns a pointer to that copy. ^The [sqlite3_value] returned
|
| +** is a [protected sqlite3_value] object even if the input is not.
|
| +** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
|
| +** memory allocation fails.
|
| +**
|
| +** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object
|
| +** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer
|
| +** then sqlite3_value_free(V) is a harmless no-op.
|
| +*/
|
| +sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
|
| +void sqlite3_value_free(sqlite3_value*);
|
| +
|
| +/*
|
| ** CAPI3REF: Obtain Aggregate Function Context
|
| +** METHOD: sqlite3_context
|
| **
|
| ** Implementations of aggregate SQL functions use this
|
| ** routine to allocate memory for storing their state.
|
| @@ -4284,6 +4461,7 @@ void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
|
|
|
| /*
|
| ** CAPI3REF: User Data For Functions
|
| +** METHOD: sqlite3_context
|
| **
|
| ** ^The sqlite3_user_data() interface returns a copy of
|
| ** the pointer that was the pUserData parameter (the 5th parameter)
|
| @@ -4298,6 +4476,7 @@ void *sqlite3_user_data(sqlite3_context*);
|
|
|
| /*
|
| ** CAPI3REF: Database Connection For Functions
|
| +** METHOD: sqlite3_context
|
| **
|
| ** ^The sqlite3_context_db_handle() interface returns a copy of
|
| ** the pointer to the [database connection] (the 1st parameter)
|
| @@ -4309,6 +4488,7 @@ sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
|
|
|
| /*
|
| ** CAPI3REF: Function Auxiliary Data
|
| +** METHOD: sqlite3_context
|
| **
|
| ** These functions may be used by (non-aggregate) SQL functions to
|
| ** associate metadata with argument values. If the same value is passed to
|
| @@ -4381,6 +4561,7 @@ typedef void (*sqlite3_destructor_type)(void*);
|
|
|
| /*
|
| ** CAPI3REF: Setting The Result Of An SQL Function
|
| +** METHOD: sqlite3_context
|
| **
|
| ** These routines are used by the xFunc or xFinal callbacks that
|
| ** implement SQL functions and aggregates. See
|
| @@ -4396,9 +4577,9 @@ typedef void (*sqlite3_destructor_type)(void*);
|
| ** to by the second parameter and which is N bytes long where N is the
|
| ** 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_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
|
| +** interfaces set the result of the application-defined function to be
|
| +** a BLOB containing all zero bytes and N bytes in size.
|
| **
|
| ** ^The sqlite3_result_double() interface sets the result from
|
| ** an application-defined function to be a floating point value specified
|
| @@ -4480,7 +4661,7 @@ typedef void (*sqlite3_destructor_type)(void*);
|
| ** from [sqlite3_malloc()] before it returns.
|
| **
|
| ** ^The sqlite3_result_value() interface sets the result of
|
| -** the application-defined function to be a copy the
|
| +** the application-defined function to be a copy of the
|
| ** [unprotected sqlite3_value] object specified by the 2nd parameter. ^The
|
| ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
|
| ** so that the [sqlite3_value] specified in the parameter may change or
|
| @@ -4494,7 +4675,8 @@ typedef void (*sqlite3_destructor_type)(void*);
|
| ** the [sqlite3_context] pointer, the results are undefined.
|
| */
|
| void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
|
| -void sqlite3_result_blob64(sqlite3_context*,const void*,sqlite3_uint64,void(*)(void*));
|
| +void sqlite3_result_blob64(sqlite3_context*,const void*,
|
| + sqlite3_uint64,void(*)(void*));
|
| void sqlite3_result_double(sqlite3_context*, double);
|
| void sqlite3_result_error(sqlite3_context*, const char*, int);
|
| void sqlite3_result_error16(sqlite3_context*, const void*, int);
|
| @@ -4512,9 +4694,26 @@ void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
|
| void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
|
| void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
|
| void sqlite3_result_zeroblob(sqlite3_context*, int n);
|
| +int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
|
| +
|
| +
|
| +/*
|
| +** CAPI3REF: Setting The Subtype Of An SQL Function
|
| +** METHOD: sqlite3_context
|
| +**
|
| +** The sqlite3_result_subtype(C,T) function causes the subtype of
|
| +** the result from the [application-defined SQL function] with
|
| +** [sqlite3_context] C to be the value T. Only the lower 8 bits
|
| +** of the subtype T are preserved in current versions of SQLite;
|
| +** higher order bits are discarded.
|
| +** The number of subtype bytes preserved by SQLite might increase
|
| +** in future releases of SQLite.
|
| +*/
|
| +void sqlite3_result_subtype(sqlite3_context*,unsigned int);
|
|
|
| /*
|
| ** CAPI3REF: Define New Collating Sequences
|
| +** METHOD: sqlite3
|
| **
|
| ** ^These functions add, remove, or modify a [collation] associated
|
| ** with the [database connection] specified as the first argument.
|
| @@ -4617,6 +4816,7 @@ int sqlite3_create_collation16(
|
|
|
| /*
|
| ** CAPI3REF: Collation Needed Callbacks
|
| +** METHOD: sqlite3
|
| **
|
| ** ^To avoid having to register all collation sequences before a database
|
| ** can be used, a single callback function may be registered with the
|
| @@ -4824,6 +5024,7 @@ SQLITE_EXTERN char *sqlite3_data_directory;
|
| /*
|
| ** CAPI3REF: Test For Auto-Commit Mode
|
| ** KEYWORDS: {autocommit mode}
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_get_autocommit() interface returns non-zero or
|
| ** zero if the given database connection is or is not in autocommit mode,
|
| @@ -4846,6 +5047,7 @@ int sqlite3_get_autocommit(sqlite3*);
|
|
|
| /*
|
| ** CAPI3REF: Find The Database Handle Of A Prepared Statement
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^The sqlite3_db_handle interface returns the [database connection] handle
|
| ** to which a [prepared statement] belongs. ^The [database connection]
|
| @@ -4858,6 +5060,7 @@ sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
|
|
|
| /*
|
| ** CAPI3REF: Return The Filename For A Database Connection
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename
|
| ** associated with database N of connection D. ^The main database file
|
| @@ -4874,6 +5077,7 @@ const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName);
|
|
|
| /*
|
| ** CAPI3REF: Determine if a database is read-only
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N
|
| ** of connection D is read-only, 0 if it is read/write, or -1 if N is not
|
| @@ -4883,6 +5087,7 @@ int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
|
|
|
| /*
|
| ** CAPI3REF: Find the next prepared statement
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This interface returns a pointer to the next [prepared statement] after
|
| ** pStmt associated with the [database connection] pDb. ^If pStmt is NULL
|
| @@ -4898,6 +5103,7 @@ sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
|
|
|
| /*
|
| ** CAPI3REF: Commit And Rollback Notification Callbacks
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_commit_hook() interface registers a callback
|
| ** function to be invoked whenever a transaction is [COMMIT | committed].
|
| @@ -4947,6 +5153,7 @@ void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
|
|
|
| /*
|
| ** CAPI3REF: Data Change Notification Callbacks
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_update_hook() interface registers a callback function
|
| ** with the [database connection] identified by the first argument
|
| @@ -5023,6 +5230,11 @@ void *sqlite3_update_hook(
|
| ** future releases of SQLite. Applications that care about shared
|
| ** cache setting should set it explicitly.
|
| **
|
| +** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0
|
| +** and will always return SQLITE_MISUSE. On those systems,
|
| +** shared cache mode should be enabled per-database connection via
|
| +** [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE].
|
| +**
|
| ** This interface is threadsafe on processors where writing a
|
| ** 32-bit integer is atomic.
|
| **
|
| @@ -5048,6 +5260,7 @@ int sqlite3_release_memory(int);
|
|
|
| /*
|
| ** CAPI3REF: Free Memory Used By A Database Connection
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap
|
| ** memory as possible from database connection D. Unlike the
|
| @@ -5125,21 +5338,29 @@ SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
|
|
|
| /*
|
| ** CAPI3REF: Extract Metadata About A Column Of A Table
|
| -**
|
| -** ^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.
|
| +** METHOD: sqlite3
|
| +**
|
| +** ^(The sqlite3_table_column_metadata(X,D,T,C,....) routine returns
|
| +** information about column C of table T in database D
|
| +** on [database connection] X.)^ ^The sqlite3_table_column_metadata()
|
| +** interface returns SQLITE_OK and fills in the non-NULL pointers in
|
| +** the final five arguments with appropriate values if the specified
|
| +** column exists. ^The sqlite3_table_column_metadata() interface returns
|
| +** SQLITE_ERROR and if the specified column does not exist.
|
| +** ^If the column-name parameter to sqlite3_table_column_metadata() is a
|
| +** NULL pointer, then this routine simply checks for the existance of the
|
| +** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it
|
| +** does not.
|
| **
|
| ** ^The column is identified by the second, third and fourth parameters to
|
| -** this function. ^The second parameter is either the name of the database
|
| +** 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
|
| +** table or NULL.)^ ^If it is NULL, then all attached databases are searched
|
| ** 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
|
| -** may be NULL.
|
| +** name of the desired column, respectively.
|
| **
|
| ** ^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
|
| @@ -5158,16 +5379,17 @@ SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
|
| ** </blockquote>)^
|
| **
|
| ** ^The memory pointed to by the character pointers returned for the
|
| -** declaration type and collation sequence is valid only until the next
|
| +** declaration type and collation sequence is valid until the next
|
| ** call to any SQLite API function.
|
| **
|
| ** ^If the specified table is actually a view, an [error code] is returned.
|
| **
|
| -** ^If the specified column is "rowid", "oid" or "_rowid_" and an
|
| +** ^If the specified column is "rowid", "oid" or "_rowid_" and the table
|
| +** is not a [WITHOUT ROWID] table 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 [INTEGER PRIMARY KEY] column, then the output
|
| -** parameters are set as follows:
|
| +** [INTEGER PRIMARY KEY] column, then the outputs
|
| +** for the [rowid] are set as follows:
|
| **
|
| ** <pre>
|
| ** data type: "INTEGER"
|
| @@ -5177,13 +5399,9 @@ SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
|
| ** auto increment: 0
|
| ** </pre>)^
|
| **
|
| -** ^(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 [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] C-preprocessor symbol defined.
|
| +** ^This function causes all database schemas to be read from disk and
|
| +** parsed, if that has not already been done, and returns an error if
|
| +** any errors are encountered while loading the schema.
|
| */
|
| int sqlite3_table_column_metadata(
|
| sqlite3 *db, /* Connection handle */
|
| @@ -5199,6 +5417,7 @@ int sqlite3_table_column_metadata(
|
|
|
| /*
|
| ** CAPI3REF: Load An Extension
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This interface loads an SQLite extension library from the named file.
|
| **
|
| @@ -5240,6 +5459,7 @@ int sqlite3_load_extension(
|
|
|
| /*
|
| ** CAPI3REF: Enable Or Disable Extension Loading
|
| +** METHOD: sqlite3
|
| **
|
| ** ^So as not to open security holes in older applications that are
|
| ** unprepared to deal with [extension loading], and as a means of disabling
|
| @@ -5411,6 +5631,17 @@ struct sqlite3_module {
|
| ** ^Information about the ORDER BY clause is stored in aOrderBy[].
|
| ** ^Each term of aOrderBy records a column of the ORDER BY clause.
|
| **
|
| +** The colUsed field indicates which columns of the virtual table may be
|
| +** required by the current scan. Virtual table columns are numbered from
|
| +** zero in the order in which they appear within the CREATE TABLE statement
|
| +** passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),
|
| +** the corresponding bit is set within the colUsed mask if the column may be
|
| +** required by SQLite. If the table has at least 64 columns and any column
|
| +** to the right of the first 63 is required, then bit 63 of colUsed is also
|
| +** set. In other words, column iCol may be required if the expression
|
| +** (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to
|
| +** non-zero.
|
| +**
|
| ** The [xBestIndex] method must fill aConstraintUsage[] with information
|
| ** about what parameters to pass to xFilter. ^If argvIndex>0 then
|
| ** the right-hand side of the corresponding aConstraint[] is evaluated
|
| @@ -5436,13 +5667,31 @@ struct sqlite3_module {
|
| ** ^The estimatedRows value is an estimate of the number of rows that
|
| ** will be returned by the strategy.
|
| **
|
| +** The xBestIndex method may optionally populate the idxFlags field with a
|
| +** mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag -
|
| +** SQLITE_INDEX_SCAN_UNIQUE. If the xBestIndex method sets this flag, SQLite
|
| +** assumes that the strategy may visit at most one row.
|
| +**
|
| +** Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then
|
| +** SQLite also assumes that if a call to the xUpdate() method is made as
|
| +** part of the same statement to delete or update a virtual table row and the
|
| +** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback
|
| +** any database changes. In other words, if the xUpdate() returns
|
| +** SQLITE_CONSTRAINT, the database contents must be exactly as they were
|
| +** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not
|
| +** set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by
|
| +** the xUpdate method are automatically rolled back by SQLite.
|
| +**
|
| ** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info
|
| ** structure for SQLite version 3.8.2. If a virtual table extension is
|
| ** used with an SQLite version earlier than 3.8.2, the results of attempting
|
| ** to read or write the estimatedRows field are undefined (but are likely
|
| ** to included crashing the application). The estimatedRows field should
|
| ** therefore only be used if [sqlite3_libversion_number()] returns a
|
| -** value greater than or equal to 3008002.
|
| +** value greater than or equal to 3008002. Similarly, the idxFlags field
|
| +** was added for version 3.9.0. It may therefore only be used if
|
| +** sqlite3_libversion_number() returns a value greater than or equal to
|
| +** 3009000.
|
| */
|
| struct sqlite3_index_info {
|
| /* Inputs */
|
| @@ -5470,9 +5719,18 @@ struct sqlite3_index_info {
|
| double estimatedCost; /* Estimated cost of using this index */
|
| /* Fields below are only available in SQLite 3.8.2 and later */
|
| sqlite3_int64 estimatedRows; /* Estimated number of rows returned */
|
| + /* Fields below are only available in SQLite 3.9.0 and later */
|
| + int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */
|
| + /* Fields below are only available in SQLite 3.10.0 and later */
|
| + sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */
|
| };
|
|
|
| /*
|
| +** CAPI3REF: Virtual Table Scan Flags
|
| +*/
|
| +#define SQLITE_INDEX_SCAN_UNIQUE 1 /* Scan visits at most 1 row */
|
| +
|
| +/*
|
| ** CAPI3REF: Virtual Table Constraint Operator Codes
|
| **
|
| ** These macros defined the allowed values for the
|
| @@ -5480,15 +5738,19 @@ struct sqlite3_index_info {
|
| ** an operator that is part of a constraint term in the wHERE clause of
|
| ** a query that uses a [virtual table].
|
| */
|
| -#define SQLITE_INDEX_CONSTRAINT_EQ 2
|
| -#define SQLITE_INDEX_CONSTRAINT_GT 4
|
| -#define SQLITE_INDEX_CONSTRAINT_LE 8
|
| -#define SQLITE_INDEX_CONSTRAINT_LT 16
|
| -#define SQLITE_INDEX_CONSTRAINT_GE 32
|
| -#define SQLITE_INDEX_CONSTRAINT_MATCH 64
|
| +#define SQLITE_INDEX_CONSTRAINT_EQ 2
|
| +#define SQLITE_INDEX_CONSTRAINT_GT 4
|
| +#define SQLITE_INDEX_CONSTRAINT_LE 8
|
| +#define SQLITE_INDEX_CONSTRAINT_LT 16
|
| +#define SQLITE_INDEX_CONSTRAINT_GE 32
|
| +#define SQLITE_INDEX_CONSTRAINT_MATCH 64
|
| +#define SQLITE_INDEX_CONSTRAINT_LIKE 65
|
| +#define SQLITE_INDEX_CONSTRAINT_GLOB 66
|
| +#define SQLITE_INDEX_CONSTRAINT_REGEXP 67
|
|
|
| /*
|
| ** CAPI3REF: Register A Virtual Table Implementation
|
| +** METHOD: sqlite3
|
| **
|
| ** ^These routines are used to register a new [virtual table module] name.
|
| ** ^Module names must be registered before
|
| @@ -5546,7 +5808,7 @@ int sqlite3_create_module_v2(
|
| */
|
| struct sqlite3_vtab {
|
| const sqlite3_module *pModule; /* The module for this virtual table */
|
| - int nRef; /* NO LONGER USED */
|
| + int nRef; /* Number of open cursors */
|
| char *zErrMsg; /* Error message from sqlite3_mprintf() */
|
| /* Virtual table implementations will typically add additional fields */
|
| };
|
| @@ -5585,6 +5847,7 @@ int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
|
|
|
| /*
|
| ** CAPI3REF: Overload A Function For A Virtual Table
|
| +** METHOD: sqlite3
|
| **
|
| ** ^(Virtual tables can provide alternative implementations of functions
|
| ** using the [xFindFunction] method of the [virtual table module].
|
| @@ -5627,6 +5890,8 @@ typedef struct sqlite3_blob sqlite3_blob;
|
|
|
| /*
|
| ** CAPI3REF: Open A BLOB For Incremental I/O
|
| +** METHOD: sqlite3
|
| +** CONSTRUCTOR: sqlite3_blob
|
| **
|
| ** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located
|
| ** in row iRow, column zColumn, table zTable in database zDb;
|
| @@ -5636,26 +5901,42 @@ typedef struct sqlite3_blob sqlite3_blob;
|
| ** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
|
| ** </pre>)^
|
| **
|
| +** ^(Parameter zDb is not the filename that contains the database, but
|
| +** rather the symbolic name of the database. For attached databases, this is
|
| +** the name that appears after the AS keyword in the [ATTACH] statement.
|
| +** For the main database file, the database name is "main". For TEMP
|
| +** tables, the database name is "temp".)^
|
| +**
|
| ** ^If the flags parameter is non-zero, then the BLOB is opened for read
|
| -** and write access. ^If it is zero, the BLOB is opened for read access.
|
| -** ^It is not possible to open a column that is part of an index or primary
|
| -** key for writing. ^If [foreign key constraints] are enabled, it is
|
| -** not possible to open a column that is part of a [child key] for writing.
|
| -**
|
| -** ^Note that the database name is not the filename that contains
|
| -** the database but rather the symbolic name of the database that
|
| -** appears after the AS keyword 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 [BLOB handle] is written
|
| -** to *ppBlob. Otherwise an [error code] is returned and *ppBlob is set
|
| -** to be a null pointer.)^
|
| -** ^This function sets the [database connection] error code and message
|
| -** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()] and related
|
| -** functions. ^Note that the *ppBlob variable is always initialized in a
|
| -** way that makes it safe to invoke [sqlite3_blob_close()] on *ppBlob
|
| -** regardless of the success or failure of this routine.
|
| +** and write access. ^If the flags parameter is zero, the BLOB is opened for
|
| +** read-only access.
|
| +**
|
| +** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is stored
|
| +** in *ppBlob. Otherwise an [error code] is returned and, unless the error
|
| +** code is SQLITE_MISUSE, *ppBlob is set to NULL.)^ ^This means that, provided
|
| +** the API is not misused, it is always safe to call [sqlite3_blob_close()]
|
| +** on *ppBlob after this function it returns.
|
| +**
|
| +** This function fails with SQLITE_ERROR if any of the following are true:
|
| +** <ul>
|
| +** <li> ^(Database zDb does not exist)^,
|
| +** <li> ^(Table zTable does not exist within database zDb)^,
|
| +** <li> ^(Table zTable is a WITHOUT ROWID table)^,
|
| +** <li> ^(Column zColumn does not exist)^,
|
| +** <li> ^(Row iRow is not present in the table)^,
|
| +** <li> ^(The specified column of row iRow contains a value that is not
|
| +** a TEXT or BLOB value)^,
|
| +** <li> ^(Column zColumn is part of an index, PRIMARY KEY or UNIQUE
|
| +** constraint and the blob is being opened for read/write access)^,
|
| +** <li> ^([foreign key constraints | Foreign key constraints] are enabled,
|
| +** column zColumn is part of a [child key] definition and the blob is
|
| +** being opened for read/write access)^.
|
| +** </ul>
|
| +**
|
| +** ^Unless it returns SQLITE_MISUSE, this function sets the
|
| +** [database connection] error code and message accessible via
|
| +** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
|
| +**
|
| **
|
| ** ^(If the row that a BLOB handle points to is modified by an
|
| ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
|
| @@ -5673,13 +5954,9 @@ typedef struct sqlite3_blob sqlite3_blob;
|
| ** interface. Use the [UPDATE] SQL command to change the size of a
|
| ** blob.
|
| **
|
| -** ^The [sqlite3_blob_open()] interface will fail for a [WITHOUT ROWID]
|
| -** table. Incremental BLOB I/O is not possible on [WITHOUT ROWID] tables.
|
| -**
|
| ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
|
| -** and the built-in [zeroblob] SQL function can be used, if desired,
|
| -** to create an empty, zero-filled blob in which to read or write using
|
| -** this interface.
|
| +** and the built-in [zeroblob] SQL function may be used to create a
|
| +** zero-filled blob to read or write using the incremental-blob interface.
|
| **
|
| ** To avoid a resource leak, every open [BLOB handle] should eventually
|
| ** be released by a call to [sqlite3_blob_close()].
|
| @@ -5696,6 +5973,7 @@ int sqlite3_blob_open(
|
|
|
| /*
|
| ** CAPI3REF: Move a BLOB Handle to a New Row
|
| +** METHOD: sqlite3_blob
|
| **
|
| ** ^This function is used to move an existing blob handle so that it points
|
| ** to a different row of the same database table. ^The new row is identified
|
| @@ -5716,34 +5994,34 @@ int sqlite3_blob_open(
|
| **
|
| ** ^This function sets the database handle error code and message.
|
| */
|
| -SQLITE_EXPERIMENTAL int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
|
| +int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
|
|
|
| /*
|
| ** CAPI3REF: Close A BLOB Handle
|
| +** DESTRUCTOR: sqlite3_blob
|
| **
|
| -** ^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].
|
| -** ^If any writes were made to the BLOB, they might be held in cache
|
| -** until the close operation if they will fit.
|
| +** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed
|
| +** unconditionally. Even if this routine returns an error code, the
|
| +** handle is still closed.)^
|
| **
|
| -** ^(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. Any errors that occur during
|
| -** closing are reported as a non-zero return value.)^
|
| +** ^If the blob handle being closed was opened for read-write access, and if
|
| +** the database is in auto-commit mode and there are no other open read-write
|
| +** blob handles or active write statements, the current transaction is
|
| +** committed. ^If an error occurs while committing the transaction, an error
|
| +** code is returned and the transaction rolled back.
|
| **
|
| -** ^(The BLOB is closed unconditionally. Even if this routine returns
|
| -** an error code, the BLOB is still closed.)^
|
| -**
|
| -** ^Calling this routine with a null pointer (such as would be returned
|
| -** by a failed call to [sqlite3_blob_open()]) is a harmless no-op.
|
| +** Calling this function with an argument that is not a NULL pointer or an
|
| +** open blob handle results in undefined behaviour. ^Calling this routine
|
| +** with a null pointer (such as would be returned by a failed call to
|
| +** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function
|
| +** is passed a valid open blob handle, the values returned by the
|
| +** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning.
|
| */
|
| int sqlite3_blob_close(sqlite3_blob *);
|
|
|
| /*
|
| ** CAPI3REF: Return The Size Of An Open BLOB
|
| +** METHOD: sqlite3_blob
|
| **
|
| ** ^Returns the size in bytes of the BLOB accessible via the
|
| ** successfully opened [BLOB handle] in its only argument. ^The
|
| @@ -5759,6 +6037,7 @@ int sqlite3_blob_bytes(sqlite3_blob *);
|
|
|
| /*
|
| ** CAPI3REF: Read Data From A BLOB Incrementally
|
| +** METHOD: sqlite3_blob
|
| **
|
| ** ^(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
|
| @@ -5787,22 +6066,29 @@ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
|
|
|
| /*
|
| ** CAPI3REF: Write Data Into A BLOB Incrementally
|
| +** METHOD: sqlite3_blob
|
| **
|
| -** ^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.
|
| +** ^(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.)^
|
| +**
|
| +** ^(On success, sqlite3_blob_write() returns SQLITE_OK.
|
| +** Otherwise, an [error code] or an [extended error code] is returned.)^
|
| +** ^Unless SQLITE_MISUSE is returned, this function sets the
|
| +** [database connection] error code and message accessible via
|
| +** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
|
| **
|
| ** ^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
|
| +** 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.
|
| -** The size of the BLOB (and hence the maximum value of N+iOffset)
|
| -** can be determined using the [sqlite3_blob_bytes()] interface.
|
| +** [SQLITE_ERROR] is returned and no data is written. The size of the
|
| +** BLOB (and hence the maximum value of N+iOffset) can be determined
|
| +** using the [sqlite3_blob_bytes()] interface. ^If N or iOffset are less
|
| +** than zero [SQLITE_ERROR] is returned and no data is written.
|
| **
|
| ** ^An attempt to write to an expired [BLOB handle] fails with an
|
| ** error code of [SQLITE_ABORT]. ^Writes to the BLOB that occurred
|
| @@ -5811,9 +6097,6 @@ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
|
| ** have been overwritten by the statement that expired the BLOB handle
|
| ** or by other independent statements.
|
| **
|
| -** ^(On success, sqlite3_blob_write() returns SQLITE_OK.
|
| -** Otherwise, an [error code] or an [extended error code] is returned.)^
|
| -**
|
| ** This routine only works on a [BLOB handle] which has been created
|
| ** by a prior successful call to [sqlite3_blob_open()] and which has not
|
| ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
|
| @@ -5866,34 +6149,34 @@ int sqlite3_vfs_unregister(sqlite3_vfs*);
|
| **
|
| ** The SQLite source code contains multiple implementations
|
| ** of these mutex routines. An appropriate implementation
|
| -** is selected automatically at compile-time. ^(The following
|
| +** is selected automatically at compile-time. The following
|
| ** implementations are available in the SQLite core:
|
| **
|
| ** <ul>
|
| ** <li> SQLITE_MUTEX_PTHREADS
|
| ** <li> SQLITE_MUTEX_W32
|
| ** <li> SQLITE_MUTEX_NOOP
|
| -** </ul>)^
|
| +** </ul>
|
| **
|
| -** ^The SQLITE_MUTEX_NOOP implementation is a set of routines
|
| +** 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_PTHREADS and
|
| +** a single-threaded application. The SQLITE_MUTEX_PTHREADS and
|
| ** SQLITE_MUTEX_W32 implementations are appropriate for use on Unix
|
| ** and Windows.
|
| **
|
| -** ^(If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
|
| +** 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. 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().)^
|
| +** function that calls sqlite3_initialize().
|
| **
|
| ** ^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
|
| -** will unwind its stack and return an error. ^(The argument
|
| -** to sqlite3_mutex_alloc() is one of these integer constants:
|
| +** mutex and returns a pointer to it. ^The sqlite3_mutex_alloc()
|
| +** routine returns NULL if it is unable to allocate the requested
|
| +** mutex. The argument to sqlite3_mutex_alloc() must one of these
|
| +** integer constants:
|
| **
|
| ** <ul>
|
| ** <li> SQLITE_MUTEX_FAST
|
| @@ -5906,7 +6189,11 @@ int sqlite3_vfs_unregister(sqlite3_vfs*);
|
| ** <li> SQLITE_MUTEX_STATIC_PMEM
|
| ** <li> SQLITE_MUTEX_STATIC_APP1
|
| ** <li> SQLITE_MUTEX_STATIC_APP2
|
| -** </ul>)^
|
| +** <li> SQLITE_MUTEX_STATIC_APP3
|
| +** <li> SQLITE_MUTEX_STATIC_VFS1
|
| +** <li> SQLITE_MUTEX_STATIC_VFS2
|
| +** <li> SQLITE_MUTEX_STATIC_VFS3
|
| +** </ul>
|
| **
|
| ** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
|
| ** cause sqlite3_mutex_alloc() to create
|
| @@ -5914,14 +6201,14 @@ int sqlite3_vfs_unregister(sqlite3_vfs*);
|
| ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
|
| ** The mutex implementation does not need to make a distinction
|
| ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
|
| -** not want to. ^SQLite will only request a recursive mutex in
|
| -** cases where it really needs one. ^If a faster non-recursive mutex
|
| +** not want to. SQLite will only request a recursive mutex in
|
| +** cases where it really needs one. 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.
|
| **
|
| ** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other
|
| ** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
|
| -** a pointer to a static preexisting mutex. ^Six static mutexes are
|
| +** a pointer to a static preexisting mutex. ^Nine static mutexes are
|
| ** used by the current version of SQLite. Future versions of SQLite
|
| ** may add additional static mutexes. Static mutexes are for internal
|
| ** use by SQLite only. Applications that use SQLite mutexes should
|
| @@ -5930,16 +6217,13 @@ int sqlite3_vfs_unregister(sqlite3_vfs*);
|
| **
|
| ** ^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. ^But for the static
|
| +** returns a different mutex on every call. ^For the static
|
| ** mutex types, the same mutex is returned on every call that has
|
| ** the same type number.
|
| **
|
| ** ^The sqlite3_mutex_free() routine deallocates a previously
|
| -** allocated dynamic mutex. ^SQLite is careful to deallocate every
|
| -** dynamic mutex that it allocates. The dynamic mutexes must not be in
|
| -** use when they are deallocated. Attempting to deallocate a static
|
| -** mutex results in undefined behavior. ^SQLite never deallocates
|
| -** a static mutex.
|
| +** allocated dynamic mutex. Attempting to deallocate a static
|
| +** mutex results in undefined behavior.
|
| **
|
| ** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
|
| ** to enter a mutex. ^If another thread is already within the mutex,
|
| @@ -5947,23 +6231,21 @@ int sqlite3_vfs_unregister(sqlite3_vfs*);
|
| ** SQLITE_BUSY. ^The sqlite3_mutex_try() interface returns [SQLITE_OK]
|
| ** upon successful entry. ^(Mutexes created using
|
| ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
|
| -** In such cases the,
|
| +** In such cases, the
|
| ** mutex must be exited an equal number of times before another thread
|
| -** can enter.)^ ^(If the same thread tries to enter any other
|
| -** kind of mutex more than once, the behavior is undefined.
|
| -** SQLite will never exhibit
|
| -** such behavior in its own use of mutexes.)^
|
| +** can enter.)^ If the same thread tries to enter any mutex other
|
| +** than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.
|
| **
|
| ** ^(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. The SQLite core only ever uses
|
| -** sqlite3_mutex_try() as an optimization so this is acceptable behavior.)^
|
| +** will always return SQLITE_BUSY. The SQLite core only ever uses
|
| +** sqlite3_mutex_try() as an optimization so this is acceptable
|
| +** behavior.)^
|
| **
|
| ** ^The sqlite3_mutex_leave() routine exits a mutex that was
|
| -** previously entered by the same thread. ^(The behavior
|
| +** previously entered by the same thread. The behavior
|
| ** is undefined if the mutex is not currently entered by the
|
| -** calling thread or is not currently allocated. SQLite will
|
| -** never do either.)^
|
| +** calling thread or is not currently allocated.
|
| **
|
| ** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
|
| ** sqlite3_mutex_leave() is a NULL pointer, then all three routines
|
| @@ -5984,9 +6266,9 @@ void sqlite3_mutex_leave(sqlite3_mutex*);
|
| ** 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
|
| +** sufficient, however the application 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
|
| +** does not provide a suitable implementation. In this case, the application
|
| ** 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
|
| @@ -6027,13 +6309,13 @@ void sqlite3_mutex_leave(sqlite3_mutex*);
|
| ** (i.e. it is acceptable to provide an implementation that segfaults if
|
| ** it is passed a NULL pointer).
|
| **
|
| -** The xMutexInit() method must be threadsafe. ^It must be harmless to
|
| +** The xMutexInit() method must be threadsafe. It must be harmless to
|
| ** invoke xMutexInit() multiple times within the same process and without
|
| ** intervening calls to xMutexEnd(). Second and subsequent calls to
|
| ** xMutexInit() must be no-ops.
|
| **
|
| -** ^xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
|
| -** and its associates). ^Similarly, xMutexAlloc() must not use SQLite memory
|
| +** xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
|
| +** and its associates). Similarly, xMutexAlloc() must not use SQLite memory
|
| ** allocation for a static mutex. ^However xMutexAlloc() may use SQLite
|
| ** memory allocation for a fast or recursive mutex.
|
| **
|
| @@ -6059,29 +6341,29 @@ struct sqlite3_mutex_methods {
|
| ** CAPI3REF: Mutex Verification Routines
|
| **
|
| ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
|
| -** are intended for use inside assert() statements. ^The SQLite core
|
| +** are intended for use inside assert() statements. The SQLite core
|
| ** never uses these routines except inside an assert() and applications
|
| -** are advised to follow the lead of the core. ^The SQLite core only
|
| +** are advised to follow the lead of the core. The SQLite core only
|
| ** provides implementations for these routines when it is compiled
|
| -** with the SQLITE_DEBUG flag. ^External mutex implementations
|
| +** with the SQLITE_DEBUG flag. External mutex implementations
|
| ** are only required to provide these routines if SQLITE_DEBUG is
|
| ** defined and if NDEBUG is not defined.
|
| **
|
| -** ^These routines should return true if the mutex in their argument
|
| +** These routines should return true if the mutex in their argument
|
| ** is held or not held, respectively, by the calling thread.
|
| **
|
| -** ^The implementation is not required to provide versions of these
|
| +** The implementation is not required to provide 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.
|
| **
|
| -** ^If the argument to sqlite3_mutex_held() is a NULL pointer then
|
| +** If the argument to sqlite3_mutex_held() is a NULL pointer then
|
| ** the routine should return 1. This seems counter-intuitive since
|
| ** clearly the mutex cannot be held if it does not exist. But
|
| ** 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. ^The sqlite3_mutex_notheld()
|
| +** the appropriate thing to do. The sqlite3_mutex_notheld()
|
| ** interface should also return 1 when given a NULL pointer.
|
| */
|
| #ifndef NDEBUG
|
| @@ -6112,9 +6394,13 @@ int sqlite3_mutex_notheld(sqlite3_mutex*);
|
| #define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */
|
| #define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */
|
| #define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */
|
| +#define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */
|
| +#define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */
|
| +#define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */
|
|
|
| /*
|
| ** CAPI3REF: Retrieve the mutex for a database connection
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This interface returns a pointer the [sqlite3_mutex] object that
|
| ** serializes access to the [database connection] given in the argument
|
| @@ -6126,6 +6412,7 @@ sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
|
|
|
| /*
|
| ** CAPI3REF: Low-Level Control Of Database Files
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The [sqlite3_file_control()] interface makes a direct call to the
|
| ** xFileControl method for the [sqlite3_io_methods] object associated
|
| @@ -6209,12 +6496,13 @@ int sqlite3_test_control(int op, ...);
|
| #define SQLITE_TESTCTRL_BYTEORDER 22
|
| #define SQLITE_TESTCTRL_ISINIT 23
|
| #define SQLITE_TESTCTRL_SORTER_MMAP 24
|
| -#define SQLITE_TESTCTRL_LAST 24
|
| +#define SQLITE_TESTCTRL_IMPOSTER 25
|
| +#define SQLITE_TESTCTRL_LAST 25
|
|
|
| /*
|
| ** CAPI3REF: SQLite Runtime Status
|
| **
|
| -** ^This interface is used to retrieve runtime status information
|
| +** ^These interfaces are used to retrieve runtime status information
|
| ** about the performance 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
|
| @@ -6228,19 +6516,22 @@ int sqlite3_test_control(int op, ...);
|
| ** ^(Other parameters record only the highwater mark and not the current
|
| ** value. For these latter parameters nothing is written into *pCurrent.)^
|
| **
|
| -** ^The sqlite3_status() routine returns SQLITE_OK on success and a
|
| -** non-zero [error code] on failure.
|
| +** ^The sqlite3_status() and sqlite3_status64() routines return
|
| +** SQLITE_OK on success and a non-zero [error code] on failure.
|
| **
|
| -** This routine is threadsafe but is not atomic. This routine can be
|
| -** 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.
|
| +** If either the current value or the highwater mark is too large to
|
| +** be represented by a 32-bit integer, then the values returned by
|
| +** sqlite3_status() are undefined.
|
| **
|
| ** See also: [sqlite3_db_status()]
|
| */
|
| int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
|
| +int sqlite3_status64(
|
| + int op,
|
| + sqlite3_int64 *pCurrent,
|
| + sqlite3_int64 *pHighwater,
|
| + int resetFlag
|
| +);
|
|
|
|
|
| /*
|
| @@ -6319,7 +6610,8 @@ int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
|
| ** The value written into the *pCurrent parameter is undefined.</dd>)^
|
| **
|
| ** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
|
| -** <dd>This parameter records the deepest parser stack. It is only
|
| +** <dd>The *pHighwater parameter records the deepest parser stack.
|
| +** The *pCurrent value is undefined. The *pHighwater value is only
|
| ** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
|
| ** </dl>
|
| **
|
| @@ -6338,6 +6630,7 @@ int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
|
|
|
| /*
|
| ** CAPI3REF: Database Connection Status
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This interface is used to retrieve runtime status information
|
| ** about a single [database connection]. ^The first argument is the
|
| @@ -6466,6 +6759,7 @@ int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
|
|
|
| /*
|
| ** CAPI3REF: Prepared Statement Status
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^(Each prepared statement maintains various
|
| ** [SQLITE_STMTSTATUS counters] that measure the number
|
| @@ -6814,6 +7108,10 @@ typedef struct sqlite3_backup sqlite3_backup;
|
| ** must be different or else sqlite3_backup_init(D,N,S,M) will fail with
|
| ** an error.
|
| **
|
| +** ^A call to sqlite3_backup_init() will fail, returning SQLITE_ERROR, if
|
| +** there is already a read or read-write transaction open on the
|
| +** destination database.
|
| +**
|
| ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
|
| ** returned and an error code and error message are stored in the
|
| ** destination [database connection] D.
|
| @@ -6906,20 +7204,20 @@ typedef struct sqlite3_backup sqlite3_backup;
|
| ** is not a permanent error and does not affect the return value of
|
| ** sqlite3_backup_finish().
|
| **
|
| -** [[sqlite3_backup__remaining()]] [[sqlite3_backup_pagecount()]]
|
| +** [[sqlite3_backup_remaining()]] [[sqlite3_backup_pagecount()]]
|
| ** <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b>
|
| **
|
| -** ^Each call to sqlite3_backup_step() sets two values inside
|
| -** the [sqlite3_backup] object: the number of pages still to be backed
|
| -** up and the total number of pages in the source database file.
|
| -** The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces
|
| -** retrieve these two values, respectively.
|
| -**
|
| -** ^The values returned by these functions are only updated by
|
| -** sqlite3_backup_step(). ^If the source database is modified during a backup
|
| -** operation, then the values are not updated to account for any extra
|
| -** pages that need to be updated or the size of the source database file
|
| -** changing.
|
| +** ^The sqlite3_backup_remaining() routine returns the number of pages still
|
| +** to be backed up at the conclusion of the most recent sqlite3_backup_step().
|
| +** ^The sqlite3_backup_pagecount() routine returns the total number of pages
|
| +** in the source database at the conclusion of the most recent
|
| +** sqlite3_backup_step().
|
| +** ^(The values returned by these functions are only updated by
|
| +** sqlite3_backup_step(). If the source database is modified in a way that
|
| +** changes the size of the source database or the number of pages remaining,
|
| +** those changes are not reflected in the output of sqlite3_backup_pagecount()
|
| +** and sqlite3_backup_remaining() until after the next
|
| +** sqlite3_backup_step().)^
|
| **
|
| ** <b>Concurrent Usage of Database Handles</b>
|
| **
|
| @@ -6965,6 +7263,7 @@ int sqlite3_backup_pagecount(sqlite3_backup *p);
|
|
|
| /*
|
| ** CAPI3REF: Unlock Notification
|
| +** METHOD: sqlite3
|
| **
|
| ** ^When running in shared-cache mode, a database operation may fail with
|
| ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
|
| @@ -7098,18 +7397,82 @@ int sqlite3_strnicmp(const char *, const char *, int);
|
| /*
|
| ** CAPI3REF: String Globbing
|
| *
|
| -** ^The [sqlite3_strglob(P,X)] interface returns zero if string X matches
|
| -** the glob pattern P, and it returns non-zero if string X does not match
|
| -** the glob pattern P. ^The definition of glob pattern matching used in
|
| +** ^The [sqlite3_strglob(P,X)] interface returns zero if and only if
|
| +** string X matches the [GLOB] pattern P.
|
| +** ^The definition of [GLOB] pattern matching used in
|
| ** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the
|
| -** SQL dialect used by SQLite. ^The sqlite3_strglob(P,X) function is case
|
| -** sensitive.
|
| +** SQL dialect understood by SQLite. ^The [sqlite3_strglob(P,X)] function
|
| +** is case sensitive.
|
| **
|
| ** Note that this routine returns zero on a match and non-zero if the strings
|
| ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
|
| +**
|
| +** See also: [sqlite3_strlike()].
|
| */
|
| int sqlite3_strglob(const char *zGlob, const char *zStr);
|
|
|
| +/* Begin recover virtual table patch for Chromium */
|
| +/* Our patches don't conform to SQLite's amalgamation processing. Hack it. */
|
| +#ifndef CHROMIUM_SQLITE_API
|
| +#define CHROMIUM_SQLITE_API SQLITE_API
|
| +#endif
|
| +/*
|
| +** Call to initialize the recover virtual-table modules (see recover.c).
|
| +**
|
| +** This could be loaded by default in main.c, but that would make the
|
| +** virtual table available to Web SQL. Breaking it out allows only
|
| +** selected users to enable it (currently sql/recovery.cc).
|
| +*/
|
| +CHROMIUM_SQLITE_API
|
| +int recoverVtableInit(sqlite3 *db);
|
| +/* End recover virtual table patch for Chromium */
|
| +
|
| +/* Begin WebDatabase patch for Chromium */
|
| +/* Expose some SQLite internals for the WebDatabase vfs.
|
| +** DO NOT EXTEND THE USE OF THIS.
|
| +*/
|
| +#ifndef CHROMIUM_SQLITE_API
|
| +#define CHROMIUM_SQLITE_API SQLITE_API
|
| +#endif
|
| +#if defined(CHROMIUM_SQLITE_INTERNALS)
|
| +#ifdef _WIN32
|
| +CHROMIUM_SQLITE_API
|
| +void chromium_sqlite3_initialize_win_sqlite3_file(sqlite3_file* file, HANDLE handle);
|
| +#else /* _WIN32 */
|
| +CHROMIUM_SQLITE_API
|
| +int chromium_sqlite3_fill_in_unix_sqlite3_file(sqlite3_vfs* pVfs,
|
| + int fd,
|
| + sqlite3_file* pFile,
|
| + const char* zPath,
|
| + int noLock,
|
| + int flags);
|
| +#endif /* _WIN32 */
|
| +#endif /* CHROMIUM_SQLITE_INTERNALS */
|
| +/* End WebDatabase patch for Chromium */
|
| +
|
| +/*
|
| +** CAPI3REF: String LIKE Matching
|
| +*
|
| +** ^The [sqlite3_strlike(P,X,E)] interface returns zero if and only if
|
| +** string X matches the [LIKE] pattern P with escape character E.
|
| +** ^The definition of [LIKE] pattern matching used in
|
| +** [sqlite3_strlike(P,X,E)] is the same as for the "X LIKE P ESCAPE E"
|
| +** operator in the SQL dialect understood by SQLite. ^For "X LIKE P" without
|
| +** the ESCAPE clause, set the E parameter of [sqlite3_strlike(P,X,E)] to 0.
|
| +** ^As with the LIKE operator, the [sqlite3_strlike(P,X,E)] function is case
|
| +** insensitive - equivalent upper and lower case ASCII characters match
|
| +** one another.
|
| +**
|
| +** ^The [sqlite3_strlike(P,X,E)] function matches Unicode characters, though
|
| +** only ASCII characters are case folded.
|
| +**
|
| +** Note that this routine returns zero on a match and non-zero if the strings
|
| +** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
|
| +**
|
| +** See also: [sqlite3_strglob()].
|
| +*/
|
| +int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc);
|
| +
|
| /*
|
| ** CAPI3REF: Error Logging Interface
|
| **
|
| @@ -7135,14 +7498,13 @@ void sqlite3_log(int iErrCode, const char *zFormat, ...);
|
|
|
| /*
|
| ** CAPI3REF: Write-Ahead Log Commit Hook
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The [sqlite3_wal_hook()] function is used to register a callback that
|
| -** will be invoked each time a database connection commits data to a
|
| -** [write-ahead log] (i.e. whenever a transaction is committed in
|
| -** [journal_mode | journal_mode=WAL mode]).
|
| +** is invoked each time data is committed to a database in wal mode.
|
| **
|
| -** ^The callback is invoked by SQLite after the commit has taken place and
|
| -** the associated write-lock on the database released, so the implementation
|
| +** ^(The callback is invoked by SQLite after the commit has taken place and
|
| +** the associated write-lock on the database released)^, so the implementation
|
| ** may read, write or [checkpoint] the database as required.
|
| **
|
| ** ^The first parameter passed to the callback function when it is invoked
|
| @@ -7176,6 +7538,7 @@ void *sqlite3_wal_hook(
|
|
|
| /*
|
| ** CAPI3REF: Configure an auto-checkpoint
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
|
| ** [sqlite3_wal_hook()] that causes any database on [database connection] D
|
| @@ -7206,98 +7569,117 @@ int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
|
|
|
| /*
|
| ** CAPI3REF: Checkpoint a database
|
| +** METHOD: sqlite3
|
| **
|
| -** ^The [sqlite3_wal_checkpoint(D,X)] interface causes database named X
|
| -** on [database connection] D to be [checkpointed]. ^If X is NULL or an
|
| -** empty string, then a checkpoint is run on all databases of
|
| -** connection D. ^If the database connection D is not in
|
| -** [WAL | write-ahead log mode] then this interface is a harmless no-op.
|
| -** ^The [sqlite3_wal_checkpoint(D,X)] interface initiates a
|
| -** [sqlite3_wal_checkpoint_v2|PASSIVE] checkpoint.
|
| -** Use the [sqlite3_wal_checkpoint_v2()] interface to get a FULL
|
| -** or RESET checkpoint.
|
| +** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to
|
| +** [sqlite3_wal_checkpoint_v2](D,X,[SQLITE_CHECKPOINT_PASSIVE],0,0).)^
|
| **
|
| -** ^The [wal_checkpoint pragma] can be used to invoke this interface
|
| -** from SQL. ^The [sqlite3_wal_autocheckpoint()] interface and the
|
| -** [wal_autocheckpoint pragma] can be used to cause this interface to be
|
| -** run whenever the WAL reaches a certain size threshold.
|
| +** In brief, sqlite3_wal_checkpoint(D,X) causes the content in the
|
| +** [write-ahead log] for database X on [database connection] D to be
|
| +** transferred into the database file and for the write-ahead log to
|
| +** be reset. See the [checkpointing] documentation for addition
|
| +** information.
|
| **
|
| -** See also: [sqlite3_wal_checkpoint_v2()]
|
| +** This interface used to be the only way to cause a checkpoint to
|
| +** occur. But then the newer and more powerful [sqlite3_wal_checkpoint_v2()]
|
| +** interface was added. This interface is retained for backwards
|
| +** compatibility and as a convenience for applications that need to manually
|
| +** start a callback but which do not need the full power (and corresponding
|
| +** complication) of [sqlite3_wal_checkpoint_v2()].
|
| */
|
| int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
|
|
|
| /*
|
| ** CAPI3REF: Checkpoint a database
|
| +** METHOD: sqlite3
|
| **
|
| -** Run a checkpoint operation on WAL database zDb attached to database
|
| -** handle db. The specific operation is determined by the value of the
|
| -** eMode parameter:
|
| +** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint
|
| +** operation on database X of [database connection] D in mode M. Status
|
| +** information is written back into integers pointed to by L and C.)^
|
| +** ^(The M parameter must be a valid [checkpoint mode]:)^
|
| **
|
| ** <dl>
|
| ** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
|
| -** Checkpoint as many frames as possible without waiting for any database
|
| -** readers or writers to finish. Sync the db file if all frames in the log
|
| -** are checkpointed. This mode is the same as calling
|
| -** sqlite3_wal_checkpoint(). The [sqlite3_busy_handler|busy-handler callback]
|
| -** is never invoked.
|
| +** ^Checkpoint as many frames as possible without waiting for any database
|
| +** readers or writers to finish, then sync the database file if all frames
|
| +** in the log were checkpointed. ^The [busy-handler callback]
|
| +** is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.
|
| +** ^On the other hand, passive mode might leave the checkpoint unfinished
|
| +** if there are concurrent readers or writers.
|
| **
|
| ** <dt>SQLITE_CHECKPOINT_FULL<dd>
|
| -** This mode blocks (it invokes the
|
| +** ^This mode blocks (it invokes the
|
| ** [sqlite3_busy_handler|busy-handler callback]) until there is no
|
| ** database writer and all readers are reading from the most recent database
|
| -** snapshot. It then checkpoints all frames in the log file and syncs the
|
| -** database file. This call blocks database writers while it is running,
|
| -** but not database readers.
|
| +** snapshot. ^It then checkpoints all frames in the log file and syncs the
|
| +** database file. ^This mode blocks new database writers while it is pending,
|
| +** but new database readers are allowed to continue unimpeded.
|
| **
|
| ** <dt>SQLITE_CHECKPOINT_RESTART<dd>
|
| -** This mode works the same way as SQLITE_CHECKPOINT_FULL, except after
|
| -** checkpointing the log file it blocks (calls the
|
| -** [sqlite3_busy_handler|busy-handler callback])
|
| -** until all readers are reading from the database file only. This ensures
|
| -** that the next client to write to the database file restarts the log file
|
| -** from the beginning. This call blocks database writers while it is running,
|
| -** but not database readers.
|
| +** ^This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition
|
| +** that after checkpointing the log file it blocks (calls the
|
| +** [busy-handler callback])
|
| +** until all readers are reading from the database file only. ^This ensures
|
| +** that the next writer will restart the log file from the beginning.
|
| +** ^Like SQLITE_CHECKPOINT_FULL, this mode blocks new
|
| +** database writer attempts while it is pending, but does not impede readers.
|
| +**
|
| +** <dt>SQLITE_CHECKPOINT_TRUNCATE<dd>
|
| +** ^This mode works the same way as SQLITE_CHECKPOINT_RESTART with the
|
| +** addition that it also truncates the log file to zero bytes just prior
|
| +** to a successful return.
|
| ** </dl>
|
| **
|
| -** If pnLog is not NULL, then *pnLog is set to the total number of frames in
|
| -** the log file before returning. If pnCkpt is not NULL, then *pnCkpt is set to
|
| -** the total number of checkpointed frames (including any that were already
|
| -** checkpointed when this function is called). *pnLog and *pnCkpt may be
|
| -** populated even if sqlite3_wal_checkpoint_v2() returns other than SQLITE_OK.
|
| -** If no values are available because of an error, they are both set to -1
|
| -** before returning to communicate this to the caller.
|
| -**
|
| -** All calls obtain an exclusive "checkpoint" lock on the database file. If
|
| +** ^If pnLog is not NULL, then *pnLog is set to the total number of frames in
|
| +** the log file or to -1 if the checkpoint could not run because
|
| +** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not
|
| +** NULL,then *pnCkpt is set to the total number of checkpointed frames in the
|
| +** log file (including any that were already checkpointed before the function
|
| +** was called) or to -1 if the checkpoint could not run due to an error or
|
| +** because the database is not in WAL mode. ^Note that upon successful
|
| +** completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been
|
| +** truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.
|
| +**
|
| +** ^All calls obtain an exclusive "checkpoint" lock on the database file. ^If
|
| ** any other process is running a checkpoint operation at the same time, the
|
| -** lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a
|
| +** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a
|
| ** busy-handler configured, it will not be invoked in this case.
|
| **
|
| -** The SQLITE_CHECKPOINT_FULL and RESTART modes also obtain the exclusive
|
| -** "writer" lock on the database file. If the writer lock cannot be obtained
|
| -** immediately, and a busy-handler is configured, it is invoked and the writer
|
| -** lock retried until either the busy-handler returns 0 or the lock is
|
| -** successfully obtained. The busy-handler is also invoked while waiting for
|
| -** database readers as described above. If the busy-handler returns 0 before
|
| +** ^The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the
|
| +** exclusive "writer" lock on the database file. ^If the writer lock cannot be
|
| +** obtained immediately, and a busy-handler is configured, it is invoked and
|
| +** the writer lock retried until either the busy-handler returns 0 or the lock
|
| +** is successfully obtained. ^The busy-handler is also invoked while waiting for
|
| +** database readers as described above. ^If the busy-handler returns 0 before
|
| ** the writer lock is obtained or while waiting for database readers, the
|
| ** checkpoint operation proceeds from that point in the same way as
|
| ** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
|
| -** without blocking any further. SQLITE_BUSY is returned in this case.
|
| +** without blocking any further. ^SQLITE_BUSY is returned in this case.
|
| **
|
| -** If parameter zDb is NULL or points to a zero length string, then the
|
| -** specified operation is attempted on all WAL databases. In this case the
|
| -** values written to output parameters *pnLog and *pnCkpt are undefined. If
|
| +** ^If parameter zDb is NULL or points to a zero length string, then the
|
| +** specified operation is attempted on all WAL databases [attached] to
|
| +** [database connection] db. In this case the
|
| +** values written to output parameters *pnLog and *pnCkpt are undefined. ^If
|
| ** an SQLITE_BUSY error is encountered when processing one or more of the
|
| ** attached WAL databases, the operation is still attempted on any remaining
|
| -** attached databases and SQLITE_BUSY is returned to the caller. If any other
|
| +** attached databases and SQLITE_BUSY is returned at the end. ^If any other
|
| ** error occurs while processing an attached database, processing is abandoned
|
| -** and the error code returned to the caller immediately. If no error
|
| +** and the error code is returned to the caller immediately. ^If no error
|
| ** (SQLITE_BUSY or otherwise) is encountered while processing the attached
|
| ** databases, SQLITE_OK is returned.
|
| **
|
| -** If database zDb is the name of an attached database that is not in WAL
|
| -** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If
|
| +** ^If database zDb is the name of an attached database that is not in WAL
|
| +** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If
|
| ** zDb is not NULL (or a zero length string) and is not the name of any
|
| ** attached database, SQLITE_ERROR is returned to the caller.
|
| +**
|
| +** ^Unless it returns SQLITE_MISUSE,
|
| +** the sqlite3_wal_checkpoint_v2() interface
|
| +** sets the error information that is queried by
|
| +** [sqlite3_errcode()] and [sqlite3_errmsg()].
|
| +**
|
| +** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface
|
| +** from SQL.
|
| */
|
| int sqlite3_wal_checkpoint_v2(
|
| sqlite3 *db, /* Database handle */
|
| @@ -7308,16 +7690,18 @@ int sqlite3_wal_checkpoint_v2(
|
| );
|
|
|
| /*
|
| -** CAPI3REF: Checkpoint operation parameters
|
| +** CAPI3REF: Checkpoint Mode Values
|
| +** KEYWORDS: {checkpoint mode}
|
| **
|
| -** These constants can be used as the 3rd parameter to
|
| -** [sqlite3_wal_checkpoint_v2()]. See the [sqlite3_wal_checkpoint_v2()]
|
| -** documentation for additional information about the meaning and use of
|
| -** each of these values.
|
| +** These constants define all valid values for the "checkpoint mode" passed
|
| +** as the third parameter to the [sqlite3_wal_checkpoint_v2()] interface.
|
| +** See the [sqlite3_wal_checkpoint_v2()] documentation for details on the
|
| +** meaning of each of these checkpoint modes.
|
| */
|
| -#define SQLITE_CHECKPOINT_PASSIVE 0
|
| -#define SQLITE_CHECKPOINT_FULL 1
|
| -#define SQLITE_CHECKPOINT_RESTART 2
|
| +#define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */
|
| +#define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */
|
| +#define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for for readers */
|
| +#define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */
|
|
|
| /*
|
| ** CAPI3REF: Virtual Table Interface Configuration
|
| @@ -7406,46 +7790,232 @@ int sqlite3_vtab_on_conflict(sqlite3 *);
|
| /* #define SQLITE_ABORT 4 // Also an error code */
|
| #define SQLITE_REPLACE 5
|
|
|
| +/*
|
| +** CAPI3REF: Prepared Statement Scan Status Opcodes
|
| +** KEYWORDS: {scanstatus options}
|
| +**
|
| +** The following constants can be used for the T parameter to the
|
| +** [sqlite3_stmt_scanstatus(S,X,T,V)] interface. Each constant designates a
|
| +** different metric for sqlite3_stmt_scanstatus() to return.
|
| +**
|
| +** When the value returned to V is a string, space to hold that string is
|
| +** managed by the prepared statement S and will be automatically freed when
|
| +** S is finalized.
|
| +**
|
| +** <dl>
|
| +** [[SQLITE_SCANSTAT_NLOOP]] <dt>SQLITE_SCANSTAT_NLOOP</dt>
|
| +** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be
|
| +** set to the total number of times that the X-th loop has run.</dd>
|
| +**
|
| +** [[SQLITE_SCANSTAT_NVISIT]] <dt>SQLITE_SCANSTAT_NVISIT</dt>
|
| +** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set
|
| +** to the total number of rows examined by all iterations of the X-th loop.</dd>
|
| +**
|
| +** [[SQLITE_SCANSTAT_EST]] <dt>SQLITE_SCANSTAT_EST</dt>
|
| +** <dd>^The "double" variable pointed to by the T parameter will be set to the
|
| +** query planner's estimate for the average number of rows output from each
|
| +** iteration of the X-th loop. If the query planner's estimates was accurate,
|
| +** then this value will approximate the quotient NVISIT/NLOOP and the
|
| +** product of this value for all prior loops with the same SELECTID will
|
| +** be the NLOOP value for the current loop.
|
| +**
|
| +** [[SQLITE_SCANSTAT_NAME]] <dt>SQLITE_SCANSTAT_NAME</dt>
|
| +** <dd>^The "const char *" variable pointed to by the T parameter will be set
|
| +** to a zero-terminated UTF-8 string containing the name of the index or table
|
| +** used for the X-th loop.
|
| +**
|
| +** [[SQLITE_SCANSTAT_EXPLAIN]] <dt>SQLITE_SCANSTAT_EXPLAIN</dt>
|
| +** <dd>^The "const char *" variable pointed to by the T parameter will be set
|
| +** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN]
|
| +** description for the X-th loop.
|
| +**
|
| +** [[SQLITE_SCANSTAT_SELECTID]] <dt>SQLITE_SCANSTAT_SELECT</dt>
|
| +** <dd>^The "int" variable pointed to by the T parameter will be set to the
|
| +** "select-id" for the X-th loop. The select-id identifies which query or
|
| +** subquery the loop is part of. The main query has a select-id of zero.
|
| +** The select-id is the same value as is output in the first column
|
| +** of an [EXPLAIN QUERY PLAN] query.
|
| +** </dl>
|
| +*/
|
| +#define SQLITE_SCANSTAT_NLOOP 0
|
| +#define SQLITE_SCANSTAT_NVISIT 1
|
| +#define SQLITE_SCANSTAT_EST 2
|
| +#define SQLITE_SCANSTAT_NAME 3
|
| +#define SQLITE_SCANSTAT_EXPLAIN 4
|
| +#define SQLITE_SCANSTAT_SELECTID 5
|
|
|
| +/*
|
| +** CAPI3REF: Prepared Statement Scan Status
|
| +** METHOD: sqlite3_stmt
|
| +**
|
| +** This interface returns information about the predicted and measured
|
| +** performance for pStmt. Advanced applications can use this
|
| +** interface to compare the predicted and the measured performance and
|
| +** issue warnings and/or rerun [ANALYZE] if discrepancies are found.
|
| +**
|
| +** Since this interface is expected to be rarely used, it is only
|
| +** available if SQLite is compiled using the [SQLITE_ENABLE_STMT_SCANSTATUS]
|
| +** compile-time option.
|
| +**
|
| +** The "iScanStatusOp" parameter determines which status information to return.
|
| +** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior
|
| +** of this interface is undefined.
|
| +** ^The requested measurement is written into a variable pointed to by
|
| +** the "pOut" parameter.
|
| +** Parameter "idx" identifies the specific loop to retrieve statistics for.
|
| +** Loops are numbered starting from zero. ^If idx is out of range - less than
|
| +** zero or greater than or equal to the total number of loops used to implement
|
| +** the statement - a non-zero value is returned and the variable that pOut
|
| +** points to is unchanged.
|
| +**
|
| +** ^Statistics might not be available for all loops in all statements. ^In cases
|
| +** where there exist loops with no available statistics, this function behaves
|
| +** as if the loop did not exist - it returns non-zero and leave the variable
|
| +** that pOut points to unchanged.
|
| +**
|
| +** See also: [sqlite3_stmt_scanstatus_reset()]
|
| +*/
|
| +int sqlite3_stmt_scanstatus(
|
| + sqlite3_stmt *pStmt, /* Prepared statement for which info desired */
|
| + int idx, /* Index of loop to report on */
|
| + int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */
|
| + void *pOut /* Result written here */
|
| +);
|
|
|
| -/* Begin recover virtual table patch for Chromium */
|
| -/* Our patches don't conform to SQLite's amalgamation processing. Hack it. */
|
| -#ifndef CHROMIUM_SQLITE_API
|
| -#define CHROMIUM_SQLITE_API SQLITE_API
|
| -#endif
|
| /*
|
| -** Call to initialize the recover virtual-table modules (see recover.c).
|
| +** CAPI3REF: Zero Scan-Status Counters
|
| +** METHOD: sqlite3_stmt
|
| **
|
| -** This could be loaded by default in main.c, but that would make the
|
| -** virtual table available to Web SQL. Breaking it out allows only
|
| -** selected users to enable it (currently sql/recovery.cc).
|
| +** ^Zero all [sqlite3_stmt_scanstatus()] related event counters.
|
| +**
|
| +** This API is only available if the library is built with pre-processor
|
| +** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined.
|
| */
|
| -CHROMIUM_SQLITE_API
|
| -int recoverVtableInit(sqlite3 *db);
|
| -/* End recover virtual table patch for Chromium */
|
| +void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);
|
|
|
| -/* Begin WebDatabase patch for Chromium */
|
| -/* Expose some SQLite internals for the WebDatabase vfs.
|
| -** DO NOT EXTEND THE USE OF THIS.
|
| +/*
|
| +** CAPI3REF: Flush caches to disk mid-transaction
|
| +**
|
| +** ^If a write-transaction is open on [database connection] D when the
|
| +** [sqlite3_db_cacheflush(D)] interface invoked, any dirty
|
| +** pages in the pager-cache that are not currently in use are written out
|
| +** to disk. A dirty page may be in use if a database cursor created by an
|
| +** active SQL statement is reading from it, or if it is page 1 of a database
|
| +** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)]
|
| +** interface flushes caches for all schemas - "main", "temp", and
|
| +** any [attached] databases.
|
| +**
|
| +** ^If this function needs to obtain extra database locks before dirty pages
|
| +** can be flushed to disk, it does so. ^If those locks cannot be obtained
|
| +** immediately and there is a busy-handler callback configured, it is invoked
|
| +** in the usual manner. ^If the required lock still cannot be obtained, then
|
| +** the database is skipped and an attempt made to flush any dirty pages
|
| +** belonging to the next (if any) database. ^If any databases are skipped
|
| +** because locks cannot be obtained, but no other error occurs, this
|
| +** function returns SQLITE_BUSY.
|
| +**
|
| +** ^If any other error occurs while flushing dirty pages to disk (for
|
| +** example an IO error or out-of-memory condition), then processing is
|
| +** abandoned and an SQLite [error code] is returned to the caller immediately.
|
| +**
|
| +** ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK.
|
| +**
|
| +** ^This function does not set the database handle error code or message
|
| +** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions.
|
| */
|
| -#ifndef CHROMIUM_SQLITE_API
|
| -#define CHROMIUM_SQLITE_API SQLITE_API
|
| -#endif
|
| -#if defined(CHROMIUM_SQLITE_INTERNALS)
|
| -#ifdef _WIN32
|
| -CHROMIUM_SQLITE_API
|
| -void chromium_sqlite3_initialize_win_sqlite3_file(sqlite3_file* file, HANDLE handle);
|
| -#else /* _WIN32 */
|
| -CHROMIUM_SQLITE_API
|
| -int chromium_sqlite3_fill_in_unix_sqlite3_file(sqlite3_vfs* pVfs,
|
| - int fd,
|
| - sqlite3_file* pFile,
|
| - const char* zPath,
|
| - int noLock,
|
| - int flags);
|
| -#endif /* _WIN32 */
|
| -#endif /* CHROMIUM_SQLITE_INTERNALS */
|
| -/* End WebDatabase patch for Chromium */
|
| +int sqlite3_db_cacheflush(sqlite3*);
|
| +
|
| +/*
|
| +** CAPI3REF: Database Snapshot
|
| +** KEYWORDS: {snapshot}
|
| +** EXPERIMENTAL
|
| +**
|
| +** An instance of the snapshot object records the state of a [WAL mode]
|
| +** database for some specific point in history.
|
| +**
|
| +** In [WAL mode], multiple [database connections] that are open on the
|
| +** same database file can each be reading a different historical version
|
| +** of the database file. When a [database connection] begins a read
|
| +** transaction, that connection sees an unchanging copy of the database
|
| +** as it existed for the point in time when the transaction first started.
|
| +** Subsequent changes to the database from other connections are not seen
|
| +** by the reader until a new read transaction is started.
|
| +**
|
| +** The sqlite3_snapshot object records state information about an historical
|
| +** version of the database file so that it is possible to later open a new read
|
| +** transaction that sees that historical version of the database rather than
|
| +** the most recent version.
|
| +**
|
| +** The constructor for this object is [sqlite3_snapshot_get()]. The
|
| +** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer
|
| +** to an historical snapshot (if possible). The destructor for
|
| +** sqlite3_snapshot objects is [sqlite3_snapshot_free()].
|
| +*/
|
| +typedef struct sqlite3_snapshot sqlite3_snapshot;
|
| +
|
| +/*
|
| +** CAPI3REF: Record A Database Snapshot
|
| +** EXPERIMENTAL
|
| +**
|
| +** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a
|
| +** new [sqlite3_snapshot] object that records the current state of
|
| +** schema S in database connection D. ^On success, the
|
| +** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly
|
| +** created [sqlite3_snapshot] object into *P and returns SQLITE_OK.
|
| +** ^If schema S of [database connection] D is not a [WAL mode] database
|
| +** that is in a read transaction, then [sqlite3_snapshot_get(D,S,P)]
|
| +** leaves the *P value unchanged and returns an appropriate [error code].
|
| +**
|
| +** The [sqlite3_snapshot] object returned from a successful call to
|
| +** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()]
|
| +** to avoid a memory leak.
|
| +**
|
| +** The [sqlite3_snapshot_get()] interface is only available when the
|
| +** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
|
| +*/
|
| +SQLITE_EXPERIMENTAL int sqlite3_snapshot_get(
|
| + sqlite3 *db,
|
| + const char *zSchema,
|
| + sqlite3_snapshot **ppSnapshot
|
| +);
|
| +
|
| +/*
|
| +** CAPI3REF: Start a read transaction on an historical snapshot
|
| +** EXPERIMENTAL
|
| +**
|
| +** ^The [sqlite3_snapshot_open(D,S,P)] interface attempts to move the
|
| +** read transaction that is currently open on schema S of
|
| +** [database connection] D so that it refers to historical [snapshot] P.
|
| +** ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success
|
| +** or an appropriate [error code] if it fails.
|
| +**
|
| +** ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be
|
| +** the first operation, apart from other sqlite3_snapshot_open() calls,
|
| +** following the [BEGIN] that starts a new read transaction.
|
| +** ^A [snapshot] will fail to open if it has been overwritten by a
|
| +** [checkpoint].
|
| +**
|
| +** The [sqlite3_snapshot_open()] interface is only available when the
|
| +** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
|
| +*/
|
| +SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(
|
| + sqlite3 *db,
|
| + const char *zSchema,
|
| + sqlite3_snapshot *pSnapshot
|
| +);
|
| +
|
| +/*
|
| +** CAPI3REF: Destroy a snapshot
|
| +** EXPERIMENTAL
|
| +**
|
| +** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P.
|
| +** The application must eventually free every [sqlite3_snapshot] object
|
| +** using this routine to avoid a memory leak.
|
| +**
|
| +** The [sqlite3_snapshot_free()] interface is only available when the
|
| +** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
|
| +*/
|
| +SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*);
|
|
|
| /*
|
| ** Undo the hack that converts floating point types to integer for
|
|
|
Chromium Code Reviews
Issue 1610963002:
Import SQLite 3.10.2. (Closed)
Base URL: https://chromium.googlesource.com/chromium/src.git@master