1.1 --- a/src/sqlite3.h Mon Sep 01 17:50:28 2014 +0200
1.2 +++ b/src/sqlite3.h Mon Sep 01 18:36:42 2014 +0200
1.3 @@ -107,9 +107,9 @@
1.4 ** [sqlite3_libversion_number()], [sqlite3_sourceid()],
1.5 ** [sqlite_version()] and [sqlite_source_id()].
1.6 */
1.7 -#define SQLITE_VERSION "3.8.2"
1.8 -#define SQLITE_VERSION_NUMBER 3008002
1.9 -#define SQLITE_SOURCE_ID "2013-12-06 14:53:30 27392118af4c38c5203a04b8013e1afdb1cebd0d"
1.10 +#define SQLITE_VERSION "3.8.6"
1.11 +#define SQLITE_VERSION_NUMBER 3008006
1.12 +#define SQLITE_SOURCE_ID "2014-08-15 11:46:33 9491ba7d738528f168657adb43a198238abde19e"
1.13
1.14 /*
1.15 ** CAPI3REF: Run-Time Library Version Numbers
1.16 @@ -269,7 +269,7 @@
1.17 **
1.18 ** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
1.19 ** for the [sqlite3] object.
1.20 -** ^Calls to sqlite3_close() and sqlite3_close_v2() return SQLITE_OK if
1.21 +** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
1.22 ** the [sqlite3] object is successfully destroyed and all associated
1.23 ** resources are deallocated.
1.24 **
1.25 @@ -277,7 +277,7 @@
1.26 ** statements or unfinished sqlite3_backup objects then sqlite3_close()
1.27 ** will leave the database connection open and return [SQLITE_BUSY].
1.28 ** ^If sqlite3_close_v2() is called with unfinalized prepared statements
1.29 -** and unfinished sqlite3_backups, then the database connection becomes
1.30 +** and/or unfinished sqlite3_backups, then the database connection becomes
1.31 ** an unusable "zombie" which will automatically be deallocated when the
1.32 ** last prepared statement is finalized or the last sqlite3_backup is
1.33 ** finished. The sqlite3_close_v2() interface is intended for use with
1.34 @@ -290,7 +290,7 @@
1.35 ** with the [sqlite3] object prior to attempting to close the object. ^If
1.36 ** sqlite3_close_v2() is called on a [database connection] that still has
1.37 ** outstanding [prepared statements], [BLOB handles], and/or
1.38 -** [sqlite3_backup] objects then it returns SQLITE_OK but the deallocation
1.39 +** [sqlite3_backup] objects then it returns [SQLITE_OK] and the deallocation
1.40 ** of resources is deferred until all [prepared statements], [BLOB handles],
1.41 ** and [sqlite3_backup] objects are also destroyed.
1.42 **
1.43 @@ -386,16 +386,14 @@
1.44
1.45 /*
1.46 ** CAPI3REF: Result Codes
1.47 -** KEYWORDS: SQLITE_OK {error code} {error codes}
1.48 -** KEYWORDS: {result code} {result codes}
1.49 +** KEYWORDS: {result code definitions}
1.50 **
1.51 ** Many SQLite functions return an integer result code from the set shown
1.52 ** here in order to indicate success or failure.
1.53 **
1.54 ** New error codes may be added in future versions of SQLite.
1.55 **
1.56 -** See also: [SQLITE_IOERR_READ | extended result codes],
1.57 -** [sqlite3_vtab_on_conflict()] [SQLITE_ROLLBACK | result codes].
1.58 +** See also: [extended result code definitions]
1.59 */
1.60 #define SQLITE_OK 0 /* Successful result */
1.61 /* beginning-of-error-codes */
1.62 @@ -433,26 +431,19 @@
1.63
1.64 /*
1.65 ** CAPI3REF: Extended Result Codes
1.66 -** KEYWORDS: {extended error code} {extended error codes}
1.67 -** KEYWORDS: {extended result code} {extended result codes}
1.68 -**
1.69 -** In its default configuration, SQLite API routines return one of 26 integer
1.70 -** [SQLITE_OK | result codes]. However, experience has shown that many of
1.71 +** KEYWORDS: {extended result code definitions}
1.72 +**
1.73 +** In its default configuration, SQLite API routines return one of 30 integer
1.74 +** [result codes]. However, experience has shown that many of
1.75 ** these result codes are too coarse-grained. They do not provide as
1.76 ** much information about problems as programmers might like. In an effort to
1.77 ** address this, newer versions of SQLite (version 3.3.8 and later) include
1.78 ** support for additional result codes that provide more detailed information
1.79 -** about errors. The extended result codes are enabled or disabled
1.80 +** about errors. These [extended result codes] are enabled or disabled
1.81 ** on a per database connection basis using the
1.82 -** [sqlite3_extended_result_codes()] API.
1.83 -**
1.84 -** Some of the available extended result codes are listed here.
1.85 -** One may expect the number of extended result codes will increase
1.86 -** over time. Software that uses extended result codes should expect
1.87 -** to see new result codes in future releases of SQLite.
1.88 -**
1.89 -** The SQLITE_OK result code will never be extended. It will always
1.90 -** be exactly zero.
1.91 +** [sqlite3_extended_result_codes()] API. Or, the extended code for
1.92 +** the most recent error can be obtained using
1.93 +** [sqlite3_extended_errcode()].
1.94 */
1.95 #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
1.96 #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
1.97 @@ -491,6 +482,7 @@
1.98 #define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8))
1.99 #define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8))
1.100 #define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8))
1.101 +#define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8))
1.102 #define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8))
1.103 #define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8))
1.104 #define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8))
1.105 @@ -558,7 +550,11 @@
1.106 ** after reboot following a crash or power loss, the only bytes in a
1.107 ** file that were written at the application level might have changed
1.108 ** and that adjacent bytes, even bytes within the same sector are
1.109 -** guaranteed to be unchanged.
1.110 +** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
1.111 +** flag indicate that a file cannot be deleted when open. The
1.112 +** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
1.113 +** read-only media and cannot be changed even by processes with
1.114 +** elevated privileges.
1.115 */
1.116 #define SQLITE_IOCAP_ATOMIC 0x00000001
1.117 #define SQLITE_IOCAP_ATOMIC512 0x00000002
1.118 @@ -573,6 +569,7 @@
1.119 #define SQLITE_IOCAP_SEQUENTIAL 0x00000400
1.120 #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
1.121 #define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000
1.122 +#define SQLITE_IOCAP_IMMUTABLE 0x00002000
1.123
1.124 /*
1.125 ** CAPI3REF: File Locking Levels
1.126 @@ -679,7 +676,7 @@
1.127 ** locking strategy (for example to use dot-file locks), to inquire
1.128 ** about the status of a lock, or to break stale locks. The SQLite
1.129 ** core reserves all opcodes less than 100 for its own use.
1.130 -** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
1.131 +** A [file control opcodes | list of opcodes] less than 100 is available.
1.132 ** Applications that define a custom xFileControl method should use opcodes
1.133 ** greater than 100 to avoid conflicts. VFS implementations should
1.134 ** return [SQLITE_NOTFOUND] for file control opcodes that they do not
1.135 @@ -752,6 +749,7 @@
1.136
1.137 /*
1.138 ** CAPI3REF: Standard File Control Opcodes
1.139 +** KEYWORDS: {file control opcodes} {file control opcode}
1.140 **
1.141 ** These integer constants are opcodes for the xFileControl method
1.142 ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
1.143 @@ -789,15 +787,29 @@
1.144 ** additional information.
1.145 **
1.146 ** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
1.147 -** ^(The [SQLITE_FCNTL_SYNC_OMITTED] opcode is generated internally by
1.148 -** SQLite and sent to all VFSes in place of a call to the xSync method
1.149 -** when the database connection has [PRAGMA synchronous] set to OFF.)^
1.150 -** Some specialized VFSes need this signal in order to operate correctly
1.151 -** when [PRAGMA synchronous | PRAGMA synchronous=OFF] is set, but most
1.152 -** VFSes do not need this signal and should silently ignore this opcode.
1.153 -** Applications should not call [sqlite3_file_control()] with this
1.154 -** opcode as doing so may disrupt the operation of the specialized VFSes
1.155 -** that do require it.
1.156 +** No longer in use.
1.157 +**
1.158 +** <li>[[SQLITE_FCNTL_SYNC]]
1.159 +** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
1.160 +** sent to the VFS immediately before the xSync method is invoked on a
1.161 +** database file descriptor. Or, if the xSync method is not invoked
1.162 +** because the user has configured SQLite with
1.163 +** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place
1.164 +** of the xSync method. In most cases, the pointer argument passed with
1.165 +** this file-control is NULL. However, if the database file is being synced
1.166 +** as part of a multi-database commit, the argument points to a nul-terminated
1.167 +** string containing the transactions master-journal file name. VFSes that
1.168 +** do not need this signal should silently ignore this opcode. Applications
1.169 +** should not call [sqlite3_file_control()] with this opcode as doing so may
1.170 +** disrupt the operation of the specialized VFSes that do require it.
1.171 +**
1.172 +** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]
1.173 +** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
1.174 +** and sent to the VFS after a transaction has been committed immediately
1.175 +** but before the database is unlocked. VFSes that do not need this signal
1.176 +** should silently ignore this opcode. Applications should not call
1.177 +** [sqlite3_file_control()] with this opcode as doing so may disrupt the
1.178 +** operation of the specialized VFSes that do require it.
1.179 **
1.180 ** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
1.181 ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
1.182 @@ -921,6 +933,18 @@
1.183 ** SQLite stack may generate instances of this file control if
1.184 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
1.185 **
1.186 +** <li>[[SQLITE_FCNTL_HAS_MOVED]]
1.187 +** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
1.188 +** pointer to an integer and it writes a boolean into that integer depending
1.189 +** on whether or not the file has been renamed, moved, or deleted since it
1.190 +** was first opened.
1.191 +**
1.192 +** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
1.193 +** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This
1.194 +** opcode causes the xFileControl method to swap the file handle with the one
1.195 +** pointed to by the pArg argument. This capability is used during testing
1.196 +** and only needs to be supported when SQLITE_TEST is defined.
1.197 +**
1.198 ** </ul>
1.199 */
1.200 #define SQLITE_FCNTL_LOCKSTATE 1
1.201 @@ -941,6 +965,10 @@
1.202 #define SQLITE_FCNTL_TEMPFILENAME 16
1.203 #define SQLITE_FCNTL_MMAP_SIZE 18
1.204 #define SQLITE_FCNTL_TRACE 19
1.205 +#define SQLITE_FCNTL_HAS_MOVED 20
1.206 +#define SQLITE_FCNTL_SYNC 21
1.207 +#define SQLITE_FCNTL_COMMIT_PHASETWO 22
1.208 +#define SQLITE_FCNTL_WIN32_SET_HANDLE 23
1.209
1.210 /*
1.211 ** CAPI3REF: Mutex Handle
1.212 @@ -2001,27 +2029,33 @@
1.213 /*
1.214 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
1.215 **
1.216 -** ^This routine sets a callback function that might be invoked whenever
1.217 -** an attempt is made to open a database table that another thread
1.218 -** or process has locked.
1.219 -**
1.220 -** ^If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]
1.221 +** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
1.222 +** that might be invoked with argument P whenever
1.223 +** an attempt is made to access a database table associated with
1.224 +** [database connection] D when another thread
1.225 +** or process has the table locked.
1.226 +** The sqlite3_busy_handler() interface is used to implement
1.227 +** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
1.228 +**
1.229 +** ^If the busy callback is NULL, then [SQLITE_BUSY]
1.230 ** is returned immediately upon encountering the lock. ^If the busy callback
1.231 ** is not NULL, then the callback might be invoked with two arguments.
1.232 **
1.233 ** ^The first argument to the busy handler is a copy of the void* pointer which
1.234 ** is the third argument to sqlite3_busy_handler(). ^The second argument to
1.235 ** the busy handler callback is the number of times that the busy handler has
1.236 -** been invoked for this locking event. ^If the
1.237 +** been invoked for the same locking event. ^If the
1.238 ** busy callback returns 0, then no additional attempts are made to
1.239 -** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
1.240 +** access the database and [SQLITE_BUSY] is returned
1.241 +** to the application.
1.242 ** ^If the callback returns non-zero, then another attempt
1.243 -** is made to open the database for reading and the cycle repeats.
1.244 +** is made to access the database and the cycle repeats.
1.245 **
1.246 ** The presence of a busy handler does not guarantee that it will be invoked
1.247 ** when there is lock contention. ^If SQLite determines that invoking the busy
1.248 ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
1.249 -** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler.
1.250 +** to the application instead of invoking the
1.251 +** busy handler.
1.252 ** Consider a scenario where one process is holding a read lock that
1.253 ** it is trying to promote to a reserved lock and
1.254 ** a second process is holding a reserved lock that it is trying
1.255 @@ -2035,28 +2069,15 @@
1.256 **
1.257 ** ^The default busy callback is NULL.
1.258 **
1.259 -** ^The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
1.260 -** when SQLite is in the middle of a large transaction where all the
1.261 -** changes will not fit into the in-memory cache. SQLite will
1.262 -** already hold a RESERVED lock on the database file, but it needs
1.263 -** to promote this lock to EXCLUSIVE so that it can spill cache
1.264 -** pages into the database file without harm to concurrent
1.265 -** readers. ^If it is unable to promote the lock, then the in-memory
1.266 -** cache will be left in an inconsistent state and so the error
1.267 -** code is promoted from the relatively benign [SQLITE_BUSY] to
1.268 -** the more severe [SQLITE_IOERR_BLOCKED]. ^This error code promotion
1.269 -** forces an automatic rollback of the changes. See the
1.270 -** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">
1.271 -** CorruptionFollowingBusyError</a> wiki page for a discussion of why
1.272 -** this is important.
1.273 -**
1.274 ** ^(There can only be a single busy handler defined for each
1.275 ** [database connection]. Setting a new busy handler clears any
1.276 ** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
1.277 -** will also set or clear the busy handler.
1.278 +** or evaluating [PRAGMA busy_timeout=N] will change the
1.279 +** busy handler and thus clear any previously set busy handler.
1.280 **
1.281 ** The busy callback should not take any actions which modify the
1.282 -** database connection that invoked the busy handler. Any such actions
1.283 +** database connection that invoked the busy handler. In other words,
1.284 +** the busy handler is not reentrant. Any such actions
1.285 ** result in undefined behavior.
1.286 **
1.287 ** A busy handler must not close the database connection
1.288 @@ -2072,7 +2093,7 @@
1.289 ** will sleep multiple times until at least "ms" milliseconds of sleeping
1.290 ** have accumulated. ^After at least "ms" milliseconds of sleeping,
1.291 ** the handler returns 0 which causes [sqlite3_step()] to return
1.292 -** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
1.293 +** [SQLITE_BUSY].
1.294 **
1.295 ** ^Calling this routine with an argument less than or equal to zero
1.296 ** turns off all busy handlers.
1.297 @@ -2081,6 +2102,8 @@
1.298 ** [database connection] any any given moment. If another busy handler
1.299 ** was defined (using [sqlite3_busy_handler()]) prior to calling
1.300 ** this routine, that other busy handler is cleared.)^
1.301 +**
1.302 +** See also: [PRAGMA busy_timeout]
1.303 */
1.304 SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
1.305
1.306 @@ -2375,11 +2398,13 @@
1.307 ** applications to access the same PRNG for other purposes.
1.308 **
1.309 ** ^A call to this routine stores N bytes of randomness into buffer P.
1.310 -**
1.311 -** ^The first time this routine is invoked (either internally or by
1.312 -** the application) the PRNG is seeded using randomness obtained
1.313 -** from the xRandomness method of the default [sqlite3_vfs] object.
1.314 -** ^On all subsequent invocations, the pseudo-randomness is generated
1.315 +** ^If N is less than one, then P can be a NULL pointer.
1.316 +**
1.317 +** ^If this routine has not been previously called or if the previous
1.318 +** call had N less than one, then the PRNG is seeded using randomness
1.319 +** obtained from the xRandomness method of the default [sqlite3_vfs] object.
1.320 +** ^If the previous call to this routine had an N of 1 or more then
1.321 +** the pseudo-randomness is generated
1.322 ** internally and without recourse to the [sqlite3_vfs] xRandomness
1.323 ** method.
1.324 */
1.325 @@ -2480,8 +2505,8 @@
1.326 ** [sqlite3_set_authorizer | authorizer documentation] for additional
1.327 ** information.
1.328 **
1.329 -** Note that SQLITE_IGNORE is also used as a [SQLITE_ROLLBACK | return code]
1.330 -** from the [sqlite3_vtab_on_conflict()] interface.
1.331 +** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
1.332 +** returned from the [sqlite3_vtab_on_conflict()] interface.
1.333 */
1.334 #define SQLITE_DENY 1 /* Abort the SQL statement with an error */
1.335 #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
1.336 @@ -2539,6 +2564,7 @@
1.337 #define SQLITE_FUNCTION 31 /* NULL Function Name */
1.338 #define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
1.339 #define SQLITE_COPY 0 /* No longer used */
1.340 +#define SQLITE_RECURSIVE 33 /* NULL NULL */
1.341
1.342 /*
1.343 ** CAPI3REF: Tracing And Profiling Functions
1.344 @@ -2751,6 +2777,30 @@
1.345 ** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
1.346 ** a URI filename, its value overrides any behavior requested by setting
1.347 ** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
1.348 +**
1.349 +** <li> <b>psow</b>: ^The psow parameter may be "true" (or "on" or "yes" or
1.350 +** "1") or "false" (or "off" or "no" or "0") to indicate that the
1.351 +** [powersafe overwrite] property does or does not apply to the
1.352 +** storage media on which the database file resides. ^The psow query
1.353 +** parameter only works for the built-in unix and Windows VFSes.
1.354 +**
1.355 +** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
1.356 +** which if set disables file locking in rollback journal modes. This
1.357 +** is useful for accessing a database on a filesystem that does not
1.358 +** support locking. Caution: Database corruption might result if two
1.359 +** or more processes write to the same database and any one of those
1.360 +** processes uses nolock=1.
1.361 +**
1.362 +** <li> <b>immutable</b>: ^The immutable parameter is a boolean query
1.363 +** parameter that indicates that the database file is stored on
1.364 +** read-only media. ^When immutable is set, SQLite assumes that the
1.365 +** database file cannot be changed, even by a process with higher
1.366 +** privilege, and so the database is opened read-only and all locking
1.367 +** and change detection is disabled. Caution: Setting the immutable
1.368 +** property on a database file that does in fact change can result
1.369 +** in incorrect query results and/or [SQLITE_CORRUPT] errors.
1.370 +** See also: [SQLITE_IOCAP_IMMUTABLE].
1.371 +**
1.372 ** </ul>
1.373 **
1.374 ** ^Specifying an unknown parameter in the query component of a URI is not an
1.375 @@ -2780,8 +2830,9 @@
1.376 ** Open file "data.db" in the current directory for read-only access.
1.377 ** Regardless of whether or not shared-cache mode is enabled by
1.378 ** default, use a private cache.
1.379 -** <tr><td> file:/home/fred/data.db?vfs=unix-nolock <td>
1.380 -** Open file "/home/fred/data.db". Use the special VFS "unix-nolock".
1.381 +** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
1.382 +** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
1.383 +** that uses dot-files in place of posix advisory locking.
1.384 ** <tr><td> file:data.db?mode=readonly <td>
1.385 ** An error. "readonly" is not a valid option for the "mode" parameter.
1.386 ** </table>
1.387 @@ -3957,15 +4008,24 @@
1.388 **
1.389 ** ^The fourth parameter, eTextRep, specifies what
1.390 ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
1.391 -** its parameters. Every SQL function implementation must be able to work
1.392 -** with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
1.393 -** more efficient with one encoding than another. ^An application may
1.394 -** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
1.395 -** times with the same function but with different values of eTextRep.
1.396 +** its parameters. The application should set this parameter to
1.397 +** [SQLITE_UTF16LE] if the function implementation invokes
1.398 +** [sqlite3_value_text16le()] on an input, or [SQLITE_UTF16BE] if the
1.399 +** implementation invokes [sqlite3_value_text16be()] on an input, or
1.400 +** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8]
1.401 +** otherwise. ^The same SQL function may be registered multiple times using
1.402 +** different preferred text encodings, with different implementations for
1.403 +** each encoding.
1.404 ** ^When multiple implementations of the same function are available, SQLite
1.405 ** will pick the one that involves the least amount of data conversion.
1.406 -** If there is only a single implementation which does not care what text
1.407 -** encoding is used, then the fourth argument should be [SQLITE_ANY].
1.408 +**
1.409 +** ^The fourth parameter may optionally be ORed with [SQLITE_DETERMINISTIC]
1.410 +** to signal that the function will always return the same result given
1.411 +** the same inputs within a single SQL statement. Most SQL functions are
1.412 +** deterministic. The built-in [random()] SQL function is an example of a
1.413 +** function that is not deterministic. The SQLite query planner is able to
1.414 +** perform additional optimizations on deterministic functions, so use
1.415 +** of the [SQLITE_DETERMINISTIC] flag is recommended where possible.
1.416 **
1.417 ** ^(The fifth parameter is an arbitrary pointer. The implementation of the
1.418 ** function can gain access to this pointer using [sqlite3_user_data()].)^
1.419 @@ -4051,10 +4111,20 @@
1.420 #define SQLITE_UTF16LE 2
1.421 #define SQLITE_UTF16BE 3
1.422 #define SQLITE_UTF16 4 /* Use native byte order */
1.423 -#define SQLITE_ANY 5 /* sqlite3_create_function only */
1.424 +#define SQLITE_ANY 5 /* Deprecated */
1.425 #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
1.426
1.427 /*
1.428 +** CAPI3REF: Function Flags
1.429 +**
1.430 +** These constants may be ORed together with the
1.431 +** [SQLITE_UTF8 | preferred text encoding] as the fourth argument
1.432 +** to [sqlite3_create_function()], [sqlite3_create_function16()], or
1.433 +** [sqlite3_create_function_v2()].
1.434 +*/
1.435 +#define SQLITE_DETERMINISTIC 0x800
1.436 +
1.437 +/*
1.438 ** CAPI3REF: Deprecated Functions
1.439 ** DEPRECATED
1.440 **
1.441 @@ -4623,6 +4693,13 @@
1.442 ** is a NULL pointer, then SQLite performs a search for an appropriate
1.443 ** temporary file directory.
1.444 **
1.445 +** Applications are strongly discouraged from using this global variable.
1.446 +** It is required to set a temporary folder on Windows Runtime (WinRT).
1.447 +** But for all other platforms, it is highly recommended that applications
1.448 +** neither read nor write this variable. This global variable is a relic
1.449 +** that exists for backwards compatibility of legacy applications and should
1.450 +** be avoided in new projects.
1.451 +**
1.452 ** It is not safe to read or modify this variable in more than one
1.453 ** thread at a time. It is not safe to read or modify this variable
1.454 ** if a [database connection] is being used at the same time in a separate
1.455 @@ -4641,6 +4718,11 @@
1.456 ** Hence, if this variable is modified directly, either it should be
1.457 ** made NULL or made to point to memory obtained from [sqlite3_malloc]
1.458 ** or else the use of the [temp_store_directory pragma] should be avoided.
1.459 +** Except when requested by the [temp_store_directory pragma], SQLite
1.460 +** does not free the memory that sqlite3_temp_directory points to. If
1.461 +** the application wants that memory to be freed, it must do
1.462 +** so itself, taking care to only do so after all [database connection]
1.463 +** objects have been destroyed.
1.464 **
1.465 ** <b>Note to Windows Runtime users:</b> The temporary directory must be set
1.466 ** prior to calling [sqlite3_open] or [sqlite3_open_v2]. Otherwise, various
1.467 @@ -5775,10 +5857,12 @@
1.468 ** <li> SQLITE_MUTEX_RECURSIVE
1.469 ** <li> SQLITE_MUTEX_STATIC_MASTER
1.470 ** <li> SQLITE_MUTEX_STATIC_MEM
1.471 -** <li> SQLITE_MUTEX_STATIC_MEM2
1.472 +** <li> SQLITE_MUTEX_STATIC_OPEN
1.473 ** <li> SQLITE_MUTEX_STATIC_PRNG
1.474 ** <li> SQLITE_MUTEX_STATIC_LRU
1.475 -** <li> SQLITE_MUTEX_STATIC_LRU2
1.476 +** <li> SQLITE_MUTEX_STATIC_PMEM
1.477 +** <li> SQLITE_MUTEX_STATIC_APP1
1.478 +** <li> SQLITE_MUTEX_STATIC_APP2
1.479 ** </ul>)^
1.480 **
1.481 ** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
1.482 @@ -5982,6 +6066,9 @@
1.483 #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
1.484 #define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */
1.485 #define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */
1.486 +#define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */
1.487 +#define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */
1.488 +#define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */
1.489
1.490 /*
1.491 ** CAPI3REF: Retrieve the mutex for a database connection
1.492 @@ -6075,7 +6162,10 @@
1.493 #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18
1.494 #define SQLITE_TESTCTRL_EXPLAIN_STMT 19
1.495 #define SQLITE_TESTCTRL_NEVER_CORRUPT 20
1.496 -#define SQLITE_TESTCTRL_LAST 20
1.497 +#define SQLITE_TESTCTRL_VDBE_COVERAGE 21
1.498 +#define SQLITE_TESTCTRL_BYTEORDER 22
1.499 +#define SQLITE_TESTCTRL_ISINIT 23
1.500 +#define SQLITE_TESTCTRL_LAST 23
1.501
1.502 /*
1.503 ** CAPI3REF: SQLite Runtime Status
1.504 @@ -7059,6 +7149,9 @@
1.505 ** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
1.506 ** from SQL.
1.507 **
1.508 +** ^Checkpoints initiated by this mechanism are
1.509 +** [sqlite3_wal_checkpoint_v2|PASSIVE].
1.510 +**
1.511 ** ^Every new [database connection] defaults to having the auto-checkpoint
1.512 ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]
1.513 ** pages. The use of this interface
1.514 @@ -7075,6 +7168,10 @@
1.515 ** empty string, then a checkpoint is run on all databases of
1.516 ** connection D. ^If the database connection D is not in
1.517 ** [WAL | write-ahead log mode] then this interface is a harmless no-op.
1.518 +** ^The [sqlite3_wal_checkpoint(D,X)] interface initiates a
1.519 +** [sqlite3_wal_checkpoint_v2|PASSIVE] checkpoint.
1.520 +** Use the [sqlite3_wal_checkpoint_v2()] interface to get a FULL
1.521 +** or RESET checkpoint.
1.522 **
1.523 ** ^The [wal_checkpoint pragma] can be used to invoke this interface
1.524 ** from SQL. ^The [sqlite3_wal_autocheckpoint()] interface and the
1.525 @@ -7097,10 +7194,12 @@
1.526 ** Checkpoint as many frames as possible without waiting for any database
1.527 ** readers or writers to finish. Sync the db file if all frames in the log
1.528 ** are checkpointed. This mode is the same as calling
1.529 -** sqlite3_wal_checkpoint(). The busy-handler callback is never invoked.
1.530 +** sqlite3_wal_checkpoint(). The [sqlite3_busy_handler|busy-handler callback]
1.531 +** is never invoked.
1.532 **
1.533 ** <dt>SQLITE_CHECKPOINT_FULL<dd>
1.534 -** This mode blocks (calls the busy-handler callback) until there is no
1.535 +** This mode blocks (it invokes the
1.536 +** [sqlite3_busy_handler|busy-handler callback]) until there is no
1.537 ** database writer and all readers are reading from the most recent database
1.538 ** snapshot. It then checkpoints all frames in the log file and syncs the
1.539 ** database file. This call blocks database writers while it is running,
1.540 @@ -7108,7 +7207,8 @@
1.541 **
1.542 ** <dt>SQLITE_CHECKPOINT_RESTART<dd>
1.543 ** This mode works the same way as SQLITE_CHECKPOINT_FULL, except after
1.544 -** checkpointing the log file it blocks (calls the busy-handler callback)
1.545 +** checkpointing the log file it blocks (calls the
1.546 +** [sqlite3_busy_handler|busy-handler callback])
1.547 ** until all readers are reading from the database file only. This ensures
1.548 ** that the next client to write to the database file restarts the log file
1.549 ** from the beginning. This call blocks database writers while it is running,
1.550 @@ -7246,6 +7346,7 @@
1.551
1.552 /*
1.553 ** CAPI3REF: Conflict resolution modes
1.554 +** KEYWORDS: {conflict resolution mode}
1.555 **
1.556 ** These constants are returned by [sqlite3_vtab_on_conflict()] to
1.557 ** inform a [virtual table] implementation what the [ON CONFLICT] mode
1.558 @@ -7298,6 +7399,16 @@
1.559 #endif
1.560
1.561 typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
1.562 +typedef struct sqlite3_rtree_query_info sqlite3_rtree_query_info;
1.563 +
1.564 +/* The double-precision datatype used by RTree depends on the
1.565 +** SQLITE_RTREE_INT_ONLY compile-time option.
1.566 +*/
1.567 +#ifdef SQLITE_RTREE_INT_ONLY
1.568 + typedef sqlite3_int64 sqlite3_rtree_dbl;
1.569 +#else
1.570 + typedef double sqlite3_rtree_dbl;
1.571 +#endif
1.572
1.573 /*
1.574 ** Register a geometry callback named zGeom that can be used as part of an
1.575 @@ -7308,11 +7419,7 @@
1.576 SQLITE_API int sqlite3_rtree_geometry_callback(
1.577 sqlite3 *db,
1.578 const char *zGeom,
1.579 -#ifdef SQLITE_RTREE_INT_ONLY
1.580 - int (*xGeom)(sqlite3_rtree_geometry*, int n, sqlite3_int64 *a, int *pRes),
1.581 -#else
1.582 - int (*xGeom)(sqlite3_rtree_geometry*, int n, double *a, int *pRes),
1.583 -#endif
1.584 + int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*),
1.585 void *pContext
1.586 );
1.587
1.588 @@ -7324,11 +7431,60 @@
1.589 struct sqlite3_rtree_geometry {
1.590 void *pContext; /* Copy of pContext passed to s_r_g_c() */
1.591 int nParam; /* Size of array aParam[] */
1.592 - double *aParam; /* Parameters passed to SQL geom function */
1.593 + sqlite3_rtree_dbl *aParam; /* Parameters passed to SQL geom function */
1.594 void *pUser; /* Callback implementation user data */
1.595 void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */
1.596 };
1.597
1.598 +/*
1.599 +** Register a 2nd-generation geometry callback named zScore that can be
1.600 +** used as part of an R-Tree geometry query as follows:
1.601 +**
1.602 +** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...)
1.603 +*/
1.604 +SQLITE_API int sqlite3_rtree_query_callback(
1.605 + sqlite3 *db,
1.606 + const char *zQueryFunc,
1.607 + int (*xQueryFunc)(sqlite3_rtree_query_info*),
1.608 + void *pContext,
1.609 + void (*xDestructor)(void*)
1.610 +);
1.611 +
1.612 +
1.613 +/*
1.614 +** A pointer to a structure of the following type is passed as the
1.615 +** argument to scored geometry callback registered using
1.616 +** sqlite3_rtree_query_callback().
1.617 +**
1.618 +** Note that the first 5 fields of this structure are identical to
1.619 +** sqlite3_rtree_geometry. This structure is a subclass of
1.620 +** sqlite3_rtree_geometry.
1.621 +*/
1.622 +struct sqlite3_rtree_query_info {
1.623 + void *pContext; /* pContext from when function registered */
1.624 + int nParam; /* Number of function parameters */
1.625 + sqlite3_rtree_dbl *aParam; /* value of function parameters */
1.626 + void *pUser; /* callback can use this, if desired */
1.627 + void (*xDelUser)(void*); /* function to free pUser */
1.628 + sqlite3_rtree_dbl *aCoord; /* Coordinates of node or entry to check */
1.629 + unsigned int *anQueue; /* Number of pending entries in the queue */
1.630 + int nCoord; /* Number of coordinates */
1.631 + int iLevel; /* Level of current node or entry */
1.632 + int mxLevel; /* The largest iLevel value in the tree */
1.633 + sqlite3_int64 iRowid; /* Rowid for current entry */
1.634 + sqlite3_rtree_dbl rParentScore; /* Score of parent node */
1.635 + int eParentWithin; /* Visibility of parent node */
1.636 + int eWithin; /* OUT: Visiblity */
1.637 + sqlite3_rtree_dbl rScore; /* OUT: Write the score here */
1.638 +};
1.639 +
1.640 +/*
1.641 +** Allowed values for sqlite3_rtree_query.eWithin and .eParentWithin.
1.642 +*/
1.643 +#define NOT_WITHIN 0 /* Object completely outside of query region */
1.644 +#define PARTLY_WITHIN 1 /* Object partially overlaps query region */
1.645 +#define FULLY_WITHIN 2 /* Object fully contained within query region */
1.646 +
1.647
1.648 #ifdef __cplusplus
1.649 } /* end of the 'extern "C"' block */