|
|
@ -107,9 +107,9 @@ extern "C" { |
|
|
|
** [sqlite3_libversion_number()], [sqlite3_sourceid()], |
|
|
|
** [sqlite_version()] and [sqlite_source_id()]. |
|
|
|
*/ |
|
|
|
#define SQLITE_VERSION "3.8.2" |
|
|
|
#define SQLITE_VERSION_NUMBER 3008002 |
|
|
|
#define SQLITE_SOURCE_ID "2013-12-06 14:53:30 27392118af4c38c5203a04b8013e1afdb1cebd0d" |
|
|
|
#define SQLITE_VERSION "3.8.6" |
|
|
|
#define SQLITE_VERSION_NUMBER 3008006 |
|
|
|
#define SQLITE_SOURCE_ID "2014-08-15 11:46:33 9491ba7d738528f168657adb43a198238abde19e" |
|
|
|
|
|
|
|
/* |
|
|
|
** CAPI3REF: Run-Time Library Version Numbers |
|
|
@ -269,7 +269,7 @@ typedef sqlite_uint64 sqlite3_uint64; |
|
|
|
** |
|
|
|
** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors |
|
|
|
** for the [sqlite3] object. |
|
|
|
** ^Calls to sqlite3_close() and sqlite3_close_v2() return SQLITE_OK if |
|
|
|
** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if |
|
|
|
** the [sqlite3] object is successfully destroyed and all associated |
|
|
|
** resources are deallocated. |
|
|
|
** |
|
|
@ -277,7 +277,7 @@ typedef sqlite_uint64 sqlite3_uint64; |
|
|
|
** statements or unfinished sqlite3_backup objects then sqlite3_close() |
|
|
|
** will leave the database connection open and return [SQLITE_BUSY]. |
|
|
|
** ^If sqlite3_close_v2() is called with unfinalized prepared statements |
|
|
|
** and unfinished sqlite3_backups, then the database connection becomes |
|
|
|
** and/or unfinished sqlite3_backups, then the database connection becomes |
|
|
|
** an unusable "zombie" which will automatically be deallocated when the |
|
|
|
** last prepared statement is finalized or the last sqlite3_backup is |
|
|
|
** finished. The sqlite3_close_v2() interface is intended for use with |
|
|
@ -290,7 +290,7 @@ typedef sqlite_uint64 sqlite3_uint64; |
|
|
|
** with the [sqlite3] object prior to attempting to close the object. ^If |
|
|
|
** sqlite3_close_v2() is called on a [database connection] that still has |
|
|
|
** outstanding [prepared statements], [BLOB handles], and/or |
|
|
|
** [sqlite3_backup] objects then it returns SQLITE_OK but the deallocation |
|
|
|
** [sqlite3_backup] objects then it returns [SQLITE_OK] and the deallocation |
|
|
|
** of resources is deferred until all [prepared statements], [BLOB handles], |
|
|
|
** and [sqlite3_backup] objects are also destroyed. |
|
|
|
** |
|
|
@ -386,16 +386,14 @@ SQLITE_API int sqlite3_exec( |
|
|
|
|
|
|
|
/* |
|
|
|
** CAPI3REF: Result Codes |
|
|
|
** KEYWORDS: SQLITE_OK {error code} {error codes} |
|
|
|
** KEYWORDS: {result code} {result codes} |
|
|
|
** KEYWORDS: {result code definitions} |
|
|
|
** |
|
|
|
** Many SQLite functions return an integer result code from the set shown |
|
|
|
** here in order to indicate success or failure. |
|
|
|
** |
|
|
|
** New error codes may be added in future versions of SQLite. |
|
|
|
** |
|
|
|
** See also: [SQLITE_IOERR_READ | extended result codes], |
|
|
|
** [sqlite3_vtab_on_conflict()] [SQLITE_ROLLBACK | result codes]. |
|
|
|
** See also: [extended result code definitions] |
|
|
|
*/ |
|
|
|
#define SQLITE_OK 0 /* Successful result */ |
|
|
|
/* beginning-of-error-codes */ |
|
|
@ -433,26 +431,19 @@ SQLITE_API int sqlite3_exec( |
|
|
|
|
|
|
|
/* |
|
|
|
** CAPI3REF: Extended Result Codes |
|
|
|
** KEYWORDS: {extended error code} {extended error codes} |
|
|
|
** KEYWORDS: {extended result code} {extended result codes} |
|
|
|
** KEYWORDS: {extended result code definitions} |
|
|
|
** |
|
|
|
** In its default configuration, SQLite API routines return one of 26 integer |
|
|
|
** [SQLITE_OK | result codes]. However, experience has shown that many of |
|
|
|
** In its default configuration, SQLite API routines return one of 30 integer |
|
|
|
** [result codes]. However, experience has shown that many of |
|
|
|
** these result codes are too coarse-grained. They do not provide as |
|
|
|
** much information about problems as programmers might like. In an effort to |
|
|
|
** address this, newer versions of SQLite (version 3.3.8 and later) include |
|
|
|
** support for additional result codes that provide more detailed information |
|
|
|
** about errors. The extended result codes are enabled or disabled |
|
|
|
** about errors. These [extended result codes] are enabled or disabled |
|
|
|
** on a per database connection basis using the |
|
|
|
** [sqlite3_extended_result_codes()] API. |
|
|
|
** |
|
|
|
** Some of the available extended result codes are listed here. |
|
|
|
** One may expect the number of extended result codes will increase |
|
|
|
** over time. Software that uses extended result codes should expect |
|
|
|
** to see new result codes in future releases of SQLite. |
|
|
|
** |
|
|
|
** The SQLITE_OK result code will never be extended. It will always |
|
|
|
** be exactly zero. |
|
|
|
** [sqlite3_extended_result_codes()] API. Or, the extended code for |
|
|
|
** the most recent error can be obtained using |
|
|
|
** [sqlite3_extended_errcode()]. |
|
|
|
*/ |
|
|
|
#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) |
|
|
|
#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) |
|
|
@ -491,6 +482,7 @@ SQLITE_API int sqlite3_exec( |
|
|
|
#define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8)) |
|
|
|
#define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8)) |
|
|
|
#define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8)) |
|
|
|
#define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8)) |
|
|
|
#define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8)) |
|
|
|
#define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8)) |
|
|
|
#define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8)) |
|
|
@ -558,7 +550,11 @@ SQLITE_API int sqlite3_exec( |
|
|
|
** after reboot following a crash or power loss, the only bytes in a |
|
|
|
** file that were written at the application level might have changed |
|
|
|
** and that adjacent bytes, even bytes within the same sector are |
|
|
|
** guaranteed to be unchanged. |
|
|
|
** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN |
|
|
|
** flag indicate that a file cannot be deleted when open. The |
|
|
|
** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on |
|
|
|
** read-only media and cannot be changed even by processes with |
|
|
|
** elevated privileges. |
|
|
|
*/ |
|
|
|
#define SQLITE_IOCAP_ATOMIC 0x00000001 |
|
|
|
#define SQLITE_IOCAP_ATOMIC512 0x00000002 |
|
|
@ -573,6 +569,7 @@ SQLITE_API int sqlite3_exec( |
|
|
|
#define SQLITE_IOCAP_SEQUENTIAL 0x00000400 |
|
|
|
#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800 |
|
|
|
#define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000 |
|
|
|
#define SQLITE_IOCAP_IMMUTABLE 0x00002000 |
|
|
|
|
|
|
|
/* |
|
|
|
** CAPI3REF: File Locking Levels |
|
|
@ -679,7 +676,7 @@ struct sqlite3_file { |
|
|
|
** locking strategy (for example to use dot-file locks), to inquire |
|
|
|
** about the status of a lock, or to break stale locks. The SQLite |
|
|
|
** core reserves all opcodes less than 100 for its own use. |
|
|
|
** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. |
|
|
|
** A [file control opcodes | list of opcodes] less than 100 is available. |
|
|
|
** Applications that define a custom xFileControl method should use opcodes |
|
|
|
** greater than 100 to avoid conflicts. VFS implementations should |
|
|
|
** return [SQLITE_NOTFOUND] for file control opcodes that they do not |
|
|
@ -752,6 +749,7 @@ struct sqlite3_io_methods { |
|
|
|
|
|
|
|
/* |
|
|
|
** CAPI3REF: Standard File Control Opcodes |
|
|
|
** KEYWORDS: {file control opcodes} {file control opcode} |
|
|
|
** |
|
|
|
** These integer constants are opcodes for the xFileControl method |
|
|
|
** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()] |
|
|
@ -789,15 +787,29 @@ struct sqlite3_io_methods { |
|
|
|
** additional information. |
|
|
|
** |
|
|
|
** <li>[[SQLITE_FCNTL_SYNC_OMITTED]] |
|
|
|
** ^(The [SQLITE_FCNTL_SYNC_OMITTED] opcode is generated internally by |
|
|
|
** SQLite and sent to all VFSes in place of a call to the xSync method |
|
|
|
** when the database connection has [PRAGMA synchronous] set to OFF.)^ |
|
|
|
** Some specialized VFSes need this signal in order to operate correctly |
|
|
|
** when [PRAGMA synchronous | PRAGMA synchronous=OFF] is set, but most |
|
|
|
** VFSes do not need this signal and should silently ignore this opcode. |
|
|
|
** Applications should not call [sqlite3_file_control()] with this |
|
|
|
** opcode as doing so may disrupt the operation of the specialized VFSes |
|
|
|
** that do require it. |
|
|
|
** No longer in use. |
|
|
|
** |
|
|
|
** <li>[[SQLITE_FCNTL_SYNC]] |
|
|
|
** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and |
|
|
|
** sent to the VFS immediately before the xSync method is invoked on a |
|
|
|
** database file descriptor. Or, if the xSync method is not invoked |
|
|
|
** because the user has configured SQLite with |
|
|
|
** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place |
|
|
|
** of the xSync method. In most cases, the pointer argument passed with |
|
|
|
** this file-control is NULL. However, if the database file is being synced |
|
|
|
** as part of a multi-database commit, the argument points to a nul-terminated |
|
|
|
** string containing the transactions master-journal file name. VFSes that |
|
|
|
** do not need this signal should silently ignore this opcode. Applications |
|
|
|
** should not call [sqlite3_file_control()] with this opcode as doing so may |
|
|
|
** disrupt the operation of the specialized VFSes that do require it. |
|
|
|
** |
|
|
|
** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]] |
|
|
|
** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite |
|
|
|
** and sent to the VFS after a transaction has been committed immediately |
|
|
|
** but before the database is unlocked. VFSes that do not need this signal |
|
|
|
** should silently ignore this opcode. Applications should not call |
|
|
|
** [sqlite3_file_control()] with this opcode as doing so may disrupt the |
|
|
|
** operation of the specialized VFSes that do require it. |
|
|
|
** |
|
|
|
** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]] |
|
|
|
** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic |
|
|
@ -921,6 +933,18 @@ struct sqlite3_io_methods { |
|
|
|
** SQLite stack may generate instances of this file control if |
|
|
|
** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled. |
|
|
|
** |
|
|
|
** <li>[[SQLITE_FCNTL_HAS_MOVED]] |
|
|
|
** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a |
|
|
|
** pointer to an integer and it writes a boolean into that integer depending |
|
|
|
** on whether or not the file has been renamed, moved, or deleted since it |
|
|
|
** was first opened. |
|
|
|
** |
|
|
|
** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]] |
|
|
|
** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This |
|
|
|
** opcode causes the xFileControl method to swap the file handle with the one |
|
|
|
** pointed to by the pArg argument. This capability is used during testing |
|
|
|
** and only needs to be supported when SQLITE_TEST is defined. |
|
|
|
** |
|
|
|
** </ul> |
|
|
|
*/ |
|
|
|
#define SQLITE_FCNTL_LOCKSTATE 1 |
|
|
@ -941,6 +965,10 @@ struct sqlite3_io_methods { |
|
|
|
#define SQLITE_FCNTL_TEMPFILENAME 16 |
|
|
|
#define SQLITE_FCNTL_MMAP_SIZE 18 |
|
|
|
#define SQLITE_FCNTL_TRACE 19 |
|
|
|
#define SQLITE_FCNTL_HAS_MOVED 20 |
|
|
|
#define SQLITE_FCNTL_SYNC 21 |
|
|
|
#define SQLITE_FCNTL_COMMIT_PHASETWO 22 |
|
|
|
#define SQLITE_FCNTL_WIN32_SET_HANDLE 23 |
|
|
|
|
|
|
|
/* |
|
|
|
** CAPI3REF: Mutex Handle |
|
|
@ -2001,27 +2029,33 @@ SQLITE_API int sqlite3_complete16(const void *sql); |
|
|
|
/* |
|
|
|
** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors |
|
|
|
** |
|
|
|
** ^This routine sets a callback function that might be invoked whenever |
|
|
|
** an attempt is made to open a database table that another thread |
|
|
|
** or process has locked. |
|
|
|
** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X |
|
|
|
** that might be invoked with argument P whenever |
|
|
|
** an attempt is made to access a database table associated with |
|
|
|
** [database connection] D when another thread |
|
|
|
** or process has the table locked. |
|
|
|
** The sqlite3_busy_handler() interface is used to implement |
|
|
|
** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout]. |
|
|
|
** |
|
|
|
** ^If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] |
|
|
|
** ^If the busy callback is NULL, then [SQLITE_BUSY] |
|
|
|
** is returned immediately upon encountering the lock. ^If the busy callback |
|
|
|
** is not NULL, then the callback might be invoked with two arguments. |
|
|
|
** |
|
|
|
** ^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 this locking event. ^If the |
|
|
|
** been invoked for the same locking event. ^If the |
|
|
|
** busy callback returns 0, then no additional attempts are made to |
|
|
|
** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. |
|
|
|
** access the database and [SQLITE_BUSY] is returned |
|
|
|
** to the application. |
|
|
|
** ^If the callback returns non-zero, then another attempt |
|
|
|
** is made to open the database for reading and the cycle repeats. |
|
|
|
** is made to access the database and the cycle repeats. |
|
|
|
** |
|
|
|
** The presence of a busy handler does not guarantee that it will be invoked |
|
|
|
** when there is lock contention. ^If SQLite determines that invoking the busy |
|
|
|
** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY] |
|
|
|
** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler. |
|
|
|
** to the application instead of invoking the |
|
|
|
** busy handler. |
|
|
|
** Consider a scenario where one process is holding a read lock that |
|
|
|
** it is trying to promote to a reserved lock and |
|
|
|
** a second process is holding a reserved lock that it is trying |
|
|
@ -2035,28 +2069,15 @@ SQLITE_API int sqlite3_complete16(const void *sql); |
|
|
|
** |
|
|
|
** ^The default busy callback is NULL. |
|
|
|
** |
|
|
|
** ^The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] |
|
|
|
** when SQLite is in the middle of a large transaction where all the |
|
|
|
** changes will not fit into the in-memory cache. SQLite will |
|
|
|
** already hold a RESERVED lock on the database file, but it needs |
|
|
|
** to promote this lock to EXCLUSIVE so that it can spill cache |
|
|
|
** pages into the database file without harm to concurrent |
|
|
|
** readers. ^If it is unable to promote the lock, then the in-memory |
|
|
|
** cache will be left in an inconsistent state and so the error |
|
|
|
** code is promoted from the relatively benign [SQLITE_BUSY] to |
|
|
|
** the more severe [SQLITE_IOERR_BLOCKED]. ^This error code promotion |
|
|
|
** forces an automatic rollback of the changes. See the |
|
|
|
** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError"> |
|
|
|
** CorruptionFollowingBusyError</a> wiki page for a discussion of why |
|
|
|
** this is important. |
|
|
|
** |
|
|
|
** ^(There can only be a single busy handler defined for each |
|
|
|
** [database connection]. Setting a new busy handler clears any |
|
|
|
** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()] |
|
|
|
** will also set or clear the busy handler. |
|
|
|
** or evaluating [PRAGMA busy_timeout=N] will change the |
|
|
|
** busy handler and thus clear any previously set busy handler. |
|
|
|
** |
|
|
|
** The busy callback should not take any actions which modify the |
|
|
|
** database connection that invoked the busy handler. Any such actions |
|
|
|
** database connection that invoked the busy handler. In other words, |
|
|
|
** the busy handler is not reentrant. Any such actions |
|
|
|
** result in undefined behavior. |
|
|
|
** |
|
|
|
** A busy handler must not close the database connection |
|
|
@ -2072,7 +2093,7 @@ SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); |
|
|
|
** will sleep multiple times until at least "ms" milliseconds of sleeping |
|
|
|
** have accumulated. ^After at least "ms" milliseconds of sleeping, |
|
|
|
** the handler returns 0 which causes [sqlite3_step()] to return |
|
|
|
** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. |
|
|
|
** [SQLITE_BUSY]. |
|
|
|
** |
|
|
|
** ^Calling this routine with an argument less than or equal to zero |
|
|
|
** turns off all busy handlers. |
|
|
@ -2081,6 +2102,8 @@ SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); |
|
|
|
** [database connection] any any given moment. If another busy handler |
|
|
|
** was defined (using [sqlite3_busy_handler()]) prior to calling |
|
|
|
** this routine, that other busy handler is cleared.)^ |
|
|
|
** |
|
|
|
** See also: [PRAGMA busy_timeout] |
|
|
|
*/ |
|
|
|
SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); |
|
|
|
|
|
|
@ -2375,11 +2398,13 @@ SQLITE_API 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 first time this routine is invoked (either internally or by |
|
|
|
** the application) the PRNG is seeded using randomness obtained |
|
|
|
** from the xRandomness method of the default [sqlite3_vfs] object. |
|
|
|
** ^On all subsequent invocations, the pseudo-randomness is generated |
|
|
|
** ^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 |
|
|
|
** internally and without recourse to the [sqlite3_vfs] xRandomness |
|
|
|
** method. |
|
|
|
*/ |
|
|
@ -2480,8 +2505,8 @@ SQLITE_API int sqlite3_set_authorizer( |
|
|
|
** [sqlite3_set_authorizer | authorizer documentation] for additional |
|
|
|
** information. |
|
|
|
** |
|
|
|
** Note that SQLITE_IGNORE is also used as a [SQLITE_ROLLBACK | return code] |
|
|
|
** from the [sqlite3_vtab_on_conflict()] interface. |
|
|
|
** Note that SQLITE_IGNORE is also used as a [conflict resolution mode] |
|
|
|
** returned from the [sqlite3_vtab_on_conflict()] interface. |
|
|
|
*/ |
|
|
|
#define SQLITE_DENY 1 /* Abort the SQL statement with an error */ |
|
|
|
#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ |
|
|
@ -2539,6 +2564,7 @@ SQLITE_API int sqlite3_set_authorizer( |
|
|
|
#define SQLITE_FUNCTION 31 /* NULL Function Name */ |
|
|
|
#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ |
|
|
|
#define SQLITE_COPY 0 /* No longer used */ |
|
|
|
#define SQLITE_RECURSIVE 33 /* NULL NULL */ |
|
|
|
|
|
|
|
/* |
|
|
|
** CAPI3REF: Tracing And Profiling Functions |
|
|
@ -2751,6 +2777,30 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); |
|
|
|
** ^If sqlite3_open_v2() is used and the "cache" parameter is present in |
|
|
|
** a URI filename, its value overrides any behavior requested by setting |
|
|
|
** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag. |
|
|
|
** |
|
|
|
** <li> <b>psow</b>: ^The psow parameter may be "true" (or "on" or "yes" or |
|
|
|
** "1") or "false" (or "off" or "no" or "0") to indicate that the |
|
|
|
** [powersafe overwrite] property does or does not apply to the |
|
|
|
** storage media on which the database file resides. ^The psow query |
|
|
|
** parameter only works for the built-in unix and Windows VFSes. |
|
|
|
** |
|
|
|
** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter |
|
|
|
** which if set disables file locking in rollback journal modes. This |
|
|
|
** is useful for accessing a database on a filesystem that does not |
|
|
|
** support locking. Caution: Database corruption might result if two |
|
|
|
** or more processes write to the same database and any one of those |
|
|
|
** processes uses nolock=1. |
|
|
|
** |
|
|
|
** <li> <b>immutable</b>: ^The immutable parameter is a boolean query |
|
|
|
** parameter that indicates that the database file is stored on |
|
|
|
** read-only media. ^When immutable is set, SQLite assumes that the |
|
|
|
** database file cannot be changed, even by a process with higher |
|
|
|
** privilege, and so the database is opened read-only and all locking |
|
|
|
** and change detection is disabled. Caution: Setting the immutable |
|
|
|
** property on a database file that does in fact change can result |
|
|
|
** in incorrect query results and/or [SQLITE_CORRUPT] errors. |
|
|
|
** See also: [SQLITE_IOCAP_IMMUTABLE]. |
|
|
|
** |
|
|
|
** </ul> |
|
|
|
** |
|
|
|
** ^Specifying an unknown parameter in the query component of a URI is not an |
|
|
@ -2780,8 +2830,9 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); |
|
|
|
** Open file "data.db" in the current directory for read-only access. |
|
|
|
** Regardless of whether or not shared-cache mode is enabled by |
|
|
|
** default, use a private cache. |
|
|
|
** <tr><td> file:/home/fred/data.db?vfs=unix-nolock <td> |
|
|
|
** Open file "/home/fred/data.db". Use the special VFS "unix-nolock". |
|
|
|
** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td> |
|
|
|
** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile" |
|
|
|
** that uses dot-files in place of posix advisory locking. |
|
|
|
** <tr><td> file:data.db?mode=readonly <td> |
|
|
|
** An error. "readonly" is not a valid option for the "mode" parameter. |
|
|
|
** </table> |
|
|
@ -3957,15 +4008,24 @@ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt); |
|
|
|
** |
|
|
|
** ^The fourth parameter, eTextRep, specifies what |
|
|
|
** [SQLITE_UTF8 | text encoding] this SQL function prefers for |
|
|
|
** its parameters. Every SQL function implementation must be able to work |
|
|
|
** with UTF-8, UTF-16le, or UTF-16be. But some implementations may be |
|
|
|
** more efficient with one encoding than another. ^An application may |
|
|
|
** invoke sqlite3_create_function() or sqlite3_create_function16() multiple |
|
|
|
** times with the same function but with different values of eTextRep. |
|
|
|
** its parameters. The application should set this parameter to |
|
|
|
** [SQLITE_UTF16LE] if the function implementation invokes |
|
|
|
** [sqlite3_value_text16le()] on an input, or [SQLITE_UTF16BE] if the |
|
|
|
** implementation invokes [sqlite3_value_text16be()] on an input, or |
|
|
|
** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8] |
|
|
|
** otherwise. ^The same SQL function may be registered multiple times using |
|
|
|
** different preferred text encodings, with different implementations for |
|
|
|
** each encoding. |
|
|
|
** ^When multiple implementations of the same function are available, SQLite |
|
|
|
** will pick the one that involves the least amount of data conversion. |
|
|
|
** If there is only a single implementation which does not care what text |
|
|
|
** encoding is used, then the fourth argument should be [SQLITE_ANY]. |
|
|
|
** |
|
|
|
** ^The fourth parameter may optionally be ORed with [SQLITE_DETERMINISTIC] |
|
|
|
** to signal that the function will always return the same result given |
|
|
|
** the same inputs within a single SQL statement. Most SQL functions are |
|
|
|
** deterministic. The built-in [random()] SQL function is an example of a |
|
|
|
** function that is not deterministic. The SQLite query planner is able to |
|
|
|
** perform additional optimizations on deterministic functions, so use |
|
|
|
** of the [SQLITE_DETERMINISTIC] flag is recommended where possible. |
|
|
|
** |
|
|
|
** ^(The fifth parameter is an arbitrary pointer. The implementation of the |
|
|
|
** function can gain access to this pointer using [sqlite3_user_data()].)^ |
|
|
@ -4051,9 +4111,19 @@ SQLITE_API int sqlite3_create_function_v2( |
|
|
|
#define SQLITE_UTF16LE 2 |
|
|
|
#define SQLITE_UTF16BE 3 |
|
|
|
#define SQLITE_UTF16 4 /* Use native byte order */ |
|
|
|
#define SQLITE_ANY 5 /* sqlite3_create_function only */ |
|
|
|
#define SQLITE_ANY 5 /* Deprecated */ |
|
|
|
#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ |
|
|
|
|
|
|
|
/* |
|
|
|
** CAPI3REF: Function Flags |
|
|
|
** |
|
|
|
** These constants may be ORed together with the |
|
|
|
** [SQLITE_UTF8 | preferred text encoding] as the fourth argument |
|
|
|
** to [sqlite3_create_function()], [sqlite3_create_function16()], or |
|
|
|
** [sqlite3_create_function_v2()]. |
|
|
|
*/ |
|
|
|
#define SQLITE_DETERMINISTIC 0x800 |
|
|
|
|
|
|
|
/* |
|
|
|
** CAPI3REF: Deprecated Functions |
|
|
|
** DEPRECATED |
|
|
@ -4623,6 +4693,13 @@ SQLITE_API int sqlite3_sleep(int); |
|
|
|
** is a NULL pointer, then SQLite performs a search for an appropriate |
|
|
|
** temporary file directory. |
|
|
|
** |
|
|
|
** Applications are strongly discouraged from using this global variable. |
|
|
|
** It is required to set a temporary folder on Windows Runtime (WinRT). |
|
|
|
** But for all other platforms, it is highly recommended that applications |
|
|
|
** neither read nor write this variable. This global variable is a relic |
|
|
|
** that exists for backwards compatibility of legacy applications and should |
|
|
|
** be avoided in new projects. |
|
|
|
** |
|
|
|
** It is not safe to read or modify this variable in more than one |
|
|
|
** thread at a time. It is not safe to read or modify this variable |
|
|
|
** if a [database connection] is being used at the same time in a separate |
|
|
@ -4641,6 +4718,11 @@ SQLITE_API int sqlite3_sleep(int); |
|
|
|
** Hence, if this variable is modified directly, either it should be |
|
|
|
** made NULL or made to point to memory obtained from [sqlite3_malloc] |
|
|
|
** or else the use of the [temp_store_directory pragma] should be avoided. |
|
|
|
** Except when requested by the [temp_store_directory pragma], SQLite |
|
|
|
** does not free the memory that sqlite3_temp_directory points to. If |
|
|
|
** the application wants that memory to be freed, it must do |
|
|
|
** so itself, taking care to only do so after all [database connection] |
|
|
|
** objects have been destroyed. |
|
|
|
** |
|
|
|
** <b>Note to Windows Runtime users:</b> The temporary directory must be set |
|
|
|
** prior to calling [sqlite3_open] or [sqlite3_open_v2]. Otherwise, various |
|
|
@ -5775,10 +5857,12 @@ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*); |
|
|
|
** <li> SQLITE_MUTEX_RECURSIVE |
|
|
|
** <li> SQLITE_MUTEX_STATIC_MASTER |
|
|
|
** <li> SQLITE_MUTEX_STATIC_MEM |
|
|
|
** <li> SQLITE_MUTEX_STATIC_MEM2 |
|
|
|
** <li> SQLITE_MUTEX_STATIC_OPEN |
|
|
|
** <li> SQLITE_MUTEX_STATIC_PRNG |
|
|
|
** <li> SQLITE_MUTEX_STATIC_LRU |
|
|
|
** <li> SQLITE_MUTEX_STATIC_LRU2 |
|
|
|
** <li> SQLITE_MUTEX_STATIC_PMEM |
|
|
|
** <li> SQLITE_MUTEX_STATIC_APP1 |
|
|
|
** <li> SQLITE_MUTEX_STATIC_APP2 |
|
|
|
** </ul>)^ |
|
|
|
** |
|
|
|
** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) |
|
|
@ -5982,6 +6066,9 @@ SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*); |
|
|
|
#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ |
|
|
|
#define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */ |
|
|
|
#define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */ |
|
|
|
#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 */ |
|
|
|
|
|
|
|
/* |
|
|
|
** CAPI3REF: Retrieve the mutex for a database connection |
|
|
@ -6075,7 +6162,10 @@ SQLITE_API int sqlite3_test_control(int op, ...); |
|
|
|
#define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 |
|
|
|
#define SQLITE_TESTCTRL_EXPLAIN_STMT 19 |
|
|
|
#define SQLITE_TESTCTRL_NEVER_CORRUPT 20 |
|
|
|
#define SQLITE_TESTCTRL_LAST 20 |
|
|
|
#define SQLITE_TESTCTRL_VDBE_COVERAGE 21 |
|
|
|
#define SQLITE_TESTCTRL_BYTEORDER 22 |
|
|
|
#define SQLITE_TESTCTRL_ISINIT 23 |
|
|
|
#define SQLITE_TESTCTRL_LAST 23 |
|
|
|
|
|
|
|
/* |
|
|
|
** CAPI3REF: SQLite Runtime Status |
|
|
@ -7059,6 +7149,9 @@ SQLITE_API void *sqlite3_wal_hook( |
|
|
|
** ^The [wal_autocheckpoint pragma] can be used to invoke this interface |
|
|
|
** from SQL. |
|
|
|
** |
|
|
|
** ^Checkpoints initiated by this mechanism are |
|
|
|
** [sqlite3_wal_checkpoint_v2|PASSIVE]. |
|
|
|
** |
|
|
|
** ^Every new [database connection] defaults to having the auto-checkpoint |
|
|
|
** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT] |
|
|
|
** pages. The use of this interface |
|
|
@ -7075,6 +7168,10 @@ SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N); |
|
|
|
** 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 [wal_checkpoint pragma] can be used to invoke this interface |
|
|
|
** from SQL. ^The [sqlite3_wal_autocheckpoint()] interface and the |
|
|
@ -7097,10 +7194,12 @@ SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb); |
|
|
|
** 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 busy-handler callback is never invoked. |
|
|
|
** sqlite3_wal_checkpoint(). The [sqlite3_busy_handler|busy-handler callback] |
|
|
|
** is never invoked. |
|
|
|
** |
|
|
|
** <dt>SQLITE_CHECKPOINT_FULL<dd> |
|
|
|
** This mode blocks (calls the busy-handler callback) until there is no |
|
|
|
** 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, |
|
|
@ -7108,7 +7207,8 @@ SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb); |
|
|
|
** |
|
|
|
** <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 busy-handler callback) |
|
|
|
** 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, |
|
|
@ -7246,6 +7346,7 @@ SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *); |
|
|
|
|
|
|
|
/* |
|
|
|
** CAPI3REF: Conflict resolution modes |
|
|
|
** KEYWORDS: {conflict resolution mode} |
|
|
|
** |
|
|
|
** These constants are returned by [sqlite3_vtab_on_conflict()] to |
|
|
|
** inform a [virtual table] implementation what the [ON CONFLICT] mode |
|
|
@ -7298,6 +7399,16 @@ extern "C" { |
|
|
|
#endif |
|
|
|
|
|
|
|
typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry; |
|
|
|
typedef struct sqlite3_rtree_query_info sqlite3_rtree_query_info; |
|
|
|
|
|
|
|
/* The double-precision datatype used by RTree depends on the |
|
|
|
** SQLITE_RTREE_INT_ONLY compile-time option. |
|
|
|
*/ |
|
|
|
#ifdef SQLITE_RTREE_INT_ONLY |
|
|
|
typedef sqlite3_int64 sqlite3_rtree_dbl; |
|
|
|
#else |
|
|
|
typedef double sqlite3_rtree_dbl; |
|
|
|
#endif |
|
|
|
|
|
|
|
/* |
|
|
|
** Register a geometry callback named zGeom that can be used as part of an |
|
|
@ -7308,11 +7419,7 @@ typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry; |
|
|
|
SQLITE_API int sqlite3_rtree_geometry_callback( |
|
|
|
sqlite3 *db, |
|
|
|
const char *zGeom, |
|
|
|
#ifdef SQLITE_RTREE_INT_ONLY |
|
|
|
int (*xGeom)(sqlite3_rtree_geometry*, int n, sqlite3_int64 *a, int *pRes), |
|
|
|
#else |
|
|
|
int (*xGeom)(sqlite3_rtree_geometry*, int n, double *a, int *pRes), |
|
|
|
#endif |
|
|
|
int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*), |
|
|
|
void *pContext |
|
|
|
); |
|
|
|
|
|
|
@ -7324,11 +7431,60 @@ SQLITE_API int sqlite3_rtree_geometry_callback( |
|
|
|
struct sqlite3_rtree_geometry { |
|
|
|
void *pContext; /* Copy of pContext passed to s_r_g_c() */ |
|
|
|
int nParam; /* Size of array aParam[] */ |
|
|
|
double *aParam; /* Parameters passed to SQL geom function */ |
|
|
|
sqlite3_rtree_dbl *aParam; /* Parameters passed to SQL geom function */ |
|
|
|
void *pUser; /* Callback implementation user data */ |
|
|
|
void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */ |
|
|
|
}; |
|
|
|
|
|
|
|
/* |
|
|
|
** Register a 2nd-generation geometry callback named zScore that can be |
|
|
|
** used as part of an R-Tree geometry query as follows: |
|
|
|
** |
|
|
|
** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...) |
|
|
|
*/ |
|
|
|
SQLITE_API int sqlite3_rtree_query_callback( |
|
|
|
sqlite3 *db, |
|
|
|
const char *zQueryFunc, |
|
|
|
int (*xQueryFunc)(sqlite3_rtree_query_info*), |
|
|
|
void *pContext, |
|
|
|
void (*xDestructor)(void*) |
|
|
|
); |
|
|
|
|
|
|
|
|
|
|
|
/* |
|
|
|
** A pointer to a structure of the following type is passed as the |
|
|
|
** argument to scored geometry callback registered using |
|
|
|
** sqlite3_rtree_query_callback(). |
|
|
|
** |
|
|
|
** Note that the first 5 fields of this structure are identical to |
|
|
|
** sqlite3_rtree_geometry. This structure is a subclass of |
|
|
|
** sqlite3_rtree_geometry. |
|
|
|
*/ |
|
|
|
struct sqlite3_rtree_query_info { |
|
|
|
void *pContext; /* pContext from when function registered */ |
|
|
|
int nParam; /* Number of function parameters */ |
|
|
|
sqlite3_rtree_dbl *aParam; /* value of function parameters */ |
|
|
|
void *pUser; /* callback can use this, if desired */ |
|
|
|
void (*xDelUser)(void*); /* function to free pUser */ |
|
|
|
sqlite3_rtree_dbl *aCoord; /* Coordinates of node or entry to check */ |
|
|
|
unsigned int *anQueue; /* Number of pending entries in the queue */ |
|
|
|
int nCoord; /* Number of coordinates */ |
|
|
|
int iLevel; /* Level of current node or entry */ |
|
|
|
int mxLevel; /* The largest iLevel value in the tree */ |
|
|
|
sqlite3_int64 iRowid; /* Rowid for current entry */ |
|
|
|
sqlite3_rtree_dbl rParentScore; /* Score of parent node */ |
|
|
|
int eParentWithin; /* Visibility of parent node */ |
|
|
|
int eWithin; /* OUT: Visiblity */ |
|
|
|
sqlite3_rtree_dbl rScore; /* OUT: Write the score here */ |
|
|
|
}; |
|
|
|
|
|
|
|
/* |
|
|
|
** Allowed values for sqlite3_rtree_query.eWithin and .eParentWithin. |
|
|
|
*/ |
|
|
|
#define NOT_WITHIN 0 /* Object completely outside of query region */ |
|
|
|
#define PARTLY_WITHIN 1 /* Object partially overlaps query region */ |
|
|
|
#define FULLY_WITHIN 2 /* Object fully contained within query region */ |
|
|
|
|
|
|
|
|
|
|
|
#ifdef __cplusplus |
|
|
|
} /* end of the 'extern "C"' block */ |
|
|
|