X-Git-Url: https://git.pterodactylus.net/?a=blobdiff_plain;f=libs%2Fsqlite3%2Fsqlite3.h;h=dfac084d64c6a71ef9566f233b87d5f44eebe285;hb=9ae3b1434e51788e6feb72e1415ec800d05c535a;hp=e8356498beee4863b5e3acaa62339f4baaebca0c;hpb=d5c9f7e6c1dd263dfc85a3cb5941a378a5ddd923;p=fms.git diff --git a/libs/sqlite3/sqlite3.h b/libs/sqlite3/sqlite3.h index e835649..dfac084 100644 --- a/libs/sqlite3/sqlite3.h +++ b/libs/sqlite3/sqlite3.h @@ -30,7 +30,7 @@ ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** -** @(#) $Id: sqlite.h.in,v 1.404 2008/10/12 00:27:54 shane Exp $ +** @(#) $Id: sqlite.h.in,v 1.432 2009/02/12 17:07:35 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ @@ -107,8 +107,8 @@ extern "C" { ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z ** are the major version, minor version, and release number. */ -#define SQLITE_VERSION "3.6.4" -#define SQLITE_VERSION_NUMBER 3006004 +#define SQLITE_VERSION "3.6.11" +#define SQLITE_VERSION_NUMBER 3006011 /* ** CAPI3REF: Run-Time Library Version Numbers {H10020} @@ -378,12 +378,14 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**); ** *E to NULL if E is not NULL and there are no errors. ** ** {H12137} The [sqlite3_exec(D,S,C,A,E)] function shall set the [error code] -** and message accessible via [sqlite3_errcode()], +** and message accessible via [sqlite3_errcode()], +** [sqlite3_extended_errcode()], ** [sqlite3_errmsg()], and [sqlite3_errmsg16()]. ** ** {H12138} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL or an ** empty string or contains nothing other than whitespace, comments, ** and/or semicolons, then results of [sqlite3_errcode()], +** [sqlite3_extended_errcode()], ** [sqlite3_errmsg()], and [sqlite3_errmsg16()] ** shall reset to indicate no errors. ** @@ -505,6 +507,8 @@ int sqlite3_exec( #define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8)) #define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8)) #define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8)) +#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8)) +#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8)) /* ** CAPI3REF: Flags For File Open Operations {H10230} @@ -585,7 +589,7 @@ int sqlite3_exec( ** sync operation only needs to flush data to mass storage. Inode ** information need not be flushed. The SQLITE_SYNC_NORMAL flag means ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means -** to use Mac OS-X style fullsync instead of fsync(). +** to use Mac OS X style fullsync instead of fsync(). */ #define SQLITE_SYNC_NORMAL 0x00002 #define SQLITE_SYNC_FULL 0x00003 @@ -617,7 +621,7 @@ struct sqlite3_file { ** ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). -** The second choice is a Mac OS-X style fullsync. The [SQLITE_SYNC_DATAONLY] +** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY] ** flag may be ORed in to indicate that only the data of the file ** and not its inode needs to be synced. ** @@ -680,6 +684,12 @@ struct sqlite3_file { ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that ** information is written to disk in the same order as calls ** to xWrite(). +** +** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill +** in the unread portions of the buffer with zeros. A VFS that +** fails to zero-fill short reads might seem to work. However, +** failure to zero-fill short reads will eventually lead to +** database corruption. */ typedef struct sqlite3_io_methods sqlite3_io_methods; struct sqlite3_io_methods { @@ -715,6 +725,9 @@ struct sqlite3_io_methods { ** is defined. */ #define SQLITE_FCNTL_LOCKSTATE 1 +#define SQLITE_GET_LOCKPROXYFILE 2 +#define SQLITE_SET_LOCKPROXYFILE 3 +#define SQLITE_LAST_ERRNO 4 /* ** CAPI3REF: Mutex Handle {H17110} @@ -762,11 +775,11 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** The zName field holds the name of the VFS module. The name must ** be unique across all VFS modules. ** -** {H11141} SQLite will guarantee that the zFilename parameter to xOpen +** SQLite will guarantee that the zFilename parameter to xOpen ** is either a NULL pointer or string obtained ** from xFullPathname(). SQLite further guarantees that ** the string will be valid and unchanged until xClose() is -** called. {END} Because of the previous sentense, +** called. Because of the previous sentense, ** the [sqlite3_file] can safely store a pointer to the ** filename if it needs to remember the filename for some reason. ** If the zFilename parameter is xOpen is a NULL pointer then xOpen @@ -774,14 +787,14 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** xFilename parameter is NULL it will also be the case that the ** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE]. ** -** {H11142} The flags argument to xOpen() includes all bits set in +** The flags argument to xOpen() includes all bits set in ** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()] ** or [sqlite3_open16()] is used, then flags includes at least -** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END} +** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. ** If xOpen() opens a file read-only then it sets *pOutFlags to ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set. ** -** {H11143} SQLite will also add one of the following flags to the xOpen() +** SQLite will also add one of the following flags to the xOpen() ** call, depending on the object being opened: ** **
    @@ -792,7 +805,7 @@ typedef struct sqlite3_mutex sqlite3_mutex; **
  • [SQLITE_OPEN_TRANSIENT_DB] **
  • [SQLITE_OPEN_SUBJOURNAL] **
  • [SQLITE_OPEN_MASTER_JOURNAL] -**
{END} +** ** ** The file I/O implementation can use the object type flags to ** change the way it deals with files. For example, an application @@ -810,28 +823,28 @@ typedef struct sqlite3_mutex sqlite3_mutex; **
  • [SQLITE_OPEN_EXCLUSIVE] ** ** -** {H11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be -** deleted when it is closed. {H11146} The [SQLITE_OPEN_DELETEONCLOSE] +** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be +** deleted when it is closed. The [SQLITE_OPEN_DELETEONCLOSE] ** will be set for TEMP databases, journals and for subjournals. ** -** {H11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened +** The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened ** for exclusive access. This flag is set for all files except ** for the main database file. ** -** {H11148} At least szOsFile bytes of memory are allocated by SQLite +** At least szOsFile bytes of memory are allocated by SQLite ** to hold the [sqlite3_file] structure passed as the third -** argument to xOpen. {END} The xOpen method does not have to +** argument to xOpen. The xOpen method does not have to ** allocate the structure; it should just fill it in. ** -** {H11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] +** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ] -** to test whether a file is at least readable. {END} The file can be a +** to test whether a file is at least readable. The file can be a ** directory. ** -** {H11150} SQLite will always allocate at least mxPathname+1 bytes for the -** output buffer xFullPathname. {H11151} The exact size of the output buffer -** is also passed as a parameter to both methods. {END} If the output buffer +** SQLite will always allocate at least mxPathname+1 bytes for the +** output buffer xFullPathname. The exact size of the output buffer +** is also passed as a parameter to both methods. If the output buffer ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is ** handled as a fatal error by SQLite, vfs implementations should endeavor ** to prevent this by setting mxPathname to a sufficiently large value. @@ -845,6 +858,7 @@ typedef struct sqlite3_mutex sqlite3_mutex; ** The xSleep() method causes the calling thread to sleep for at ** least the number of microseconds given. The xCurrentTime() ** method returns a Julian Day Number for the current date and time. +** */ typedef struct sqlite3_vfs sqlite3_vfs; struct sqlite3_vfs { @@ -861,7 +875,7 @@ struct sqlite3_vfs { int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut); void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); - void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol); + void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void); void (*xDlClose)(sqlite3_vfs*, void*); int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); int (*xSleep)(sqlite3_vfs*, int microseconds); @@ -874,14 +888,14 @@ struct sqlite3_vfs { /* ** CAPI3REF: Flags for the xAccess VFS method {H11190} ** -** {H11191} These integer constants can be used as the third parameter to +** These integer constants can be used as the third parameter to ** the xAccess method of an [sqlite3_vfs] object. {END} They determine ** what kind of permissions the xAccess method is looking for. -** {H11192} With SQLITE_ACCESS_EXISTS, the xAccess method +** With SQLITE_ACCESS_EXISTS, the xAccess method ** simply checks whether the file exists. -** {H11193} With SQLITE_ACCESS_READWRITE, the xAccess method +** With SQLITE_ACCESS_READWRITE, the xAccess method ** checks whether the file is both readable and writable. -** {H11194} With SQLITE_ACCESS_READ, the xAccess method +** With SQLITE_ACCESS_READ, the xAccess method ** checks whether the file is readable. */ #define SQLITE_ACCESS_EXISTS 0 @@ -1036,7 +1050,7 @@ int sqlite3_os_end(void); ** S is a pointer to an aligned memory buffer not less than ** Z*N bytes in size shall cause S to be used by the ** [scratch memory allocator] for as many as N simulataneous -** allocations each of size Z. +** allocations each of size (Z & ~7). ** ** {H14153} A successful call to [sqlite3_config]([SQLITE_CONFIG_SCRATCH],S,Z,N) ** where S is a NULL pointer shall disable the @@ -1048,7 +1062,7 @@ int sqlite3_os_end(void); ** S is a pointer to an aligned memory buffer not less than ** Z*N bytes in size shall cause S to be used by the ** [pagecache memory allocator] for as many as N simulataneous -** allocations each of size Z. +** allocations each of size (Z & ~7). ** ** {H14159} A successful call to ** [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],S,Z,N) @@ -1266,7 +1280,10 @@ struct sqlite3_mem_methods { ** **
    SQLITE_CONFIG_PAGECACHE
    **
    This option specifies a static memory buffer that SQLite can use for -** the database page cache. There are three arguments: A pointer to the +** the database page cache with the default page cache implemenation. +** This configuration should not be used if an application-define page +** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option. +** There are three arguments to this option: A pointer to the ** memory, the size of each page buffer (sz), and the number of pages (N). ** The sz argument must be a power of two between 512 and 32768. The first ** argument should point to an allocation of at least sz*N bytes of memory. @@ -1311,6 +1328,17 @@ struct sqlite3_mem_methods { ** size of each lookaside buffer slot and the second is the number of ** slots allocated to each database connection.
    ** +**
    SQLITE_CONFIG_PCACHE
    +**
    This option takes a single argument which is a pointer to +** an [sqlite3_pcache_methods] object. This object specifies the interface +** to a custom page cache implementation. SQLite makes a copy of the +** object and uses it for page cache memory allocations.
    +** +**
    SQLITE_CONFIG_GETPCACHE
    +**
    This option takes a single argument which is a pointer to an +** [sqlite3_pcache_methods] object. SQLite copies of the current +** page cache implementation into that object.
    +** ** */ #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ @@ -1324,8 +1352,10 @@ struct sqlite3_mem_methods { #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ -#define SQLITE_CONFIG_CHUNKALLOC 12 /* int threshold */ +/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ #define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ +#define SQLITE_CONFIG_PCACHE 14 /* sqlite3_pcache_methods* */ +#define SQLITE_CONFIG_GETPCACHE 15 /* sqlite3_pcache_methods* */ /* ** CAPI3REF: Configuration Options {H10170} @@ -1380,18 +1410,18 @@ int sqlite3_extended_result_codes(sqlite3*, int onoff); ** CAPI3REF: Last Insert Rowid {H12220} ** ** Each entry in an SQLite table has a unique 64-bit signed -** integer key called the "rowid". The rowid is always available +** integer key called the [ROWID | "rowid"]. The rowid is always available ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those ** names are not also used by explicitly declared columns. If -** the table has a column of type INTEGER PRIMARY KEY then that column +** the table has a column of type [INTEGER PRIMARY KEY] then that column ** is another alias for the rowid. ** -** This routine returns the rowid of the most recent +** This routine returns the [rowid] of the most recent ** successful [INSERT] into the database from the [database connection] ** in the first argument. If no successful [INSERT]s ** have ever occurred on that database connection, zero is returned. ** -** If an [INSERT] occurs within a trigger, then the rowid of the inserted +** If an [INSERT] occurs within a trigger, then the [rowid] of the inserted ** row is returned by this routine as long as the trigger is running. ** But once the trigger terminates, the value returned by this routine ** reverts to the last value inserted before the trigger fired. @@ -1411,7 +1441,8 @@ int sqlite3_extended_result_codes(sqlite3*, int onoff); ** ** INVARIANTS: ** -** {H12221} The [sqlite3_last_insert_rowid()] function shall return the rowid +** {H12221} The [sqlite3_last_insert_rowid()] function shall return +** the [rowid] ** of the most recent successful [INSERT] performed on the same ** [database connection] and within the same or higher level ** trigger context, or zero if there have been no qualifying @@ -1425,10 +1456,10 @@ int sqlite3_extended_result_codes(sqlite3*, int onoff); ** ** {A12232} If a separate thread performs a new [INSERT] on the same ** database connection while the [sqlite3_last_insert_rowid()] -** function is running and thus changes the last insert rowid, +** function is running and thus changes the last insert [rowid], ** then the value returned by [sqlite3_last_insert_rowid()] is ** unpredictable and might not equal either the old or the new -** last insert rowid. +** last insert [rowid]. */ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); @@ -2004,7 +2035,7 @@ char *sqlite3_snprintf(int,char*,const char*, ...); ** memory might result in a segmentation fault or other severe error. ** Memory corruption, a segmentation fault, or other severe error ** might result if sqlite3_free() is called with a non-NULL pointer that -** was not obtained from sqlite3_malloc() or sqlite3_free(). +** was not obtained from sqlite3_malloc() or sqlite3_realloc(). ** ** The sqlite3_realloc() interface attempts to resize a ** prior memory allocation to be at least N bytes, where N is the @@ -2139,8 +2170,8 @@ sqlite3_int64 sqlite3_memory_highwater(int resetFlag); ** CAPI3REF: Pseudo-Random Number Generator {H17390} ** ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to -** select random ROWIDs when inserting new records into a table that -** already uses the largest possible ROWID. The PRNG is also used for +** select random [ROWID | ROWIDs] when inserting new records into a table that +** already uses the largest possible [ROWID]. The PRNG is also used for ** the build-in random() and randomblob() SQL functions. This interface allows ** applications to access the same PRNG for other purposes. ** @@ -2366,7 +2397,7 @@ int sqlite3_set_authorizer( #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ #define SQLITE_READ 20 /* Table Name Column Name */ #define SQLITE_SELECT 21 /* NULL NULL */ -#define SQLITE_TRANSACTION 22 /* NULL NULL */ +#define SQLITE_TRANSACTION 22 /* Operation NULL */ #define SQLITE_UPDATE 23 /* Table Name Column Name */ #define SQLITE_ATTACH 24 /* Filename NULL */ #define SQLITE_DETACH 25 /* Database Name NULL */ @@ -2375,7 +2406,8 @@ int sqlite3_set_authorizer( #define SQLITE_ANALYZE 28 /* Table Name NULL */ #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ -#define SQLITE_FUNCTION 31 /* Function Name NULL */ +#define SQLITE_FUNCTION 31 /* NULL Function Name */ +#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ #define SQLITE_COPY 0 /* No longer used */ /* @@ -2658,7 +2690,10 @@ int sqlite3_open_v2( ** [extended result code] for the most recent failed sqlite3_* API call ** associated with a [database connection]. If a prior API call failed ** but the most recent API call succeeded, the return value from -** sqlite3_errcode() is undefined. +** sqlite3_errcode() is undefined. The sqlite3_extended_errcode() +** interface is the same except that it always returns the +** [extended result code] even when extended result codes are +** disabled. ** ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language ** text that describes the error, as either UTF-8 or UTF-16 respectively. @@ -2667,6 +2702,16 @@ int sqlite3_open_v2( ** However, the error string might be overwritten or deallocated by ** subsequent calls to other SQLite interface functions. ** +** When the serialized [threading mode] is in use, it might be the +** case that a second error occurs on a separate thread in between +** the time of the first error and the call to these interfaces. +** When that happens, the second error will be reported since these +** interfaces always report the most recent result. To avoid +** this, each thread can obtain exclusive use of the [database connection] D +** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning +** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after +** all calls to the interfaces listed here are completed. +** ** If an interface fails with SQLITE_MISUSE, that means the interface ** was invoked incorrectly by the application. In that case, the ** error code and message may or may not be set. @@ -2677,6 +2722,10 @@ int sqlite3_open_v2( ** [result code] or [extended result code] for the most recently ** failed interface call associated with the [database connection] D. ** +** {H12802} The [sqlite3_extended_errcode(D)] interface returns the numeric +** [extended result code] for the most recently +** failed interface call associated with the [database connection] D. +** ** {H12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)] ** interfaces return English-language text that describes ** the error in the mostly recently failed interface call, @@ -2688,15 +2737,18 @@ int sqlite3_open_v2( ** {H12808} Calls to API routines that do not return an error code ** (example: [sqlite3_data_count()]) do not ** change the error code or message returned by -** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()]. +** [sqlite3_errcode()], [sqlite3_extended_errcode()], +** [sqlite3_errmsg()], or [sqlite3_errmsg16()]. ** ** {H12809} Interfaces that are not associated with a specific ** [database connection] (examples: ** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()] ** do not change the values returned by -** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()]. +** [sqlite3_errcode()], [sqlite3_extended_errcode()], +** [sqlite3_errmsg()], or [sqlite3_errmsg16()]. */ int sqlite3_errcode(sqlite3 *db); +int sqlite3_extended_errcode(sqlite3 *db); const char *sqlite3_errmsg(sqlite3*); const void *sqlite3_errmsg16(sqlite3*); @@ -2737,8 +2789,10 @@ typedef struct sqlite3_stmt sqlite3_stmt; ** new limit for that construct. The function returns the old limit. ** ** If the new limit is a negative number, the limit is unchanged. -** For the limit category of SQLITE_LIMIT_XYZ there is a hard upper -** bound set by a compile-time C preprocessor macro named SQLITE_MAX_XYZ. +** For the limit category of SQLITE_LIMIT_XYZ there is a +** [limits | hard upper bound] +** set by a compile-time C preprocessor macro named +** [limits | SQLITE_MAX_XYZ]. ** (The "_LIMIT_" in the name is changed to "_MAX_".) ** Attempts to increase a limit above its hard upper bound are ** silently truncated to the hard upper limit. @@ -2746,7 +2800,7 @@ typedef struct sqlite3_stmt sqlite3_stmt; ** Run time limits are intended for use in applications that manage ** both their own internal database and also databases that are controlled ** by untrusted external sources. An example application might be a -** webbrowser that has its own databases for storing history and +** web browser that has its own databases for storing history and ** separate databases controlled by JavaScript applications downloaded ** off the Internet. The internal databases can be given the ** large, default limits. Databases managed by external sources can @@ -2778,9 +2832,10 @@ int sqlite3_limit(sqlite3*, int id, int newVal); ** CAPI3REF: Run-Time Limit Categories {H12790} ** KEYWORDS: {limit category} {limit categories} ** -** These constants define various aspects of a [database connection] -** that can be limited in size by calls to [sqlite3_limit()]. -** The meanings of the various limits are as follows: +** These constants define various performance limits +** that can be lowered at run-time using [sqlite3_limit()]. +** The synopsis of the meanings of the various limits is shown below. +** Additional information is available at [limits | Limits in SQLite]. ** **
    **
    SQLITE_LIMIT_LENGTH
    @@ -2791,7 +2846,7 @@ int sqlite3_limit(sqlite3*, int id, int newVal); ** **
    SQLITE_LIMIT_COLUMN
    **
    The maximum number of columns in a table definition or in the -** result set of a SELECT or the maximum number of columns in an index +** result set of a [SELECT] or the maximum number of columns in an index ** or in an ORDER BY or GROUP BY clause.
    ** **
    SQLITE_LIMIT_EXPR_DEPTH
    @@ -2808,11 +2863,11 @@ int sqlite3_limit(sqlite3*, int id, int newVal); **
    The maximum number of arguments on a function.
    ** **
    SQLITE_LIMIT_ATTACHED
    -**
    The maximum number of attached databases.
    +**
    The maximum number of [ATTACH | attached databases].
    ** **
    SQLITE_LIMIT_LIKE_PATTERN_LENGTH
    -**
    The maximum length of the pattern argument to the LIKE or -** GLOB operators.
    +**
    The maximum length of the pattern argument to the [LIKE] or +** [GLOB] operators.
    ** **
    SQLITE_LIMIT_VARIABLE_NUMBER
    **
    The maximum number of variables in an SQL statement that can @@ -3047,7 +3102,7 @@ typedef struct sqlite3_context sqlite3_context; ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding} ** ** In the SQL strings input to [sqlite3_prepare_v2()] and its variants, -** literals may be replaced by a parameter in one of these forms: +** literals may be replaced by a [parameter] in one of these forms: ** **
      **
    • ? @@ -4123,7 +4178,7 @@ int sqlite3_create_function16( ** backwards compatibility with older code, these functions continue ** to be supported. However, new applications should avoid ** the use of these functions. To help encourage people to avoid -** using these functions, we are not going to tell you want they do. +** using these functions, we are not going to tell you what they do. */ #ifndef SQLITE_OMIT_DEPRECATED SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*); @@ -4925,8 +4980,8 @@ int sqlite3_get_autocommit(sqlite3*); ** CAPI3REF: Find The Database Handle Of A Prepared Statement {H13120} ** ** The sqlite3_db_handle interface returns the [database connection] handle -** to which a [prepared statement] belongs. The database handle returned by -** sqlite3_db_handle is the same database handle that was the first argument +** to which a [prepared statement] belongs. The [database connection] +** returned by sqlite3_db_handle is the same [database connection] that was the first argument ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to ** create the statement in the first place. ** @@ -5069,8 +5124,8 @@ void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); ** to be invoked. ** The third and fourth arguments to the callback contain pointers to the ** database and table name containing the affected row. -** The final callback parameter is the rowid of the row. In the case of -** an update, this is the rowid after the update takes place. +** The final callback parameter is the [rowid] of the row. +** In the case of an update, this is the [rowid] after the update takes place. ** ** The update hook is not invoked when internal system tables are ** modified (i.e. sqlite_master and sqlite_sequence). @@ -5113,7 +5168,7 @@ void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); ** to zero-terminated UTF-8 strings which are the names of the ** database and table that is being updated. -** {H12985} The final callback parameter is the rowid of the row after +** {H12985} The final callback parameter is the [rowid] of the row after ** the change occurs. */ void *sqlite3_update_hook( @@ -5131,7 +5186,7 @@ void *sqlite3_update_hook( ** to the same database. Sharing is enabled if the argument is true ** and disabled if the argument is false. ** -** Cache sharing is enabled and disabled for an entire process. {END} +** Cache sharing is enabled and disabled for an entire process. ** This is a change as of SQLite version 3.5.0. In prior versions of SQLite, ** sharing was enabled or disabled for each thread separately. ** @@ -5151,6 +5206,8 @@ void *sqlite3_update_hook( ** future releases of SQLite. Applications that care about shared ** cache setting should set it explicitly. ** +** See Also: [SQLite Shared-Cache Mode] +** ** INVARIANTS: ** ** {H10331} A successful invocation of [sqlite3_enable_shared_cache(B)] @@ -5279,7 +5336,7 @@ void sqlite3_soft_heap_limit(int); ** 6th const char* Name of default collation sequence ** 7th int True if column has a NOT NULL constraint ** 8th int True if column is part of the PRIMARY KEY -** 9th int True if column is AUTOINCREMENT +** 9th int True if column is [AUTOINCREMENT] ** ** ** @@ -5290,9 +5347,9 @@ void sqlite3_soft_heap_limit(int); ** If the specified table is actually a view, an [error code] is returned. ** ** If the specified column is "rowid", "oid" or "_rowid_" and an -** INTEGER PRIMARY KEY column has been explicitly declared, then the output +** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output ** parameters are set for the explicitly declared column. If there is no -** explicitly declared INTEGER PRIMARY KEY column, then the output +** explicitly declared [INTEGER PRIMARY KEY] column, then the output ** parameters are set as follows: ** ** 
      @@ -5399,7 +5456,7 @@ int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
 **
 ** {H12644} Automatic extensions apply across all threads.
 */
-int sqlite3_auto_extension(void *xEntryPoint);
+int sqlite3_auto_extension(void (*xEntryPoint)(void));
 
 /*
 ** CAPI3REF: Reset Automatic Extension Loading {H12660} 
@@ -5716,7 +5773,7 @@ typedef struct sqlite3_blob sqlite3_blob;
 ** in other words, the same BLOB that would be selected by:
 **
 ** 
      -**     SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
+**     SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
 ** 
       {END}
 **
 ** If the flags parameter is non-zero, the the BLOB is opened for read
@@ -5765,6 +5822,7 @@ typedef struct sqlite3_blob sqlite3_blob;
 **
 ** {H17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)]
 **          then subsequent calls to [sqlite3_errcode(D)],
+**          [sqlite3_extended_errcode()], 
 **          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
 **          information appropriate for that error.
 **
@@ -5878,6 +5936,7 @@ int sqlite3_blob_bytes(sqlite3_blob *);
 **
 ** {H17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)]
 **          then subsequent calls to [sqlite3_errcode(D)],
+**          [sqlite3_extended_errcode()],
 **          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
 **          information appropriate for that error, where D is the
 **          [database connection] that was used to open the [BLOB handle] P.
@@ -5947,6 +6006,7 @@ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
 **
 ** {H17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)]
 **          then subsequent calls to [sqlite3_errcode(D)],
+**          [sqlite3_extended_errcode()],
 **          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
 **          information appropriate for that error.
 */
@@ -6245,6 +6305,17 @@ int sqlite3_mutex_notheld(sqlite3_mutex*);
 #define SQLITE_MUTEX_STATIC_LRU2      7  /* lru page list */
 
 /*
+** CAPI3REF: Retrieve the mutex for a database connection {H17002} 
+**
+** This interface returns a pointer the [sqlite3_mutex] object that 
+** serializes access to the [database connection] given in the argument
+** when the [threading mode] is Serialized.
+** If the [threading mode] is Single-thread or Multi-thread then this
+** routine returns a NULL pointer.
+*/
+sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
+
+/*
 ** CAPI3REF: Low-Level Control Of Database Files {H11300} 
 **
 ** {H11301} The [sqlite3_file_control()] interface makes a direct call to the
@@ -6306,6 +6377,7 @@ int sqlite3_test_control(int op, ...);
 #define SQLITE_TESTCTRL_BITVEC_TEST              8
 #define SQLITE_TESTCTRL_FAULT_INSTALL            9
 #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS     10
+#define SQLITE_TESTCTRL_PENDING_BYTE            11
 
 /*
 ** CAPI3REF: SQLite Runtime Status {H17200} 
@@ -6514,6 +6586,345 @@ SQLITE_EXPERIMENTAL int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
 #define SQLITE_STMTSTATUS_SORT              2
 
 /*
+** CAPI3REF: Custom Page Cache Object
+** EXPERIMENTAL
+**
+** The sqlite3_pcache type is opaque.  It is implemented by
+** the pluggable module.  The SQLite core has no knowledge of
+** its size or internal structure and never deals with the
+** sqlite3_pcache object except by holding and passing pointers
+** to the object.
+**
+** See [sqlite3_pcache_methods] for additional information.
+*/
+typedef struct sqlite3_pcache sqlite3_pcache;
+
+/*
+** CAPI3REF: Application Defined Page Cache.
+** EXPERIMENTAL
+**
+** The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
+** register an alternative page cache implementation by passing in an 
+** instance of the sqlite3_pcache_methods structure. The majority of the 
+** heap memory used by sqlite is used by the page cache to cache data read 
+** from, or ready to be written to, the database file. By implementing a 
+** custom page cache using this API, an application can control more 
+** precisely the amount of memory consumed by sqlite, the way in which 
+** said memory is allocated and released, and the policies used to 
+** determine exactly which parts of a database file are cached and for 
+** how long.
+**
+** The contents of the structure are copied to an internal buffer by sqlite
+** within the call to [sqlite3_config].
+**
+** The xInit() method is called once for each call to [sqlite3_initialize()]
+** (usually only once during the lifetime of the process). It is passed
+** a copy of the sqlite3_pcache_methods.pArg value. It can be used to set
+** up global structures and mutexes required by the custom page cache 
+** implementation. The xShutdown() method is called from within 
+** [sqlite3_shutdown()], if the application invokes this API. It can be used
+** to clean up any outstanding resources before process shutdown, if required.
+**
+** The xCreate() method is used to construct a new cache instance. The
+** first parameter, szPage, is the size in bytes of the pages that must
+** be allocated by the cache. szPage will not be a power of two. The
+** second argument, bPurgeable, is true if the cache being created will
+** be used to cache database pages read from a file stored on disk, or
+** false if it is used for an in-memory database. The cache implementation
+** does not have to do anything special based on the value of bPurgeable,
+** it is purely advisory. 
+**
+** The xCachesize() method may be called at any time by SQLite to set the
+** suggested maximum cache-size (number of pages stored by) the cache
+** instance passed as the first argument. This is the value configured using
+** the SQLite "[PRAGMA cache_size]" command. As with the bPurgeable parameter,
+** the implementation is not required to do anything special with this
+** value, it is advisory only.
+**
+** The xPagecount() method should return the number of pages currently
+** stored in the cache supplied as an argument.
+** 
+** The xFetch() method is used to fetch a page and return a pointer to it. 
+** A 'page', in this context, is a buffer of szPage bytes aligned at an
+** 8-byte boundary. The page to be fetched is determined by the key. The
+** mimimum key value is 1. After it has been retrieved using xFetch, the page 
+** is considered to be pinned.
+**
+** If the requested page is already in the page cache, then a pointer to
+** the cached buffer should be returned with its contents intact. If the
+** page is not already in the cache, then the expected behaviour of the
+** cache is determined by the value of the createFlag parameter passed
+** to xFetch, according to the following table:
+**
+** 
+**   
      createFlagExpected Behaviour
+**   
      0NULL should be returned. No new cache entry is created.
+**   
      1If createFlag is set to 1, this indicates that 
+**                SQLite is holding pinned pages that can be unpinned
+**                by writing their contents to the database file (a
+**                relatively expensive operation). In this situation the
+**                cache implementation has two choices: it can return NULL,
+**                in which case SQLite will attempt to unpin one or more 
+**                pages before re-requesting the same page, or it can
+**                allocate a new page and return a pointer to it. If a new
+**                page is allocated, then the first sizeof(void*) bytes of
+**                it (at least) must be zeroed before it is returned.
+**   
      2If createFlag is set to 2, then SQLite is not holding any
+**                pinned pages associated with the specific cache passed
+**                as the first argument to xFetch() that can be unpinned. The
+**                cache implementation should attempt to allocate a new
+**                cache entry and return a pointer to it. Again, the first
+**                sizeof(void*) bytes of the page should be zeroed before 
+**                it is returned. If the xFetch() method returns NULL when 
+**                createFlag==2, SQLite assumes that a memory allocation 
+**                failed and returns SQLITE_NOMEM to the user.
+** 
      
+**
+** xUnpin() is called by SQLite with a pointer to a currently pinned page
+** as its second argument. If the third parameter, discard, is non-zero,
+** then the page should be evicted from the cache. In this case SQLite 
+** assumes that the next time the page is retrieved from the cache using
+** the xFetch() method, it will be zeroed. If the discard parameter is
+** zero, then the page is considered to be unpinned. The cache implementation
+** may choose to reclaim (free or recycle) unpinned pages at any time.
+** SQLite assumes that next time the page is retrieved from the cache
+** it will either be zeroed, or contain the same data that it did when it
+** was unpinned.
+**
+** The cache is not required to perform any reference counting. A single 
+** call to xUnpin() unpins the page regardless of the number of prior calls 
+** to xFetch().
+**
+** The xRekey() method is used to change the key value associated with the
+** page passed as the second argument from oldKey to newKey. If the cache
+** previously contains an entry associated with newKey, it should be
+** discarded. Any prior cache entry associated with newKey is guaranteed not
+** to be pinned.
+**
+** When SQLite calls the xTruncate() method, the cache must discard all
+** existing cache entries with page numbers (keys) greater than or equal
+** to the value of the iLimit parameter passed to xTruncate(). If any
+** of these pages are pinned, they are implicitly unpinned, meaning that
+** they can be safely discarded.
+**
+** The xDestroy() method is used to delete a cache allocated by xCreate().
+** All resources associated with the specified cache should be freed. After
+** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
+** handle invalid, and will not use it with any other sqlite3_pcache_methods
+** functions.
+*/
+typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
+struct sqlite3_pcache_methods {
+  void *pArg;
+  int (*xInit)(void*);
+  void (*xShutdown)(void*);
+  sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);
+  void (*xCachesize)(sqlite3_pcache*, int nCachesize);
+  int (*xPagecount)(sqlite3_pcache*);
+  void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
+  void (*xUnpin)(sqlite3_pcache*, void*, int discard);
+  void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
+  void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
+  void (*xDestroy)(sqlite3_pcache*);
+};
+
+/*
+** CAPI3REF: Online Backup Object
+** EXPERIMENTAL
+**
+** The sqlite3_backup object records state information about an ongoing
+** online backup operation.  The sqlite3_backup object is created by
+** a call to [sqlite3_backup_init()] and is destroyed by a call to
+** [sqlite3_backup_finish()].
+**
+** See Also: [Using the SQLite Online Backup API]
+*/
+typedef struct sqlite3_backup sqlite3_backup;
+
+/*
+** CAPI3REF: Online Backup API.
+** EXPERIMENTAL
+**
+** This API is used to overwrite the contents of one database with that
+** of another. It is useful either for creating backups of databases or
+** for copying in-memory databases to or from persistent files. 
+**
+** See Also: [Using the SQLite Online Backup API]
+**
+** Exclusive access is required to the destination database for the 
+** duration of the operation. However the source database is only
+** read-locked while it is actually being read, it is not locked
+** continuously for the entire operation. Thus, the backup may be
+** performed on a live database without preventing other users from
+** writing to the database for an extended period of time.
+** 
+** To perform a backup operation: 
+**   
        
+**     
      1. sqlite3_backup_init() is called once to initialize the
+**         backup, 
+**     
      2. sqlite3_backup_step() is called one or more times to transfer 
+**         the data between the two databases, and finally
+**     
      3. sqlite3_backup_finish() is called to release all resources 
+**         associated with the backup operation. 
+**   
      
+** There should be exactly one call to sqlite3_backup_finish() for each
+** successful call to sqlite3_backup_init().
+**
+** sqlite3_backup_init()
+**
+** The first two arguments passed to [sqlite3_backup_init()] are the database
+** handle associated with the destination database and the database name 
+** used to attach the destination database to the handle. The database name
+** is "main" for the main database, "temp" for the temporary database, or
+** the name specified as part of the [ATTACH] statement if the destination is
+** an attached database. The third and fourth arguments passed to 
+** sqlite3_backup_init() identify the [database connection]
+** and database name used
+** to access the source database. The values passed for the source and 
+** destination [database connection] parameters must not be the same.
+**
+** If an error occurs within sqlite3_backup_init(), then NULL is returned
+** and an error code and error message written into the [database connection] 
+** passed as the first argument. They may be retrieved using the
+** [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()] functions.
+** Otherwise, if successful, a pointer to an [sqlite3_backup] object is
+** returned. This pointer may be used with the sqlite3_backup_step() and
+** sqlite3_backup_finish() functions to perform the specified backup 
+** operation.
+**
+** sqlite3_backup_step()
+**
+** Function [sqlite3_backup_step()] is used to copy up to nPage pages between 
+** the source and destination databases, where nPage is the value of the 
+** second parameter passed to sqlite3_backup_step(). If nPage is a negative
+** value, all remaining source pages are copied. If the required pages are 
+** succesfully copied, but there are still more pages to copy before the 
+** backup is complete, it returns [SQLITE_OK]. If no error occured and there 
+** are no more pages to copy, then [SQLITE_DONE] is returned. If an error 
+** occurs, then an SQLite error code is returned. As well as [SQLITE_OK] and
+** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
+** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
+** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
+**
+** As well as the case where the destination database file was opened for
+** read-only access, sqlite3_backup_step() may return [SQLITE_READONLY] if
+** the destination is an in-memory database with a different page size
+** from the source database.
+**
+** If sqlite3_backup_step() cannot obtain a required file-system lock, then
+** the [sqlite3_busy_handler | busy-handler function]
+** is invoked (if one is specified). If the 
+** busy-handler returns non-zero before the lock is available, then 
+** [SQLITE_BUSY] is returned to the caller. In this case the call to
+** sqlite3_backup_step() can be retried later. If the source
+** [database connection]
+** is being used to write to the source database when sqlite3_backup_step()
+** is called, then [SQLITE_LOCKED] is returned immediately. Again, in this
+** case the call to sqlite3_backup_step() can be retried later on. If
+** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
+** [SQLITE_READONLY] is returned, then 
+** there is no point in retrying the call to sqlite3_backup_step(). These 
+** errors are considered fatal. At this point the application must accept 
+** that the backup operation has failed and pass the backup operation handle 
+** to the sqlite3_backup_finish() to release associated resources.
+**
+** Following the first call to sqlite3_backup_step(), an exclusive lock is
+** obtained on the destination file. It is not released until either 
+** sqlite3_backup_finish() is called or the backup operation is complete 
+** and sqlite3_backup_step() returns [SQLITE_DONE]. Additionally, each time 
+** a call to sqlite3_backup_step() is made a [shared lock] is obtained on
+** the source database file. This lock is released before the
+** sqlite3_backup_step() call returns. Because the source database is not
+** locked between calls to sqlite3_backup_step(), it may be modified mid-way
+** through the backup procedure. If the source database is modified by an
+** external process or via a database connection other than the one being
+** used by the backup operation, then the backup will be transparently
+** restarted by the next call to sqlite3_backup_step(). If the source 
+** database is modified by the using the same database connection as is used
+** by the backup operation, then the backup database is transparently 
+** updated at the same time.
+**
+** sqlite3_backup_finish()
+**
+** Once sqlite3_backup_step() has returned [SQLITE_DONE], or when the 
+** application wishes to abandon the backup operation, the [sqlite3_backup]
+** object should be passed to sqlite3_backup_finish(). This releases all
+** resources associated with the backup operation. If sqlite3_backup_step()
+** has not yet returned [SQLITE_DONE], then any active write-transaction on the
+** destination database is rolled back. The [sqlite3_backup] object is invalid
+** and may not be used following a call to sqlite3_backup_finish().
+**
+** The value returned by sqlite3_backup_finish is [SQLITE_OK] if no error
+** occurred, regardless or whether or not sqlite3_backup_step() was called
+** a sufficient number of times to complete the backup operation. Or, if
+** an out-of-memory condition or IO error occured during a call to
+** sqlite3_backup_step() then [SQLITE_NOMEM] or an
+** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] error code
+** is returned. In this case the error code and an error message are
+** written to the destination [database connection].
+**
+** A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step() is
+** not a permanent error and does not affect the return value of
+** sqlite3_backup_finish().
+**
+** sqlite3_backup_remaining(), sqlite3_backup_pagecount()
+**
+** Each call to sqlite3_backup_step() sets two values stored internally
+** by an [sqlite3_backup] object. The number of pages still to be backed
+** up, which may be queried by sqlite3_backup_remaining(), and the total
+** number of pages in the source database file, which may be queried by
+** sqlite3_backup_pagecount().
+**
+** The values returned by these functions are only updated by
+** sqlite3_backup_step(). If the source database is modified during a backup
+** operation, then the values are not updated to account for any extra
+** pages that need to be updated or the size of the source database file
+** changing.
+**
+** Concurrent Usage of Database Handles
+**
+** The source [database connection] may be used by the application for other
+** purposes while a backup operation is underway or being initialized.
+** If SQLite is compiled and configured to support threadsafe database
+** connections, then the source database connection may be used concurrently
+** from within other threads.
+**
+** However, the application must guarantee that the destination database
+** connection handle is not passed to any other API (by any thread) after 
+** sqlite3_backup_init() is called and before the corresponding call to
+** sqlite3_backup_finish(). Unfortunately SQLite does not currently check
+** for this, if the application does use the destination [database connection]
+** for some other purpose during a backup operation, things may appear to
+** work correctly but in fact be subtly malfunctioning.  Use of the
+** destination database connection while a backup is in progress might
+** also cause a mutex deadlock.
+**
+** Furthermore, if running in [shared cache mode], the application must
+** guarantee that the shared cache used by the destination database
+** is not accessed while the backup is running. In practice this means
+** that the application must guarantee that the file-system file being 
+** backed up to is not accessed by any connection within the process,
+** not just the specific connection that was passed to sqlite3_backup_init().
+**
+** The [sqlite3_backup] object itself is partially threadsafe. Multiple 
+** threads may safely make multiple concurrent calls to sqlite3_backup_step().
+** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
+** APIs are not strictly speaking threadsafe. If they are invoked at the
+** same time as another thread is invoking sqlite3_backup_step() it is
+** possible that they return invalid values.
+*/
+sqlite3_backup *sqlite3_backup_init(
+  sqlite3 *pDest,                        /* Destination database handle */
+  const char *zDestName,                 /* Destination database name */
+  sqlite3 *pSource,                      /* Source database handle */
+  const char *zSourceName                /* Source database name */
+);
+int sqlite3_backup_step(sqlite3_backup *p, int nPage);
+int sqlite3_backup_finish(sqlite3_backup *p);
+int sqlite3_backup_remaining(sqlite3_backup *p);
+int sqlite3_backup_pagecount(sqlite3_backup *p);
+
+/*
 ** Undo the hack that converts floating point types to integer for
 ** builds on processors without floating point support.
 */