src/sqlite3.h
changeset 26 843e629627bf
parent 0 16f27efbef98
     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 */