sqlite3.h (226031) | sqlite3.h (226128) |
---|---|
1/* 2** 2001 September 15 3** 4** The author disclaims copyright to this source code. In place of 5** a legal notice, here is a blessing: 6** 7** May you do good and not evil. 8** May you find forgiveness for yourself and forgive others. --- 83 unchanged lines hidden (view full) --- 92** numbers used in [SQLITE_VERSION].)^ 93** The SQLITE_VERSION_NUMBER for any given release of SQLite will also 94** be larger than the release from which it is derived. Either Y will 95** be held constant and Z will be incremented or else Y will be incremented 96** and Z will be reset to zero. 97** 98** Since version 3.6.18, SQLite source code has been stored in the 99** <a href="http://www.fossil-scm.org/">Fossil configuration management | 1/* 2** 2001 September 15 3** 4** The author disclaims copyright to this source code. In place of 5** a legal notice, here is a blessing: 6** 7** May you do good and not evil. 8** May you find forgiveness for yourself and forgive others. --- 83 unchanged lines hidden (view full) --- 92** numbers used in [SQLITE_VERSION].)^ 93** The SQLITE_VERSION_NUMBER for any given release of SQLite will also 94** be larger than the release from which it is derived. Either Y will 95** be held constant and Z will be incremented or else Y will be incremented 96** and Z will be reset to zero. 97** 98** Since version 3.6.18, SQLite source code has been stored in the 99** <a href="http://www.fossil-scm.org/">Fossil configuration management |
100** system. ^The SQLITE_SOURCE_ID macro evalutes to | 100** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to |
101** a string which identifies a particular check-in of SQLite 102** within its configuration management system. ^The SQLITE_SOURCE_ID 103** string contains the date and time of the check-in (UTC) and an SHA1 104** hash of the entire source tree. 105** 106** See also: [sqlite3_libversion()], 107** [sqlite3_libversion_number()], [sqlite3_sourceid()], 108** [sqlite_version()] and [sqlite_source_id()]. 109*/ | 101** a string which identifies a particular check-in of SQLite 102** within its configuration management system. ^The SQLITE_SOURCE_ID 103** string contains the date and time of the check-in (UTC) and an SHA1 104** hash of the entire source tree. 105** 106** See also: [sqlite3_libversion()], 107** [sqlite3_libversion_number()], [sqlite3_sourceid()], 108** [sqlite_version()] and [sqlite_source_id()]. 109*/ |
110#define SQLITE_VERSION "3.6.23.1" 111#define SQLITE_VERSION_NUMBER 3006023 112#define SQLITE_SOURCE_ID "2010-03-26 22:28:06 b078b588d617e07886ad156e9f54ade6d823568e" | 110#define SQLITE_VERSION "3.7.8" 111#define SQLITE_VERSION_NUMBER 3007008 112#define SQLITE_SOURCE_ID "2011-09-19 14:49:19 3e0da808d2f5b4d12046e05980ca04578f581177" |
113 114/* 115** CAPI3REF: Run-Time Library Version Numbers 116** KEYWORDS: sqlite3_version, sqlite3_sourceid 117** 118** These interfaces provide the same information as the [SQLITE_VERSION], 119** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros 120** but are associated with the library instead of the header file. ^(Cautious --- 9 unchanged lines hidden (view full) --- 130** </pre></blockquote>)^ 131** 132** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION] 133** macro. ^The sqlite3_libversion() function returns a pointer to the 134** to the sqlite3_version[] string constant. The sqlite3_libversion() 135** function is provided for use in DLLs since DLL users usually do not have 136** direct access to string constants within the DLL. ^The 137** sqlite3_libversion_number() function returns an integer equal to | 113 114/* 115** CAPI3REF: Run-Time Library Version Numbers 116** KEYWORDS: sqlite3_version, sqlite3_sourceid 117** 118** These interfaces provide the same information as the [SQLITE_VERSION], 119** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros 120** but are associated with the library instead of the header file. ^(Cautious --- 9 unchanged lines hidden (view full) --- 130** </pre></blockquote>)^ 131** 132** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION] 133** macro. ^The sqlite3_libversion() function returns a pointer to the 134** to the sqlite3_version[] string constant. The sqlite3_libversion() 135** function is provided for use in DLLs since DLL users usually do not have 136** direct access to string constants within the DLL. ^The 137** sqlite3_libversion_number() function returns an integer equal to |
138** [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns 139** a pointer to a string constant whose value is the same as the | 138** [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns 139** a pointer to a string constant whose value is the same as the |
140** [SQLITE_SOURCE_ID] C preprocessor macro. 141** 142** See also: [sqlite_version()] and [sqlite_source_id()]. 143*/ 144SQLITE_API SQLITE_EXTERN const char sqlite3_version[]; 145SQLITE_API const char *sqlite3_libversion(void); 146SQLITE_API const char *sqlite3_sourceid(void); 147SQLITE_API int sqlite3_libversion_number(void); 148 | 140** [SQLITE_SOURCE_ID] C preprocessor macro. 141** 142** See also: [sqlite_version()] and [sqlite_source_id()]. 143*/ 144SQLITE_API SQLITE_EXTERN const char sqlite3_version[]; 145SQLITE_API const char *sqlite3_libversion(void); 146SQLITE_API const char *sqlite3_sourceid(void); 147SQLITE_API int sqlite3_libversion_number(void); 148 |
149#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS | |
150/* 151** CAPI3REF: Run-Time Library Compilation Options Diagnostics 152** | 149/* 150** CAPI3REF: Run-Time Library Compilation Options Diagnostics 151** |
153** ^The sqlite3_compileoption_used() function returns 0 or 1 154** indicating whether the specified option was defined at 155** compile time. ^The SQLITE_ prefix may be omitted from the 156** option name passed to sqlite3_compileoption_used(). | 152** ^The sqlite3_compileoption_used() function returns 0 or 1 153** indicating whether the specified option was defined at 154** compile time. ^The SQLITE_ prefix may be omitted from the 155** option name passed to sqlite3_compileoption_used(). |
157** | 156** |
158** ^The sqlite3_compileoption_get() function allows interating | 157** ^The sqlite3_compileoption_get() function allows iterating |
159** over the list of options that were defined at compile time by 160** returning the N-th compile time option string. ^If N is out of range, | 158** over the list of options that were defined at compile time by 159** returning the N-th compile time option string. ^If N is out of range, |
161** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_ 162** prefix is omitted from any strings returned by | 160** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_ 161** prefix is omitted from any strings returned by |
163** sqlite3_compileoption_get(). 164** 165** ^Support for the diagnostic functions sqlite3_compileoption_used() | 162** sqlite3_compileoption_get(). 163** 164** ^Support for the diagnostic functions sqlite3_compileoption_used() |
166** and sqlite3_compileoption_get() may be omitted by specifing the | 165** and sqlite3_compileoption_get() may be omitted by specifying the |
167** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time. 168** 169** See also: SQL functions [sqlite_compileoption_used()] and 170** [sqlite_compileoption_get()] and the [compile_options pragma]. 171*/ | 166** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time. 167** 168** See also: SQL functions [sqlite_compileoption_used()] and 169** [sqlite_compileoption_get()] and the [compile_options pragma]. 170*/ |
171#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS |
|
172SQLITE_API int sqlite3_compileoption_used(const char *zOptName); 173SQLITE_API const char *sqlite3_compileoption_get(int N); | 172SQLITE_API int sqlite3_compileoption_used(const char *zOptName); 173SQLITE_API const char *sqlite3_compileoption_get(int N); |
174#endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */ | 174#endif |
175 176/* 177** CAPI3REF: Test To See If The Library Is Threadsafe 178** 179** ^The sqlite3_threadsafe() function returns zero if and only if 180** SQLite was compiled mutexing code omitted due to the 181** [SQLITE_THREADSAFE] compile-time option being set to 0. 182** 183** SQLite can be compiled with or without mutexes. When 184** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes 185** are enabled and SQLite is threadsafe. When the | 175 176/* 177** CAPI3REF: Test To See If The Library Is Threadsafe 178** 179** ^The sqlite3_threadsafe() function returns zero if and only if 180** SQLite was compiled mutexing code omitted due to the 181** [SQLITE_THREADSAFE] compile-time option being set to 0. 182** 183** SQLite can be compiled with or without mutexes. When 184** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes 185** are enabled and SQLite is threadsafe. When the |
186** [SQLITE_THREADSAFE] macro is 0, | 186** [SQLITE_THREADSAFE] macro is 0, |
187** the mutexes are omitted. Without the mutexes, it is not safe 188** to use SQLite concurrently from more than one thread. 189** 190** Enabling mutexes incurs a measurable performance penalty. 191** So if speed is of utmost importance, it makes sense to disable 192** the mutexes. But for maximum safety, mutexes should be enabled. 193** ^The default behavior is for mutexes to be enabled. 194** --- 39 unchanged lines hidden (view full) --- 234** SQLite includes typedefs for 64-bit signed and unsigned integers. 235** 236** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions. 237** The sqlite_int64 and sqlite_uint64 types are supported for backwards 238** compatibility only. 239** 240** ^The sqlite3_int64 and sqlite_int64 types can store integer values 241** between -9223372036854775808 and +9223372036854775807 inclusive. ^The | 187** the mutexes are omitted. Without the mutexes, it is not safe 188** to use SQLite concurrently from more than one thread. 189** 190** Enabling mutexes incurs a measurable performance penalty. 191** So if speed is of utmost importance, it makes sense to disable 192** the mutexes. But for maximum safety, mutexes should be enabled. 193** ^The default behavior is for mutexes to be enabled. 194** --- 39 unchanged lines hidden (view full) --- 234** SQLite includes typedefs for 64-bit signed and unsigned integers. 235** 236** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions. 237** The sqlite_int64 and sqlite_uint64 types are supported for backwards 238** compatibility only. 239** 240** ^The sqlite3_int64 and sqlite_int64 types can store integer values 241** between -9223372036854775808 and +9223372036854775807 inclusive. ^The |
242** sqlite3_uint64 and sqlite_uint64 types can store integer values | 242** sqlite3_uint64 and sqlite_uint64 types can store integer values |
243** between 0 and +18446744073709551615 inclusive. 244*/ 245#ifdef SQLITE_INT64_TYPE 246 typedef SQLITE_INT64_TYPE sqlite_int64; 247 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; 248#elif defined(_MSC_VER) || defined(__BORLANDC__) 249 typedef __int64 sqlite_int64; 250 typedef unsigned __int64 sqlite_uint64; --- 12 unchanged lines hidden (view full) --- 263# define double sqlite3_int64 264#endif 265 266/* 267** CAPI3REF: Closing A Database Connection 268** 269** ^The sqlite3_close() routine is the destructor for the [sqlite3] object. 270** ^Calls to sqlite3_close() return SQLITE_OK if the [sqlite3] object is | 243** between 0 and +18446744073709551615 inclusive. 244*/ 245#ifdef SQLITE_INT64_TYPE 246 typedef SQLITE_INT64_TYPE sqlite_int64; 247 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; 248#elif defined(_MSC_VER) || defined(__BORLANDC__) 249 typedef __int64 sqlite_int64; 250 typedef unsigned __int64 sqlite_uint64; --- 12 unchanged lines hidden (view full) --- 263# define double sqlite3_int64 264#endif 265 266/* 267** CAPI3REF: Closing A Database Connection 268** 269** ^The sqlite3_close() routine is the destructor for the [sqlite3] object. 270** ^Calls to sqlite3_close() return SQLITE_OK if the [sqlite3] object is |
271** successfullly destroyed and all associated resources are deallocated. | 271** successfully destroyed and all associated resources are deallocated. |
272** 273** Applications must [sqlite3_finalize | finalize] all [prepared statements] 274** and [sqlite3_blob_close | close] all [BLOB handles] associated with 275** the [sqlite3] object prior to attempting to close the object. ^If 276** sqlite3_close() is called on a [database connection] that still has 277** outstanding [prepared statements] or [BLOB handles], then it returns 278** SQLITE_BUSY. 279** 280** ^If [sqlite3_close()] is invoked while a transaction is open, 281** the transaction is automatically rolled back. 282** 283** The C parameter to [sqlite3_close(C)] must be either a NULL 284** pointer or an [sqlite3] object pointer obtained 285** from [sqlite3_open()], [sqlite3_open16()], or 286** [sqlite3_open_v2()], and not previously closed. | 272** 273** Applications must [sqlite3_finalize | finalize] all [prepared statements] 274** and [sqlite3_blob_close | close] all [BLOB handles] associated with 275** the [sqlite3] object prior to attempting to close the object. ^If 276** sqlite3_close() is called on a [database connection] that still has 277** outstanding [prepared statements] or [BLOB handles], then it returns 278** SQLITE_BUSY. 279** 280** ^If [sqlite3_close()] is invoked while a transaction is open, 281** the transaction is automatically rolled back. 282** 283** The C parameter to [sqlite3_close(C)] must be either a NULL 284** pointer or an [sqlite3] object pointer obtained 285** from [sqlite3_open()], [sqlite3_open16()], or 286** [sqlite3_open_v2()], and not previously closed. |
287** ^Calling sqlite3_close() with a NULL pointer argument is a | 287** ^Calling sqlite3_close() with a NULL pointer argument is a |
288** harmless no-op. 289*/ 290SQLITE_API int sqlite3_close(sqlite3 *); 291 292/* 293** The type for a callback function. 294** This is legacy and deprecated. It is included for historical 295** compatibility and is not documented. 296*/ 297typedef int (*sqlite3_callback)(void*,int,char**, char**); 298 299/* 300** CAPI3REF: One-Step Query Execution Interface 301** 302** The sqlite3_exec() interface is a convenience wrapper around 303** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()], 304** that allows an application to run multiple statements of SQL | 288** harmless no-op. 289*/ 290SQLITE_API int sqlite3_close(sqlite3 *); 291 292/* 293** The type for a callback function. 294** This is legacy and deprecated. It is included for historical 295** compatibility and is not documented. 296*/ 297typedef int (*sqlite3_callback)(void*,int,char**, char**); 298 299/* 300** CAPI3REF: One-Step Query Execution Interface 301** 302** The sqlite3_exec() interface is a convenience wrapper around 303** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()], 304** that allows an application to run multiple statements of SQL |
305** without having to use a lot of C code. | 305** without having to use a lot of C code. |
306** 307** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded, 308** semicolon-separate SQL statements passed into its 2nd argument, 309** in the context of the [database connection] passed in as its 1st 310** argument. ^If the callback function of the 3rd argument to 311** sqlite3_exec() is not NULL, then it is invoked for each result row 312** coming out of the evaluated SQL statements. ^The 4th argument to | 306** 307** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded, 308** semicolon-separate SQL statements passed into its 2nd argument, 309** in the context of the [database connection] passed in as its 1st 310** argument. ^If the callback function of the 3rd argument to 311** sqlite3_exec() is not NULL, then it is invoked for each result row 312** coming out of the evaluated SQL statements. ^The 4th argument to |
313** to sqlite3_exec() is relayed through to the 1st argument of each | 313** sqlite3_exec() is relayed through to the 1st argument of each |
314** callback invocation. ^If the callback pointer to sqlite3_exec() 315** is NULL, then no callback is ever invoked and result rows are 316** ignored. 317** 318** ^If an error occurs while evaluating the SQL statements passed into 319** sqlite3_exec(), then execution of the current statement stops and 320** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec() 321** is not NULL then any error message is written into memory obtained --- 15 unchanged lines hidden (view full) --- 337** [sqlite3_column_text()], one for each column. ^If an element of a 338** result row is NULL then the corresponding string pointer for the 339** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the 340** sqlite3_exec() callback is an array of pointers to strings where each 341** entry represents the name of corresponding result column as obtained 342** from [sqlite3_column_name()]. 343** 344** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer | 314** callback invocation. ^If the callback pointer to sqlite3_exec() 315** is NULL, then no callback is ever invoked and result rows are 316** ignored. 317** 318** ^If an error occurs while evaluating the SQL statements passed into 319** sqlite3_exec(), then execution of the current statement stops and 320** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec() 321** is not NULL then any error message is written into memory obtained --- 15 unchanged lines hidden (view full) --- 337** [sqlite3_column_text()], one for each column. ^If an element of a 338** result row is NULL then the corresponding string pointer for the 339** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the 340** sqlite3_exec() callback is an array of pointers to strings where each 341** entry represents the name of corresponding result column as obtained 342** from [sqlite3_column_name()]. 343** 344** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer |
345** to an empty string, or a pointer that contains only whitespace and/or | 345** to an empty string, or a pointer that contains only whitespace and/or |
346** SQL comments, then no SQL statements are evaluated and the database 347** is not changed. 348** 349** Restrictions: 350** 351** <ul> 352** <li> The application must insure that the 1st parameter to sqlite3_exec() 353** is a valid and open [database connection]. --- 16 unchanged lines hidden (view full) --- 370** KEYWORDS: SQLITE_OK {error code} {error codes} 371** KEYWORDS: {result code} {result codes} 372** 373** Many SQLite functions return an integer result code from the set shown 374** here in order to indicates success or failure. 375** 376** New error codes may be added in future versions of SQLite. 377** | 346** SQL comments, then no SQL statements are evaluated and the database 347** is not changed. 348** 349** Restrictions: 350** 351** <ul> 352** <li> The application must insure that the 1st parameter to sqlite3_exec() 353** is a valid and open [database connection]. --- 16 unchanged lines hidden (view full) --- 370** KEYWORDS: SQLITE_OK {error code} {error codes} 371** KEYWORDS: {result code} {result codes} 372** 373** Many SQLite functions return an integer result code from the set shown 374** here in order to indicates success or failure. 375** 376** New error codes may be added in future versions of SQLite. 377** |
378** See also: [SQLITE_IOERR_READ | extended result codes] | 378** See also: [SQLITE_IOERR_READ | extended result codes], 379** [sqlite3_vtab_on_conflict()] [SQLITE_ROLLBACK | result codes]. |
379*/ 380#define SQLITE_OK 0 /* Successful result */ 381/* beginning-of-error-codes */ 382#define SQLITE_ERROR 1 /* SQL error or missing database */ 383#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */ 384#define SQLITE_PERM 3 /* Access permission denied */ 385#define SQLITE_ABORT 4 /* Callback routine requested an abort */ 386#define SQLITE_BUSY 5 /* The database file is locked */ 387#define SQLITE_LOCKED 6 /* A table in the database is locked */ 388#define SQLITE_NOMEM 7 /* A malloc() failed */ 389#define SQLITE_READONLY 8 /* Attempt to write a readonly database */ 390#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ 391#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ 392#define SQLITE_CORRUPT 11 /* The database disk image is malformed */ | 380*/ 381#define SQLITE_OK 0 /* Successful result */ 382/* beginning-of-error-codes */ 383#define SQLITE_ERROR 1 /* SQL error or missing database */ 384#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */ 385#define SQLITE_PERM 3 /* Access permission denied */ 386#define SQLITE_ABORT 4 /* Callback routine requested an abort */ 387#define SQLITE_BUSY 5 /* The database file is locked */ 388#define SQLITE_LOCKED 6 /* A table in the database is locked */ 389#define SQLITE_NOMEM 7 /* A malloc() failed */ 390#define SQLITE_READONLY 8 /* Attempt to write a readonly database */ 391#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ 392#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ 393#define SQLITE_CORRUPT 11 /* The database disk image is malformed */ |
393#define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */ | 394#define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */ |
394#define SQLITE_FULL 13 /* Insertion failed because database is full */ 395#define SQLITE_CANTOPEN 14 /* Unable to open the database file */ | 395#define SQLITE_FULL 13 /* Insertion failed because database is full */ 396#define SQLITE_CANTOPEN 14 /* Unable to open the database file */ |
396#define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */ | 397#define SQLITE_PROTOCOL 15 /* Database lock protocol error */ |
397#define SQLITE_EMPTY 16 /* Database is empty */ 398#define SQLITE_SCHEMA 17 /* The database schema changed */ 399#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */ 400#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */ 401#define SQLITE_MISMATCH 20 /* Data type mismatch */ 402#define SQLITE_MISUSE 21 /* Library used incorrectly */ 403#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ 404#define SQLITE_AUTH 23 /* Authorization denied */ --- 39 unchanged lines hidden (view full) --- 444#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) 445#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) 446#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) 447#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8)) 448#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8)) 449#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8)) 450#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8)) 451#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8)) | 398#define SQLITE_EMPTY 16 /* Database is empty */ 399#define SQLITE_SCHEMA 17 /* The database schema changed */ 400#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */ 401#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */ 402#define SQLITE_MISMATCH 20 /* Data type mismatch */ 403#define SQLITE_MISUSE 21 /* Library used incorrectly */ 404#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ 405#define SQLITE_AUTH 23 /* Authorization denied */ --- 39 unchanged lines hidden (view full) --- 445#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) 446#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) 447#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) 448#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8)) 449#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8)) 450#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8)) 451#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8)) 452#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8)) |
452#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8) ) | 453#define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8)) 454#define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8)) 455#define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8)) 456#define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8)) 457#define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8)) 458#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8)) 459#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8)) 460#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8)) 461#define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8)) 462#define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8)) 463#define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8)) |
453 454/* 455** CAPI3REF: Flags For File Open Operations 456** 457** These bit values are intended for use in the 458** 3rd parameter to the [sqlite3_open_v2()] interface and | 464 465/* 466** CAPI3REF: Flags For File Open Operations 467** 468** These bit values are intended for use in the 469** 3rd parameter to the [sqlite3_open_v2()] interface and |
459** in the 4th parameter to the xOpen method of the 460** [sqlite3_vfs] object. | 470** in the 4th parameter to the [sqlite3_vfs.xOpen] method. |
461*/ 462#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */ 463#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */ 464#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */ 465#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */ 466#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */ 467#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */ | 471*/ 472#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */ 473#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */ 474#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */ 475#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */ 476#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */ 477#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */ |
478#define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */ |
|
468#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */ 469#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */ 470#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */ 471#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */ 472#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */ 473#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */ 474#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */ 475#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */ 476#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */ 477#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */ 478#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */ | 479#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */ 480#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */ 481#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */ 482#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */ 483#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */ 484#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */ 485#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */ 486#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */ 487#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */ 488#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */ 489#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */ |
490#define SQLITE_OPEN_WAL 0x00080000 /* VFS only */ |
|
479 | 491 |
492/* Reserved: 0x00F00000 */ 493 |
|
480/* 481** CAPI3REF: Device Characteristics 482** | 494/* 495** CAPI3REF: Device Characteristics 496** |
483** The xDeviceCapabilities method of the [sqlite3_io_methods] | 497** The xDeviceCharacteristics method of the [sqlite3_io_methods] |
484** object returns an integer which is a vector of the these 485** bit values expressing I/O characteristics of the mass storage 486** device that holds the file that the [sqlite3_io_methods] 487** refers to. 488** 489** The SQLITE_IOCAP_ATOMIC property means that all writes of 490** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values 491** mean that writes of blocks that are nnn bytes in size and 492** are aligned to an address which is an integer multiple of 493** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means 494** that when data is appended to a file, the data is appended 495** first then the size of the file is extended, never the other 496** way around. The SQLITE_IOCAP_SEQUENTIAL property means that 497** information is written to disk in the same order as calls 498** to xWrite(). 499*/ | 498** object returns an integer which is a vector of the these 499** bit values expressing I/O characteristics of the mass storage 500** device that holds the file that the [sqlite3_io_methods] 501** refers to. 502** 503** The SQLITE_IOCAP_ATOMIC property means that all writes of 504** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values 505** mean that writes of blocks that are nnn bytes in size and 506** are aligned to an address which is an integer multiple of 507** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means 508** that when data is appended to a file, the data is appended 509** first then the size of the file is extended, never the other 510** way around. The SQLITE_IOCAP_SEQUENTIAL property means that 511** information is written to disk in the same order as calls 512** to xWrite(). 513*/ |
500#define SQLITE_IOCAP_ATOMIC 0x00000001 501#define SQLITE_IOCAP_ATOMIC512 0x00000002 502#define SQLITE_IOCAP_ATOMIC1K 0x00000004 503#define SQLITE_IOCAP_ATOMIC2K 0x00000008 504#define SQLITE_IOCAP_ATOMIC4K 0x00000010 505#define SQLITE_IOCAP_ATOMIC8K 0x00000020 506#define SQLITE_IOCAP_ATOMIC16K 0x00000040 507#define SQLITE_IOCAP_ATOMIC32K 0x00000080 508#define SQLITE_IOCAP_ATOMIC64K 0x00000100 509#define SQLITE_IOCAP_SAFE_APPEND 0x00000200 510#define SQLITE_IOCAP_SEQUENTIAL 0x00000400 | 514#define SQLITE_IOCAP_ATOMIC 0x00000001 515#define SQLITE_IOCAP_ATOMIC512 0x00000002 516#define SQLITE_IOCAP_ATOMIC1K 0x00000004 517#define SQLITE_IOCAP_ATOMIC2K 0x00000008 518#define SQLITE_IOCAP_ATOMIC4K 0x00000010 519#define SQLITE_IOCAP_ATOMIC8K 0x00000020 520#define SQLITE_IOCAP_ATOMIC16K 0x00000040 521#define SQLITE_IOCAP_ATOMIC32K 0x00000080 522#define SQLITE_IOCAP_ATOMIC64K 0x00000100 523#define SQLITE_IOCAP_SAFE_APPEND 0x00000200 524#define SQLITE_IOCAP_SEQUENTIAL 0x00000400 525#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800 |
511 512/* 513** CAPI3REF: File Locking Levels 514** 515** SQLite uses one of these integer values as the second 516** argument to calls it makes to the xLock() and xUnlock() methods 517** of an [sqlite3_io_methods] object. 518*/ --- 11 unchanged lines hidden (view full) --- 530** these integer values as the second argument. 531** 532** When the SQLITE_SYNC_DATAONLY flag is used, it means that the 533** sync operation only needs to flush data to mass storage. Inode 534** information need not be flushed. If the lower four bits of the flag 535** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics. 536** If the lower four bits equal SQLITE_SYNC_FULL, that means 537** to use Mac OS X style fullsync instead of fsync(). | 526 527/* 528** CAPI3REF: File Locking Levels 529** 530** SQLite uses one of these integer values as the second 531** argument to calls it makes to the xLock() and xUnlock() methods 532** of an [sqlite3_io_methods] object. 533*/ --- 11 unchanged lines hidden (view full) --- 545** these integer values as the second argument. 546** 547** When the SQLITE_SYNC_DATAONLY flag is used, it means that the 548** sync operation only needs to flush data to mass storage. Inode 549** information need not be flushed. If the lower four bits of the flag 550** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics. 551** If the lower four bits equal SQLITE_SYNC_FULL, that means 552** to use Mac OS X style fullsync instead of fsync(). |
553** 554** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags 555** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL 556** settings. The [synchronous pragma] determines when calls to the 557** xSync VFS method occur and applies uniformly across all platforms. 558** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how 559** energetic or rigorous or forceful the sync operations are and 560** only make a difference on Mac OSX for the default SQLite code. 561** (Third-party VFS implementations might also make the distinction 562** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the 563** operating systems natively supported by SQLite, only Mac OSX 564** cares about the difference.) |
|
538*/ 539#define SQLITE_SYNC_NORMAL 0x00002 540#define SQLITE_SYNC_FULL 0x00003 541#define SQLITE_SYNC_DATAONLY 0x00010 542 543/* 544** CAPI3REF: OS Interface Open File Handle 545** | 565*/ 566#define SQLITE_SYNC_NORMAL 0x00002 567#define SQLITE_SYNC_FULL 0x00003 568#define SQLITE_SYNC_DATAONLY 0x00010 569 570/* 571** CAPI3REF: OS Interface Open File Handle 572** |
546** An [sqlite3_file] object represents an open file in the | 573** An [sqlite3_file] object represents an open file in the |
547** [sqlite3_vfs | OS interface layer]. Individual OS interface 548** implementations will 549** want to subclass this object by appending additional fields 550** for their own use. The pMethods entry is a pointer to an 551** [sqlite3_io_methods] object that defines methods for performing 552** I/O operations on the open file. 553*/ 554typedef struct sqlite3_file sqlite3_file; 555struct sqlite3_file { 556 const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ 557}; 558 559/* 560** CAPI3REF: OS Interface File Virtual Methods Object 561** | 574** [sqlite3_vfs | OS interface layer]. Individual OS interface 575** implementations will 576** want to subclass this object by appending additional fields 577** for their own use. The pMethods entry is a pointer to an 578** [sqlite3_io_methods] object that defines methods for performing 579** I/O operations on the open file. 580*/ 581typedef struct sqlite3_file sqlite3_file; 582struct sqlite3_file { 583 const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ 584}; 585 586/* 587** CAPI3REF: OS Interface File Virtual Methods Object 588** |
562** Every file opened by the [sqlite3_vfs] xOpen method populates an | 589** Every file opened by the [sqlite3_vfs.xOpen] method populates an |
563** [sqlite3_file] object (or, more commonly, a subclass of the 564** [sqlite3_file] object) with a pointer to an instance of this object. 565** This object defines the methods used to perform various operations 566** against the open file represented by the [sqlite3_file] object. 567** | 590** [sqlite3_file] object (or, more commonly, a subclass of the 591** [sqlite3_file] object) with a pointer to an instance of this object. 592** This object defines the methods used to perform various operations 593** against the open file represented by the [sqlite3_file] object. 594** |
568** If the xOpen method sets the sqlite3_file.pMethods element | 595** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element |
569** to a non-NULL pointer, then the sqlite3_io_methods.xClose method | 596** to a non-NULL pointer, then the sqlite3_io_methods.xClose method |
570** may be invoked even if the xOpen reported that it failed. The 571** only way to prevent a call to xClose following a failed xOpen 572** is for the xOpen to set the sqlite3_file.pMethods element to NULL. | 597** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed. The 598** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen] 599** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element 600** to NULL. |
573** 574** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or 575** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). 576** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY] 577** flag may be ORed in to indicate that only the data of the file 578** and not its inode needs to be synced. 579** 580** The integer values to xLock() and xUnlock() are one of --- 17 unchanged lines hidden (view full) --- 598** point to a structure that may contain arguments or space in which to 599** write return values. Potential uses for xFileControl() might be 600** functions to enable blocking locks with timeouts, to change the 601** locking strategy (for example to use dot-file locks), to inquire 602** about the status of a lock, or to break stale locks. The SQLite 603** core reserves all opcodes less than 100 for its own use. 604** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. 605** Applications that define a custom xFileControl method should use opcodes | 601** 602** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or 603** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). 604** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY] 605** flag may be ORed in to indicate that only the data of the file 606** and not its inode needs to be synced. 607** 608** The integer values to xLock() and xUnlock() are one of --- 17 unchanged lines hidden (view full) --- 626** point to a structure that may contain arguments or space in which to 627** write return values. Potential uses for xFileControl() might be 628** functions to enable blocking locks with timeouts, to change the 629** locking strategy (for example to use dot-file locks), to inquire 630** about the status of a lock, or to break stale locks. The SQLite 631** core reserves all opcodes less than 100 for its own use. 632** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. 633** Applications that define a custom xFileControl method should use opcodes |
606** greater than 100 to avoid conflicts. | 634** greater than 100 to avoid conflicts. VFS implementations should 635** return [SQLITE_NOTFOUND] for file control opcodes that they do not 636** recognize. |
607** 608** The xSectorSize() method returns the sector size of the 609** device that underlies the file. The sector size is the 610** minimum write that can be performed without disturbing 611** other bytes in the file. The xDeviceCharacteristics() 612** method returns a bit vector describing behaviors of the 613** underlying device: 614** --- 38 unchanged lines hidden (view full) --- 653 int (*xSync)(sqlite3_file*, int flags); 654 int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); 655 int (*xLock)(sqlite3_file*, int); 656 int (*xUnlock)(sqlite3_file*, int); 657 int (*xCheckReservedLock)(sqlite3_file*, int *pResOut); 658 int (*xFileControl)(sqlite3_file*, int op, void *pArg); 659 int (*xSectorSize)(sqlite3_file*); 660 int (*xDeviceCharacteristics)(sqlite3_file*); | 637** 638** The xSectorSize() method returns the sector size of the 639** device that underlies the file. The sector size is the 640** minimum write that can be performed without disturbing 641** other bytes in the file. The xDeviceCharacteristics() 642** method returns a bit vector describing behaviors of the 643** underlying device: 644** --- 38 unchanged lines hidden (view full) --- 683 int (*xSync)(sqlite3_file*, int flags); 684 int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); 685 int (*xLock)(sqlite3_file*, int); 686 int (*xUnlock)(sqlite3_file*, int); 687 int (*xCheckReservedLock)(sqlite3_file*, int *pResOut); 688 int (*xFileControl)(sqlite3_file*, int op, void *pArg); 689 int (*xSectorSize)(sqlite3_file*); 690 int (*xDeviceCharacteristics)(sqlite3_file*); |
691 /* Methods above are valid for version 1 */ 692 int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**); 693 int (*xShmLock)(sqlite3_file*, int offset, int n, int flags); 694 void (*xShmBarrier)(sqlite3_file*); 695 int (*xShmUnmap)(sqlite3_file*, int deleteFlag); 696 /* Methods above are valid for version 2 */ |
|
661 /* Additional methods may be added in future releases */ 662}; 663 664/* 665** CAPI3REF: Standard File Control Opcodes 666** 667** These integer constants are opcodes for the xFileControl method 668** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()] 669** interface. 670** 671** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This 672** opcode causes the xFileControl method to write the current state of 673** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED], 674** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE]) 675** into an integer that the pArg argument points to. This capability 676** is used during testing and only needs to be supported when SQLITE_TEST 677** is defined. | 697 /* Additional methods may be added in future releases */ 698}; 699 700/* 701** CAPI3REF: Standard File Control Opcodes 702** 703** These integer constants are opcodes for the xFileControl method 704** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()] 705** interface. 706** 707** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This 708** opcode causes the xFileControl method to write the current state of 709** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED], 710** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE]) 711** into an integer that the pArg argument points to. This capability 712** is used during testing and only needs to be supported when SQLITE_TEST 713** is defined. |
714** 715** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS 716** layer a hint of how large the database file will grow to be during the 717** current transaction. This hint is not guaranteed to be accurate but it 718** is often close. The underlying VFS might choose to preallocate database 719** file space based on this hint in order to help writes to the database 720** file run faster. 721** 722** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS 723** extends and truncates the database file in chunks of a size specified 724** by the user. The fourth argument to [sqlite3_file_control()] should 725** point to an integer (type int) containing the new chunk-size to use 726** for the nominated database. Allocating database file space in large 727** chunks (say 1MB at a time), may reduce file-system fragmentation and 728** improve performance on some systems. 729** 730** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer 731** to the [sqlite3_file] object associated with a particular database 732** connection. See the [sqlite3_file_control()] documentation for 733** additional information. 734** 735** ^(The [SQLITE_FCNTL_SYNC_OMITTED] opcode is generated internally by 736** SQLite and sent to all VFSes in place of a call to the xSync method 737** when the database connection has [PRAGMA synchronous] set to OFF.)^ 738** Some specialized VFSes need this signal in order to operate correctly 739** when [PRAGMA synchronous | PRAGMA synchronous=OFF] is set, but most 740** VFSes do not need this signal and should silently ignore this opcode. 741** Applications should not call [sqlite3_file_control()] with this 742** opcode as doing so may disrupt the operation of the specialized VFSes 743** that do require it. 744** 745** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic 746** retry counts and intervals for certain disk I/O operations for the 747** windows [VFS] in order to work to provide robustness against 748** anti-virus programs. By default, the windows VFS will retry file read, 749** file write, and file delete opertions up to 10 times, with a delay 750** of 25 milliseconds before the first retry and with the delay increasing 751** by an additional 25 milliseconds with each subsequent retry. This 752** opcode allows those to values (10 retries and 25 milliseconds of delay) 753** to be adjusted. The values are changed for all database connections 754** within the same process. The argument is a pointer to an array of two 755** integers where the first integer i the new retry count and the second 756** integer is the delay. If either integer is negative, then the setting 757** is not changed but instead the prior value of that setting is written 758** into the array entry, allowing the current retry settings to be 759** interrogated. The zDbName parameter is ignored. 760** 761** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the 762** persistent [WAL | Write AHead Log] setting. By default, the auxiliary 763** write ahead log and shared memory files used for transaction control 764** are automatically deleted when the latest connection to the database 765** closes. Setting persistent WAL mode causes those files to persist after 766** close. Persisting the files is useful when other processes that do not 767** have write permission on the directory containing the database file want 768** to read the database file, as the WAL and shared memory files must exist 769** in order for the database to be readable. The fourth parameter to 770** [sqlite3_file_control()] for this opcode should be a pointer to an integer. 771** That integer is 0 to disable persistent WAL mode or 1 to enable persistent 772** WAL mode. If the integer is -1, then it is overwritten with the current 773** WAL persistence setting. 774** |
|
678*/ 679#define SQLITE_FCNTL_LOCKSTATE 1 680#define SQLITE_GET_LOCKPROXYFILE 2 681#define SQLITE_SET_LOCKPROXYFILE 3 682#define SQLITE_LAST_ERRNO 4 | 775*/ 776#define SQLITE_FCNTL_LOCKSTATE 1 777#define SQLITE_GET_LOCKPROXYFILE 2 778#define SQLITE_SET_LOCKPROXYFILE 3 779#define SQLITE_LAST_ERRNO 4 |
780#define SQLITE_FCNTL_SIZE_HINT 5 781#define SQLITE_FCNTL_CHUNK_SIZE 6 782#define SQLITE_FCNTL_FILE_POINTER 7 783#define SQLITE_FCNTL_SYNC_OMITTED 8 784#define SQLITE_FCNTL_WIN32_AV_RETRY 9 785#define SQLITE_FCNTL_PERSIST_WAL 10 |
|
683 684/* 685** CAPI3REF: Mutex Handle 686** 687** The mutex module within SQLite defines [sqlite3_mutex] to be an 688** abstract type for a mutex object. The SQLite core never looks 689** at the internal representation of an [sqlite3_mutex]. It only 690** deals with pointers to the [sqlite3_mutex] object. 691** 692** Mutexes are created using [sqlite3_mutex_alloc()]. 693*/ 694typedef struct sqlite3_mutex sqlite3_mutex; 695 696/* 697** CAPI3REF: OS Interface Object 698** 699** An instance of the sqlite3_vfs object defines the interface between 700** the SQLite core and the underlying operating system. The "vfs" | 786 787/* 788** CAPI3REF: Mutex Handle 789** 790** The mutex module within SQLite defines [sqlite3_mutex] to be an 791** abstract type for a mutex object. The SQLite core never looks 792** at the internal representation of an [sqlite3_mutex]. It only 793** deals with pointers to the [sqlite3_mutex] object. 794** 795** Mutexes are created using [sqlite3_mutex_alloc()]. 796*/ 797typedef struct sqlite3_mutex sqlite3_mutex; 798 799/* 800** CAPI3REF: OS Interface Object 801** 802** An instance of the sqlite3_vfs object defines the interface between 803** the SQLite core and the underlying operating system. The "vfs" |
701** in the name of the object stands for "virtual file system". | 804** in the name of the object stands for "virtual file system". See 805** the [VFS | VFS documentation] for further information. |
702** 703** The value of the iVersion field is initially 1 but may be larger in 704** future versions of SQLite. Additional fields may be appended to this 705** object when the iVersion value is increased. Note that the structure 706** of the sqlite3_vfs object changes in the transaction between 707** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not 708** modified. 709** --- 12 unchanged lines hidden (view full) --- 722** structure that SQLite will ever modify. SQLite will only access 723** or modify this field while holding a particular static mutex. 724** The application should never modify anything within the sqlite3_vfs 725** object once the object has been registered. 726** 727** The zName field holds the name of the VFS module. The name must 728** be unique across all VFS modules. 729** | 806** 807** The value of the iVersion field is initially 1 but may be larger in 808** future versions of SQLite. Additional fields may be appended to this 809** object when the iVersion value is increased. Note that the structure 810** of the sqlite3_vfs object changes in the transaction between 811** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not 812** modified. 813** --- 12 unchanged lines hidden (view full) --- 826** structure that SQLite will ever modify. SQLite will only access 827** or modify this field while holding a particular static mutex. 828** The application should never modify anything within the sqlite3_vfs 829** object once the object has been registered. 830** 831** The zName field holds the name of the VFS module. The name must 832** be unique across all VFS modules. 833** |
730** SQLite will guarantee that the zFilename parameter to xOpen | 834** [[sqlite3_vfs.xOpen]] 835** ^SQLite guarantees that the zFilename parameter to xOpen |
731** is either a NULL pointer or string obtained | 836** is either a NULL pointer or string obtained |
732** from xFullPathname(). SQLite further guarantees that | 837** from xFullPathname() with an optional suffix added. 838** ^If a suffix is added to the zFilename parameter, it will 839** consist of a single "-" character followed by no more than 840** 10 alphanumeric and/or "-" characters. 841** ^SQLite further guarantees that |
733** the string will be valid and unchanged until xClose() is 734** called. Because of the previous sentence, 735** the [sqlite3_file] can safely store a pointer to the 736** filename if it needs to remember the filename for some reason. | 842** the string will be valid and unchanged until xClose() is 843** called. Because of the previous sentence, 844** the [sqlite3_file] can safely store a pointer to the 845** filename if it needs to remember the filename for some reason. |
737** If the zFilename parameter is xOpen is a NULL pointer then xOpen 738** must invent its own temporary name for the file. Whenever the | 846** If the zFilename parameter to xOpen is a NULL pointer then xOpen 847** must invent its own temporary name for the file. ^Whenever the |
739** xFilename parameter is NULL it will also be the case that the 740** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE]. 741** 742** The flags argument to xOpen() includes all bits set in 743** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()] 744** or [sqlite3_open16()] is used, then flags includes at least | 848** xFilename parameter is NULL it will also be the case that the 849** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE]. 850** 851** The flags argument to xOpen() includes all bits set in 852** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()] 853** or [sqlite3_open16()] is used, then flags includes at least |
745** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. | 854** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. |
746** If xOpen() opens a file read-only then it sets *pOutFlags to 747** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set. 748** | 855** If xOpen() opens a file read-only then it sets *pOutFlags to 856** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set. 857** |
749** SQLite will also add one of the following flags to the xOpen() | 858** ^(SQLite will also add one of the following flags to the xOpen() |
750** call, depending on the object being opened: 751** 752** <ul> 753** <li> [SQLITE_OPEN_MAIN_DB] 754** <li> [SQLITE_OPEN_MAIN_JOURNAL] 755** <li> [SQLITE_OPEN_TEMP_DB] 756** <li> [SQLITE_OPEN_TEMP_JOURNAL] 757** <li> [SQLITE_OPEN_TRANSIENT_DB] 758** <li> [SQLITE_OPEN_SUBJOURNAL] 759** <li> [SQLITE_OPEN_MASTER_JOURNAL] | 859** call, depending on the object being opened: 860** 861** <ul> 862** <li> [SQLITE_OPEN_MAIN_DB] 863** <li> [SQLITE_OPEN_MAIN_JOURNAL] 864** <li> [SQLITE_OPEN_TEMP_DB] 865** <li> [SQLITE_OPEN_TEMP_JOURNAL] 866** <li> [SQLITE_OPEN_TRANSIENT_DB] 867** <li> [SQLITE_OPEN_SUBJOURNAL] 868** <li> [SQLITE_OPEN_MASTER_JOURNAL] |
760** </ul> | 869** <li> [SQLITE_OPEN_WAL] 870** </ul>)^ |
761** 762** The file I/O implementation can use the object type flags to 763** change the way it deals with files. For example, an application 764** that does not care about crash recovery or rollback might make 765** the open of a journal file a no-op. Writes to this journal would 766** also be no-ops, and any attempt to read the journal would return 767** SQLITE_IOERR. Or the implementation might recognize that a database 768** file will be doing page-aligned sector reads and writes in a random 769** order and set up its I/O subsystem accordingly. 770** 771** SQLite might also add one of the following flags to the xOpen method: 772** 773** <ul> 774** <li> [SQLITE_OPEN_DELETEONCLOSE] 775** <li> [SQLITE_OPEN_EXCLUSIVE] 776** </ul> 777** 778** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be | 871** 872** The file I/O implementation can use the object type flags to 873** change the way it deals with files. For example, an application 874** that does not care about crash recovery or rollback might make 875** the open of a journal file a no-op. Writes to this journal would 876** also be no-ops, and any attempt to read the journal would return 877** SQLITE_IOERR. Or the implementation might recognize that a database 878** file will be doing page-aligned sector reads and writes in a random 879** order and set up its I/O subsystem accordingly. 880** 881** SQLite might also add one of the following flags to the xOpen method: 882** 883** <ul> 884** <li> [SQLITE_OPEN_DELETEONCLOSE] 885** <li> [SQLITE_OPEN_EXCLUSIVE] 886** </ul> 887** 888** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be |
779** deleted when it is closed. The [SQLITE_OPEN_DELETEONCLOSE] 780** will be set for TEMP databases, journals and for subjournals. | 889** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE] 890** will be set for TEMP databases and their journals, transient 891** databases, and subjournals. |
781** | 892** |
782** The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction | 893** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction |
783** with the [SQLITE_OPEN_CREATE] flag, which are both directly 784** analogous to the O_EXCL and O_CREAT flags of the POSIX open() | 894** with the [SQLITE_OPEN_CREATE] flag, which are both directly 895** analogous to the O_EXCL and O_CREAT flags of the POSIX open() |
785** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the | 896** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the |
786** SQLITE_OPEN_CREATE, is used to indicate that file should always 787** be created, and that it is an error if it already exists. | 897** SQLITE_OPEN_CREATE, is used to indicate that file should always 898** be created, and that it is an error if it already exists. |
788** It is not used to indicate the file should be opened | 899** It is <i>not</i> used to indicate the file should be opened |
789** for exclusive access. 790** | 900** for exclusive access. 901** |
791** At least szOsFile bytes of memory are allocated by SQLite | 902** ^At least szOsFile bytes of memory are allocated by SQLite |
792** to hold the [sqlite3_file] structure passed as the third 793** argument to xOpen. The xOpen method does not have to 794** allocate the structure; it should just fill it in. Note that 795** the xOpen method must set the sqlite3_file.pMethods to either 796** a valid [sqlite3_io_methods] object or to NULL. xOpen must do 797** this even if the open fails. SQLite expects that the sqlite3_file.pMethods 798** element will be valid after xOpen returns regardless of the success 799** or failure of the xOpen call. 800** | 903** to hold the [sqlite3_file] structure passed as the third 904** argument to xOpen. The xOpen method does not have to 905** allocate the structure; it should just fill it in. Note that 906** the xOpen method must set the sqlite3_file.pMethods to either 907** a valid [sqlite3_io_methods] object or to NULL. xOpen must do 908** this even if the open fails. SQLite expects that the sqlite3_file.pMethods 909** element will be valid after xOpen returns regardless of the success 910** or failure of the xOpen call. 911** |
801** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] | 912** [[sqlite3_vfs.xAccess]] 913** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] |
802** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to 803** test whether a file is readable and writable, or [SQLITE_ACCESS_READ] 804** to test whether a file is at least readable. The file can be a 805** directory. 806** | 914** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to 915** test whether a file is readable and writable, or [SQLITE_ACCESS_READ] 916** to test whether a file is at least readable. The file can be a 917** directory. 918** |
807** SQLite will always allocate at least mxPathname+1 bytes for the | 919** ^SQLite will always allocate at least mxPathname+1 bytes for the |
808** output buffer xFullPathname. The exact size of the output buffer 809** is also passed as a parameter to both methods. If the output buffer 810** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is 811** handled as a fatal error by SQLite, vfs implementations should endeavor 812** to prevent this by setting mxPathname to a sufficiently large value. 813** | 920** output buffer xFullPathname. The exact size of the output buffer 921** is also passed as a parameter to both methods. If the output buffer 922** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is 923** handled as a fatal error by SQLite, vfs implementations should endeavor 924** to prevent this by setting mxPathname to a sufficiently large value. 925** |
814** The xRandomness(), xSleep(), and xCurrentTime() interfaces 815** are not strictly a part of the filesystem, but they are | 926** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64() 927** interfaces are not strictly a part of the filesystem, but they are |
816** included in the VFS structure for completeness. 817** The xRandomness() function attempts to return nBytes bytes 818** of good-quality randomness into zOut. The return value is 819** the actual number of bytes of randomness obtained. 820** The xSleep() method causes the calling thread to sleep for at | 928** included in the VFS structure for completeness. 929** The xRandomness() function attempts to return nBytes bytes 930** of good-quality randomness into zOut. The return value is 931** the actual number of bytes of randomness obtained. 932** The xSleep() method causes the calling thread to sleep for at |
821** least the number of microseconds given. The xCurrentTime() 822** method returns a Julian Day Number for the current date and time. | 933** least the number of microseconds given. ^The xCurrentTime() 934** method returns a Julian Day Number for the current date and time as 935** a floating point value. 936** ^The xCurrentTimeInt64() method returns, as an integer, the Julian 937** Day Number multiplied by 86400000 (the number of milliseconds in 938** a 24-hour day). 939** ^SQLite will use the xCurrentTimeInt64() method to get the current 940** date and time if that method is available (if iVersion is 2 or 941** greater and the function pointer is not NULL) and will fall back 942** to xCurrentTime() if xCurrentTimeInt64() is unavailable. |
823** | 943** |
944** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces 945** are not used by the SQLite core. These optional interfaces are provided 946** by some VFSes to facilitate testing of the VFS code. By overriding 947** system calls with functions under its control, a test program can 948** simulate faults and error conditions that would otherwise be difficult 949** or impossible to induce. The set of system calls that can be overridden 950** varies from one VFS to another, and from one version of the same VFS to the 951** next. Applications that use these interfaces must be prepared for any 952** or all of these interfaces to be NULL or for their behavior to change 953** from one release to the next. Applications must not attempt to access 954** any of these methods if the iVersion of the VFS is less than 3. |
|
824*/ 825typedef struct sqlite3_vfs sqlite3_vfs; | 955*/ 956typedef struct sqlite3_vfs sqlite3_vfs; |
957typedef void (*sqlite3_syscall_ptr)(void); |
|
826struct sqlite3_vfs { | 958struct sqlite3_vfs { |
827 int iVersion; /* Structure version number */ | 959 int iVersion; /* Structure version number (currently 3) */ |
828 int szOsFile; /* Size of subclassed sqlite3_file */ 829 int mxPathname; /* Maximum file pathname length */ 830 sqlite3_vfs *pNext; /* Next registered VFS */ 831 const char *zName; /* Name of this virtual file system */ 832 void *pAppData; /* Pointer to application-specific data */ 833 int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*, 834 int flags, int *pOutFlags); 835 int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir); 836 int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut); 837 int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut); 838 void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); 839 void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); 840 void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void); 841 void (*xDlClose)(sqlite3_vfs*, void*); 842 int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); 843 int (*xSleep)(sqlite3_vfs*, int microseconds); 844 int (*xCurrentTime)(sqlite3_vfs*, double*); 845 int (*xGetLastError)(sqlite3_vfs*, int, char *); | 960 int szOsFile; /* Size of subclassed sqlite3_file */ 961 int mxPathname; /* Maximum file pathname length */ 962 sqlite3_vfs *pNext; /* Next registered VFS */ 963 const char *zName; /* Name of this virtual file system */ 964 void *pAppData; /* Pointer to application-specific data */ 965 int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*, 966 int flags, int *pOutFlags); 967 int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir); 968 int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut); 969 int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut); 970 void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); 971 void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); 972 void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void); 973 void (*xDlClose)(sqlite3_vfs*, void*); 974 int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); 975 int (*xSleep)(sqlite3_vfs*, int microseconds); 976 int (*xCurrentTime)(sqlite3_vfs*, double*); 977 int (*xGetLastError)(sqlite3_vfs*, int, char *); |
846 /* New fields may be appended in figure versions. The iVersion 847 ** value will increment whenever this happens. */ | 978 /* 979 ** The methods above are in version 1 of the sqlite_vfs object 980 ** definition. Those that follow are added in version 2 or later 981 */ 982 int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*); 983 /* 984 ** The methods above are in versions 1 and 2 of the sqlite_vfs object. 985 ** Those below are for version 3 and greater. 986 */ 987 int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr); 988 sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName); 989 const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName); 990 /* 991 ** The methods above are in versions 1 through 3 of the sqlite_vfs object. 992 ** New fields may be appended in figure versions. The iVersion 993 ** value will increment whenever this happens. 994 */ |
848}; 849 850/* 851** CAPI3REF: Flags for the xAccess VFS method 852** 853** These integer constants can be used as the third parameter to 854** the xAccess method of an [sqlite3_vfs] object. They determine 855** what kind of permissions the xAccess method is looking for. 856** With SQLITE_ACCESS_EXISTS, the xAccess method 857** simply checks whether the file exists. 858** With SQLITE_ACCESS_READWRITE, the xAccess method | 995}; 996 997/* 998** CAPI3REF: Flags for the xAccess VFS method 999** 1000** These integer constants can be used as the third parameter to 1001** the xAccess method of an [sqlite3_vfs] object. They determine 1002** what kind of permissions the xAccess method is looking for. 1003** With SQLITE_ACCESS_EXISTS, the xAccess method 1004** simply checks whether the file exists. 1005** With SQLITE_ACCESS_READWRITE, the xAccess method |
859** checks whether the file is both readable and writable. | 1006** checks whether the named directory is both readable and writable 1007** (in other words, if files can be added, removed, and renamed within 1008** the directory). 1009** The SQLITE_ACCESS_READWRITE constant is currently used only by the 1010** [temp_store_directory pragma], though this could change in a future 1011** release of SQLite. |
860** With SQLITE_ACCESS_READ, the xAccess method | 1012** With SQLITE_ACCESS_READ, the xAccess method |
861** checks whether the file is readable. | 1013** checks whether the file is readable. The SQLITE_ACCESS_READ constant is 1014** currently unused, though it might be used in a future release of 1015** SQLite. |
862*/ 863#define SQLITE_ACCESS_EXISTS 0 | 1016*/ 1017#define SQLITE_ACCESS_EXISTS 0 |
864#define SQLITE_ACCESS_READWRITE 1 865#define SQLITE_ACCESS_READ 2 | 1018#define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */ 1019#define SQLITE_ACCESS_READ 2 /* Unused */ |
866 867/* | 1020 1021/* |
1022** CAPI3REF: Flags for the xShmLock VFS method 1023** 1024** These integer constants define the various locking operations 1025** allowed by the xShmLock method of [sqlite3_io_methods]. The 1026** following are the only legal combinations of flags to the 1027** xShmLock method: 1028** 1029** <ul> 1030** <li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED 1031** <li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE 1032** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED 1033** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE 1034** </ul> 1035** 1036** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as 1037** was given no the corresponding lock. 1038** 1039** The xShmLock method can transition between unlocked and SHARED or 1040** between unlocked and EXCLUSIVE. It cannot transition between SHARED 1041** and EXCLUSIVE. 1042*/ 1043#define SQLITE_SHM_UNLOCK 1 1044#define SQLITE_SHM_LOCK 2 1045#define SQLITE_SHM_SHARED 4 1046#define SQLITE_SHM_EXCLUSIVE 8 1047 1048/* 1049** CAPI3REF: Maximum xShmLock index 1050** 1051** The xShmLock method on [sqlite3_io_methods] may use values 1052** between 0 and this upper bound as its "offset" argument. 1053** The SQLite core will never attempt to acquire or release a 1054** lock outside of this range 1055*/ 1056#define SQLITE_SHM_NLOCK 8 1057 1058 1059/* |
|
868** CAPI3REF: Initialize The SQLite Library 869** 870** ^The sqlite3_initialize() routine initializes the 871** SQLite library. ^The sqlite3_shutdown() routine 872** deallocates any resources that were allocated by sqlite3_initialize(). 873** These routines are designed to aid in process initialization and 874** shutdown on embedded systems. Workstation applications using 875** SQLite normally do not need to invoke either of these routines. --- 83 unchanged lines hidden (view full) --- 959** may only be invoked prior to library initialization using 960** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()]. 961** ^If sqlite3_config() is called after [sqlite3_initialize()] and before 962** [sqlite3_shutdown()] then it will return SQLITE_MISUSE. 963** Note, however, that ^sqlite3_config() can be called as part of the 964** implementation of an application-defined [sqlite3_os_init()]. 965** 966** The first argument to sqlite3_config() is an integer | 1060** CAPI3REF: Initialize The SQLite Library 1061** 1062** ^The sqlite3_initialize() routine initializes the 1063** SQLite library. ^The sqlite3_shutdown() routine 1064** deallocates any resources that were allocated by sqlite3_initialize(). 1065** These routines are designed to aid in process initialization and 1066** shutdown on embedded systems. Workstation applications using 1067** SQLite normally do not need to invoke either of these routines. --- 83 unchanged lines hidden (view full) --- 1151** may only be invoked prior to library initialization using 1152** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()]. 1153** ^If sqlite3_config() is called after [sqlite3_initialize()] and before 1154** [sqlite3_shutdown()] then it will return SQLITE_MISUSE. 1155** Note, however, that ^sqlite3_config() can be called as part of the 1156** implementation of an application-defined [sqlite3_os_init()]. 1157** 1158** The first argument to sqlite3_config() is an integer |
967** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines | 1159** [configuration option] that determines |
968** what property of SQLite is to be configured. Subsequent arguments | 1160** what property of SQLite is to be configured. Subsequent arguments |
969** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option] | 1161** vary depending on the [configuration option] |
970** in the first argument. 971** 972** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK]. 973** ^If the option is unknown or SQLite is unable to set the option 974** then this routine returns a non-zero [error code]. 975*/ | 1162** in the first argument. 1163** 1164** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK]. 1165** ^If the option is unknown or SQLite is unable to set the option 1166** then this routine returns a non-zero [error code]. 1167*/ |
976SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_config(int, ...); | 1168SQLITE_API int sqlite3_config(int, ...); |
977 978/* 979** CAPI3REF: Configure database connections | 1169 1170/* 1171** CAPI3REF: Configure database connections |
980** EXPERIMENTAL | |
981** 982** The sqlite3_db_config() interface is used to make configuration 983** changes to a [database connection]. The interface is similar to 984** [sqlite3_config()] except that the changes apply to a single | 1172** 1173** The sqlite3_db_config() interface is used to make configuration 1174** changes to a [database connection]. The interface is similar to 1175** [sqlite3_config()] except that the changes apply to a single |
985** [database connection] (specified in the first argument). The 986** sqlite3_db_config() interface should only be used immediately after 987** the database connection is created using [sqlite3_open()], 988** [sqlite3_open16()], or [sqlite3_open_v2()]. | 1176** [database connection] (specified in the first argument). |
989** 990** The second argument to sqlite3_db_config(D,V,...) is the | 1177** 1178** The second argument to sqlite3_db_config(D,V,...) is the |
991** configuration verb - an integer code that indicates what 992** aspect of the [database connection] is being configured. 993** The only choice for this value is [SQLITE_DBCONFIG_LOOKASIDE]. 994** New verbs are likely to be added in future releases of SQLite. 995** Additional arguments depend on the verb. | 1179** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code 1180** that indicates what aspect of the [database connection] is being configured. 1181** Subsequent arguments vary depending on the configuration verb. |
996** 997** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if 998** the call is considered successful. 999*/ | 1182** 1183** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if 1184** the call is considered successful. 1185*/ |
1000SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...); | 1186SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...); |
1001 1002/* 1003** CAPI3REF: Memory Allocation Routines | 1187 1188/* 1189** CAPI3REF: Memory Allocation Routines |
1004** EXPERIMENTAL | |
1005** 1006** An instance of this object defines the interface between SQLite 1007** and low-level memory allocation routines. 1008** 1009** This object is used in only one place in the SQLite interface. 1010** A pointer to an instance of this object is the argument to 1011** [sqlite3_config()] when the configuration option is | 1190** 1191** An instance of this object defines the interface between SQLite 1192** and low-level memory allocation routines. 1193** 1194** This object is used in only one place in the SQLite interface. 1195** A pointer to an instance of this object is the argument to 1196** [sqlite3_config()] when the configuration option is |
1012** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC]. | 1197** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC]. |
1013** By creating an instance of this object 1014** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC]) 1015** during configuration, an application can specify an alternative 1016** memory allocation subsystem for SQLite to use for all of its 1017** dynamic memory needs. 1018** 1019** Note that SQLite comes with several [built-in memory allocators] 1020** that are perfectly adequate for the overwhelming majority of applications 1021** and that this object is only useful to a tiny minority of applications 1022** with specialized memory allocation requirements. This object is 1023** also used during testing of SQLite in order to specify an alternative 1024** memory allocator that simulates memory out-of-memory conditions in 1025** order to verify that SQLite recovers gracefully from such 1026** conditions. 1027** | 1198** By creating an instance of this object 1199** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC]) 1200** during configuration, an application can specify an alternative 1201** memory allocation subsystem for SQLite to use for all of its 1202** dynamic memory needs. 1203** 1204** Note that SQLite comes with several [built-in memory allocators] 1205** that are perfectly adequate for the overwhelming majority of applications 1206** and that this object is only useful to a tiny minority of applications 1207** with specialized memory allocation requirements. This object is 1208** also used during testing of SQLite in order to specify an alternative 1209** memory allocator that simulates memory out-of-memory conditions in 1210** order to verify that SQLite recovers gracefully from such 1211** conditions. 1212** |
1028** The xMalloc and xFree methods must work like the 1029** malloc() and free() functions from the standard C library. 1030** The xRealloc method must work like realloc() from the standard C library 1031** with the exception that if the second argument to xRealloc is zero, 1032** xRealloc must be a no-op - it must not perform any allocation or 1033** deallocation. ^SQLite guarantees that the second argument to | 1213** The xMalloc, xRealloc, and xFree methods must work like the 1214** malloc(), realloc() and free() functions from the standard C library. 1215** ^SQLite guarantees that the second argument to |
1034** xRealloc is always a value returned by a prior call to xRoundup. | 1216** xRealloc is always a value returned by a prior call to xRoundup. |
1035** And so in cases where xRoundup always returns a positive number, 1036** xRealloc can perform exactly as the standard library realloc() and 1037** still be in compliance with this specification. | |
1038** 1039** xSize should return the allocated size of a memory allocation 1040** previously obtained from xMalloc or xRealloc. The allocated size 1041** is always at least as big as the requested size but may be larger. 1042** 1043** The xRoundup method returns what would be the allocated size of 1044** a memory allocation given a particular requested size. Most memory 1045** allocators round up memory allocations at least to the next multiple 1046** of 8. Some allocators round up to a larger multiple or to a power of 2. 1047** Every memory allocation request coming in through [sqlite3_malloc()] | 1217** 1218** xSize should return the allocated size of a memory allocation 1219** previously obtained from xMalloc or xRealloc. The allocated size 1220** is always at least as big as the requested size but may be larger. 1221** 1222** The xRoundup method returns what would be the allocated size of 1223** a memory allocation given a particular requested size. Most memory 1224** allocators round up memory allocations at least to the next multiple 1225** of 8. Some allocators round up to a larger multiple or to a power of 2. 1226** Every memory allocation request coming in through [sqlite3_malloc()] |
1048** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0, | 1227** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0, |
1049** that causes the corresponding memory allocation to fail. 1050** 1051** The xInit method initializes the memory allocator. (For example, 1052** it might allocate any require mutexes or initialize internal data 1053** structures. The xShutdown method is invoked (indirectly) by 1054** [sqlite3_shutdown()] and should deallocate any resources acquired 1055** by xInit. The pAppData pointer is used as the only parameter to 1056** xInit and xShutdown. --- 21 unchanged lines hidden (view full) --- 1078 int (*xRoundup)(int); /* Round up request size to allocation size */ 1079 int (*xInit)(void*); /* Initialize the memory allocator */ 1080 void (*xShutdown)(void*); /* Deinitialize the memory allocator */ 1081 void *pAppData; /* Argument to xInit() and xShutdown() */ 1082}; 1083 1084/* 1085** CAPI3REF: Configuration Options | 1228** that causes the corresponding memory allocation to fail. 1229** 1230** The xInit method initializes the memory allocator. (For example, 1231** it might allocate any require mutexes or initialize internal data 1232** structures. The xShutdown method is invoked (indirectly) by 1233** [sqlite3_shutdown()] and should deallocate any resources acquired 1234** by xInit. The pAppData pointer is used as the only parameter to 1235** xInit and xShutdown. --- 21 unchanged lines hidden (view full) --- 1257 int (*xRoundup)(int); /* Round up request size to allocation size */ 1258 int (*xInit)(void*); /* Initialize the memory allocator */ 1259 void (*xShutdown)(void*); /* Deinitialize the memory allocator */ 1260 void *pAppData; /* Argument to xInit() and xShutdown() */ 1261}; 1262 1263/* 1264** CAPI3REF: Configuration Options |
1086** EXPERIMENTAL | 1265** KEYWORDS: {configuration option} |
1087** 1088** These constants are the available integer configuration options that 1089** can be passed as the first argument to the [sqlite3_config()] interface. 1090** 1091** New configuration options may be added in future releases of SQLite. 1092** Existing configuration options might be discontinued. Applications 1093** should check the return code from [sqlite3_config()] to make sure that 1094** the call worked. The [sqlite3_config()] interface will return a 1095** non-zero [error code] if a discontinued or unsupported configuration option 1096** is invoked. 1097** 1098** <dl> | 1266** 1267** These constants are the available integer configuration options that 1268** can be passed as the first argument to the [sqlite3_config()] interface. 1269** 1270** New configuration options may be added in future releases of SQLite. 1271** Existing configuration options might be discontinued. Applications 1272** should check the return code from [sqlite3_config()] to make sure that 1273** the call worked. The [sqlite3_config()] interface will return a 1274** non-zero [error code] if a discontinued or unsupported configuration option 1275** is invoked. 1276** 1277** <dl> |
1099** | 1278** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt> |
1100** <dd>There are no arguments to this option. ^This option sets the 1101** [threading mode] to Single-thread. In other words, it disables 1102** all mutexing and puts SQLite into a mode where it can only be used 1103** by a single thread. ^If SQLite is compiled with 1104** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1105** it is not possible to change the [threading mode] from its default | 1279** <dd>There are no arguments to this option. ^This option sets the 1280** [threading mode] to Single-thread. In other words, it disables 1281** all mutexing and puts SQLite into a mode where it can only be used 1282** by a single thread. ^If SQLite is compiled with 1283** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1284** it is not possible to change the [threading mode] from its default |
1106** value of Single-thread and so [sqlite3_config()] will return | 1285** value of Single-thread and so [sqlite3_config()] will return |
1107** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD 1108** configuration option.</dd> 1109** | 1286** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD 1287** configuration option.</dd> 1288** |
1110** | 1289** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt> |
1111** <dd>There are no arguments to this option. ^This option sets the 1112** [threading mode] to Multi-thread. In other words, it disables 1113** mutexing on [database connection] and [prepared statement] objects. 1114** The application is responsible for serializing access to 1115** [database connections] and [prepared statements]. But other mutexes 1116** are enabled so that SQLite will be safe to use in a multi-threaded 1117** environment as long as no two threads attempt to use the same 1118** [database connection] at the same time. ^If SQLite is compiled with 1119** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1120** it is not possible to set the Multi-thread [threading mode] and 1121** [sqlite3_config()] will return [SQLITE_ERROR] if called with the 1122** SQLITE_CONFIG_MULTITHREAD configuration option.</dd> 1123** | 1290** <dd>There are no arguments to this option. ^This option sets the 1291** [threading mode] to Multi-thread. In other words, it disables 1292** mutexing on [database connection] and [prepared statement] objects. 1293** The application is responsible for serializing access to 1294** [database connections] and [prepared statements]. But other mutexes 1295** are enabled so that SQLite will be safe to use in a multi-threaded 1296** environment as long as no two threads attempt to use the same 1297** [database connection] at the same time. ^If SQLite is compiled with 1298** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1299** it is not possible to set the Multi-thread [threading mode] and 1300** [sqlite3_config()] will return [SQLITE_ERROR] if called with the 1301** SQLITE_CONFIG_MULTITHREAD configuration option.</dd> 1302** |
1124** | 1303** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt> |
1125** <dd>There are no arguments to this option. ^This option sets the 1126** [threading mode] to Serialized. In other words, this option enables 1127** all mutexes including the recursive 1128** mutexes on [database connection] and [prepared statement] objects. 1129** In this mode (which is the default when SQLite is compiled with 1130** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access 1131** to [database connections] and [prepared statements] so that the 1132** application is free to use the same [database connection] or the 1133** same [prepared statement] in different threads at the same time. 1134** ^If SQLite is compiled with 1135** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1136** it is not possible to set the Serialized [threading mode] and 1137** [sqlite3_config()] will return [SQLITE_ERROR] if called with the 1138** SQLITE_CONFIG_SERIALIZED configuration option.</dd> 1139** | 1304** <dd>There are no arguments to this option. ^This option sets the 1305** [threading mode] to Serialized. In other words, this option enables 1306** all mutexes including the recursive 1307** mutexes on [database connection] and [prepared statement] objects. 1308** In this mode (which is the default when SQLite is compiled with 1309** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access 1310** to [database connections] and [prepared statements] so that the 1311** application is free to use the same [database connection] or the 1312** same [prepared statement] in different threads at the same time. 1313** ^If SQLite is compiled with 1314** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1315** it is not possible to set the Serialized [threading mode] and 1316** [sqlite3_config()] will return [SQLITE_ERROR] if called with the 1317** SQLITE_CONFIG_SERIALIZED configuration option.</dd> 1318** |
1140** | 1319** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt> |
1141** <dd> ^(This option takes a single argument which is a pointer to an 1142** instance of the [sqlite3_mem_methods] structure. The argument specifies 1143** alternative low-level memory allocation routines to be used in place of 1144** the memory allocation routines built into SQLite.)^ ^SQLite makes 1145** its own private copy of the content of the [sqlite3_mem_methods] structure 1146** before the [sqlite3_config()] call returns.</dd> 1147** | 1320** <dd> ^(This option takes a single argument which is a pointer to an 1321** instance of the [sqlite3_mem_methods] structure. The argument specifies 1322** alternative low-level memory allocation routines to be used in place of 1323** the memory allocation routines built into SQLite.)^ ^SQLite makes 1324** its own private copy of the content of the [sqlite3_mem_methods] structure 1325** before the [sqlite3_config()] call returns.</dd> 1326** |
1148** | 1327** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt> |
1149** <dd> ^(This option takes a single argument which is a pointer to an 1150** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods] 1151** structure is filled with the currently defined memory allocation routines.)^ 1152** This option can be used to overload the default memory allocation 1153** routines with a wrapper that simulations memory allocation failure or 1154** tracks memory usage, for example. </dd> 1155** | 1328** <dd> ^(This option takes a single argument which is a pointer to an 1329** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods] 1330** structure is filled with the currently defined memory allocation routines.)^ 1331** This option can be used to overload the default memory allocation 1332** routines with a wrapper that simulations memory allocation failure or 1333** tracks memory usage, for example. </dd> 1334** |
1156** 1157** 1158** boolean, which enables or disables the collection of memory allocation 1159** statistics. ^(When memory allocation statistics are disabled, the | 1335** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt> 1336** <dd> ^This option takes single argument of type int, interpreted as a 1337** boolean, which enables or disables the collection of memory allocation 1338** statistics. ^(When memory allocation statistics are disabled, the |
1160** following SQLite interfaces become non-operational: 1161** <ul> 1162** <li> [sqlite3_memory_used()] 1163** <li> [sqlite3_memory_highwater()] | 1339** following SQLite interfaces become non-operational: 1340** <ul> 1341** <li> [sqlite3_memory_used()] 1342** <li> [sqlite3_memory_highwater()] |
1164** | 1343** <li> [sqlite3_soft_heap_limit64()] |
1165** <li> [sqlite3_status()] 1166** </ul>)^ 1167** ^Memory allocation statistics are enabled by default unless SQLite is 1168** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory 1169** allocation statistics are disabled by default. 1170** </dd> 1171** | 1344** <li> [sqlite3_status()] 1345** </ul>)^ 1346** ^Memory allocation statistics are enabled by default unless SQLite is 1347** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory 1348** allocation statistics are disabled by default. 1349** </dd> 1350** |
1172** | 1351** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt> |
1173** <dd> ^This option specifies a static memory buffer that SQLite can use for 1174** scratch memory. There are three arguments: A pointer an 8-byte | 1352** <dd> ^This option specifies a static memory buffer that SQLite can use for 1353** scratch memory. There are three arguments: A pointer an 8-byte |
1175** aligned memory buffer from which the scrach allocations will be | 1354** aligned memory buffer from which the scratch allocations will be |
1176** drawn, the size of each scratch allocation (sz), 1177** and the maximum number of scratch allocations (N). The sz | 1355** drawn, the size of each scratch allocation (sz), 1356** and the maximum number of scratch allocations (N). The sz |
1178** argument must be a multiple of 16. The sz parameter should be a few bytes 1179** larger than the actual scratch space required due to internal overhead. | 1357** argument must be a multiple of 16. |
1180** The first argument must be a pointer to an 8-byte aligned buffer 1181** of at least sz*N bytes of memory. | 1358** The first argument must be a pointer to an 8-byte aligned buffer 1359** of at least sz*N bytes of memory. |
1182** ^SQLite will use no more than one scratch buffer per thread. So 1183** N should be set to the expected maximum number of threads. ^SQLite will 1184** never require a scratch buffer that is more than 6 times the database 1185** page size. ^If SQLite needs needs additional scratch memory beyond 1186** what is provided by this configuration option, then | 1360** ^SQLite will use no more than two scratch buffers per thread. So 1361** N should be set to twice the expected maximum number of threads. 1362** ^SQLite will never require a scratch buffer that is more than 6 1363** times the database page size. ^If SQLite needs needs additional 1364** scratch memory beyond what is provided by this configuration option, then |
1187** [sqlite3_malloc()] will be used to obtain the memory needed.</dd> 1188** | 1365** [sqlite3_malloc()] will be used to obtain the memory needed.</dd> 1366** |
1189** | 1367** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt> |
1190** <dd> ^This option specifies a static memory buffer that SQLite can use for | 1368** <dd> ^This option specifies a static memory buffer that SQLite can use for |
1191** the database page cache with the default page cache implemenation. | 1369** the database page cache with the default page cache implementation. |
1192** This configuration should not be used if an application-define page 1193** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option. 1194** There are three arguments to this option: A pointer to 8-byte aligned 1195** memory, the size of each page buffer (sz), and the number of pages (N). 1196** The sz argument should be the size of the largest database page 1197** (a power of two between 512 and 32768) plus a little extra for each 1198** page header. ^The page header size is 20 to 40 bytes depending on 1199** the host architecture. ^It is harmless, apart from the wasted memory, 1200** to make sz a little too large. The first 1201** argument should point to an allocation of at least sz*N bytes of memory. 1202** ^SQLite will use the memory provided by the first argument to satisfy its 1203** memory needs for the first N pages that it adds to cache. ^If additional 1204** page cache memory is needed beyond what is provided by this option, then 1205** SQLite goes to [sqlite3_malloc()] for the additional storage space. | 1370** This configuration should not be used if an application-define page 1371** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option. 1372** There are three arguments to this option: A pointer to 8-byte aligned 1373** memory, the size of each page buffer (sz), and the number of pages (N). 1374** The sz argument should be the size of the largest database page 1375** (a power of two between 512 and 32768) plus a little extra for each 1376** page header. ^The page header size is 20 to 40 bytes depending on 1377** the host architecture. ^It is harmless, apart from the wasted memory, 1378** to make sz a little too large. The first 1379** argument should point to an allocation of at least sz*N bytes of memory. 1380** ^SQLite will use the memory provided by the first argument to satisfy its 1381** memory needs for the first N pages that it adds to cache. ^If additional 1382** page cache memory is needed beyond what is provided by this option, then 1383** SQLite goes to [sqlite3_malloc()] for the additional storage space. |
1206** ^The implementation might use one or more of the N buffers to hold 1207** memory accounting information. The pointer in the first argument must | 1384** The pointer in the first argument must |
1208** be aligned to an 8-byte boundary or subsequent behavior of SQLite 1209** will be undefined.</dd> 1210** | 1385** be aligned to an 8-byte boundary or subsequent behavior of SQLite 1386** will be undefined.</dd> 1387** |
1211** | 1388** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt> |
1212** <dd> ^This option specifies a static memory buffer that SQLite will use 1213** for all of its dynamic memory allocation needs beyond those provided 1214** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE]. 1215** There are three arguments: An 8-byte aligned pointer to the memory, 1216** the number of bytes in the memory buffer, and the minimum allocation size. 1217** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts 1218** to using its default memory allocator (the system malloc() implementation), 1219** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the 1220** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or 1221** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory 1222** allocator is engaged to handle all of SQLites memory allocation needs. 1223** The first pointer (the memory pointer) must be aligned to an 8-byte | 1389** <dd> ^This option specifies a static memory buffer that SQLite will use 1390** for all of its dynamic memory allocation needs beyond those provided 1391** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE]. 1392** There are three arguments: An 8-byte aligned pointer to the memory, 1393** the number of bytes in the memory buffer, and the minimum allocation size. 1394** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts 1395** to using its default memory allocator (the system malloc() implementation), 1396** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the 1397** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or 1398** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory 1399** allocator is engaged to handle all of SQLites memory allocation needs. 1400** The first pointer (the memory pointer) must be aligned to an 8-byte |
1224** boundary or subsequent behavior of SQLite will be undefined.</dd> | 1401** boundary or subsequent behavior of SQLite will be undefined. 1402** The minimum allocation size is capped at 2^12. Reasonable values 1403** for the minimum allocation size are 2^5 through 2^8.</dd> |
1225** | 1404** |
1226** | 1405** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt> |
1227** <dd> ^(This option takes a single argument which is a pointer to an 1228** instance of the [sqlite3_mutex_methods] structure. The argument specifies 1229** alternative low-level mutex routines to be used in place 1230** the mutex routines built into SQLite.)^ ^SQLite makes a copy of the 1231** content of the [sqlite3_mutex_methods] structure before the call to 1232** [sqlite3_config()] returns. ^If SQLite is compiled with 1233** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1234** the entire mutexing subsystem is omitted from the build and hence calls to 1235** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will 1236** return [SQLITE_ERROR].</dd> 1237** | 1406** <dd> ^(This option takes a single argument which is a pointer to an 1407** instance of the [sqlite3_mutex_methods] structure. The argument specifies 1408** alternative low-level mutex routines to be used in place 1409** the mutex routines built into SQLite.)^ ^SQLite makes a copy of the 1410** content of the [sqlite3_mutex_methods] structure before the call to 1411** [sqlite3_config()] returns. ^If SQLite is compiled with 1412** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1413** the entire mutexing subsystem is omitted from the build and hence calls to 1414** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will 1415** return [SQLITE_ERROR].</dd> 1416** |
1238** | 1417** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt> |
1239** <dd> ^(This option takes a single argument which is a pointer to an 1240** instance of the [sqlite3_mutex_methods] structure. The 1241** [sqlite3_mutex_methods] 1242** structure is filled with the currently defined mutex routines.)^ 1243** This option can be used to overload the default mutex allocation 1244** routines with a wrapper used to track mutex usage for performance 1245** profiling or testing, for example. ^If SQLite is compiled with 1246** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1247** the entire mutexing subsystem is omitted from the build and hence calls to 1248** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will 1249** return [SQLITE_ERROR].</dd> 1250** | 1418** <dd> ^(This option takes a single argument which is a pointer to an 1419** instance of the [sqlite3_mutex_methods] structure. The 1420** [sqlite3_mutex_methods] 1421** structure is filled with the currently defined mutex routines.)^ 1422** This option can be used to overload the default mutex allocation 1423** routines with a wrapper used to track mutex usage for performance 1424** profiling or testing, for example. ^If SQLite is compiled with 1425** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1426** the entire mutexing subsystem is omitted from the build and hence calls to 1427** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will 1428** return [SQLITE_ERROR].</dd> 1429** |
1251** | 1430** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt> |
1252** <dd> ^(This option takes two arguments that determine the default 1253** memory allocation for the lookaside memory allocator on each 1254** [database connection]. The first argument is the 1255** size of each lookaside buffer slot and the second is the number of 1256** slots allocated to each database connection.)^ ^(This option sets the 1257** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE] 1258** verb to [sqlite3_db_config()] can be used to change the lookaside 1259** configuration on individual connections.)^ </dd> 1260** | 1431** <dd> ^(This option takes two arguments that determine the default 1432** memory allocation for the lookaside memory allocator on each 1433** [database connection]. The first argument is the 1434** size of each lookaside buffer slot and the second is the number of 1435** slots allocated to each database connection.)^ ^(This option sets the 1436** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE] 1437** verb to [sqlite3_db_config()] can be used to change the lookaside 1438** configuration on individual connections.)^ </dd> 1439** |
1261** | 1440** [[SQLITE_CONFIG_PCACHE]] <dt>SQLITE_CONFIG_PCACHE</dt> |
1262** <dd> ^(This option takes a single argument which is a pointer to 1263** an [sqlite3_pcache_methods] object. This object specifies the interface 1264** to a custom page cache implementation.)^ ^SQLite makes a copy of the 1265** object and uses it for page cache memory allocations.</dd> 1266** | 1441** <dd> ^(This option takes a single argument which is a pointer to 1442** an [sqlite3_pcache_methods] object. This object specifies the interface 1443** to a custom page cache implementation.)^ ^SQLite makes a copy of the 1444** object and uses it for page cache memory allocations.</dd> 1445** |
1267** | 1446** [[SQLITE_CONFIG_GETPCACHE]] <dt>SQLITE_CONFIG_GETPCACHE</dt> |
1268** <dd> ^(This option takes a single argument which is a pointer to an 1269** [sqlite3_pcache_methods] object. SQLite copies of the current 1270** page cache implementation into that object.)^ </dd> 1271** | 1447** <dd> ^(This option takes a single argument which is a pointer to an 1448** [sqlite3_pcache_methods] object. SQLite copies of the current 1449** page cache implementation into that object.)^ </dd> 1450** |
1451** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt> 1452** <dd> ^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a 1453** function with a call signature of void(*)(void*,int,const char*), 1454** and a pointer to void. ^If the function pointer is not NULL, it is 1455** invoked by [sqlite3_log()] to process each logging event. ^If the 1456** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op. 1457** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is 1458** passed through as the first parameter to the application-defined logger 1459** function whenever that function is invoked. ^The second parameter to 1460** the logger function is a copy of the first parameter to the corresponding 1461** [sqlite3_log()] call and is intended to be a [result code] or an 1462** [extended result code]. ^The third parameter passed to the logger is 1463** log message after formatting via [sqlite3_snprintf()]. 1464** The SQLite logging interface is not reentrant; the logger function 1465** supplied by the application must not invoke any SQLite interface. 1466** In a multi-threaded application, the application-defined logger 1467** function must be threadsafe. </dd> 1468** 1469** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI 1470** <dd> This option takes a single argument of type int. If non-zero, then 1471** URI handling is globally enabled. If the parameter is zero, then URI handling 1472** is globally disabled. If URI handling is globally enabled, all filenames 1473** passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or 1474** specified as part of [ATTACH] commands are interpreted as URIs, regardless 1475** of whether or not the [SQLITE_OPEN_URI] flag is set when the database 1476** connection is opened. If it is globally disabled, filenames are 1477** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the 1478** database connection is opened. By default, URI handling is globally 1479** disabled. The default value may be changed by compiling with the 1480** [SQLITE_USE_URI] symbol defined. |
|
1272** </dl> 1273*/ 1274#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ 1275#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ 1276#define SQLITE_CONFIG_SERIALIZED 3 /* nil */ 1277#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ 1278#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ 1279#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ 1280#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ 1281#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ 1282#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ 1283#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ 1284#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ | 1481** </dl> 1482*/ 1483#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ 1484#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ 1485#define SQLITE_CONFIG_SERIALIZED 3 /* nil */ 1486#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ 1487#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ 1488#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ 1489#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ 1490#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ 1491#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ 1492#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ 1493#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ |
1285/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ | 1494/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ |
1286#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ 1287#define SQLITE_CONFIG_PCACHE 14 /* sqlite3_pcache_methods* */ 1288#define SQLITE_CONFIG_GETPCACHE 15 /* sqlite3_pcache_methods* */ 1289#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */ | 1495#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ 1496#define SQLITE_CONFIG_PCACHE 14 /* sqlite3_pcache_methods* */ 1497#define SQLITE_CONFIG_GETPCACHE 15 /* sqlite3_pcache_methods* */ 1498#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */ |
1499#define SQLITE_CONFIG_URI 17 /* int */ |
|
1290 1291/* | 1500 1501/* |
1292** CAPI3REF: Configuration Options 1293** EXPERIMENTAL | 1502** CAPI3REF: Database Connection Configuration Options |
1294** 1295** These constants are the available integer configuration options that 1296** can be passed as the second argument to the [sqlite3_db_config()] interface. 1297** 1298** New configuration options may be added in future releases of SQLite. 1299** Existing configuration options might be discontinued. Applications 1300** should check the return code from [sqlite3_db_config()] to make sure that 1301** the call worked. ^The [sqlite3_db_config()] interface will return a 1302** non-zero [error code] if a discontinued or unsupported configuration option 1303** is invoked. 1304** 1305** <dl> 1306** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt> | 1503** 1504** These constants are the available integer configuration options that 1505** can be passed as the second argument to the [sqlite3_db_config()] interface. 1506** 1507** New configuration options may be added in future releases of SQLite. 1508** Existing configuration options might be discontinued. Applications 1509** should check the return code from [sqlite3_db_config()] to make sure that 1510** the call worked. ^The [sqlite3_db_config()] interface will return a 1511** non-zero [error code] if a discontinued or unsupported configuration option 1512** is invoked. 1513** 1514** <dl> 1515** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt> |
1307** | 1516** <dd> ^This option takes three additional arguments that determine the |
1308** [lookaside memory allocator] configuration for the [database connection]. 1309** ^The first argument (the third parameter to [sqlite3_db_config()] is a | 1517** [lookaside memory allocator] configuration for the [database connection]. 1518** ^The first argument (the third parameter to [sqlite3_db_config()] is a |
1310** pointer to an memory buffer to use for lookaside memory. | 1519** pointer to a memory buffer to use for lookaside memory. |
1311** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb 1312** may be NULL in which case SQLite will allocate the 1313** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the 1314** size of each lookaside buffer slot. ^The third argument is the number of 1315** slots. The size of the buffer in the first argument must be greater than 1316** or equal to the product of the second and third arguments. The buffer 1317** must be aligned to an 8-byte boundary. ^If the second argument to 1318** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally | 1520** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb 1521** may be NULL in which case SQLite will allocate the 1522** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the 1523** size of each lookaside buffer slot. ^The third argument is the number of 1524** slots. The size of the buffer in the first argument must be greater than 1525** or equal to the product of the second and third arguments. The buffer 1526** must be aligned to an 8-byte boundary. ^If the second argument to 1527** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally |
1319** rounded down to the next smaller 1320** multiple of 8. See also: [SQLITE_CONFIG_LOOKASIDE]</dd> | 1528** rounded down to the next smaller multiple of 8. ^(The lookaside memory 1529** configuration for a database connection can only be changed when that 1530** connection is not currently using lookaside memory, or in other words 1531** when the "current value" returned by 1532** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero. 1533** Any attempt to change the lookaside memory configuration when lookaside 1534** memory is in use leaves the configuration unchanged and returns 1535** [SQLITE_BUSY].)^</dd> |
1321** | 1536** |
1537** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt> 1538** <dd> ^This option is used to enable or disable the enforcement of 1539** [foreign key constraints]. There should be two additional arguments. 1540** The first argument is an integer which is 0 to disable FK enforcement, 1541** positive to enable FK enforcement or negative to leave FK enforcement 1542** unchanged. The second parameter is a pointer to an integer into which 1543** is written 0 or 1 to indicate whether FK enforcement is off or on 1544** following this call. The second parameter may be a NULL pointer, in 1545** which case the FK enforcement setting is not reported back. </dd> 1546** 1547** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt> 1548** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers]. 1549** There should be two additional arguments. 1550** The first argument is an integer which is 0 to disable triggers, 1551** positive to enable triggers or negative to leave the setting unchanged. 1552** The second parameter is a pointer to an integer into which 1553** is written 0 or 1 to indicate whether triggers are disabled or enabled 1554** following this call. The second parameter may be a NULL pointer, in 1555** which case the trigger setting is not reported back. </dd> 1556** |
|
1322** </dl> 1323*/ | 1557** </dl> 1558*/ |
1324#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ | 1559#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ 1560#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ 1561#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */ |
1325 1326 1327/* 1328** CAPI3REF: Enable Or Disable Extended Result Codes 1329** 1330** ^The sqlite3_extended_result_codes() routine enables or disables the 1331** [extended result codes] feature of SQLite. ^The extended result 1332** codes are disabled by default for historical compatibility. --- 7 unchanged lines hidden (view full) --- 1340** integer key called the [ROWID | "rowid"]. ^The rowid is always available 1341** as an undeclared column named ROWID, OID, or _ROWID_ as long as those 1342** names are not also used by explicitly declared columns. ^If 1343** the table has a column of type [INTEGER PRIMARY KEY] then that column 1344** is another alias for the rowid. 1345** 1346** ^This routine returns the [rowid] of the most recent 1347** successful [INSERT] into the database from the [database connection] | 1562 1563 1564/* 1565** CAPI3REF: Enable Or Disable Extended Result Codes 1566** 1567** ^The sqlite3_extended_result_codes() routine enables or disables the 1568** [extended result codes] feature of SQLite. ^The extended result 1569** codes are disabled by default for historical compatibility. --- 7 unchanged lines hidden (view full) --- 1577** integer key called the [ROWID | "rowid"]. ^The rowid is always available 1578** as an undeclared column named ROWID, OID, or _ROWID_ as long as those 1579** names are not also used by explicitly declared columns. ^If 1580** the table has a column of type [INTEGER PRIMARY KEY] then that column 1581** is another alias for the rowid. 1582** 1583** ^This routine returns the [rowid] of the most recent 1584** successful [INSERT] into the database from the [database connection] |
1348** in the first argument. ^If no successful [INSERT]s | 1585** in the first argument. ^As of SQLite version 3.7.7, this routines 1586** records the last insert rowid of both ordinary tables and [virtual tables]. 1587** ^If no successful [INSERT]s |
1349** have ever occurred on that database connection, zero is returned. 1350** | 1588** have ever occurred on that database connection, zero is returned. 1589** |
1351** ^(If an [INSERT] occurs within a trigger, then the [rowid] of the inserted 1352** row is returned by this routine as long as the trigger is running. 1353** But once the trigger terminates, the value returned by this routine 1354** reverts to the last value inserted before the trigger fired.)^ | 1590** ^(If an [INSERT] occurs within a trigger or within a [virtual table] 1591** method, then this routine will return the [rowid] of the inserted 1592** row as long as the trigger or virtual table method is running. 1593** But once the trigger or virtual table method ends, the value returned 1594** by this routine reverts to what it was before the trigger or virtual 1595** table method began.)^ |
1355** 1356** ^An [INSERT] that fails due to a constraint violation is not a 1357** successful [INSERT] and does not change the value returned by this 1358** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, 1359** and INSERT OR ABORT make no changes to the return value of this 1360** routine when their insertion fails. ^(When INSERT OR REPLACE 1361** encounters a constraint violation, it does not fail. The 1362** INSERT continues to completion after deleting rows that caused --- 32 unchanged lines hidden (view full) --- 1395** 1396** ^(A "row change" is a change to a single row of a single table 1397** caused by an INSERT, DELETE, or UPDATE statement. Rows that 1398** are changed as side effects of [REPLACE] constraint resolution, 1399** rollback, ABORT processing, [DROP TABLE], or by any other 1400** mechanisms do not count as direct row changes.)^ 1401** 1402** A "trigger context" is a scope of execution that begins and | 1596** 1597** ^An [INSERT] that fails due to a constraint violation is not a 1598** successful [INSERT] and does not change the value returned by this 1599** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, 1600** and INSERT OR ABORT make no changes to the return value of this 1601** routine when their insertion fails. ^(When INSERT OR REPLACE 1602** encounters a constraint violation, it does not fail. The 1603** INSERT continues to completion after deleting rows that caused --- 32 unchanged lines hidden (view full) --- 1636** 1637** ^(A "row change" is a change to a single row of a single table 1638** caused by an INSERT, DELETE, or UPDATE statement. Rows that 1639** are changed as side effects of [REPLACE] constraint resolution, 1640** rollback, ABORT processing, [DROP TABLE], or by any other 1641** mechanisms do not count as direct row changes.)^ 1642** 1643** A "trigger context" is a scope of execution that begins and |
1403** ends with the script of a [CREATE TRIGGER | trigger]. | 1644** ends with the script of a [CREATE TRIGGER | trigger]. |
1404** Most SQL statements are 1405** evaluated outside of any trigger. This is the "top level" 1406** trigger context. If a trigger fires from the top level, a 1407** new trigger context is entered for the duration of that one 1408** trigger. Subtriggers create subcontexts for their duration. 1409** 1410** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does 1411** not create a new trigger context. --- 26 unchanged lines hidden (view full) --- 1438** ^This function returns the number of row changes caused by [INSERT], 1439** [UPDATE] or [DELETE] statements since the [database connection] was opened. 1440** ^(The count returned by sqlite3_total_changes() includes all changes 1441** from all [CREATE TRIGGER | trigger] contexts and changes made by 1442** [foreign key actions]. However, 1443** the count does not include changes used to implement [REPLACE] constraints, 1444** do rollbacks or ABORT processing, or [DROP TABLE] processing. The 1445** count does not include rows of views that fire an [INSTEAD OF trigger], | 1645** Most SQL statements are 1646** evaluated outside of any trigger. This is the "top level" 1647** trigger context. If a trigger fires from the top level, a 1648** new trigger context is entered for the duration of that one 1649** trigger. Subtriggers create subcontexts for their duration. 1650** 1651** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does 1652** not create a new trigger context. --- 26 unchanged lines hidden (view full) --- 1679** ^This function returns the number of row changes caused by [INSERT], 1680** [UPDATE] or [DELETE] statements since the [database connection] was opened. 1681** ^(The count returned by sqlite3_total_changes() includes all changes 1682** from all [CREATE TRIGGER | trigger] contexts and changes made by 1683** [foreign key actions]. However, 1684** the count does not include changes used to implement [REPLACE] constraints, 1685** do rollbacks or ABORT processing, or [DROP TABLE] processing. The 1686** count does not include rows of views that fire an [INSTEAD OF trigger], |
1446** though if the INSTEAD OF trigger makes changes of its own, those changes | 1687** though if the INSTEAD OF trigger makes changes of its own, those changes |
1447** are counted.)^ 1448** ^The sqlite3_total_changes() function counts the changes as soon as 1449** the statement that makes them is completed (when the statement handle 1450** is passed to [sqlite3_reset()] or [sqlite3_finalize()]). 1451** 1452** See also the [sqlite3_changes()] interface, the 1453** [count_changes pragma], and the [total_changes() SQL function]. 1454** --- 23 unchanged lines hidden (view full) --- 1478** 1479** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT]. 1480** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE 1481** that is inside an explicit transaction, then the entire transaction 1482** will be rolled back automatically. 1483** 1484** ^The sqlite3_interrupt(D) call is in effect until all currently running 1485** SQL statements on [database connection] D complete. ^Any new SQL statements | 1688** are counted.)^ 1689** ^The sqlite3_total_changes() function counts the changes as soon as 1690** the statement that makes them is completed (when the statement handle 1691** is passed to [sqlite3_reset()] or [sqlite3_finalize()]). 1692** 1693** See also the [sqlite3_changes()] interface, the 1694** [count_changes pragma], and the [total_changes() SQL function]. 1695** --- 23 unchanged lines hidden (view full) --- 1719** 1720** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT]. 1721** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE 1722** that is inside an explicit transaction, then the entire transaction 1723** will be rolled back automatically. 1724** 1725** ^The sqlite3_interrupt(D) call is in effect until all currently running 1726** SQL statements on [database connection] D complete. ^Any new SQL statements |
1486** that are started after the sqlite3_interrupt() call and before the | 1727** that are started after the sqlite3_interrupt() call and before the |
1487** running statements reaches zero are interrupted as if they had been 1488** running prior to the sqlite3_interrupt() call. ^New SQL statements 1489** that are started after the running statement count reaches zero are 1490** not effected by the sqlite3_interrupt(). 1491** ^A call to sqlite3_interrupt(D) that occurs when there are no running 1492** SQL statements is a no-op and has no effect on SQL statements 1493** that are started after the sqlite3_interrupt() call returns. 1494** --- 18 unchanged lines hidden (view full) --- 1513** and comments that follow the final semicolon are ignored. 1514** 1515** ^These routines return 0 if the statement is incomplete. ^If a 1516** memory allocation fails, then SQLITE_NOMEM is returned. 1517** 1518** ^These routines do not parse the SQL statements thus 1519** will not detect syntactically incorrect SQL. 1520** | 1728** running statements reaches zero are interrupted as if they had been 1729** running prior to the sqlite3_interrupt() call. ^New SQL statements 1730** that are started after the running statement count reaches zero are 1731** not effected by the sqlite3_interrupt(). 1732** ^A call to sqlite3_interrupt(D) that occurs when there are no running 1733** SQL statements is a no-op and has no effect on SQL statements 1734** that are started after the sqlite3_interrupt() call returns. 1735** --- 18 unchanged lines hidden (view full) --- 1754** and comments that follow the final semicolon are ignored. 1755** 1756** ^These routines return 0 if the statement is incomplete. ^If a 1757** memory allocation fails, then SQLITE_NOMEM is returned. 1758** 1759** ^These routines do not parse the SQL statements thus 1760** will not detect syntactically incorrect SQL. 1761** |
1521** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior | 1762** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior |
1522** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked 1523** automatically by sqlite3_complete16(). If that initialization fails, 1524** then the return value from sqlite3_complete16() will be non-zero 1525** regardless of whether or not the input SQL is complete.)^ 1526** 1527** The input to [sqlite3_complete()] must be a zero-terminated 1528** UTF-8 string. 1529** --- 58 unchanged lines hidden (view full) --- 1588** ^(There can only be a single busy handler defined for each 1589** [database connection]. Setting a new busy handler clears any 1590** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()] 1591** will also set or clear the busy handler. 1592** 1593** The busy callback should not take any actions which modify the 1594** database connection that invoked the busy handler. Any such actions 1595** result in undefined behavior. | 1763** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked 1764** automatically by sqlite3_complete16(). If that initialization fails, 1765** then the return value from sqlite3_complete16() will be non-zero 1766** regardless of whether or not the input SQL is complete.)^ 1767** 1768** The input to [sqlite3_complete()] must be a zero-terminated 1769** UTF-8 string. 1770** --- 58 unchanged lines hidden (view full) --- 1829** ^(There can only be a single busy handler defined for each 1830** [database connection]. Setting a new busy handler clears any 1831** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()] 1832** will also set or clear the busy handler. 1833** 1834** The busy callback should not take any actions which modify the 1835** database connection that invoked the busy handler. Any such actions 1836** result in undefined behavior. |
1596** | 1837** |
1597** A busy handler must not close the database connection 1598** or [prepared statement] that invoked the busy handler. 1599*/ 1600SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); 1601 1602/* 1603** CAPI3REF: Set A Busy Timeout 1604** --- 12 unchanged lines hidden (view full) --- 1617** was defined (using [sqlite3_busy_handler()]) prior to calling 1618** this routine, that other busy handler is cleared.)^ 1619*/ 1620SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); 1621 1622/* 1623** CAPI3REF: Convenience Routines For Running Queries 1624** | 1838** A busy handler must not close the database connection 1839** or [prepared statement] that invoked the busy handler. 1840*/ 1841SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); 1842 1843/* 1844** CAPI3REF: Set A Busy Timeout 1845** --- 12 unchanged lines hidden (view full) --- 1858** was defined (using [sqlite3_busy_handler()]) prior to calling 1859** this routine, that other busy handler is cleared.)^ 1860*/ 1861SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); 1862 1863/* 1864** CAPI3REF: Convenience Routines For Running Queries 1865** |
1866** This is a legacy interface that is preserved for backwards compatibility. 1867** Use of this interface is not recommended. 1868** |
|
1625** Definition: A <b>result table</b> is memory data structure created by the 1626** [sqlite3_get_table()] interface. A result table records the 1627** complete query results from one or more queries. 1628** 1629** The table conceptually has a number of rows and columns. But 1630** these numbers are not part of the result table itself. These 1631** numbers are obtained separately. Let N be the number of rows 1632** and M be the number of columns. --- 4 unchanged lines hidden (view full) --- 1637** The remaining entries all point to query results. NULL values result 1638** in NULL pointers. All other values are in their UTF-8 zero-terminated 1639** string representation as returned by [sqlite3_column_text()]. 1640** 1641** A result table might consist of one or more memory allocations. 1642** It is not safe to pass a result table directly to [sqlite3_free()]. 1643** A result table should be deallocated using [sqlite3_free_table()]. 1644** | 1869** Definition: A <b>result table</b> is memory data structure created by the 1870** [sqlite3_get_table()] interface. A result table records the 1871** complete query results from one or more queries. 1872** 1873** The table conceptually has a number of rows and columns. But 1874** these numbers are not part of the result table itself. These 1875** numbers are obtained separately. Let N be the number of rows 1876** and M be the number of columns. --- 4 unchanged lines hidden (view full) --- 1881** The remaining entries all point to query results. NULL values result 1882** in NULL pointers. All other values are in their UTF-8 zero-terminated 1883** string representation as returned by [sqlite3_column_text()]. 1884** 1885** A result table might consist of one or more memory allocations. 1886** It is not safe to pass a result table directly to [sqlite3_free()]. 1887** A result table should be deallocated using [sqlite3_free_table()]. 1888** |
1645** As an example of the result table format, suppose a query result | 1889** ^(As an example of the result table format, suppose a query result |
1646** is as follows: 1647** 1648** <blockquote><pre> 1649** Name | Age 1650** ----------------------- 1651** Alice | 43 1652** Bob | 28 1653** Cindy | 21 --- 7 unchanged lines hidden (view full) --- 1661** azResult[0] = "Name"; 1662** azResult[1] = "Age"; 1663** azResult[2] = "Alice"; 1664** azResult[3] = "43"; 1665** azResult[4] = "Bob"; 1666** azResult[5] = "28"; 1667** azResult[6] = "Cindy"; 1668** azResult[7] = "21"; | 1890** is as follows: 1891** 1892** <blockquote><pre> 1893** Name | Age 1894** ----------------------- 1895** Alice | 43 1896** Bob | 28 1897** Cindy | 21 --- 7 unchanged lines hidden (view full) --- 1905** azResult[0] = "Name"; 1906** azResult[1] = "Age"; 1907** azResult[2] = "Alice"; 1908** azResult[3] = "43"; 1909** azResult[4] = "Bob"; 1910** azResult[5] = "28"; 1911** azResult[6] = "Cindy"; 1912** azResult[7] = "21"; |
1669** | 1913** </pre></blockquote>)^ |
1670** 1671** ^The sqlite3_get_table() function evaluates one or more 1672** semicolon-separated SQL statements in the zero-terminated UTF-8 1673** string of its 2nd parameter and returns a result table to the 1674** pointer given in its 3rd parameter. 1675** 1676** After the application has finished with the result from sqlite3_get_table(), | 1914** 1915** ^The sqlite3_get_table() function evaluates one or more 1916** semicolon-separated SQL statements in the zero-terminated UTF-8 1917** string of its 2nd parameter and returns a result table to the 1918** pointer given in its 3rd parameter. 1919** 1920** After the application has finished with the result from sqlite3_get_table(), |
1677** it should pass the result table pointer to sqlite3_free_table() in order to | 1921** it must pass the result table pointer to sqlite3_free_table() in order to |
1678** release the memory that was malloced. Because of the way the 1679** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling 1680** function must not try to call [sqlite3_free()] directly. Only 1681** [sqlite3_free_table()] is able to release the memory properly and safely. 1682** | 1922** release the memory that was malloced. Because of the way the 1923** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling 1924** function must not try to call [sqlite3_free()] directly. Only 1925** [sqlite3_free_table()] is able to release the memory properly and safely. 1926** |
1683** ^(The sqlite3_get_table() interface is implemented as a wrapper around | 1927** The sqlite3_get_table() interface is implemented as a wrapper around |
1684** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access 1685** to any internal data structures of SQLite. It uses only the public 1686** interface defined here. As a consequence, errors that occur in the 1687** wrapper layer outside of the internal [sqlite3_exec()] call are not 1688** reflected in subsequent calls to [sqlite3_errcode()] or | 1928** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access 1929** to any internal data structures of SQLite. It uses only the public 1930** interface defined here. As a consequence, errors that occur in the 1931** wrapper layer outside of the internal [sqlite3_exec()] call are not 1932** reflected in subsequent calls to [sqlite3_errcode()] or |
1689** [sqlite3_errmsg()].)^ | 1933** [sqlite3_errmsg()]. |
1690*/ 1691SQLITE_API int sqlite3_get_table( 1692 sqlite3 *db, /* An open database */ 1693 const char *zSql, /* SQL to be evaluated */ 1694 char ***pazResult, /* Results of the query */ 1695 int *pnRow, /* Number of result rows written here */ 1696 int *pnColumn, /* Number of result columns written here */ 1697 char **pzErrmsg /* Error msg written here */ --- 8 unchanged lines hidden (view full) --- 1706** 1707** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their 1708** results into memory obtained from [sqlite3_malloc()]. 1709** The strings returned by these two routines should be 1710** released by [sqlite3_free()]. ^Both routines return a 1711** NULL pointer if [sqlite3_malloc()] is unable to allocate enough 1712** memory to hold the resulting string. 1713** | 1934*/ 1935SQLITE_API int sqlite3_get_table( 1936 sqlite3 *db, /* An open database */ 1937 const char *zSql, /* SQL to be evaluated */ 1938 char ***pazResult, /* Results of the query */ 1939 int *pnRow, /* Number of result rows written here */ 1940 int *pnColumn, /* Number of result columns written here */ 1941 char **pzErrmsg /* Error msg written here */ --- 8 unchanged lines hidden (view full) --- 1950** 1951** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their 1952** results into memory obtained from [sqlite3_malloc()]. 1953** The strings returned by these two routines should be 1954** released by [sqlite3_free()]. ^Both routines return a 1955** NULL pointer if [sqlite3_malloc()] is unable to allocate enough 1956** memory to hold the resulting string. 1957** |
1714** ^(In sqlite3_snprintf() routine is similar to "snprintf()" from | 1958** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from |
1715** the standard C library. The result is written into the 1716** buffer supplied as the second parameter whose size is given by 1717** the first parameter. Note that the order of the 1718** first two parameters is reversed from snprintf().)^ This is an 1719** historical accident that cannot be fixed without breaking 1720** backwards compatibility. ^(Note also that sqlite3_snprintf() 1721** returns a pointer to its buffer instead of the number of 1722** characters actually written into the buffer.)^ We admit that 1723** the number of characters written would be a more useful return 1724** value but we cannot change the implementation of sqlite3_snprintf() 1725** now without breaking compatibility. 1726** 1727** ^As long as the buffer size is greater than zero, sqlite3_snprintf() 1728** guarantees that the buffer is always zero-terminated. ^The first 1729** parameter "n" is the total size of the buffer, including space for 1730** the zero terminator. So the longest string that can be completely 1731** written will be n-1 characters. 1732** | 1959** the standard C library. The result is written into the 1960** buffer supplied as the second parameter whose size is given by 1961** the first parameter. Note that the order of the 1962** first two parameters is reversed from snprintf().)^ This is an 1963** historical accident that cannot be fixed without breaking 1964** backwards compatibility. ^(Note also that sqlite3_snprintf() 1965** returns a pointer to its buffer instead of the number of 1966** characters actually written into the buffer.)^ We admit that 1967** the number of characters written would be a more useful return 1968** value but we cannot change the implementation of sqlite3_snprintf() 1969** now without breaking compatibility. 1970** 1971** ^As long as the buffer size is greater than zero, sqlite3_snprintf() 1972** guarantees that the buffer is always zero-terminated. ^The first 1973** parameter "n" is the total size of the buffer, including space for 1974** the zero terminator. So the longest string that can be completely 1975** written will be n-1 characters. 1976** |
1977** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf(). 1978** |
|
1733** These routines all implement some additional formatting 1734** options that are useful for constructing SQL statements. 1735** All of the usual printf() formatting options apply. In addition, there 1736** is are "%q", "%Q", and "%z" options. 1737** 1738** ^(The %q option works like %s in that it substitutes a null-terminated 1739** string from the argument list. But %q also doubles every '\'' character. 1740** %q is designed for use inside a string literal.)^ By doubling each '\'' --- 47 unchanged lines hidden (view full) --- 1788** 1789** ^(The "%z" formatting option works like "%s" but with the 1790** addition that after the string has been read and copied into 1791** the result, [sqlite3_free()] is called on the input string.)^ 1792*/ 1793SQLITE_API char *sqlite3_mprintf(const char*,...); 1794SQLITE_API char *sqlite3_vmprintf(const char*, va_list); 1795SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...); | 1979** These routines all implement some additional formatting 1980** options that are useful for constructing SQL statements. 1981** All of the usual printf() formatting options apply. In addition, there 1982** is are "%q", "%Q", and "%z" options. 1983** 1984** ^(The %q option works like %s in that it substitutes a null-terminated 1985** string from the argument list. But %q also doubles every '\'' character. 1986** %q is designed for use inside a string literal.)^ By doubling each '\'' --- 47 unchanged lines hidden (view full) --- 2034** 2035** ^(The "%z" formatting option works like "%s" but with the 2036** addition that after the string has been read and copied into 2037** the result, [sqlite3_free()] is called on the input string.)^ 2038*/ 2039SQLITE_API char *sqlite3_mprintf(const char*,...); 2040SQLITE_API char *sqlite3_vmprintf(const char*, va_list); 2041SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...); |
2042SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list); |
|
1796 1797/* 1798** CAPI3REF: Memory Allocation Subsystem 1799** 1800** The SQLite core uses these three routines for all of its own 1801** internal memory allocation needs. "Core" in the previous sentence 1802** does not include operating-system specific VFS implementation. The 1803** Windows VFS uses native malloc() and free() for some operations. --- 29 unchanged lines hidden (view full) --- 1833** of at least N bytes in size or NULL if sufficient memory is unavailable. 1834** ^If M is the size of the prior allocation, then min(N,M) bytes 1835** of the prior allocation are copied into the beginning of buffer returned 1836** by sqlite3_realloc() and the prior allocation is freed. 1837** ^If sqlite3_realloc() returns NULL, then the prior allocation 1838** is not freed. 1839** 1840** ^The memory returned by sqlite3_malloc() and sqlite3_realloc() | 2043 2044/* 2045** CAPI3REF: Memory Allocation Subsystem 2046** 2047** The SQLite core uses these three routines for all of its own 2048** internal memory allocation needs. "Core" in the previous sentence 2049** does not include operating-system specific VFS implementation. The 2050** Windows VFS uses native malloc() and free() for some operations. --- 29 unchanged lines hidden (view full) --- 2080** of at least N bytes in size or NULL if sufficient memory is unavailable. 2081** ^If M is the size of the prior allocation, then min(N,M) bytes 2082** of the prior allocation are copied into the beginning of buffer returned 2083** by sqlite3_realloc() and the prior allocation is freed. 2084** ^If sqlite3_realloc() returns NULL, then the prior allocation 2085** is not freed. 2086** 2087** ^The memory returned by sqlite3_malloc() and sqlite3_realloc() |
1841** is always aligned to at least an 8 byte boundary. | 2088** is always aligned to at least an 8 byte boundary, or to a 2089** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time 2090** option is used. |
1842** 1843** In SQLite version 3.5.0 and 3.5.1, it was possible to define 1844** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in 1845** implementation of these routines to be omitted. That capability 1846** is no longer provided. Only built-in memory allocators can be used. 1847** 1848** The Windows OS interface layer calls 1849** the system malloc() and free() directly when converting --- 60 unchanged lines hidden (view full) --- 1910** internally and without recourse to the [sqlite3_vfs] xRandomness 1911** method. 1912*/ 1913SQLITE_API void sqlite3_randomness(int N, void *P); 1914 1915/* 1916** CAPI3REF: Compile-Time Authorization Callbacks 1917** | 2091** 2092** In SQLite version 3.5.0 and 3.5.1, it was possible to define 2093** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in 2094** implementation of these routines to be omitted. That capability 2095** is no longer provided. Only built-in memory allocators can be used. 2096** 2097** The Windows OS interface layer calls 2098** the system malloc() and free() directly when converting --- 60 unchanged lines hidden (view full) --- 2159** internally and without recourse to the [sqlite3_vfs] xRandomness 2160** method. 2161*/ 2162SQLITE_API void sqlite3_randomness(int N, void *P); 2163 2164/* 2165** CAPI3REF: Compile-Time Authorization Callbacks 2166** |
1918** ^This routine registers a authorizer callback with a particular | 2167** ^This routine registers an authorizer callback with a particular |
1919** [database connection], supplied in the first argument. 1920** ^The authorizer callback is invoked as SQL statements are being compiled 1921** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], 1922** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. ^At various 1923** points during the compilation process, as logic is being created 1924** to perform various actions, the authorizer callback is invoked to 1925** see if those actions are allowed. ^The authorizer callback should 1926** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the 1927** specific action but allow the SQL statement to continue to be 1928** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be 1929** rejected with an error. ^If the authorizer callback returns 1930** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] 1931** then the [sqlite3_prepare_v2()] or equivalent call that triggered 1932** the authorizer will fail with an error message. 1933** 1934** When the callback returns [SQLITE_OK], that means the operation 1935** requested is ok. ^When the callback returns [SQLITE_DENY], the 1936** [sqlite3_prepare_v2()] or equivalent call that triggered the 1937** authorizer will fail with an error message explaining that | 2168** [database connection], supplied in the first argument. 2169** ^The authorizer callback is invoked as SQL statements are being compiled 2170** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], 2171** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. ^At various 2172** points during the compilation process, as logic is being created 2173** to perform various actions, the authorizer callback is invoked to 2174** see if those actions are allowed. ^The authorizer callback should 2175** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the 2176** specific action but allow the SQL statement to continue to be 2177** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be 2178** rejected with an error. ^If the authorizer callback returns 2179** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] 2180** then the [sqlite3_prepare_v2()] or equivalent call that triggered 2181** the authorizer will fail with an error message. 2182** 2183** When the callback returns [SQLITE_OK], that means the operation 2184** requested is ok. ^When the callback returns [SQLITE_DENY], the 2185** [sqlite3_prepare_v2()] or equivalent call that triggered the 2186** authorizer will fail with an error message explaining that |
1938** access is denied. | 2187** access is denied. |
1939** 1940** ^The first parameter to the authorizer callback is a copy of the third 1941** parameter to the sqlite3_set_authorizer() interface. ^The second parameter 1942** to the callback is an integer [SQLITE_COPY | action code] that specifies 1943** the particular action to be authorized. ^The third through sixth parameters 1944** to the callback are zero-terminated strings that contain additional 1945** details about the action to be authorized. 1946** --- 30 unchanged lines hidden (view full) --- 1977** The authorizer is disabled by default. 1978** 1979** The authorizer callback must not do anything that will modify 1980** the database connection that invoked the authorizer callback. 1981** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their 1982** database connections for the meaning of "modify" in this paragraph. 1983** 1984** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the | 2188** 2189** ^The first parameter to the authorizer callback is a copy of the third 2190** parameter to the sqlite3_set_authorizer() interface. ^The second parameter 2191** to the callback is an integer [SQLITE_COPY | action code] that specifies 2192** the particular action to be authorized. ^The third through sixth parameters 2193** to the callback are zero-terminated strings that contain additional 2194** details about the action to be authorized. 2195** --- 30 unchanged lines hidden (view full) --- 2226** The authorizer is disabled by default. 2227** 2228** The authorizer callback must not do anything that will modify 2229** the database connection that invoked the authorizer callback. 2230** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their 2231** database connections for the meaning of "modify" in this paragraph. 2232** 2233** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the |
1985** statement might be re-prepared during [sqlite3_step()] due to a | 2234** statement might be re-prepared during [sqlite3_step()] due to a |
1986** schema change. Hence, the application should ensure that the 1987** correct authorizer callback remains in place during the [sqlite3_step()]. 1988** 1989** ^Note that the authorizer callback is invoked only during 1990** [sqlite3_prepare()] or its variants. Authorization is not 1991** performed during statement evaluation in [sqlite3_step()], unless 1992** as stated in the previous paragraph, sqlite3_step() invokes 1993** sqlite3_prepare_v2() to reprepare a statement after a schema change. --- 7 unchanged lines hidden (view full) --- 2001/* 2002** CAPI3REF: Authorizer Return Codes 2003** 2004** The [sqlite3_set_authorizer | authorizer callback function] must 2005** return either [SQLITE_OK] or one of these two constants in order 2006** to signal SQLite whether or not the action is permitted. See the 2007** [sqlite3_set_authorizer | authorizer documentation] for additional 2008** information. | 2235** schema change. Hence, the application should ensure that the 2236** correct authorizer callback remains in place during the [sqlite3_step()]. 2237** 2238** ^Note that the authorizer callback is invoked only during 2239** [sqlite3_prepare()] or its variants. Authorization is not 2240** performed during statement evaluation in [sqlite3_step()], unless 2241** as stated in the previous paragraph, sqlite3_step() invokes 2242** sqlite3_prepare_v2() to reprepare a statement after a schema change. --- 7 unchanged lines hidden (view full) --- 2250/* 2251** CAPI3REF: Authorizer Return Codes 2252** 2253** The [sqlite3_set_authorizer | authorizer callback function] must 2254** return either [SQLITE_OK] or one of these two constants in order 2255** to signal SQLite whether or not the action is permitted. See the 2256** [sqlite3_set_authorizer | authorizer documentation] for additional 2257** information. |
2258** 2259** Note that SQLITE_IGNORE is also used as a [SQLITE_ROLLBACK | return code] 2260** from the [sqlite3_vtab_on_conflict()] interface. |
|
2009*/ 2010#define SQLITE_DENY 1 /* Abort the SQL statement with an error */ 2011#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ 2012 2013/* 2014** CAPI3REF: Authorizer Action Codes 2015** 2016** The [sqlite3_set_authorizer()] interface registers a callback function --- 44 unchanged lines hidden (view full) --- 2061#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ 2062#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ 2063#define SQLITE_FUNCTION 31 /* NULL Function Name */ 2064#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ 2065#define SQLITE_COPY 0 /* No longer used */ 2066 2067/* 2068** CAPI3REF: Tracing And Profiling Functions | 2261*/ 2262#define SQLITE_DENY 1 /* Abort the SQL statement with an error */ 2263#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ 2264 2265/* 2266** CAPI3REF: Authorizer Action Codes 2267** 2268** The [sqlite3_set_authorizer()] interface registers a callback function --- 44 unchanged lines hidden (view full) --- 2313#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ 2314#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ 2315#define SQLITE_FUNCTION 31 /* NULL Function Name */ 2316#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ 2317#define SQLITE_COPY 0 /* No longer used */ 2318 2319/* 2320** CAPI3REF: Tracing And Profiling Functions |
2069** EXPERIMENTAL | |
2070** 2071** These routines register callback functions that can be used for 2072** tracing and profiling the execution of SQL statements. 2073** 2074** ^The callback function registered by sqlite3_trace() is invoked at 2075** various times when an SQL statement is being run by [sqlite3_step()]. 2076** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the 2077** SQL statement text as the statement first begins executing. 2078** ^(Additional sqlite3_trace() callbacks might occur 2079** as each triggered subprogram is entered. The callbacks for triggers 2080** contain a UTF-8 SQL comment that identifies the trigger.)^ 2081** 2082** ^The callback function registered by sqlite3_profile() is invoked 2083** as each SQL statement finishes. ^The profile callback contains 2084** the original statement text and an estimate of wall-clock time | 2321** 2322** These routines register callback functions that can be used for 2323** tracing and profiling the execution of SQL statements. 2324** 2325** ^The callback function registered by sqlite3_trace() is invoked at 2326** various times when an SQL statement is being run by [sqlite3_step()]. 2327** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the 2328** SQL statement text as the statement first begins executing. 2329** ^(Additional sqlite3_trace() callbacks might occur 2330** as each triggered subprogram is entered. The callbacks for triggers 2331** contain a UTF-8 SQL comment that identifies the trigger.)^ 2332** 2333** ^The callback function registered by sqlite3_profile() is invoked 2334** as each SQL statement finishes. ^The profile callback contains 2335** the original statement text and an estimate of wall-clock time |
2085** of how long that statement took to run. | 2336** of how long that statement took to run. ^The profile callback 2337** time is in units of nanoseconds, however the current implementation 2338** is only capable of millisecond resolution so the six least significant 2339** digits in the time are meaningless. Future versions of SQLite 2340** might provide greater resolution on the profiler callback. The 2341** sqlite3_profile() function is considered experimental and is 2342** subject to change in future versions of SQLite. |
2086*/ | 2343*/ |
2087SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); | 2344SQLITE_API void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); |
2088SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*, 2089 void(*xProfile)(void*,const char*,sqlite3_uint64), void*); 2090 2091/* 2092** CAPI3REF: Query Progress Callbacks 2093** | 2345SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*, 2346 void(*xProfile)(void*,const char*,sqlite3_uint64), void*); 2347 2348/* 2349** CAPI3REF: Query Progress Callbacks 2350** |
2094** ^This routine configures a callback function - the 2095** progress callback - that is invoked periodically during long 2096** running calls to [sqlite3_exec()], [sqlite3_step()] and 2097** [sqlite3_get_table()]. An example use for this | 2351** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback 2352** function X to be invoked periodically during long running calls to 2353** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for 2354** database connection D. An example use for this |
2098** interface is to keep a GUI updated during a large query. 2099** | 2355** interface is to keep a GUI updated during a large query. 2356** |
2357** ^The parameter P is passed through as the only parameter to the 2358** callback function X. ^The parameter N is the number of 2359** [virtual machine instructions] that are evaluated between successive 2360** invocations of the callback X. 2361** 2362** ^Only a single progress handler may be defined at one time per 2363** [database connection]; setting a new progress handler cancels the 2364** old one. ^Setting parameter X to NULL disables the progress handler. 2365** ^The progress handler is also disabled by setting N to a value less 2366** than 1. 2367** |
|
2100** ^If the progress callback returns non-zero, the operation is 2101** interrupted. This feature can be used to implement a 2102** "Cancel" button on a GUI progress dialog box. 2103** | 2368** ^If the progress callback returns non-zero, the operation is 2369** interrupted. This feature can be used to implement a 2370** "Cancel" button on a GUI progress dialog box. 2371** |
2104** The progress handler must not do anything that will modify | 2372** The progress handler callback must not do anything that will modify |
2105** the database connection that invoked the progress handler. 2106** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their 2107** database connections for the meaning of "modify" in this paragraph. 2108** 2109*/ 2110SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); 2111 2112/* 2113** CAPI3REF: Opening A New Database Connection 2114** | 2373** the database connection that invoked the progress handler. 2374** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their 2375** database connections for the meaning of "modify" in this paragraph. 2376** 2377*/ 2378SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); 2379 2380/* 2381** CAPI3REF: Opening A New Database Connection 2382** |
2115** ^These routines open an SQLite database file whose name is given by the | 2383** ^These routines open an SQLite database file as specified by the |
2116** filename argument. ^The filename argument is interpreted as UTF-8 for 2117** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte 2118** order for sqlite3_open16(). ^(A [database connection] handle is usually 2119** returned in *ppDb, even if an error occurs. The only exception is that 2120** if SQLite is unable to allocate memory to hold the [sqlite3] object, 2121** a NULL will be written into *ppDb instead of a pointer to the [sqlite3] 2122** object.)^ ^(If the database is opened (and/or created) successfully, then 2123** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The --- 8 unchanged lines hidden (view full) --- 2132** Whether or not an error occurs when it is opened, resources 2133** associated with the [database connection] handle should be released by 2134** passing it to [sqlite3_close()] when it is no longer required. 2135** 2136** The sqlite3_open_v2() interface works like sqlite3_open() 2137** except that it accepts two additional parameters for additional control 2138** over the new database connection. ^(The flags parameter to 2139** sqlite3_open_v2() can take one of | 2384** filename argument. ^The filename argument is interpreted as UTF-8 for 2385** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte 2386** order for sqlite3_open16(). ^(A [database connection] handle is usually 2387** returned in *ppDb, even if an error occurs. The only exception is that 2388** if SQLite is unable to allocate memory to hold the [sqlite3] object, 2389** a NULL will be written into *ppDb instead of a pointer to the [sqlite3] 2390** object.)^ ^(If the database is opened (and/or created) successfully, then 2391** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The --- 8 unchanged lines hidden (view full) --- 2400** Whether or not an error occurs when it is opened, resources 2401** associated with the [database connection] handle should be released by 2402** passing it to [sqlite3_close()] when it is no longer required. 2403** 2404** The sqlite3_open_v2() interface works like sqlite3_open() 2405** except that it accepts two additional parameters for additional control 2406** over the new database connection. ^(The flags parameter to 2407** sqlite3_open_v2() can take one of |
2140** the following three values, optionally combined with the | 2408** the following three values, optionally combined with the |
2141** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE], | 2409** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE], |
2142** and/or [SQLITE_OPEN_PRIVATECACHE] flags:)^ | 2410** [SQLITE_OPEN_PRIVATECACHE], and/or [SQLITE_OPEN_URI] flags:)^ |
2143** 2144** <dl> 2145** ^(<dt>[SQLITE_OPEN_READONLY]</dt> 2146** <dd>The database is opened in read-only mode. If the database does not 2147** already exist, an error is returned.</dd>)^ 2148** 2149** ^(<dt>[SQLITE_OPEN_READWRITE]</dt> 2150** <dd>The database is opened for reading and writing if possible, or reading 2151** only if the file is write protected by the operating system. In either 2152** case the database must already exist, otherwise an error is returned.</dd>)^ 2153** 2154** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt> | 2411** 2412** <dl> 2413** ^(<dt>[SQLITE_OPEN_READONLY]</dt> 2414** <dd>The database is opened in read-only mode. If the database does not 2415** already exist, an error is returned.</dd>)^ 2416** 2417** ^(<dt>[SQLITE_OPEN_READWRITE]</dt> 2418** <dd>The database is opened for reading and writing if possible, or reading 2419** only if the file is write protected by the operating system. In either 2420** case the database must already exist, otherwise an error is returned.</dd>)^ 2421** 2422** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt> |
2155** <dd>The database is opened for reading and writing, and is creates it if | 2423** <dd>The database is opened for reading and writing, and is created if |
2156** it does not already exist. This is the behavior that is always used for 2157** sqlite3_open() and sqlite3_open16().</dd>)^ 2158** </dl> 2159** 2160** If the 3rd parameter to sqlite3_open_v2() is not one of the | 2424** it does not already exist. This is the behavior that is always used for 2425** sqlite3_open() and sqlite3_open16().</dd>)^ 2426** </dl> 2427** 2428** If the 3rd parameter to sqlite3_open_v2() is not one of the |
2161** combinations shown above or one of the combinations shown above combined 2162** with the [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], 2163** [SQLITE_OPEN_SHAREDCACHE] and/or [SQLITE_OPEN_SHAREDCACHE] flags, | 2429** combinations shown above optionally combined with other 2430** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits] |
2164** then the behavior is undefined. 2165** 2166** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection 2167** opens in the multi-thread [threading mode] as long as the single-thread 2168** mode has not been set at compile-time or start-time. ^If the 2169** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens 2170** in the serialized [threading mode] unless single-thread was 2171** previously selected at compile-time or start-time. 2172** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be 2173** eligible to use [shared cache mode], regardless of whether or not shared 2174** cache is enabled using [sqlite3_enable_shared_cache()]. ^The 2175** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not 2176** participate in [shared cache mode] even if it is enabled. 2177** | 2431** then the behavior is undefined. 2432** 2433** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection 2434** opens in the multi-thread [threading mode] as long as the single-thread 2435** mode has not been set at compile-time or start-time. ^If the 2436** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens 2437** in the serialized [threading mode] unless single-thread was 2438** previously selected at compile-time or start-time. 2439** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be 2440** eligible to use [shared cache mode], regardless of whether or not shared 2441** cache is enabled using [sqlite3_enable_shared_cache()]. ^The 2442** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not 2443** participate in [shared cache mode] even if it is enabled. 2444** |
2445** ^The fourth parameter to sqlite3_open_v2() is the name of the 2446** [sqlite3_vfs] object that defines the operating system interface that 2447** the new database connection should use. ^If the fourth parameter is 2448** a NULL pointer then the default [sqlite3_vfs] object is used. 2449** |
|
2178** ^If the filename is ":memory:", then a private, temporary in-memory database 2179** is created for the connection. ^This in-memory database will vanish when 2180** the database connection is closed. Future versions of SQLite might 2181** make use of additional special filenames that begin with the ":" character. 2182** It is recommended that when a database filename actually does begin with 2183** a ":" character you should prefix the filename with a pathname such as 2184** "./" to avoid ambiguity. 2185** 2186** ^If the filename is an empty string, then a private, temporary 2187** on-disk database will be created. ^This private database will be 2188** automatically deleted as soon as the database connection is closed. 2189** | 2450** ^If the filename is ":memory:", then a private, temporary in-memory database 2451** is created for the connection. ^This in-memory database will vanish when 2452** the database connection is closed. Future versions of SQLite might 2453** make use of additional special filenames that begin with the ":" character. 2454** It is recommended that when a database filename actually does begin with 2455** a ":" character you should prefix the filename with a pathname such as 2456** "./" to avoid ambiguity. 2457** 2458** ^If the filename is an empty string, then a private, temporary 2459** on-disk database will be created. ^This private database will be 2460** automatically deleted as soon as the database connection is closed. 2461** |
2190** ^The fourth parameter to sqlite3_open_v2() is the name of the 2191** [sqlite3_vfs] object that defines the operating system interface that 2192** the new database connection should use. ^If the fourth parameter is 2193** a NULL pointer then the default [sqlite3_vfs] object is used. | 2462** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3> |
2194** | 2463** |
2464** ^If [URI filename] interpretation is enabled, and the filename argument 2465** begins with "file:", then the filename is interpreted as a URI. ^URI 2466** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is 2467** set in the fourth argument to sqlite3_open_v2(), or if it has 2468** been enabled globally using the [SQLITE_CONFIG_URI] option with the 2469** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option. 2470** As of SQLite version 3.7.7, URI filename interpretation is turned off 2471** by default, but future releases of SQLite might enable URI filename 2472** interpretation by default. See "[URI filenames]" for additional 2473** information. 2474** 2475** URI filenames are parsed according to RFC 3986. ^If the URI contains an 2476** authority, then it must be either an empty string or the string 2477** "localhost". ^If the authority is not an empty string or "localhost", an 2478** error is returned to the caller. ^The fragment component of a URI, if 2479** present, is ignored. 2480** 2481** ^SQLite uses the path component of the URI as the name of the disk file 2482** which contains the database. ^If the path begins with a '/' character, 2483** then it is interpreted as an absolute path. ^If the path does not begin 2484** with a '/' (meaning that the authority section is omitted from the URI) 2485** then the path is interpreted as a relative path. 2486** ^On windows, the first component of an absolute path 2487** is a drive specification (e.g. "C:"). 2488** 2489** [[core URI query parameters]] 2490** The query component of a URI may contain parameters that are interpreted 2491** either by SQLite itself, or by a [VFS | custom VFS implementation]. 2492** SQLite interprets the following three query parameters: 2493** 2494** <ul> 2495** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of 2496** a VFS object that provides the operating system interface that should 2497** be used to access the database file on disk. ^If this option is set to 2498** an empty string the default VFS object is used. ^Specifying an unknown 2499** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is 2500** present, then the VFS specified by the option takes precedence over 2501** the value passed as the fourth parameter to sqlite3_open_v2(). 2502** 2503** <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw" or 2504** "rwc". Attempting to set it to any other value is an error)^. 2505** ^If "ro" is specified, then the database is opened for read-only 2506** access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the 2507** third argument to sqlite3_prepare_v2(). ^If the mode option is set to 2508** "rw", then the database is opened for read-write (but not create) 2509** access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had 2510** been set. ^Value "rwc" is equivalent to setting both 2511** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If sqlite3_open_v2() is 2512** used, it is an error to specify a value for the mode parameter that is 2513** less restrictive than that specified by the flags passed as the third 2514** parameter. 2515** 2516** <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or 2517** "private". ^Setting it to "shared" is equivalent to setting the 2518** SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to 2519** sqlite3_open_v2(). ^Setting the cache parameter to "private" is 2520** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit. 2521** ^If sqlite3_open_v2() is used and the "cache" parameter is present in 2522** a URI filename, its value overrides any behaviour requested by setting 2523** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag. 2524** </ul> 2525** 2526** ^Specifying an unknown parameter in the query component of a URI is not an 2527** error. Future versions of SQLite might understand additional query 2528** parameters. See "[query parameters with special meaning to SQLite]" for 2529** additional information. 2530** 2531** [[URI filename examples]] <h3>URI filename examples</h3> 2532** 2533** <table border="1" align=center cellpadding=5> 2534** <tr><th> URI filenames <th> Results 2535** <tr><td> file:data.db <td> 2536** Open the file "data.db" in the current directory. 2537** <tr><td> file:/home/fred/data.db<br> 2538** file:///home/fred/data.db <br> 2539** file://localhost/home/fred/data.db <br> <td> 2540** Open the database file "/home/fred/data.db". 2541** <tr><td> file://darkstar/home/fred/data.db <td> 2542** An error. "darkstar" is not a recognized authority. 2543** <tr><td style="white-space:nowrap"> 2544** file:///C:/Documents%20and%20Settings/fred/Desktop/data.db 2545** <td> Windows only: Open the file "data.db" on fred's desktop on drive 2546** C:. Note that the %20 escaping in this example is not strictly 2547** necessary - space characters can be used literally 2548** in URI filenames. 2549** <tr><td> file:data.db?mode=ro&cache=private <td> 2550** Open file "data.db" in the current directory for read-only access. 2551** Regardless of whether or not shared-cache mode is enabled by 2552** default, use a private cache. 2553** <tr><td> file:/home/fred/data.db?vfs=unix-nolock <td> 2554** Open file "/home/fred/data.db". Use the special VFS "unix-nolock". 2555** <tr><td> file:data.db?mode=readonly <td> 2556** An error. "readonly" is not a valid option for the "mode" parameter. 2557** </table> 2558** 2559** ^URI hexadecimal escape sequences (%HH) are supported within the path and 2560** query components of a URI. A hexadecimal escape sequence consists of a 2561** percent sign - "%" - followed by exactly two hexadecimal digits 2562** specifying an octet value. ^Before the path or query components of a 2563** URI filename are interpreted, they are encoded using UTF-8 and all 2564** hexadecimal escape sequences replaced by a single byte containing the 2565** corresponding octet. If this process generates an invalid UTF-8 encoding, 2566** the results are undefined. 2567** |
|
2195** <b>Note to Windows users:</b> The encoding used for the filename argument 2196** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever 2197** codepage is currently defined. Filenames containing international 2198** characters must be converted to UTF-8 prior to passing them into 2199** sqlite3_open() or sqlite3_open_v2(). 2200*/ 2201SQLITE_API int sqlite3_open( 2202 const char *filename, /* Database filename (UTF-8) */ --- 6 unchanged lines hidden (view full) --- 2209SQLITE_API int sqlite3_open_v2( 2210 const char *filename, /* Database filename (UTF-8) */ 2211 sqlite3 **ppDb, /* OUT: SQLite db handle */ 2212 int flags, /* Flags */ 2213 const char *zVfs /* Name of VFS module to use */ 2214); 2215 2216/* | 2568** <b>Note to Windows users:</b> The encoding used for the filename argument 2569** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever 2570** codepage is currently defined. Filenames containing international 2571** characters must be converted to UTF-8 prior to passing them into 2572** sqlite3_open() or sqlite3_open_v2(). 2573*/ 2574SQLITE_API int sqlite3_open( 2575 const char *filename, /* Database filename (UTF-8) */ --- 6 unchanged lines hidden (view full) --- 2582SQLITE_API int sqlite3_open_v2( 2583 const char *filename, /* Database filename (UTF-8) */ 2584 sqlite3 **ppDb, /* OUT: SQLite db handle */ 2585 int flags, /* Flags */ 2586 const char *zVfs /* Name of VFS module to use */ 2587); 2588 2589/* |
2590** CAPI3REF: Obtain Values For URI Parameters 2591** 2592** This is a utility routine, useful to VFS implementations, that checks 2593** to see if a database file was a URI that contained a specific query 2594** parameter, and if so obtains the value of the query parameter. 2595** 2596** The zFilename argument is the filename pointer passed into the xOpen() 2597** method of a VFS implementation. The zParam argument is the name of the 2598** query parameter we seek. This routine returns the value of the zParam 2599** parameter if it exists. If the parameter does not exist, this routine 2600** returns a NULL pointer. 2601** 2602** If the zFilename argument to this function is not a pointer that SQLite 2603** passed into the xOpen VFS method, then the behavior of this routine 2604** is undefined and probably undesirable. 2605*/ 2606SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam); 2607 2608 2609/* |
|
2217** CAPI3REF: Error Codes And Messages 2218** 2219** ^The sqlite3_errcode() interface returns the numeric [result code] or 2220** [extended result code] for the most recent failed sqlite3_* API call 2221** associated with a [database connection]. If a prior API call failed 2222** but the most recent API call succeeded, the return value from 2223** sqlite3_errcode() is undefined. ^The sqlite3_extended_errcode() | 2610** CAPI3REF: Error Codes And Messages 2611** 2612** ^The sqlite3_errcode() interface returns the numeric [result code] or 2613** [extended result code] for the most recent failed sqlite3_* API call 2614** associated with a [database connection]. If a prior API call failed 2615** but the most recent API call succeeded, the return value from 2616** sqlite3_errcode() is undefined. ^The sqlite3_extended_errcode() |
2224** interface is the same except that it always returns the | 2617** interface is the same except that it always returns the |
2225** [extended result code] even when extended result codes are 2226** disabled. 2227** 2228** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language 2229** text that describes the error, as either UTF-8 or UTF-16 respectively. 2230** ^(Memory to hold the error message string is managed internally. 2231** The application does not need to worry about freeing the result. 2232** However, the error string might be overwritten or deallocated by --- 47 unchanged lines hidden (view full) --- 2280/* 2281** CAPI3REF: Run-time Limits 2282** 2283** ^(This interface allows the size of various constructs to be limited 2284** on a connection by connection basis. The first parameter is the 2285** [database connection] whose limit is to be set or queried. The 2286** second parameter is one of the [limit categories] that define a 2287** class of constructs to be size limited. The third parameter is the | 2618** [extended result code] even when extended result codes are 2619** disabled. 2620** 2621** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language 2622** text that describes the error, as either UTF-8 or UTF-16 respectively. 2623** ^(Memory to hold the error message string is managed internally. 2624** The application does not need to worry about freeing the result. 2625** However, the error string might be overwritten or deallocated by --- 47 unchanged lines hidden (view full) --- 2673/* 2674** CAPI3REF: Run-time Limits 2675** 2676** ^(This interface allows the size of various constructs to be limited 2677** on a connection by connection basis. The first parameter is the 2678** [database connection] whose limit is to be set or queried. The 2679** second parameter is one of the [limit categories] that define a 2680** class of constructs to be size limited. The third parameter is the |
2288** new limit for that construct. The function returns the old limit.)^ | 2681** new limit for that construct.)^ |
2289** 2290** ^If the new limit is a negative number, the limit is unchanged. | 2682** 2683** ^If the new limit is a negative number, the limit is unchanged. |
2291** ^(For the limit category of SQLITE_LIMIT_XYZ there is a | 2684** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a |
2292** [limits | hard upper bound] | 2685** [limits | hard upper bound] |
2293** set by a compile-time C preprocessor macro named 2294** [limits | SQLITE_MAX_XYZ]. | 2686** set at compile-time by a C preprocessor macro called 2687** [limits | SQLITE_MAX_<i>NAME</i>]. |
2295** (The "_LIMIT_" in the name is changed to "_MAX_".))^ 2296** ^Attempts to increase a limit above its hard upper bound are 2297** silently truncated to the hard upper bound. 2298** | 2688** (The "_LIMIT_" in the name is changed to "_MAX_".))^ 2689** ^Attempts to increase a limit above its hard upper bound are 2690** silently truncated to the hard upper bound. 2691** |
2692** ^Regardless of whether or not the limit was changed, the 2693** [sqlite3_limit()] interface returns the prior value of the limit. 2694** ^Hence, to find the current value of a limit without changing it, 2695** simply invoke this interface with the third parameter set to -1. 2696** |
|
2299** Run-time limits are intended for use in applications that manage 2300** both their own internal database and also databases that are controlled 2301** by untrusted external sources. An example application might be a 2302** web browser that has its own databases for storing history and 2303** separate databases controlled by JavaScript applications downloaded 2304** off the Internet. The internal databases can be given the 2305** large, default limits. Databases managed by external sources can 2306** be given much smaller limits designed to prevent a denial of service --- 11 unchanged lines hidden (view full) --- 2318** KEYWORDS: {limit category} {*limit categories} 2319** 2320** These constants define various performance limits 2321** that can be lowered at run-time using [sqlite3_limit()]. 2322** The synopsis of the meanings of the various limits is shown below. 2323** Additional information is available at [limits | Limits in SQLite]. 2324** 2325** <dl> | 2697** Run-time limits are intended for use in applications that manage 2698** both their own internal database and also databases that are controlled 2699** by untrusted external sources. An example application might be a 2700** web browser that has its own databases for storing history and 2701** separate databases controlled by JavaScript applications downloaded 2702** off the Internet. The internal databases can be given the 2703** large, default limits. Databases managed by external sources can 2704** be given much smaller limits designed to prevent a denial of service --- 11 unchanged lines hidden (view full) --- 2716** KEYWORDS: {limit category} {*limit categories} 2717** 2718** These constants define various performance limits 2719** that can be lowered at run-time using [sqlite3_limit()]. 2720** The synopsis of the meanings of the various limits is shown below. 2721** Additional information is available at [limits | Limits in SQLite]. 2722** 2723** <dl> |
2326** ^( 2327** | 2724** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt> 2725** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^ |
2328** | 2726** |
2329** ^( | 2727** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt> |
2330** <dd>The maximum length of an SQL statement, in bytes.</dd>)^ 2331** | 2728** <dd>The maximum length of an SQL statement, in bytes.</dd>)^ 2729** |
2332** ^( | 2730** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt> |
2333** <dd>The maximum number of columns in a table definition or in the 2334** result set of a [SELECT] or the maximum number of columns in an index 2335** or in an ORDER BY or GROUP BY clause.</dd>)^ 2336** | 2731** <dd>The maximum number of columns in a table definition or in the 2732** result set of a [SELECT] or the maximum number of columns in an index 2733** or in an ORDER BY or GROUP BY clause.</dd>)^ 2734** |
2337** ^( | 2735** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt> |
2338** <dd>The maximum depth of the parse tree on any expression.</dd>)^ 2339** | 2736** <dd>The maximum depth of the parse tree on any expression.</dd>)^ 2737** |
2340** ^( | 2738** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt> |
2341** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^ 2342** | 2739** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^ 2740** |
2343** ^( | 2741** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt> |
2344** <dd>The maximum number of instructions in a virtual machine program | 2742** <dd>The maximum number of instructions in a virtual machine program |
2345** used to implement an SQL statement.</dd>)^ | 2743** used to implement an SQL statement. This limit is not currently 2744** enforced, though that might be added in some future release of 2745** SQLite.</dd>)^ |
2346** | 2746** |
2347** ^( | 2747** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt> |
2348** <dd>The maximum number of arguments on a function.</dd>)^ 2349** | 2748** <dd>The maximum number of arguments on a function.</dd>)^ 2749** |
2350** ^( | 2750** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt> |
2351** <dd>The maximum number of [ATTACH | attached databases].)^</dd> 2352** | 2751** <dd>The maximum number of [ATTACH | attached databases].)^</dd> 2752** |
2753** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]] |
|
2353** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt> 2354** <dd>The maximum length of the pattern argument to the [LIKE] or 2355** [GLOB] operators.</dd>)^ 2356** | 2754** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt> 2755** <dd>The maximum length of the pattern argument to the [LIKE] or 2756** [GLOB] operators.</dd>)^ 2757** |
2758** [[SQLITE_LIMIT_VARIABLE_NUMBER]] |
|
2357** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt> | 2759** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt> |
2358** <dd>The maximum number of variables in an SQL statement that can 2359** be bound.</dd>)^ | 2760** <dd>The maximum index number of any [parameter] in an SQL statement.)^ |
2360** | 2761** |
2361** ^( | 2762** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt> |
2362** <dd>The maximum depth of recursion for triggers.</dd>)^ 2363** </dl> 2364*/ 2365#define SQLITE_LIMIT_LENGTH 0 2366#define SQLITE_LIMIT_SQL_LENGTH 1 2367#define SQLITE_LIMIT_COLUMN 2 2368#define SQLITE_LIMIT_EXPR_DEPTH 3 2369#define SQLITE_LIMIT_COMPOUND_SELECT 4 --- 53 unchanged lines hidden (view full) --- 2423** that is returned (the [sqlite3_stmt] object) contains a copy of the 2424** original SQL text. This causes the [sqlite3_step()] interface to 2425** behave differently in three ways: 2426** 2427** <ol> 2428** <li> 2429** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it 2430** always used to do, [sqlite3_step()] will automatically recompile the SQL | 2763** <dd>The maximum depth of recursion for triggers.</dd>)^ 2764** </dl> 2765*/ 2766#define SQLITE_LIMIT_LENGTH 0 2767#define SQLITE_LIMIT_SQL_LENGTH 1 2768#define SQLITE_LIMIT_COLUMN 2 2769#define SQLITE_LIMIT_EXPR_DEPTH 3 2770#define SQLITE_LIMIT_COMPOUND_SELECT 4 --- 53 unchanged lines hidden (view full) --- 2824** that is returned (the [sqlite3_stmt] object) contains a copy of the 2825** original SQL text. This causes the [sqlite3_step()] interface to 2826** behave differently in three ways: 2827** 2828** <ol> 2829** <li> 2830** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it 2831** always used to do, [sqlite3_step()] will automatically recompile the SQL |
2431** statement and try to run it again. ^If the schema has changed in 2432** a way that makes the statement no longer valid, [sqlite3_step()] will still 2433** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is 2434** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the 2435** error go away. Note: use [sqlite3_errmsg()] to find the text 2436** of the parsing error that results in an [SQLITE_SCHEMA] return. | 2832** statement and try to run it again. |
2437** </li> 2438** 2439** <li> 2440** ^When an error occurs, [sqlite3_step()] will return one of the detailed 2441** [error codes] or [extended error codes]. ^The legacy behavior was that 2442** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code 2443** and the application would have to make a second call to [sqlite3_reset()] 2444** in order to find the underlying cause of the problem. With the "v2" prepare 2445** interfaces, the underlying reason for the error is returned immediately. 2446** </li> 2447** 2448** <li> | 2833** </li> 2834** 2835** <li> 2836** ^When an error occurs, [sqlite3_step()] will return one of the detailed 2837** [error codes] or [extended error codes]. ^The legacy behavior was that 2838** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code 2839** and the application would have to make a second call to [sqlite3_reset()] 2840** in order to find the underlying cause of the problem. With the "v2" prepare 2841** interfaces, the underlying reason for the error is returned immediately. 2842** </li> 2843** 2844** <li> |
2449** ^If the value of a [parameter | host parameter] in the WHERE clause might 2450** change the query plan for a statement, then the statement may be 2451** automatically recompiled (as if there had been a schema change) on the first 2452** [sqlite3_step()] call following any change to the 2453** [sqlite3_bind_text | bindings] of the [parameter]. | 2845** ^If the specific value bound to [parameter | host parameter] in the 2846** WHERE clause might influence the choice of query plan for a statement, 2847** then the statement will be automatically recompiled, as if there had been 2848** a schema change, on the first [sqlite3_step()] call following any change 2849** to the [sqlite3_bind_text | bindings] of that [parameter]. 2850** ^The specific value of WHERE-clause [parameter] might influence the 2851** choice of query plan if the parameter is the left-hand side of a [LIKE] 2852** or [GLOB] operator or if the parameter is compared to an indexed column 2853** and the [SQLITE_ENABLE_STAT2] compile-time option is enabled. 2854** the |
2454** </li> 2455** </ol> 2456*/ 2457SQLITE_API int sqlite3_prepare( 2458 sqlite3 *db, /* Database handle */ 2459 const char *zSql, /* SQL statement, UTF-8 encoded */ 2460 int nByte, /* Maximum length of zSql in bytes. */ 2461 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ --- 26 unchanged lines hidden (view full) --- 2488** 2489** ^This interface can be used to retrieve a saved copy of the original 2490** SQL text used to create a [prepared statement] if that statement was 2491** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. 2492*/ 2493SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt); 2494 2495/* | 2855** </li> 2856** </ol> 2857*/ 2858SQLITE_API int sqlite3_prepare( 2859 sqlite3 *db, /* Database handle */ 2860 const char *zSql, /* SQL statement, UTF-8 encoded */ 2861 int nByte, /* Maximum length of zSql in bytes. */ 2862 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ --- 26 unchanged lines hidden (view full) --- 2889** 2890** ^This interface can be used to retrieve a saved copy of the original 2891** SQL text used to create a [prepared statement] if that statement was 2892** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. 2893*/ 2894SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt); 2895 2896/* |
2897** CAPI3REF: Determine If An SQL Statement Writes The Database 2898** 2899** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if 2900** and only if the [prepared statement] X makes no direct changes to 2901** the content of the database file. 2902** 2903** Note that [application-defined SQL functions] or 2904** [virtual tables] might change the database indirectly as a side effect. 2905** ^(For example, if an application defines a function "eval()" that 2906** calls [sqlite3_exec()], then the following SQL statement would 2907** change the database file through side-effects: 2908** 2909** <blockquote><pre> 2910** SELECT eval('DELETE FROM t1') FROM t2; 2911** </pre></blockquote> 2912** 2913** But because the [SELECT] statement does not change the database file 2914** directly, sqlite3_stmt_readonly() would still return true.)^ 2915** 2916** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK], 2917** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true, 2918** since the statements themselves do not actually modify the database but 2919** rather they control the timing of when other statements modify the 2920** database. ^The [ATTACH] and [DETACH] statements also cause 2921** sqlite3_stmt_readonly() to return true since, while those statements 2922** change the configuration of a database connection, they do not make 2923** changes to the content of the database files on disk. 2924*/ 2925SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt); 2926 2927/* |
|
2496** CAPI3REF: Dynamically Typed Value Object 2497** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} 2498** 2499** SQLite uses the sqlite3_value object to represent all values 2500** that can be stored in a database table. SQLite uses dynamic typing 2501** for the values it stores. ^Values stored in sqlite3_value objects 2502** can be integers, floating point values, strings, BLOBs, or NULL. 2503** 2504** An sqlite3_value object may be either "protected" or "unprotected". 2505** Some interfaces require a protected sqlite3_value. Other interfaces 2506** will accept either a protected or an unprotected sqlite3_value. 2507** Every interface that accepts sqlite3_value arguments specifies 2508** whether or not it requires a protected sqlite3_value. 2509** 2510** The terms "protected" and "unprotected" refer to whether or not | 2928** CAPI3REF: Dynamically Typed Value Object 2929** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} 2930** 2931** SQLite uses the sqlite3_value object to represent all values 2932** that can be stored in a database table. SQLite uses dynamic typing 2933** for the values it stores. ^Values stored in sqlite3_value objects 2934** can be integers, floating point values, strings, BLOBs, or NULL. 2935** 2936** An sqlite3_value object may be either "protected" or "unprotected". 2937** Some interfaces require a protected sqlite3_value. Other interfaces 2938** will accept either a protected or an unprotected sqlite3_value. 2939** Every interface that accepts sqlite3_value arguments specifies 2940** whether or not it requires a protected sqlite3_value. 2941** 2942** The terms "protected" and "unprotected" refer to whether or not |
2511** a mutex is held. A internal mutex is held for a protected | 2943** a mutex is held. An internal mutex is held for a protected |
2512** sqlite3_value object but no mutex is held for an unprotected 2513** sqlite3_value object. If SQLite is compiled to be single-threaded 2514** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0) | 2944** sqlite3_value object but no mutex is held for an unprotected 2945** sqlite3_value object. If SQLite is compiled to be single-threaded 2946** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0) |
2515** or if SQLite is run in one of reduced mutex modes | 2947** or if SQLite is run in one of reduced mutex modes |
2516** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD] 2517** then there is no distinction between protected and unprotected 2518** sqlite3_value objects and they can be used interchangeably. However, 2519** for maximum code portability it is recommended that applications | 2948** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD] 2949** then there is no distinction between protected and unprotected 2950** sqlite3_value objects and they can be used interchangeably. However, 2951** for maximum code portability it is recommended that applications |
2520** still make the distinction between between protected and unprotected | 2952** still make the distinction between protected and unprotected |
2521** sqlite3_value objects even when not strictly required. 2522** 2523** ^The sqlite3_value objects that are passed as parameters into the 2524** implementation of [application-defined SQL functions] are protected. 2525** ^The sqlite3_value object returned by 2526** [sqlite3_column_value()] is unprotected. 2527** Unprotected sqlite3_value objects may only be used with 2528** [sqlite3_result_value()] and [sqlite3_bind_value()]. --- 29 unchanged lines hidden (view full) --- 2558** <li> ? 2559** <li> ?NNN 2560** <li> :VVV 2561** <li> @VVV 2562** <li> $VVV 2563** </ul> 2564** 2565** In the templates above, NNN represents an integer literal, | 2953** sqlite3_value objects even when not strictly required. 2954** 2955** ^The sqlite3_value objects that are passed as parameters into the 2956** implementation of [application-defined SQL functions] are protected. 2957** ^The sqlite3_value object returned by 2958** [sqlite3_column_value()] is unprotected. 2959** Unprotected sqlite3_value objects may only be used with 2960** [sqlite3_result_value()] and [sqlite3_bind_value()]. --- 29 unchanged lines hidden (view full) --- 2990** <li> ? 2991** <li> ?NNN 2992** <li> :VVV 2993** <li> @VVV 2994** <li> $VVV 2995** </ul> 2996** 2997** In the templates above, NNN represents an integer literal, |
2566** and VVV represents an alphanumeric identifer.)^ ^The values of these | 2998** and VVV represents an alphanumeric identifier.)^ ^The values of these |
2567** parameters (also called "host parameter names" or "SQL parameters") 2568** can be set using the sqlite3_bind_*() routines defined here. 2569** 2570** ^The first argument to the sqlite3_bind_*() routines is always 2571** a pointer to the [sqlite3_stmt] object returned from 2572** [sqlite3_prepare_v2()] or its variants. 2573** 2574** ^The second argument is the index of the SQL parameter to be set. --- 11 unchanged lines hidden (view full) --- 2586** ^(In those routines that have a fourth argument, its value is the 2587** number of bytes in the parameter. To be clear: the value is the 2588** number of <u>bytes</u> in the value, not the number of characters.)^ 2589** ^If the fourth parameter is negative, the length of the string is 2590** the number of bytes up to the first zero terminator. 2591** 2592** ^The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and 2593** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or | 2999** parameters (also called "host parameter names" or "SQL parameters") 3000** can be set using the sqlite3_bind_*() routines defined here. 3001** 3002** ^The first argument to the sqlite3_bind_*() routines is always 3003** a pointer to the [sqlite3_stmt] object returned from 3004** [sqlite3_prepare_v2()] or its variants. 3005** 3006** ^The second argument is the index of the SQL parameter to be set. --- 11 unchanged lines hidden (view full) --- 3018** ^(In those routines that have a fourth argument, its value is the 3019** number of bytes in the parameter. To be clear: the value is the 3020** number of <u>bytes</u> in the value, not the number of characters.)^ 3021** ^If the fourth parameter is negative, the length of the string is 3022** the number of bytes up to the first zero terminator. 3023** 3024** ^The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and 3025** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or |
2594** string after SQLite has finished with it. ^If the fifth argument is | 3026** string after SQLite has finished with it. ^The destructor is called 3027** to dispose of the BLOB or string even if the call to sqlite3_bind_blob(), 3028** sqlite3_bind_text(), or sqlite3_bind_text16() fails. 3029** ^If the fifth argument is |
2595** the special value [SQLITE_STATIC], then SQLite assumes that the 2596** information is in static, unmanaged space and does not need to be freed. 2597** ^If the fifth argument has the value [SQLITE_TRANSIENT], then 2598** SQLite makes its own private copy of the data immediately, before 2599** the sqlite3_bind_*() routine returns. 2600** 2601** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that 2602** is filled with zeroes. ^A zeroblob uses a fixed amount of memory --- 104 unchanged lines hidden (view full) --- 2707SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*); 2708 2709/* 2710** CAPI3REF: Number Of Columns In A Result Set 2711** 2712** ^Return the number of columns in the result set returned by the 2713** [prepared statement]. ^This routine returns 0 if pStmt is an SQL 2714** statement that does not return data (for example an [UPDATE]). | 3030** the special value [SQLITE_STATIC], then SQLite assumes that the 3031** information is in static, unmanaged space and does not need to be freed. 3032** ^If the fifth argument has the value [SQLITE_TRANSIENT], then 3033** SQLite makes its own private copy of the data immediately, before 3034** the sqlite3_bind_*() routine returns. 3035** 3036** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that 3037** is filled with zeroes. ^A zeroblob uses a fixed amount of memory --- 104 unchanged lines hidden (view full) --- 3142SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*); 3143 3144/* 3145** CAPI3REF: Number Of Columns In A Result Set 3146** 3147** ^Return the number of columns in the result set returned by the 3148** [prepared statement]. ^This routine returns 0 if pStmt is an SQL 3149** statement that does not return data (for example an [UPDATE]). |
3150** 3151** See also: [sqlite3_data_count()] |
|
2715*/ 2716SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt); 2717 2718/* 2719** CAPI3REF: Column Names In A Result Set 2720** 2721** ^These routines return the name assigned to a particular column 2722** in the result set of a [SELECT] statement. ^The sqlite3_column_name() 2723** interface returns a pointer to a zero-terminated UTF-8 string 2724** and sqlite3_column_name16() returns a pointer to a zero-terminated 2725** UTF-16 string. ^The first parameter is the [prepared statement] 2726** that implements the [SELECT] statement. ^The second parameter is the 2727** column number. ^The leftmost column is number 0. 2728** 2729** ^The returned string pointer is valid until either the [prepared statement] | 3152*/ 3153SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt); 3154 3155/* 3156** CAPI3REF: Column Names In A Result Set 3157** 3158** ^These routines return the name assigned to a particular column 3159** in the result set of a [SELECT] statement. ^The sqlite3_column_name() 3160** interface returns a pointer to a zero-terminated UTF-8 string 3161** and sqlite3_column_name16() returns a pointer to a zero-terminated 3162** UTF-16 string. ^The first parameter is the [prepared statement] 3163** that implements the [SELECT] statement. ^The second parameter is the 3164** column number. ^The leftmost column is number 0. 3165** 3166** ^The returned string pointer is valid until either the [prepared statement] |
2730** is destroyed by [sqlite3_finalize()] or until the next call to | 3167** is destroyed by [sqlite3_finalize()] or until the statement is automatically 3168** reprepared by the first call to [sqlite3_step()] for a particular run 3169** or until the next call to |
2731** sqlite3_column_name() or sqlite3_column_name16() on the same column. 2732** 2733** ^If sqlite3_malloc() fails during the processing of either routine 2734** (for example during a conversion from UTF-8 to UTF-16) then a 2735** NULL pointer is returned. 2736** 2737** ^The name of a result column is the value of the "AS" clause for 2738** that column, if there is an AS clause. If there is no AS clause --- 9 unchanged lines hidden (view full) --- 2748** ^These routines provide a means to determine the database, table, and 2749** table column that is the origin of a particular result column in 2750** [SELECT] statement. 2751** ^The name of the database or table or column can be returned as 2752** either a UTF-8 or UTF-16 string. ^The _database_ routines return 2753** the database name, the _table_ routines return the table name, and 2754** the origin_ routines return the column name. 2755** ^The returned string is valid until the [prepared statement] is destroyed | 3170** sqlite3_column_name() or sqlite3_column_name16() on the same column. 3171** 3172** ^If sqlite3_malloc() fails during the processing of either routine 3173** (for example during a conversion from UTF-8 to UTF-16) then a 3174** NULL pointer is returned. 3175** 3176** ^The name of a result column is the value of the "AS" clause for 3177** that column, if there is an AS clause. If there is no AS clause --- 9 unchanged lines hidden (view full) --- 3187** ^These routines provide a means to determine the database, table, and 3188** table column that is the origin of a particular result column in 3189** [SELECT] statement. 3190** ^The name of the database or table or column can be returned as 3191** either a UTF-8 or UTF-16 string. ^The _database_ routines return 3192** the database name, the _table_ routines return the table name, and 3193** the origin_ routines return the column name. 3194** ^The returned string is valid until the [prepared statement] is destroyed |
2756** using [sqlite3_finalize()] or until the same information is requested | 3195** using [sqlite3_finalize()] or until the statement is automatically 3196** reprepared by the first call to [sqlite3_step()] for a particular run 3197** or until the same information is requested |
2757** again in a different encoding. 2758** 2759** ^The names returned are the original un-aliased names of the 2760** database, table, and column. 2761** 2762** ^The first argument to these interfaces is a [prepared statement]. 2763** ^These functions return information about the Nth result column returned by 2764** the statement, where N is the second function argument. --- 77 unchanged lines hidden (view full) --- 2842** ^In the legacy interface, the return value will be either [SQLITE_BUSY], 2843** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. 2844** ^With the "v2" interface, any of the other [result codes] or 2845** [extended result codes] might be returned as well. 2846** 2847** ^[SQLITE_BUSY] means that the database engine was unable to acquire the 2848** database locks it needs to do its job. ^If the statement is a [COMMIT] 2849** or occurs outside of an explicit transaction, then you can retry the | 3198** again in a different encoding. 3199** 3200** ^The names returned are the original un-aliased names of the 3201** database, table, and column. 3202** 3203** ^The first argument to these interfaces is a [prepared statement]. 3204** ^These functions return information about the Nth result column returned by 3205** the statement, where N is the second function argument. --- 77 unchanged lines hidden (view full) --- 3283** ^In the legacy interface, the return value will be either [SQLITE_BUSY], 3284** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. 3285** ^With the "v2" interface, any of the other [result codes] or 3286** [extended result codes] might be returned as well. 3287** 3288** ^[SQLITE_BUSY] means that the database engine was unable to acquire the 3289** database locks it needs to do its job. ^If the statement is a [COMMIT] 3290** or occurs outside of an explicit transaction, then you can retry the |
2850** statement. If the statement is not a [COMMIT] and occurs within a | 3291** statement. If the statement is not a [COMMIT] and occurs within an |
2851** explicit transaction then you should rollback the transaction before 2852** continuing. 2853** 2854** ^[SQLITE_DONE] means that the statement has finished executing 2855** successfully. sqlite3_step() should not be called again on this virtual 2856** machine without first calling [sqlite3_reset()] to reset the virtual 2857** machine back to its initial state. 2858** --- 13 unchanged lines hidden (view full) --- 2872** 2873** [SQLITE_MISUSE] means that the this routine was called inappropriately. 2874** Perhaps it was called on a [prepared statement] that has 2875** already been [sqlite3_finalize | finalized] or on one that had 2876** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could 2877** be the case that the same database connection is being used by two or 2878** more threads at the same moment in time. 2879** | 3292** explicit transaction then you should rollback the transaction before 3293** continuing. 3294** 3295** ^[SQLITE_DONE] means that the statement has finished executing 3296** successfully. sqlite3_step() should not be called again on this virtual 3297** machine without first calling [sqlite3_reset()] to reset the virtual 3298** machine back to its initial state. 3299** --- 13 unchanged lines hidden (view full) --- 3313** 3314** [SQLITE_MISUSE] means that the this routine was called inappropriately. 3315** Perhaps it was called on a [prepared statement] that has 3316** already been [sqlite3_finalize | finalized] or on one that had 3317** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could 3318** be the case that the same database connection is being used by two or 3319** more threads at the same moment in time. 3320** |
3321** For all versions of SQLite up to and including 3.6.23.1, a call to 3322** [sqlite3_reset()] was required after sqlite3_step() returned anything 3323** other than [SQLITE_ROW] before any subsequent invocation of 3324** sqlite3_step(). Failure to reset the prepared statement using 3325** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from 3326** sqlite3_step(). But after version 3.6.23.1, sqlite3_step() began 3327** calling [sqlite3_reset()] automatically in this circumstance rather 3328** than returning [SQLITE_MISUSE]. This is not considered a compatibility 3329** break because any application that ever receives an SQLITE_MISUSE error 3330** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option 3331** can be used to restore the legacy behavior. 3332** |
|
2880** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step() 2881** API always returns a generic error code, [SQLITE_ERROR], following any 2882** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call 2883** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the 2884** specific [error codes] that better describes the error. 2885** We admit that this is a goofy design. The problem has been fixed 2886** with the "v2" interface. If you prepare all of your SQL statements 2887** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead 2888** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces, 2889** then the more specific [error codes] are returned directly 2890** by sqlite3_step(). The use of the "v2" interface is recommended. 2891*/ 2892SQLITE_API int sqlite3_step(sqlite3_stmt*); 2893 2894/* 2895** CAPI3REF: Number of columns in a result set 2896** | 3333** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step() 3334** API always returns a generic error code, [SQLITE_ERROR], following any 3335** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call 3336** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the 3337** specific [error codes] that better describes the error. 3338** We admit that this is a goofy design. The problem has been fixed 3339** with the "v2" interface. If you prepare all of your SQL statements 3340** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead 3341** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces, 3342** then the more specific [error codes] are returned directly 3343** by sqlite3_step(). The use of the "v2" interface is recommended. 3344*/ 3345SQLITE_API int sqlite3_step(sqlite3_stmt*); 3346 3347/* 3348** CAPI3REF: Number of columns in a result set 3349** |
2897** ^The sqlite3_data_count(P) the number of columns in the 2898** of the result set of [prepared statement] P. | 3350** ^The sqlite3_data_count(P) interface returns the number of columns in the 3351** current row of the result set of [prepared statement] P. 3352** ^If prepared statement P does not have results ready to return 3353** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of 3354** interfaces) then sqlite3_data_count(P) returns 0. 3355** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer. 3356** 3357** See also: [sqlite3_column_count()] |
2899*/ 2900SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); 2901 2902/* 2903** CAPI3REF: Fundamental Datatypes 2904** KEYWORDS: SQLITE_TEXT 2905** 2906** ^(Every value in SQLite has one of five fundamental datatypes: --- 63 unchanged lines hidden (view full) --- 2970** 2971** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 2972** routine returns the number of bytes in that BLOB or string. 2973** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts 2974** the string to UTF-8 and then returns the number of bytes. 2975** ^If the result is a numeric value then sqlite3_column_bytes() uses 2976** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns 2977** the number of bytes in that string. | 3358*/ 3359SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); 3360 3361/* 3362** CAPI3REF: Fundamental Datatypes 3363** KEYWORDS: SQLITE_TEXT 3364** 3365** ^(Every value in SQLite has one of five fundamental datatypes: --- 63 unchanged lines hidden (view full) --- 3429** 3430** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 3431** routine returns the number of bytes in that BLOB or string. 3432** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts 3433** the string to UTF-8 and then returns the number of bytes. 3434** ^If the result is a numeric value then sqlite3_column_bytes() uses 3435** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns 3436** the number of bytes in that string. |
2978** ^The value returned does not include the zero terminator at the end 2979** of the string. ^For clarity: the value returned is the number of | 3437** ^If the result is NULL, then sqlite3_column_bytes() returns zero. 3438** 3439** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16() 3440** routine returns the number of bytes in that BLOB or string. 3441** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts 3442** the string to UTF-16 and then returns the number of bytes. 3443** ^If the result is a numeric value then sqlite3_column_bytes16() uses 3444** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns 3445** the number of bytes in that string. 3446** ^If the result is NULL, then sqlite3_column_bytes16() returns zero. 3447** 3448** ^The values returned by [sqlite3_column_bytes()] and 3449** [sqlite3_column_bytes16()] do not include the zero terminators at the end 3450** of the string. ^For clarity: the values returned by 3451** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of |
2980** bytes in the string, not the number of characters. 2981** 2982** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(), 2983** even empty strings, are always zero terminated. ^The return | 3452** bytes in the string, not the number of characters. 3453** 3454** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(), 3455** even empty strings, are always zero terminated. ^The return |
2984** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary 2985** pointer, possibly even a NULL pointer. | 3456** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer. |
2986** | 3457** |
2987** ^The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() 2988** but leaves the result in UTF-16 in native byte order instead of UTF-8. 2989** ^The zero terminator is not included in this count. 2990** | |
2991** ^The object returned by [sqlite3_column_value()] is an 2992** [unprotected sqlite3_value] object. An unprotected sqlite3_value object 2993** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()]. 2994** If the [unprotected sqlite3_value] object returned by 2995** [sqlite3_column_value()] is used in any other way, including calls 2996** to routines like [sqlite3_value_int()], [sqlite3_value_text()], 2997** or [sqlite3_value_bytes()], then the behavior is undefined. 2998** --- 27 unchanged lines hidden (view full) --- 3026** </blockquote>)^ 3027** 3028** The table above makes reference to standard C library functions atoi() 3029** and atof(). SQLite does not really use these functions. It has its 3030** own equivalent internal routines. The atoi() and atof() names are 3031** used in the table for brevity and because they are familiar to most 3032** C programmers. 3033** | 3458** ^The object returned by [sqlite3_column_value()] is an 3459** [unprotected sqlite3_value] object. An unprotected sqlite3_value object 3460** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()]. 3461** If the [unprotected sqlite3_value] object returned by 3462** [sqlite3_column_value()] is used in any other way, including calls 3463** to routines like [sqlite3_value_int()], [sqlite3_value_text()], 3464** or [sqlite3_value_bytes()], then the behavior is undefined. 3465** --- 27 unchanged lines hidden (view full) --- 3493** </blockquote>)^ 3494** 3495** The table above makes reference to standard C library functions atoi() 3496** and atof(). SQLite does not really use these functions. It has its 3497** own equivalent internal routines. The atoi() and atof() names are 3498** used in the table for brevity and because they are familiar to most 3499** C programmers. 3500** |
3034** ^Note that when type conversions occur, pointers returned by prior | 3501** Note that when type conversions occur, pointers returned by prior |
3035** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or 3036** sqlite3_column_text16() may be invalidated. | 3502** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or 3503** sqlite3_column_text16() may be invalidated. |
3037** ^(Type conversions and pointer invalidations might occur | 3504** Type conversions and pointer invalidations might occur |
3038** in the following cases: 3039** 3040** <ul> 3041** <li> The initial content is a BLOB and sqlite3_column_text() or 3042** sqlite3_column_text16() is called. A zero-terminator might 3043** need to be added to the string.</li> 3044** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or 3045** sqlite3_column_text16() is called. The content must be converted 3046** to UTF-16.</li> 3047** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or 3048** sqlite3_column_text() is called. The content must be converted 3049** to UTF-8.</li> | 3505** in the following cases: 3506** 3507** <ul> 3508** <li> The initial content is a BLOB and sqlite3_column_text() or 3509** sqlite3_column_text16() is called. A zero-terminator might 3510** need to be added to the string.</li> 3511** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or 3512** sqlite3_column_text16() is called. The content must be converted 3513** to UTF-16.</li> 3514** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or 3515** sqlite3_column_text() is called. The content must be converted 3516** to UTF-8.</li> |
3050** </ul>)^ | 3517** |
3051** 3052** ^Conversions between UTF-16be and UTF-16le are always done in place and do 3053** not invalidate a prior pointer, though of course the content of the buffer | 3518** 3519** ^Conversions between UTF-16be and UTF-16le are always done in place and do 3520** not invalidate a prior pointer, though of course the content of the buffer |
3054** that the prior pointer points to will have been modified. Other kinds | 3521** that the prior pointer references will have been modified. Other kinds |
3055** of conversion are done in place when it is possible, but sometimes they 3056** are not possible and in those cases prior pointers are invalidated. 3057** | 3522** of conversion are done in place when it is possible, but sometimes they 3523** are not possible and in those cases prior pointers are invalidated. 3524** |
3058** ^(The safest and easiest to remember policy is to invoke these routines | 3525** The safest and easiest to remember policy is to invoke these routines |
3059** in one of the following ways: 3060** 3061** <ul> 3062** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li> 3063** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li> 3064** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li> | 3526** in one of the following ways: 3527** 3528** <ul> 3529** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li> 3530** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li> 3531** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li> |
3065** </ul>)^ | 3532** |
3066** 3067** In other words, you should call sqlite3_column_text(), 3068** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result 3069** into the desired format, then invoke sqlite3_column_bytes() or 3070** sqlite3_column_bytes16() to find the size of the result. Do not mix calls 3071** to sqlite3_column_text() or sqlite3_column_blob() with calls to 3072** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() 3073** with calls to sqlite3_column_bytes(). --- 21 unchanged lines hidden (view full) --- 3095SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); 3096SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol); 3097SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); 3098 3099/* 3100** CAPI3REF: Destroy A Prepared Statement Object 3101** 3102** ^The sqlite3_finalize() function is called to delete a [prepared statement]. | 3533** 3534** In other words, you should call sqlite3_column_text(), 3535** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result 3536** into the desired format, then invoke sqlite3_column_bytes() or 3537** sqlite3_column_bytes16() to find the size of the result. Do not mix calls 3538** to sqlite3_column_text() or sqlite3_column_blob() with calls to 3539** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() 3540** with calls to sqlite3_column_bytes(). --- 21 unchanged lines hidden (view full) --- 3562SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); 3563SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol); 3564SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); 3565 3566/* 3567** CAPI3REF: Destroy A Prepared Statement Object 3568** 3569** ^The sqlite3_finalize() function is called to delete a [prepared statement]. |
3103** ^If the statement was executed successfully or not executed at all, then 3104** SQLITE_OK is returned. ^If execution of the statement failed then an 3105** [error code] or [extended error code] is returned. | 3570** ^If the most recent evaluation of the statement encountered no errors 3571** or if the statement is never been evaluated, then sqlite3_finalize() returns 3572** SQLITE_OK. ^If the most recent evaluation of statement S failed, then 3573** sqlite3_finalize(S) returns the appropriate [error code] or 3574** [extended error code]. |
3106** | 3575** |
3107** ^This routine can be called at any point during the execution of the 3108** [prepared statement]. ^If the virtual machine has not 3109** completed execution when this routine is called, that is like 3110** encountering an error or an [sqlite3_interrupt | interrupt]. 3111** ^Incomplete updates may be rolled back and transactions canceled, 3112** depending on the circumstances, and the 3113** [error code] returned will be [SQLITE_ABORT]. | 3576** ^The sqlite3_finalize(S) routine can be called at any point during 3577** the life cycle of [prepared statement] S: 3578** before statement S is ever evaluated, after 3579** one or more calls to [sqlite3_reset()], or after any call 3580** to [sqlite3_step()] regardless of whether or not the statement has 3581** completed execution. 3582** 3583** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op. 3584** 3585** The application must finalize every [prepared statement] in order to avoid 3586** resource leaks. It is a grievous error for the application to try to use 3587** a prepared statement after it has been finalized. Any use of a prepared 3588** statement after it has been finalized can result in undefined and 3589** undesirable behavior such as segfaults and heap corruption. |
3114*/ 3115SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt); 3116 3117/* 3118** CAPI3REF: Reset A Prepared Statement Object 3119** 3120** The sqlite3_reset() function is called to reset a [prepared statement] 3121** object back to its initial state, ready to be re-executed. --- 19 unchanged lines hidden (view full) --- 3141SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt); 3142 3143/* 3144** CAPI3REF: Create Or Redefine SQL Functions 3145** KEYWORDS: {function creation routines} 3146** KEYWORDS: {application-defined SQL function} 3147** KEYWORDS: {application-defined SQL functions} 3148** | 3590*/ 3591SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt); 3592 3593/* 3594** CAPI3REF: Reset A Prepared Statement Object 3595** 3596** The sqlite3_reset() function is called to reset a [prepared statement] 3597** object back to its initial state, ready to be re-executed. --- 19 unchanged lines hidden (view full) --- 3617SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt); 3618 3619/* 3620** CAPI3REF: Create Or Redefine SQL Functions 3621** KEYWORDS: {function creation routines} 3622** KEYWORDS: {application-defined SQL function} 3623** KEYWORDS: {application-defined SQL functions} 3624** |
3149** ^These two functions (collectively known as "function creation routines") | 3625** ^These functions (collectively known as "function creation routines") |
3150** are used to add SQL functions or aggregates or to redefine the behavior | 3626** are used to add SQL functions or aggregates or to redefine the behavior |
3151** of existing SQL functions or aggregates. The only difference between the 3152** two is that the second parameter, the name of the (scalar) function or 3153** aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16 3154** for sqlite3_create_function16(). | 3627** of existing SQL functions or aggregates. The only differences between 3628** these routines are the text encoding expected for 3629** the second parameter (the name of the function being created) 3630** and the presence or absence of a destructor callback for 3631** the application data pointer. |
3155** 3156** ^The first parameter is the [database connection] to which the SQL 3157** function is to be added. ^If an application uses more than one database 3158** connection then application-defined SQL functions must be added 3159** to each database connection separately. 3160** | 3632** 3633** ^The first parameter is the [database connection] to which the SQL 3634** function is to be added. ^If an application uses more than one database 3635** connection then application-defined SQL functions must be added 3636** to each database connection separately. 3637** |
3161** The second parameter is the name of the SQL function to be created or 3162** redefined. ^The length of the name is limited to 255 bytes, exclusive of 3163** the zero-terminator. Note that the name length limit is in bytes, not 3164** characters. ^Any attempt to create a function with a longer name 3165** will result in [SQLITE_ERROR] being returned. | 3638** ^The second parameter is the name of the SQL function to be created or 3639** redefined. ^The length of the name is limited to 255 bytes in a UTF-8 3640** representation, exclusive of the zero-terminator. ^Note that the name 3641** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes. 3642** ^Any attempt to create a function with a longer name 3643** will result in [SQLITE_MISUSE] being returned. |
3166** 3167** ^The third parameter (nArg) 3168** is the number of arguments that the SQL function or 3169** aggregate takes. ^If this parameter is -1, then the SQL function or 3170** aggregate may take any number of arguments between 0 and the limit 3171** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third 3172** parameter is less than -1 or greater than 127 then the behavior is 3173** undefined. 3174** | 3644** 3645** ^The third parameter (nArg) 3646** is the number of arguments that the SQL function or 3647** aggregate takes. ^If this parameter is -1, then the SQL function or 3648** aggregate may take any number of arguments between 0 and the limit 3649** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third 3650** parameter is less than -1 or greater than 127 then the behavior is 3651** undefined. 3652** |
3175** The fourth parameter, eTextRep, specifies what | 3653** ^The fourth parameter, eTextRep, specifies what |
3176** [SQLITE_UTF8 | text encoding] this SQL function prefers for | 3654** [SQLITE_UTF8 | text encoding] this SQL function prefers for |
3177** its parameters. Any SQL function implementation should be able to work 3178** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be | 3655** its parameters. Every SQL function implementation must be able to work 3656** with UTF-8, UTF-16le, or UTF-16be. But some implementations may be |
3179** more efficient with one encoding than another. ^An application may 3180** invoke sqlite3_create_function() or sqlite3_create_function16() multiple 3181** times with the same function but with different values of eTextRep. 3182** ^When multiple implementations of the same function are available, SQLite 3183** will pick the one that involves the least amount of data conversion. 3184** If there is only a single implementation which does not care what text 3185** encoding is used, then the fourth argument should be [SQLITE_ANY]. 3186** 3187** ^(The fifth parameter is an arbitrary pointer. The implementation of the 3188** function can gain access to this pointer using [sqlite3_user_data()].)^ 3189** | 3657** more efficient with one encoding than another. ^An application may 3658** invoke sqlite3_create_function() or sqlite3_create_function16() multiple 3659** times with the same function but with different values of eTextRep. 3660** ^When multiple implementations of the same function are available, SQLite 3661** will pick the one that involves the least amount of data conversion. 3662** If there is only a single implementation which does not care what text 3663** encoding is used, then the fourth argument should be [SQLITE_ANY]. 3664** 3665** ^(The fifth parameter is an arbitrary pointer. The implementation of the 3666** function can gain access to this pointer using [sqlite3_user_data()].)^ 3667** |
3190** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are | 3668** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are |
3191** pointers to C-language functions that implement the SQL function or 3192** aggregate. ^A scalar SQL function requires an implementation of the xFunc | 3669** pointers to C-language functions that implement the SQL function or 3670** aggregate. ^A scalar SQL function requires an implementation of the xFunc |
3193** callback only; NULL pointers should be passed as the xStep and xFinal | 3671** callback only; NULL pointers must be passed as the xStep and xFinal |
3194** parameters. ^An aggregate SQL function requires an implementation of xStep | 3672** parameters. ^An aggregate SQL function requires an implementation of xStep |
3195** and xFinal and NULL should be passed for xFunc. ^To delete an existing 3196** SQL function or aggregate, pass NULL for all three function callbacks. | 3673** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing 3674** SQL function or aggregate, pass NULL pointers for all three function 3675** callbacks. |
3197** | 3676** |
3677** ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL, 3678** then it is destructor for the application data pointer. 3679** The destructor is invoked when the function is deleted, either by being 3680** overloaded or when the database connection closes.)^ 3681** ^The destructor is also invoked if the call to 3682** sqlite3_create_function_v2() fails. 3683** ^When the destructor callback of the tenth parameter is invoked, it 3684** is passed a single argument which is a copy of the application data 3685** pointer which was the fifth parameter to sqlite3_create_function_v2(). 3686** |
|
3198** ^It is permitted to register multiple implementations of the same 3199** functions with the same name but with either differing numbers of 3200** arguments or differing preferred text encodings. ^SQLite will use 3201** the implementation that most closely matches the way in which the 3202** SQL function is used. ^A function implementation with a non-negative 3203** nArg parameter is a better match than a function implementation with 3204** a negative nArg. ^A function where the preferred text encoding 3205** matches the database encoding is a better | 3687** ^It is permitted to register multiple implementations of the same 3688** functions with the same name but with either differing numbers of 3689** arguments or differing preferred text encodings. ^SQLite will use 3690** the implementation that most closely matches the way in which the 3691** SQL function is used. ^A function implementation with a non-negative 3692** nArg parameter is a better match than a function implementation with 3693** a negative nArg. ^A function where the preferred text encoding 3694** matches the database encoding is a better |
3206** match than a function where the encoding is different. | 3695** match than a function where the encoding is different. |
3207** ^A function where the encoding difference is between UTF16le and UTF16be 3208** is a closer match than a function where the encoding difference is 3209** between UTF8 and UTF16. 3210** 3211** ^Built-in functions may be overloaded by new application-defined functions. | 3696** ^A function where the encoding difference is between UTF16le and UTF16be 3697** is a closer match than a function where the encoding difference is 3698** between UTF8 and UTF16. 3699** 3700** ^Built-in functions may be overloaded by new application-defined functions. |
3212** ^The first application-defined function with a given name overrides all 3213** built-in functions in the same [database connection] with the same name. 3214** ^Subsequent application-defined functions of the same name only override 3215** prior application-defined functions that are an exact match for the 3216** number of parameters and preferred encoding. | |
3217** 3218** ^An application-defined function is permitted to call other 3219** SQLite interfaces. However, such calls must not 3220** close the database connection nor finalize or reset the prepared 3221** statement in which the function is running. 3222*/ 3223SQLITE_API int sqlite3_create_function( 3224 sqlite3 *db, --- 10 unchanged lines hidden (view full) --- 3235 const void *zFunctionName, 3236 int nArg, 3237 int eTextRep, 3238 void *pApp, 3239 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 3240 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 3241 void (*xFinal)(sqlite3_context*) 3242); | 3701** 3702** ^An application-defined function is permitted to call other 3703** SQLite interfaces. However, such calls must not 3704** close the database connection nor finalize or reset the prepared 3705** statement in which the function is running. 3706*/ 3707SQLITE_API int sqlite3_create_function( 3708 sqlite3 *db, --- 10 unchanged lines hidden (view full) --- 3719 const void *zFunctionName, 3720 int nArg, 3721 int eTextRep, 3722 void *pApp, 3723 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 3724 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 3725 void (*xFinal)(sqlite3_context*) 3726); |
3727SQLITE_API int sqlite3_create_function_v2( 3728 sqlite3 *db, 3729 const char *zFunctionName, 3730 int nArg, 3731 int eTextRep, 3732 void *pApp, 3733 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 3734 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 3735 void (*xFinal)(sqlite3_context*), 3736 void(*xDestroy)(void*) 3737); |
|
3243 3244/* 3245** CAPI3REF: Text Encodings 3246** 3247** These constant define integer codes that represent the various 3248** text encodings supported by SQLite. 3249*/ 3250#define SQLITE_UTF8 1 3251#define SQLITE_UTF16LE 2 3252#define SQLITE_UTF16BE 3 3253#define SQLITE_UTF16 4 /* Use native byte order */ 3254#define SQLITE_ANY 5 /* sqlite3_create_function only */ 3255#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ 3256 3257/* 3258** CAPI3REF: Deprecated Functions 3259** DEPRECATED 3260** 3261** These functions are [deprecated]. In order to maintain | 3738 3739/* 3740** CAPI3REF: Text Encodings 3741** 3742** These constant define integer codes that represent the various 3743** text encodings supported by SQLite. 3744*/ 3745#define SQLITE_UTF8 1 3746#define SQLITE_UTF16LE 2 3747#define SQLITE_UTF16BE 3 3748#define SQLITE_UTF16 4 /* Use native byte order */ 3749#define SQLITE_ANY 5 /* sqlite3_create_function only */ 3750#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ 3751 3752/* 3753** CAPI3REF: Deprecated Functions 3754** DEPRECATED 3755** 3756** These functions are [deprecated]. In order to maintain |
3262** backwards compatibility with older code, these functions continue | 3757** backwards compatibility with older code, these functions continue |
3263** to be supported. However, new applications should avoid 3264** the use of these functions. To help encourage people to avoid 3265** using these functions, we are not going to tell you what they do. 3266*/ 3267#ifndef SQLITE_OMIT_DEPRECATED 3268SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*); 3269SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*); 3270SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); --- 7 unchanged lines hidden (view full) --- 3278** 3279** The C-language implementation of SQL functions and aggregates uses 3280** this set of interface routines to access the parameter values on 3281** the function or aggregate. 3282** 3283** The xFunc (for scalar functions) or xStep (for aggregates) parameters 3284** to [sqlite3_create_function()] and [sqlite3_create_function16()] 3285** define callbacks that implement the SQL functions and aggregates. | 3758** to be supported. However, new applications should avoid 3759** the use of these functions. To help encourage people to avoid 3760** using these functions, we are not going to tell you what they do. 3761*/ 3762#ifndef SQLITE_OMIT_DEPRECATED 3763SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*); 3764SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*); 3765SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); --- 7 unchanged lines hidden (view full) --- 3773** 3774** The C-language implementation of SQL functions and aggregates uses 3775** this set of interface routines to access the parameter values on 3776** the function or aggregate. 3777** 3778** The xFunc (for scalar functions) or xStep (for aggregates) parameters 3779** to [sqlite3_create_function()] and [sqlite3_create_function16()] 3780** define callbacks that implement the SQL functions and aggregates. |
3286** The 4th parameter to these callbacks is an array of pointers to | 3781** The 3rd parameter to these callbacks is an array of pointers to |
3287** [protected sqlite3_value] objects. There is one [sqlite3_value] object for 3288** each parameter to the SQL function. These routines are used to 3289** extract values from the [sqlite3_value] objects. 3290** 3291** These routines work only with [protected sqlite3_value] objects. 3292** Any attempt to use these routines on an [unprotected sqlite3_value] 3293** object results in undefined behavior. 3294** --- 34 unchanged lines hidden (view full) --- 3329SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*); 3330SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*); 3331SQLITE_API int sqlite3_value_type(sqlite3_value*); 3332SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*); 3333 3334/* 3335** CAPI3REF: Obtain Aggregate Function Context 3336** | 3782** [protected sqlite3_value] objects. There is one [sqlite3_value] object for 3783** each parameter to the SQL function. These routines are used to 3784** extract values from the [sqlite3_value] objects. 3785** 3786** These routines work only with [protected sqlite3_value] objects. 3787** Any attempt to use these routines on an [unprotected sqlite3_value] 3788** object results in undefined behavior. 3789** --- 34 unchanged lines hidden (view full) --- 3824SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*); 3825SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*); 3826SQLITE_API int sqlite3_value_type(sqlite3_value*); 3827SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*); 3828 3829/* 3830** CAPI3REF: Obtain Aggregate Function Context 3831** |
3337** Implementions of aggregate SQL functions use this | 3832** Implementations of aggregate SQL functions use this |
3338** routine to allocate memory for storing their state. 3339** | 3833** routine to allocate memory for storing their state. 3834** |
3340** ^The first time the sqlite3_aggregate_context(C,N) routine is called | 3835** ^The first time the sqlite3_aggregate_context(C,N) routine is called |
3341** for a particular aggregate function, SQLite 3342** allocates N of memory, zeroes out that memory, and returns a pointer 3343** to the new memory. ^On second and subsequent calls to 3344** sqlite3_aggregate_context() for the same aggregate function instance, 3345** the same buffer is returned. Sqlite3_aggregate_context() is normally 3346** called once for each invocation of the xStep callback and then one 3347** last time when the xFinal callback is invoked. ^(When no rows match 3348** an aggregate query, the xStep() callback of the aggregate function --- 5 unchanged lines hidden (view full) --- 3354** less than or equal to zero or if a memory allocate error occurs. 3355** 3356** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is 3357** determined by the N parameter on first successful call. Changing the 3358** value of N in subsequent call to sqlite3_aggregate_context() within 3359** the same aggregate function instance will not resize the memory 3360** allocation.)^ 3361** | 3836** for a particular aggregate function, SQLite 3837** allocates N of memory, zeroes out that memory, and returns a pointer 3838** to the new memory. ^On second and subsequent calls to 3839** sqlite3_aggregate_context() for the same aggregate function instance, 3840** the same buffer is returned. Sqlite3_aggregate_context() is normally 3841** called once for each invocation of the xStep callback and then one 3842** last time when the xFinal callback is invoked. ^(When no rows match 3843** an aggregate query, the xStep() callback of the aggregate function --- 5 unchanged lines hidden (view full) --- 3849** less than or equal to zero or if a memory allocate error occurs. 3850** 3851** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is 3852** determined by the N parameter on first successful call. Changing the 3853** value of N in subsequent call to sqlite3_aggregate_context() within 3854** the same aggregate function instance will not resize the memory 3855** allocation.)^ 3856** |
3362** ^SQLite automatically frees the memory allocated by | 3857** ^SQLite automatically frees the memory allocated by |
3363** sqlite3_aggregate_context() when the aggregate query concludes. 3364** 3365** The first parameter must be a copy of the 3366** [sqlite3_context | SQL function context] that is the first parameter 3367** to the xStep or xFinal callback routine that implements the aggregate 3368** function. 3369** 3370** This routine must be called from the same thread in which --- 210 unchanged lines hidden (view full) --- 3581SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); 3582SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); 3583SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*); 3584SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n); 3585 3586/* 3587** CAPI3REF: Define New Collating Sequences 3588** | 3858** sqlite3_aggregate_context() when the aggregate query concludes. 3859** 3860** The first parameter must be a copy of the 3861** [sqlite3_context | SQL function context] that is the first parameter 3862** to the xStep or xFinal callback routine that implements the aggregate 3863** function. 3864** 3865** This routine must be called from the same thread in which --- 210 unchanged lines hidden (view full) --- 4076SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); 4077SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); 4078SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*); 4079SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n); 4080 4081/* 4082** CAPI3REF: Define New Collating Sequences 4083** |
3589** These functions are used to add new collation sequences to the 3590** [database connection] specified as the first argument. | 4084** ^These functions add, remove, or modify a [collation] associated 4085** with the [database connection] specified as the first argument. |
3591** | 4086** |
3592** ^The name of the new collation sequence is specified as a UTF-8 string | 4087** ^The name of the collation is a UTF-8 string |
3593** for sqlite3_create_collation() and sqlite3_create_collation_v2() | 4088** for sqlite3_create_collation() and sqlite3_create_collation_v2() |
3594** and a UTF-16 string for sqlite3_create_collation16(). ^In all cases 3595** the name is passed as the second function argument. | 4089** and a UTF-16 string in native byte order for sqlite3_create_collation16(). 4090** ^Collation names that compare equal according to [sqlite3_strnicmp()] are 4091** considered to be the same name. |
3596** | 4092** |
3597** ^The third argument may be one of the constants [SQLITE_UTF8], 3598** [SQLITE_UTF16LE], or [SQLITE_UTF16BE], indicating that the user-supplied 3599** routine expects to be passed pointers to strings encoded using UTF-8, 3600** UTF-16 little-endian, or UTF-16 big-endian, respectively. ^The 3601** third argument might also be [SQLITE_UTF16] to indicate that the routine 3602** expects pointers to be UTF-16 strings in the native byte order, or the 3603** argument can be [SQLITE_UTF16_ALIGNED] if the 3604** the routine expects pointers to 16-bit word aligned strings 3605** of UTF-16 in the native byte order. | 4093** ^(The third argument (eTextRep) must be one of the constants: 4094** <ul> 4095** <li> [SQLITE_UTF8], 4096** <li> [SQLITE_UTF16LE], 4097** <li> [SQLITE_UTF16BE], 4098** <li> [SQLITE_UTF16], or 4099** <li> [SQLITE_UTF16_ALIGNED]. 4100** </ul>)^ 4101** ^The eTextRep argument determines the encoding of strings passed 4102** to the collating function callback, xCallback. 4103** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep 4104** force strings to be UTF16 with native byte order. 4105** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin 4106** on an even byte address. |
3606** | 4107** |
3607** A pointer to the user supplied routine must be passed as the fifth 3608** argument. ^If it is NULL, this is the same as deleting the collation 3609** sequence (so that SQLite cannot call it anymore). 3610** ^Each time the application supplied function is invoked, it is passed 3611** as its first parameter a copy of the void* passed as the fourth argument 3612** to sqlite3_create_collation() or sqlite3_create_collation16(). | 4108** ^The fourth argument, pArg, is an application data pointer that is passed 4109** through as the first argument to the collating function callback. |
3613** | 4110** |
3614** ^The remaining arguments to the application-supplied routine are two strings, 3615** each represented by a (length, data) pair and encoded in the encoding 3616** that was passed as the third argument when the collation sequence was 3617** registered. The application defined collation routine should 3618** return negative, zero or positive if the first string is less than, 3619** equal to, or greater than the second string. i.e. (STRING1 - STRING2). | 4111** ^The fifth argument, xCallback, is a pointer to the collating function. 4112** ^Multiple collating functions can be registered using the same name but 4113** with different eTextRep parameters and SQLite will use whichever 4114** function requires the least amount of data transformation. 4115** ^If the xCallback argument is NULL then the collating function is 4116** deleted. ^When all collating functions having the same name are deleted, 4117** that collation is no longer usable. |
3620** | 4118** |
4119** ^The collating function callback is invoked with a copy of the pArg 4120** application data pointer and with two strings in the encoding specified 4121** by the eTextRep argument. The collating function must return an 4122** integer that is negative, zero, or positive 4123** if the first string is less than, equal to, or greater than the second, 4124** respectively. A collating function must always return the same answer 4125** given the same inputs. If two or more collating functions are registered 4126** to the same collation name (using different eTextRep values) then all 4127** must give an equivalent answer when invoked with equivalent strings. 4128** The collating function must obey the following properties for all 4129** strings A, B, and C: 4130** 4131** <ol> 4132** <li> If A==B then B==A. 4133** <li> If A==B and B==C then A==C. 4134** <li> If A<B THEN B>A. 4135** <li> If A<B and B<C then A<C. 4136** </ol> 4137** 4138** If a collating function fails any of the above constraints and that 4139** collating function is registered and used, then the behavior of SQLite 4140** is undefined. 4141** |
|
3621** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation() | 4142** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation() |
3622** except that it takes an extra argument which is a destructor for 3623** the collation. ^The destructor is called when the collation is 3624** destroyed and is passed a copy of the fourth parameter void* pointer 3625** of the sqlite3_create_collation_v2(). 3626** ^Collations are destroyed when they are overridden by later calls to the 3627** collation creation functions or when the [database connection] is closed 3628** using [sqlite3_close()]. | 4143** with the addition that the xDestroy callback is invoked on pArg when 4144** the collating function is deleted. 4145** ^Collating functions are deleted when they are overridden by later 4146** calls to the collation creation functions or when the 4147** [database connection] is closed using [sqlite3_close()]. |
3629** | 4148** |
4149** ^The xDestroy callback is <u>not</u> called if the 4150** sqlite3_create_collation_v2() function fails. Applications that invoke 4151** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should 4152** check the return code and dispose of the application data pointer 4153** themselves rather than expecting SQLite to deal with it for them. 4154** This is different from every other SQLite interface. The inconsistency 4155** is unfortunate but cannot be changed without breaking backwards 4156** compatibility. 4157** |
|
3630** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()]. 3631*/ 3632SQLITE_API int sqlite3_create_collation( | 4158** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()]. 4159*/ 4160SQLITE_API int sqlite3_create_collation( |
3633 sqlite3*, 3634 const char *zName, 3635 int eTextRep, 3636 void*, | 4161 sqlite3*, 4162 const char *zName, 4163 int eTextRep, 4164 void *pArg, |
3637 int(*xCompare)(void*,int,const void*,int,const void*) 3638); 3639SQLITE_API int sqlite3_create_collation_v2( | 4165 int(*xCompare)(void*,int,const void*,int,const void*) 4166); 4167SQLITE_API int sqlite3_create_collation_v2( |
3640 sqlite3*, 3641 const char *zName, 3642 int eTextRep, 3643 void*, | 4168 sqlite3*, 4169 const char *zName, 4170 int eTextRep, 4171 void *pArg, |
3644 int(*xCompare)(void*,int,const void*,int,const void*), 3645 void(*xDestroy)(void*) 3646); 3647SQLITE_API int sqlite3_create_collation16( | 4172 int(*xCompare)(void*,int,const void*,int,const void*), 4173 void(*xDestroy)(void*) 4174); 4175SQLITE_API int sqlite3_create_collation16( |
3648 sqlite3*, | 4176 sqlite3*, |
3649 const void *zName, | 4177 const void *zName, |
3650 int eTextRep, 3651 void*, | 4178 int eTextRep, 4179 void *pArg, |
3652 int(*xCompare)(void*,int,const void*,int,const void*) 3653); 3654 3655/* 3656** CAPI3REF: Collation Needed Callbacks 3657** 3658** ^To avoid having to register all collation sequences before a database 3659** can be used, a single callback function may be registered with the --- 14 unchanged lines hidden (view full) --- 3674** sequence function required. The fourth parameter is the name of the 3675** required collation sequence.)^ 3676** 3677** The callback function should register the desired collation using 3678** [sqlite3_create_collation()], [sqlite3_create_collation16()], or 3679** [sqlite3_create_collation_v2()]. 3680*/ 3681SQLITE_API int sqlite3_collation_needed( | 4180 int(*xCompare)(void*,int,const void*,int,const void*) 4181); 4182 4183/* 4184** CAPI3REF: Collation Needed Callbacks 4185** 4186** ^To avoid having to register all collation sequences before a database 4187** can be used, a single callback function may be registered with the --- 14 unchanged lines hidden (view full) --- 4202** sequence function required. The fourth parameter is the name of the 4203** required collation sequence.)^ 4204** 4205** The callback function should register the desired collation using 4206** [sqlite3_create_collation()], [sqlite3_create_collation16()], or 4207** [sqlite3_create_collation_v2()]. 4208*/ 4209SQLITE_API int sqlite3_collation_needed( |
3682 sqlite3*, 3683 void*, | 4210 sqlite3*, 4211 void*, |
3684 void(*)(void*,sqlite3*,int eTextRep,const char*) 3685); 3686SQLITE_API int sqlite3_collation_needed16( | 4212 void(*)(void*,sqlite3*,int eTextRep,const char*) 4213); 4214SQLITE_API int sqlite3_collation_needed16( |
3687 sqlite3*, | 4215 sqlite3*, |
3688 void*, 3689 void(*)(void*,sqlite3*,int eTextRep,const void*) 3690); 3691 | 4216 void*, 4217 void(*)(void*,sqlite3*,int eTextRep,const void*) 4218); 4219 |
3692#if SQLITE_HAS_CODEC | 4220#ifdef SQLITE_HAS_CODEC |
3693/* 3694** Specify the key for an encrypted database. This routine should be 3695** called right after sqlite3_open(). 3696** 3697** The code to implement this API is not available in the public release 3698** of SQLite. 3699*/ 3700SQLITE_API int sqlite3_key( --- 10 unchanged lines hidden (view full) --- 3711** of SQLite. 3712*/ 3713SQLITE_API int sqlite3_rekey( 3714 sqlite3 *db, /* Database to be rekeyed */ 3715 const void *pKey, int nKey /* The new key */ 3716); 3717 3718/* | 4221/* 4222** Specify the key for an encrypted database. This routine should be 4223** called right after sqlite3_open(). 4224** 4225** The code to implement this API is not available in the public release 4226** of SQLite. 4227*/ 4228SQLITE_API int sqlite3_key( --- 10 unchanged lines hidden (view full) --- 4239** of SQLite. 4240*/ 4241SQLITE_API int sqlite3_rekey( 4242 sqlite3 *db, /* Database to be rekeyed */ 4243 const void *pKey, int nKey /* The new key */ 4244); 4245 4246/* |
3719** Specify the activation key for a SEE database. Unless | 4247** Specify the activation key for a SEE database. Unless |
3720** activated, none of the SEE routines will work. 3721*/ 3722SQLITE_API void sqlite3_activate_see( 3723 const char *zPassPhrase /* Activation phrase */ 3724); 3725#endif 3726 3727#ifdef SQLITE_ENABLE_CEROD 3728/* | 4248** activated, none of the SEE routines will work. 4249*/ 4250SQLITE_API void sqlite3_activate_see( 4251 const char *zPassPhrase /* Activation phrase */ 4252); 4253#endif 4254 4255#ifdef SQLITE_ENABLE_CEROD 4256/* |
3729** Specify the activation key for a CEROD database. Unless | 4257** Specify the activation key for a CEROD database. Unless |
3730** activated, none of the CEROD routines will work. 3731*/ 3732SQLITE_API void sqlite3_activate_cerod( 3733 const char *zPassPhrase /* Activation phrase */ 3734); 3735#endif 3736 3737/* 3738** CAPI3REF: Suspend Execution For A Short Time 3739** | 4258** activated, none of the CEROD routines will work. 4259*/ 4260SQLITE_API void sqlite3_activate_cerod( 4261 const char *zPassPhrase /* Activation phrase */ 4262); 4263#endif 4264 4265/* 4266** CAPI3REF: Suspend Execution For A Short Time 4267** |
3740** ^The sqlite3_sleep() function causes the current thread to suspend execution | 4268** The sqlite3_sleep() function causes the current thread to suspend execution |
3741** for at least a number of milliseconds specified in its parameter. 3742** | 4269** for at least a number of milliseconds specified in its parameter. 4270** |
3743** ^If the operating system does not support sleep requests with | 4271** If the operating system does not support sleep requests with |
3744** millisecond time resolution, then the time will be rounded up to | 4272** millisecond time resolution, then the time will be rounded up to |
3745** the nearest second. ^The number of milliseconds of sleep actually | 4273** the nearest second. The number of milliseconds of sleep actually |
3746** requested from the operating system is returned. 3747** 3748** ^SQLite implements this interface by calling the xSleep() | 4274** requested from the operating system is returned. 4275** 4276** ^SQLite implements this interface by calling the xSleep() |
3749** method of the default [sqlite3_vfs] object. | 4277** method of the default [sqlite3_vfs] object. If the xSleep() method 4278** of the default VFS is not implemented correctly, or not implemented at 4279** all, then the behavior of sqlite3_sleep() may deviate from the description 4280** in the previous paragraphs. |
3750*/ 3751SQLITE_API int sqlite3_sleep(int); 3752 3753/* 3754** CAPI3REF: Name Of The Folder Holding Temporary Files 3755** 3756** ^(If this global variable is made to point to a string which is 3757** the name of a folder (a.k.a. directory), then all temporary files --- 9 unchanged lines hidden (view full) --- 3767** It is intended that this variable be set once 3768** as part of process initialization and before any SQLite interface 3769** routines have been called and that this variable remain unchanged 3770** thereafter. 3771** 3772** ^The [temp_store_directory pragma] may modify this variable and cause 3773** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore, 3774** the [temp_store_directory pragma] always assumes that any string | 4281*/ 4282SQLITE_API int sqlite3_sleep(int); 4283 4284/* 4285** CAPI3REF: Name Of The Folder Holding Temporary Files 4286** 4287** ^(If this global variable is made to point to a string which is 4288** the name of a folder (a.k.a. directory), then all temporary files --- 9 unchanged lines hidden (view full) --- 4298** It is intended that this variable be set once 4299** as part of process initialization and before any SQLite interface 4300** routines have been called and that this variable remain unchanged 4301** thereafter. 4302** 4303** ^The [temp_store_directory pragma] may modify this variable and cause 4304** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore, 4305** the [temp_store_directory pragma] always assumes that any string |
3775** that this variable points to is held in memory obtained from | 4306** that this variable points to is held in memory obtained from |
3776** [sqlite3_malloc] and the pragma may attempt to free that memory 3777** using [sqlite3_free]. 3778** Hence, if this variable is modified directly, either it should be 3779** made NULL or made to point to memory obtained from [sqlite3_malloc] 3780** or else the use of the [temp_store_directory pragma] should be avoided. 3781*/ 3782SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory; 3783 --- 83 unchanged lines hidden (view full) --- 3867** ^The rollback hook is invoked on a rollback that results from a commit 3868** hook returning non-zero, just as it would be with any other rollback. 3869** 3870** ^For the purposes of this API, a transaction is said to have been 3871** rolled back if an explicit "ROLLBACK" statement is executed, or 3872** an error or constraint causes an implicit rollback to occur. 3873** ^The rollback callback is not invoked if a transaction is 3874** automatically rolled back because the database connection is closed. | 4307** [sqlite3_malloc] and the pragma may attempt to free that memory 4308** using [sqlite3_free]. 4309** Hence, if this variable is modified directly, either it should be 4310** made NULL or made to point to memory obtained from [sqlite3_malloc] 4311** or else the use of the [temp_store_directory pragma] should be avoided. 4312*/ 4313SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory; 4314 --- 83 unchanged lines hidden (view full) --- 4398** ^The rollback hook is invoked on a rollback that results from a commit 4399** hook returning non-zero, just as it would be with any other rollback. 4400** 4401** ^For the purposes of this API, a transaction is said to have been 4402** rolled back if an explicit "ROLLBACK" statement is executed, or 4403** an error or constraint causes an implicit rollback to occur. 4404** ^The rollback callback is not invoked if a transaction is 4405** automatically rolled back because the database connection is closed. |
3875** ^The rollback callback is not invoked if a transaction is 3876** rolled back because a commit callback returned non-zero. | |
3877** 3878** See also the [sqlite3_update_hook()] interface. 3879*/ 3880SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); 3881SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); 3882 3883/* 3884** CAPI3REF: Data Change Notification Callbacks --- 37 unchanged lines hidden (view full) --- 3922** returns the P argument from the previous call 3923** on the same [database connection] D, or NULL for 3924** the first call on D. 3925** 3926** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()] 3927** interfaces. 3928*/ 3929SQLITE_API void *sqlite3_update_hook( | 4406** 4407** See also the [sqlite3_update_hook()] interface. 4408*/ 4409SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); 4410SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); 4411 4412/* 4413** CAPI3REF: Data Change Notification Callbacks --- 37 unchanged lines hidden (view full) --- 4451** returns the P argument from the previous call 4452** on the same [database connection] D, or NULL for 4453** the first call on D. 4454** 4455** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()] 4456** interfaces. 4457*/ 4458SQLITE_API void *sqlite3_update_hook( |
3930 sqlite3*, | 4459 sqlite3*, |
3931 void(*)(void *,int ,char const *,char const *,sqlite3_int64), 3932 void* 3933); 3934 3935/* 3936** CAPI3REF: Enable Or Disable Shared Pager Cache 3937** KEYWORDS: {shared cache} 3938** --- 26 unchanged lines hidden (view full) --- 3965** CAPI3REF: Attempt To Free Heap Memory 3966** 3967** ^The sqlite3_release_memory() interface attempts to free N bytes 3968** of heap memory by deallocating non-essential memory allocations 3969** held by the database library. Memory used to cache database 3970** pages to improve performance is an example of non-essential memory. 3971** ^sqlite3_release_memory() returns the number of bytes actually freed, 3972** which might be more or less than the amount requested. | 4460 void(*)(void *,int ,char const *,char const *,sqlite3_int64), 4461 void* 4462); 4463 4464/* 4465** CAPI3REF: Enable Or Disable Shared Pager Cache 4466** KEYWORDS: {shared cache} 4467** --- 26 unchanged lines hidden (view full) --- 4494** CAPI3REF: Attempt To Free Heap Memory 4495** 4496** ^The sqlite3_release_memory() interface attempts to free N bytes 4497** of heap memory by deallocating non-essential memory allocations 4498** held by the database library. Memory used to cache database 4499** pages to improve performance is an example of non-essential memory. 4500** ^sqlite3_release_memory() returns the number of bytes actually freed, 4501** which might be more or less than the amount requested. |
4502** ^The sqlite3_release_memory() routine is a no-op returning zero 4503** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT]. |
|
3973*/ 3974SQLITE_API int sqlite3_release_memory(int); 3975 3976/* 3977** CAPI3REF: Impose A Limit On Heap Size 3978** | 4504*/ 4505SQLITE_API int sqlite3_release_memory(int); 4506 4507/* 4508** CAPI3REF: Impose A Limit On Heap Size 4509** |
3979** ^The sqlite3_soft_heap_limit() interface places a "soft" limit 3980** on the amount of heap memory that may be allocated by SQLite. 3981** ^If an internal allocation is requested that would exceed the 3982** soft heap limit, [sqlite3_release_memory()] is invoked one or 3983** more times to free up some space before the allocation is performed. | 4510** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the 4511** soft limit on the amount of heap memory that may be allocated by SQLite. 4512** ^SQLite strives to keep heap memory utilization below the soft heap 4513** limit by reducing the number of pages held in the page cache 4514** as heap memory usages approaches the limit. 4515** ^The soft heap limit is "soft" because even though SQLite strives to stay 4516** below the limit, it will exceed the limit rather than generate 4517** an [SQLITE_NOMEM] error. In other words, the soft heap limit 4518** is advisory only. |
3984** | 4519** |
3985** ^The limit is called "soft" because if [sqlite3_release_memory()] 3986** cannot free sufficient memory to prevent the limit from being exceeded, 3987** the memory is allocated anyway and the current operation proceeds. | 4520** ^The return value from sqlite3_soft_heap_limit64() is the size of 4521** the soft heap limit prior to the call. ^If the argument N is negative 4522** then no change is made to the soft heap limit. Hence, the current 4523** size of the soft heap limit can be determined by invoking 4524** sqlite3_soft_heap_limit64() with a negative argument. |
3988** | 4525** |
3989** ^A negative or zero value for N means that there is no soft heap limit and 3990** [sqlite3_release_memory()] will only be called when memory is exhausted. 3991** ^The default value for the soft heap limit is zero. | 4526** ^If the argument N is zero then the soft heap limit is disabled. |
3992** | 4527** |
3993** ^(SQLite makes a best effort to honor the soft heap limit. 3994** But if the soft heap limit cannot be honored, execution will 3995** continue without error or notification.)^ This is why the limit is 3996** called a "soft" limit. It is advisory only. | 4528** ^(The soft heap limit is not enforced in the current implementation 4529** if one or more of following conditions are true: |
3997** | 4530** |
3998** Prior to SQLite version 3.5.0, this routine only constrained the memory 3999** allocated by a single thread - the same thread in which this routine 4000** runs. Beginning with SQLite version 3.5.0, the soft heap limit is 4001** applied to all threads. The value specified for the soft heap limit 4002** is an upper bound on the total memory allocation for all threads. In 4003** version 3.5.0 there is no mechanism for limiting the heap usage for 4004** individual threads. | 4531** <ul> 4532** <li> The soft heap limit is set to zero. 4533** <li> Memory accounting is disabled using a combination of the 4534** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and 4535** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option. 4536** <li> An alternative page cache implementation is specified using 4537** [sqlite3_config]([SQLITE_CONFIG_PCACHE],...). 4538** <li> The page cache allocates from its own memory pool supplied 4539** by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than 4540** from the heap. 4541** </ul>)^ 4542** 4543** Beginning with SQLite version 3.7.3, the soft heap limit is enforced 4544** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT] 4545** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT], 4546** the soft heap limit is enforced on every memory allocation. Without 4547** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced 4548** when memory is allocated by the page cache. Testing suggests that because 4549** the page cache is the predominate memory user in SQLite, most 4550** applications will achieve adequate soft heap limit enforcement without 4551** the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT]. 4552** 4553** The circumstances under which SQLite will enforce the soft heap limit may 4554** changes in future releases of SQLite. |
4005*/ | 4555*/ |
4006SQLITE_API void sqlite3_soft_heap_limit(int); | 4556SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N); |
4007 4008/* | 4557 4558/* |
4559** CAPI3REF: Deprecated Soft Heap Limit Interface 4560** DEPRECATED 4561** 4562** This is a deprecated version of the [sqlite3_soft_heap_limit64()] 4563** interface. This routine is provided for historical compatibility 4564** only. All new applications should use the 4565** [sqlite3_soft_heap_limit64()] interface rather than this one. 4566*/ 4567SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N); 4568 4569 4570/* |
|
4009** CAPI3REF: Extract Metadata About A Column Of A Table 4010** 4011** ^This routine returns metadata about a specific column of a specific 4012** database table accessible using the [database connection] handle 4013** passed as the first function argument. 4014** 4015** ^The column is identified by the second, third and fourth parameters to 4016** this function. ^The second parameter is either the name of the database --- 105 unchanged lines hidden (view full) --- 4122** ^Extension loading is off by default. See ticket #1863. 4123** ^Call the sqlite3_enable_load_extension() routine with onoff==1 4124** to turn extension loading on and call it with onoff==0 to turn 4125** it back off again. 4126*/ 4127SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff); 4128 4129/* | 4571** CAPI3REF: Extract Metadata About A Column Of A Table 4572** 4573** ^This routine returns metadata about a specific column of a specific 4574** database table accessible using the [database connection] handle 4575** passed as the first function argument. 4576** 4577** ^The column is identified by the second, third and fourth parameters to 4578** this function. ^The second parameter is either the name of the database --- 105 unchanged lines hidden (view full) --- 4684** ^Extension loading is off by default. See ticket #1863. 4685** ^Call the sqlite3_enable_load_extension() routine with onoff==1 4686** to turn extension loading on and call it with onoff==0 to turn 4687** it back off again. 4688*/ 4689SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff); 4690 4691/* |
4130** CAPI3REF: Automatically Load An Extensions | 4692** CAPI3REF: Automatically Load Statically Linked Extensions |
4131** | 4693** |
4132** ^This API can be invoked at program startup in order to register 4133** one or more statically linked extensions that will be available 4134** to all new [database connections]. | 4694** ^This interface causes the xEntryPoint() function to be invoked for 4695** each new [database connection] that is created. The idea here is that 4696** xEntryPoint() is the entry point for a statically linked SQLite extension 4697** that is to be automatically loaded into all new database connections. |
4135** | 4698** |
4136** ^(This routine stores a pointer to the extension entry point 4137** in an array that is obtained from [sqlite3_malloc()]. That memory 4138** is deallocated by [sqlite3_reset_auto_extension()].)^ | 4699** ^(Even though the function prototype shows that xEntryPoint() takes 4700** no arguments and returns void, SQLite invokes xEntryPoint() with three 4701** arguments and expects and integer result as if the signature of the 4702** entry point where as follows: |
4139** | 4703** |
4140** ^This function registers an extension entry point that is 4141** automatically invoked whenever a new [database connection] 4142** is opened using [sqlite3_open()], [sqlite3_open16()], 4143** or [sqlite3_open_v2()]. 4144** ^Duplicate extensions are detected so calling this routine 4145** multiple times with the same extension is harmless. 4146** ^Automatic extensions apply across all threads. | 4704** <blockquote><pre> 4705** int xEntryPoint( 4706** sqlite3 *db, 4707** const char **pzErrMsg, 4708** const struct sqlite3_api_routines *pThunk 4709** ); 4710** </pre></blockquote>)^ 4711** 4712** If the xEntryPoint routine encounters an error, it should make *pzErrMsg 4713** point to an appropriate error message (obtained from [sqlite3_mprintf()]) 4714** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg 4715** is NULL before calling the xEntryPoint(). ^SQLite will invoke 4716** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns. ^If any 4717** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()], 4718** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail. 4719** 4720** ^Calling sqlite3_auto_extension(X) with an entry point X that is already 4721** on the list of automatic extensions is a harmless no-op. ^No entry point 4722** will be called more than once for each database connection that is opened. 4723** 4724** See also: [sqlite3_reset_auto_extension()]. |
4147*/ 4148SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void)); 4149 4150/* 4151** CAPI3REF: Reset Automatic Extension Loading 4152** | 4725*/ 4726SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void)); 4727 4728/* 4729** CAPI3REF: Reset Automatic Extension Loading 4730** |
4153** ^(This function disables all previously registered automatic 4154** extensions. It undoes the effect of all prior 4155** [sqlite3_auto_extension()] calls.)^ 4156** 4157** ^This function disables automatic extensions in all threads. | 4731** ^This interface disables all automatic extensions previously 4732** registered using [sqlite3_auto_extension()]. |
4158*/ 4159SQLITE_API void sqlite3_reset_auto_extension(void); 4160 4161/* | 4733*/ 4734SQLITE_API void sqlite3_reset_auto_extension(void); 4735 4736/* |
4162****** EXPERIMENTAL - subject to change without notice ************** 4163** | |
4164** The interface to the virtual-table mechanism is currently considered 4165** to be experimental. The interface might change in incompatible ways. 4166** If this is a problem for you, do not use the interface at this time. 4167** 4168** When the virtual-table mechanism stabilizes, we will declare the 4169** interface fixed, support it indefinitely, and remove this comment. 4170*/ 4171 4172/* 4173** Structures used by the virtual table interface 4174*/ 4175typedef struct sqlite3_vtab sqlite3_vtab; 4176typedef struct sqlite3_index_info sqlite3_index_info; 4177typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; 4178typedef struct sqlite3_module sqlite3_module; 4179 4180/* 4181** CAPI3REF: Virtual Table Object 4182** KEYWORDS: sqlite3_module {virtual table module} | 4737** The interface to the virtual-table mechanism is currently considered 4738** to be experimental. The interface might change in incompatible ways. 4739** If this is a problem for you, do not use the interface at this time. 4740** 4741** When the virtual-table mechanism stabilizes, we will declare the 4742** interface fixed, support it indefinitely, and remove this comment. 4743*/ 4744 4745/* 4746** Structures used by the virtual table interface 4747*/ 4748typedef struct sqlite3_vtab sqlite3_vtab; 4749typedef struct sqlite3_index_info sqlite3_index_info; 4750typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; 4751typedef struct sqlite3_module sqlite3_module; 4752 4753/* 4754** CAPI3REF: Virtual Table Object 4755** KEYWORDS: sqlite3_module {virtual table module} |
4183** EXPERIMENTAL | |
4184** | 4756** |
4185** This structure, sometimes called a a "virtual table module", 4186** defines the implementation of a [virtual tables]. | 4757** This structure, sometimes called a "virtual table module", 4758** defines the implementation of a [virtual tables]. |
4187** This structure consists mostly of methods for the module. 4188** 4189** ^A virtual table module is created by filling in a persistent 4190** instance of this structure and passing a pointer to that instance 4191** to [sqlite3_create_module()] or [sqlite3_create_module_v2()]. 4192** ^The registration remains valid until it is replaced by a different 4193** module or until the [database connection] closes. The content 4194** of this structure must not change while it is registered with --- 22 unchanged lines hidden (view full) --- 4217 int (*xBegin)(sqlite3_vtab *pVTab); 4218 int (*xSync)(sqlite3_vtab *pVTab); 4219 int (*xCommit)(sqlite3_vtab *pVTab); 4220 int (*xRollback)(sqlite3_vtab *pVTab); 4221 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, 4222 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), 4223 void **ppArg); 4224 int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); | 4759** This structure consists mostly of methods for the module. 4760** 4761** ^A virtual table module is created by filling in a persistent 4762** instance of this structure and passing a pointer to that instance 4763** to [sqlite3_create_module()] or [sqlite3_create_module_v2()]. 4764** ^The registration remains valid until it is replaced by a different 4765** module or until the [database connection] closes. The content 4766** of this structure must not change while it is registered with --- 22 unchanged lines hidden (view full) --- 4789 int (*xBegin)(sqlite3_vtab *pVTab); 4790 int (*xSync)(sqlite3_vtab *pVTab); 4791 int (*xCommit)(sqlite3_vtab *pVTab); 4792 int (*xRollback)(sqlite3_vtab *pVTab); 4793 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, 4794 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), 4795 void **ppArg); 4796 int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); |
4797 /* The methods above are in version 1 of the sqlite_module object. Those 4798 ** below are for version 2 and greater. */ 4799 int (*xSavepoint)(sqlite3_vtab *pVTab, int); 4800 int (*xRelease)(sqlite3_vtab *pVTab, int); 4801 int (*xRollbackTo)(sqlite3_vtab *pVTab, int); |
|
4225}; 4226 4227/* 4228** CAPI3REF: Virtual Table Indexing Information 4229** KEYWORDS: sqlite3_index_info | 4802}; 4803 4804/* 4805** CAPI3REF: Virtual Table Indexing Information 4806** KEYWORDS: sqlite3_index_info |
4230** EXPERIMENTAL | |
4231** | 4807** |
4232** The sqlite3_index_info structure and its substructures is used to | 4808** The sqlite3_index_info structure and its substructures is used as part 4809** of the [virtual table] interface to |
4233** pass information into and receive the reply from the [xBestIndex] 4234** method of a [virtual table module]. The fields under **Inputs** are the 4235** inputs to xBestIndex and are read-only. xBestIndex inserts its 4236** results into the **Outputs** fields. 4237** 4238** ^(The aConstraint[] array records WHERE clause constraints of the form: 4239** | 4810** pass information into and receive the reply from the [xBestIndex] 4811** method of a [virtual table module]. The fields under **Inputs** are the 4812** inputs to xBestIndex and are read-only. xBestIndex inserts its 4813** results into the **Outputs** fields. 4814** 4815** ^(The aConstraint[] array records WHERE clause constraints of the form: 4816** |
4240** <pre>column OP expr</pre> | 4817** <blockquote>column OP expr</blockquote> |
4241** 4242** where OP is =, <, <=, >, or >=.)^ ^(The particular operator is | 4818** 4819** where OP is =, <, <=, >, or >=.)^ ^(The particular operator is |
4243** stored in aConstraint[].op.)^ ^(The index of the column is stored in | 4820** stored in aConstraint[].op using one of the 4821** [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^ 4822** ^(The index of the column is stored in |
4244** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the 4245** expr on the right-hand side can be evaluated (and thus the constraint 4246** is usable) and false if it cannot.)^ 4247** 4248** ^The optimizer automatically inverts terms of the form "expr OP column" 4249** and makes other simplifications to the WHERE clause in an attempt to 4250** get as many WHERE clause terms into the form shown above as possible. 4251** ^The aConstraint[] array only reports WHERE clause terms that are --- 43 unchanged lines hidden (view full) --- 4295 unsigned char omit; /* Do not code a test for this constraint */ 4296 } *aConstraintUsage; 4297 int idxNum; /* Number used to identify the index */ 4298 char *idxStr; /* String, possibly obtained from sqlite3_malloc */ 4299 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ 4300 int orderByConsumed; /* True if output is already ordered */ 4301 double estimatedCost; /* Estimated cost of using this index */ 4302}; | 4823** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the 4824** expr on the right-hand side can be evaluated (and thus the constraint 4825** is usable) and false if it cannot.)^ 4826** 4827** ^The optimizer automatically inverts terms of the form "expr OP column" 4828** and makes other simplifications to the WHERE clause in an attempt to 4829** get as many WHERE clause terms into the form shown above as possible. 4830** ^The aConstraint[] array only reports WHERE clause terms that are --- 43 unchanged lines hidden (view full) --- 4874 unsigned char omit; /* Do not code a test for this constraint */ 4875 } *aConstraintUsage; 4876 int idxNum; /* Number used to identify the index */ 4877 char *idxStr; /* String, possibly obtained from sqlite3_malloc */ 4878 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ 4879 int orderByConsumed; /* True if output is already ordered */ 4880 double estimatedCost; /* Estimated cost of using this index */ 4881}; |
4882 4883/* 4884** CAPI3REF: Virtual Table Constraint Operator Codes 4885** 4886** These macros defined the allowed values for the 4887** [sqlite3_index_info].aConstraint[].op field. Each value represents 4888** an operator that is part of a constraint term in the wHERE clause of 4889** a query that uses a [virtual table]. 4890*/ |
|
4303#define SQLITE_INDEX_CONSTRAINT_EQ 2 4304#define SQLITE_INDEX_CONSTRAINT_GT 4 4305#define SQLITE_INDEX_CONSTRAINT_LE 8 4306#define SQLITE_INDEX_CONSTRAINT_LT 16 4307#define SQLITE_INDEX_CONSTRAINT_GE 32 4308#define SQLITE_INDEX_CONSTRAINT_MATCH 64 4309 4310/* 4311** CAPI3REF: Register A Virtual Table Implementation | 4891#define SQLITE_INDEX_CONSTRAINT_EQ 2 4892#define SQLITE_INDEX_CONSTRAINT_GT 4 4893#define SQLITE_INDEX_CONSTRAINT_LE 8 4894#define SQLITE_INDEX_CONSTRAINT_LT 16 4895#define SQLITE_INDEX_CONSTRAINT_GE 32 4896#define SQLITE_INDEX_CONSTRAINT_MATCH 64 4897 4898/* 4899** CAPI3REF: Register A Virtual Table Implementation |
4312** EXPERIMENTAL | |
4313** 4314** ^These routines are used to register a new [virtual table module] name. 4315** ^Module names must be registered before 4316** creating a new [virtual table] using the module and before using a 4317** preexisting [virtual table] for the module. 4318** 4319** ^The module name is registered on the [database connection] specified | 4900** 4901** ^These routines are used to register a new [virtual table module] name. 4902** ^Module names must be registered before 4903** creating a new [virtual table] using the module and before using a 4904** preexisting [virtual table] for the module. 4905** 4906** ^The module name is registered on the [database connection] specified |
4320** by the first parameter. ^The name of the module is given by the | 4907** by the first parameter. ^The name of the module is given by the |
4321** second parameter. ^The third parameter is a pointer to 4322** the implementation of the [virtual table module]. ^The fourth 4323** parameter is an arbitrary client data pointer that is passed through 4324** into the [xCreate] and [xConnect] methods of the virtual table module 4325** when a new virtual table is be being created or reinitialized. 4326** 4327** ^The sqlite3_create_module_v2() interface has a fifth parameter which 4328** is a pointer to a destructor for the pClientData. ^SQLite will 4329** invoke the destructor function (if it is not NULL) when SQLite | 4908** second parameter. ^The third parameter is a pointer to 4909** the implementation of the [virtual table module]. ^The fourth 4910** parameter is an arbitrary client data pointer that is passed through 4911** into the [xCreate] and [xConnect] methods of the virtual table module 4912** when a new virtual table is be being created or reinitialized. 4913** 4914** ^The sqlite3_create_module_v2() interface has a fifth parameter which 4915** is a pointer to a destructor for the pClientData. ^SQLite will 4916** invoke the destructor function (if it is not NULL) when SQLite |
4330** no longer needs the pClientData pointer. ^The sqlite3_create_module() | 4917** no longer needs the pClientData pointer. ^The destructor will also 4918** be invoked if the call to sqlite3_create_module_v2() fails. 4919** ^The sqlite3_create_module() |
4331** interface is equivalent to sqlite3_create_module_v2() with a NULL 4332** destructor. 4333*/ | 4920** interface is equivalent to sqlite3_create_module_v2() with a NULL 4921** destructor. 4922*/ |
4334SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_create_module( | 4923SQLITE_API int sqlite3_create_module( |
4335 sqlite3 *db, /* SQLite connection to register module with */ 4336 const char *zName, /* Name of the module */ 4337 const sqlite3_module *p, /* Methods for the module */ 4338 void *pClientData /* Client data for xCreate/xConnect */ 4339); | 4924 sqlite3 *db, /* SQLite connection to register module with */ 4925 const char *zName, /* Name of the module */ 4926 const sqlite3_module *p, /* Methods for the module */ 4927 void *pClientData /* Client data for xCreate/xConnect */ 4928); |
4340SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_create_module_v2( | 4929SQLITE_API int sqlite3_create_module_v2( |
4341 sqlite3 *db, /* SQLite connection to register module with */ 4342 const char *zName, /* Name of the module */ 4343 const sqlite3_module *p, /* Methods for the module */ 4344 void *pClientData, /* Client data for xCreate/xConnect */ 4345 void(*xDestroy)(void*) /* Module destructor function */ 4346); 4347 4348/* 4349** CAPI3REF: Virtual Table Instance Object 4350** KEYWORDS: sqlite3_vtab | 4930 sqlite3 *db, /* SQLite connection to register module with */ 4931 const char *zName, /* Name of the module */ 4932 const sqlite3_module *p, /* Methods for the module */ 4933 void *pClientData, /* Client data for xCreate/xConnect */ 4934 void(*xDestroy)(void*) /* Module destructor function */ 4935); 4936 4937/* 4938** CAPI3REF: Virtual Table Instance Object 4939** KEYWORDS: sqlite3_vtab |
4351** EXPERIMENTAL | |
4352** 4353** Every [virtual table module] implementation uses a subclass 4354** of this object to describe a particular instance 4355** of the [virtual table]. Each subclass will 4356** be tailored to the specific needs of the module implementation. 4357** The purpose of this superclass is to define certain fields that are 4358** common to all module implementations. 4359** --- 9 unchanged lines hidden (view full) --- 4369 int nRef; /* NO LONGER USED */ 4370 char *zErrMsg; /* Error message from sqlite3_mprintf() */ 4371 /* Virtual table implementations will typically add additional fields */ 4372}; 4373 4374/* 4375** CAPI3REF: Virtual Table Cursor Object 4376** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor} | 4940** 4941** Every [virtual table module] implementation uses a subclass 4942** of this object to describe a particular instance 4943** of the [virtual table]. Each subclass will 4944** be tailored to the specific needs of the module implementation. 4945** The purpose of this superclass is to define certain fields that are 4946** common to all module implementations. 4947** --- 9 unchanged lines hidden (view full) --- 4957 int nRef; /* NO LONGER USED */ 4958 char *zErrMsg; /* Error message from sqlite3_mprintf() */ 4959 /* Virtual table implementations will typically add additional fields */ 4960}; 4961 4962/* 4963** CAPI3REF: Virtual Table Cursor Object 4964** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor} |
4377** EXPERIMENTAL | |
4378** 4379** Every [virtual table module] implementation uses a subclass of the 4380** following structure to describe cursors that point into the 4381** [virtual table] and are used 4382** to loop through the virtual table. Cursors are created using the 4383** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed 4384** by the [sqlite3_module.xClose | xClose] method. Cursors are used 4385** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods --- 5 unchanged lines hidden (view full) --- 4391*/ 4392struct sqlite3_vtab_cursor { 4393 sqlite3_vtab *pVtab; /* Virtual table of this cursor */ 4394 /* Virtual table implementations will typically add additional fields */ 4395}; 4396 4397/* 4398** CAPI3REF: Declare The Schema Of A Virtual Table | 4965** 4966** Every [virtual table module] implementation uses a subclass of the 4967** following structure to describe cursors that point into the 4968** [virtual table] and are used 4969** to loop through the virtual table. Cursors are created using the 4970** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed 4971** by the [sqlite3_module.xClose | xClose] method. Cursors are used 4972** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods --- 5 unchanged lines hidden (view full) --- 4978*/ 4979struct sqlite3_vtab_cursor { 4980 sqlite3_vtab *pVtab; /* Virtual table of this cursor */ 4981 /* Virtual table implementations will typically add additional fields */ 4982}; 4983 4984/* 4985** CAPI3REF: Declare The Schema Of A Virtual Table |
4399** EXPERIMENTAL | |
4400** 4401** ^The [xCreate] and [xConnect] methods of a 4402** [virtual table module] call this interface 4403** to declare the format (the names and datatypes of the columns) of 4404** the virtual tables they implement. 4405*/ | 4986** 4987** ^The [xCreate] and [xConnect] methods of a 4988** [virtual table module] call this interface 4989** to declare the format (the names and datatypes of the columns) of 4990** the virtual tables they implement. 4991*/ |
4406SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_declare_vtab(sqlite3*, const char *zSQL); | 4992SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL); |
4407 4408/* 4409** CAPI3REF: Overload A Function For A Virtual Table | 4993 4994/* 4995** CAPI3REF: Overload A Function For A Virtual Table |
4410** EXPERIMENTAL | |
4411** 4412** ^(Virtual tables can provide alternative implementations of functions | 4996** 4997** ^(Virtual tables can provide alternative implementations of functions |
4413** using the [xFindFunction] method of the [virtual table module]. | 4998** using the [xFindFunction] method of the [virtual table module]. |
4414** But global versions of those functions 4415** must exist in order to be overloaded.)^ 4416** 4417** ^(This API makes sure a global version of a function with a particular 4418** name and number of parameters exists. If no such function exists 4419** before this API is called, a new function is created.)^ ^The implementation 4420** of the new function always causes an exception to be thrown. So 4421** the new function is not good for anything by itself. Its only 4422** purpose is to be a placeholder function that can be overloaded 4423** by a [virtual table]. 4424*/ | 4999** But global versions of those functions 5000** must exist in order to be overloaded.)^ 5001** 5002** ^(This API makes sure a global version of a function with a particular 5003** name and number of parameters exists. If no such function exists 5004** before this API is called, a new function is created.)^ ^The implementation 5005** of the new function always causes an exception to be thrown. So 5006** the new function is not good for anything by itself. Its only 5007** purpose is to be a placeholder function that can be overloaded 5008** by a [virtual table]. 5009*/ |
4425SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); | 5010SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); |
4426 4427/* 4428** The interface to the virtual-table mechanism defined above (back up 4429** to a comment remarkably similar to this one) is currently considered 4430** to be experimental. The interface might change in incompatible ways. 4431** If this is a problem for you, do not use the interface at this time. 4432** 4433** When the virtual-table mechanism stabilizes, we will declare the 4434** interface fixed, support it indefinitely, and remove this comment. | 5011 5012/* 5013** The interface to the virtual-table mechanism defined above (back up 5014** to a comment remarkably similar to this one) is currently considered 5015** to be experimental. The interface might change in incompatible ways. 5016** If this is a problem for you, do not use the interface at this time. 5017** 5018** When the virtual-table mechanism stabilizes, we will declare the 5019** interface fixed, support it indefinitely, and remove this comment. |
4435** 4436****** EXPERIMENTAL - subject to change without notice ************** | |
4437*/ 4438 4439/* 4440** CAPI3REF: A Handle To An Open BLOB 4441** KEYWORDS: {BLOB handle} {BLOB handles} 4442** 4443** An instance of this object represents an open BLOB on which 4444** [sqlite3_blob_open | incremental BLOB I/O] can be performed. --- 13 unchanged lines hidden (view full) --- 4458** in other words, the same BLOB that would be selected by: 4459** 4460** <pre> 4461** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow; 4462** </pre>)^ 4463** 4464** ^If the flags parameter is non-zero, then the BLOB is opened for read 4465** and write access. ^If it is zero, the BLOB is opened for read access. | 5020*/ 5021 5022/* 5023** CAPI3REF: A Handle To An Open BLOB 5024** KEYWORDS: {BLOB handle} {BLOB handles} 5025** 5026** An instance of this object represents an open BLOB on which 5027** [sqlite3_blob_open | incremental BLOB I/O] can be performed. --- 13 unchanged lines hidden (view full) --- 5041** in other words, the same BLOB that would be selected by: 5042** 5043** <pre> 5044** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow; 5045** </pre>)^ 5046** 5047** ^If the flags parameter is non-zero, then the BLOB is opened for read 5048** and write access. ^If it is zero, the BLOB is opened for read access. |
4466** ^It is not possible to open a column that is part of an index or primary 4467** key for writing. ^If [foreign key constraints] are enabled, it is | 5049** ^It is not possible to open a column that is part of an index or primary 5050** key for writing. ^If [foreign key constraints] are enabled, it is |
4468** not possible to open a column that is part of a [child key] for writing. 4469** 4470** ^Note that the database name is not the filename that contains 4471** the database but rather the symbolic name of the database that 4472** appears after the AS keyword when the database is connected using [ATTACH]. 4473** ^For the main database file, the database name is "main". 4474** ^For TEMP tables, the database name is "temp". 4475** --- 7 unchanged lines hidden (view full) --- 4483** regardless of the success or failure of this routine. 4484** 4485** ^(If the row that a BLOB handle points to is modified by an 4486** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects 4487** then the BLOB handle is marked as "expired". 4488** This is true if any column of the row is changed, even a column 4489** other than the one the BLOB handle is open on.)^ 4490** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for | 5051** not possible to open a column that is part of a [child key] for writing. 5052** 5053** ^Note that the database name is not the filename that contains 5054** the database but rather the symbolic name of the database that 5055** appears after the AS keyword when the database is connected using [ATTACH]. 5056** ^For the main database file, the database name is "main". 5057** ^For TEMP tables, the database name is "temp". 5058** --- 7 unchanged lines hidden (view full) --- 5066** regardless of the success or failure of this routine. 5067** 5068** ^(If the row that a BLOB handle points to is modified by an 5069** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects 5070** then the BLOB handle is marked as "expired". 5071** This is true if any column of the row is changed, even a column 5072** other than the one the BLOB handle is open on.)^ 5073** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for |
4491** a expired BLOB handle fail with an return code of [SQLITE_ABORT]. | 5074** an expired BLOB handle fail with a return code of [SQLITE_ABORT]. |
4492** ^(Changes written into a BLOB prior to the BLOB expiring are not 4493** rolled back by the expiration of the BLOB. Such changes will eventually 4494** commit if the transaction continues to completion.)^ 4495** 4496** ^Use the [sqlite3_blob_bytes()] interface to determine the size of 4497** the opened blob. ^The size of a blob may not be changed by this 4498** interface. Use the [UPDATE] SQL command to change the size of a 4499** blob. --- 12 unchanged lines hidden (view full) --- 4512 const char *zTable, 4513 const char *zColumn, 4514 sqlite3_int64 iRow, 4515 int flags, 4516 sqlite3_blob **ppBlob 4517); 4518 4519/* | 5075** ^(Changes written into a BLOB prior to the BLOB expiring are not 5076** rolled back by the expiration of the BLOB. Such changes will eventually 5077** commit if the transaction continues to completion.)^ 5078** 5079** ^Use the [sqlite3_blob_bytes()] interface to determine the size of 5080** the opened blob. ^The size of a blob may not be changed by this 5081** interface. Use the [UPDATE] SQL command to change the size of a 5082** blob. --- 12 unchanged lines hidden (view full) --- 5095 const char *zTable, 5096 const char *zColumn, 5097 sqlite3_int64 iRow, 5098 int flags, 5099 sqlite3_blob **ppBlob 5100); 5101 5102/* |
5103** CAPI3REF: Move a BLOB Handle to a New Row 5104** 5105** ^This function is used to move an existing blob handle so that it points 5106** to a different row of the same database table. ^The new row is identified 5107** by the rowid value passed as the second argument. Only the row can be 5108** changed. ^The database, table and column on which the blob handle is open 5109** remain the same. Moving an existing blob handle to a new row can be 5110** faster than closing the existing handle and opening a new one. 5111** 5112** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] - 5113** it must exist and there must be either a blob or text value stored in 5114** the nominated column.)^ ^If the new row is not present in the table, or if 5115** it does not contain a blob or text value, or if another error occurs, an 5116** SQLite error code is returned and the blob handle is considered aborted. 5117** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or 5118** [sqlite3_blob_reopen()] on an aborted blob handle immediately return 5119** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle 5120** always returns zero. 5121** 5122** ^This function sets the database handle error code and message. 5123*/ 5124SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64); 5125 5126/* |
|
4520** CAPI3REF: Close A BLOB Handle 4521** 4522** ^Closes an open [BLOB handle]. 4523** 4524** ^Closing a BLOB shall cause the current transaction to commit 4525** if there are no other BLOBs, no pending prepared statements, and the 4526** database connection is in [autocommit mode]. 4527** ^If any writes were made to the BLOB, they might be held in cache --- 10 unchanged lines hidden (view full) --- 4538** ^Calling this routine with a null pointer (such as would be returned 4539** by a failed call to [sqlite3_blob_open()]) is a harmless no-op. 4540*/ 4541SQLITE_API int sqlite3_blob_close(sqlite3_blob *); 4542 4543/* 4544** CAPI3REF: Return The Size Of An Open BLOB 4545** | 5127** CAPI3REF: Close A BLOB Handle 5128** 5129** ^Closes an open [BLOB handle]. 5130** 5131** ^Closing a BLOB shall cause the current transaction to commit 5132** if there are no other BLOBs, no pending prepared statements, and the 5133** database connection is in [autocommit mode]. 5134** ^If any writes were made to the BLOB, they might be held in cache --- 10 unchanged lines hidden (view full) --- 5145** ^Calling this routine with a null pointer (such as would be returned 5146** by a failed call to [sqlite3_blob_open()]) is a harmless no-op. 5147*/ 5148SQLITE_API int sqlite3_blob_close(sqlite3_blob *); 5149 5150/* 5151** CAPI3REF: Return The Size Of An Open BLOB 5152** |
4546** ^Returns the size in bytes of the BLOB accessible via the | 5153** ^Returns the size in bytes of the BLOB accessible via the |
4547** successfully opened [BLOB handle] in its only argument. ^The 4548** incremental blob I/O routines can only read or overwriting existing 4549** blob content; they cannot change the size of a blob. 4550** 4551** This routine only works on a [BLOB handle] which has been created 4552** by a prior successful call to [sqlite3_blob_open()] and which has not 4553** been closed by [sqlite3_blob_close()]. Passing any other pointer in 4554** to this routine results in undefined and probably undesirable behavior. --- 216 unchanged lines hidden (view full) --- 4771SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int); 4772SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*); 4773SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*); 4774SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*); 4775SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*); 4776 4777/* 4778** CAPI3REF: Mutex Methods Object | 5154** successfully opened [BLOB handle] in its only argument. ^The 5155** incremental blob I/O routines can only read or overwriting existing 5156** blob content; they cannot change the size of a blob. 5157** 5158** This routine only works on a [BLOB handle] which has been created 5159** by a prior successful call to [sqlite3_blob_open()] and which has not 5160** been closed by [sqlite3_blob_close()]. Passing any other pointer in 5161** to this routine results in undefined and probably undesirable behavior. --- 216 unchanged lines hidden (view full) --- 5378SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int); 5379SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*); 5380SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*); 5381SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*); 5382SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*); 5383 5384/* 5385** CAPI3REF: Mutex Methods Object |
4779** EXPERIMENTAL | |
4780** 4781** An instance of this structure defines the low-level routines 4782** used to allocate and use mutexes. 4783** 4784** Usually, the default mutex implementations provided by SQLite are 4785** sufficient, however the user has the option of substituting a custom 4786** implementation for specialized deployments or systems for which SQLite 4787** does not provide a suitable implementation. In this case, the user 4788** creates and populates an instance of this structure to pass 4789** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option. 4790** Additionally, an instance of this structure can be used as an 4791** output variable when querying the system for the current mutex 4792** implementation, using the [SQLITE_CONFIG_GETMUTEX] option. 4793** 4794** ^The xMutexInit method defined by this structure is invoked as 4795** part of system initialization by the sqlite3_initialize() function. | 5386** 5387** An instance of this structure defines the low-level routines 5388** used to allocate and use mutexes. 5389** 5390** Usually, the default mutex implementations provided by SQLite are 5391** sufficient, however the user has the option of substituting a custom 5392** implementation for specialized deployments or systems for which SQLite 5393** does not provide a suitable implementation. In this case, the user 5394** creates and populates an instance of this structure to pass 5395** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option. 5396** Additionally, an instance of this structure can be used as an 5397** output variable when querying the system for the current mutex 5398** implementation, using the [SQLITE_CONFIG_GETMUTEX] option. 5399** 5400** ^The xMutexInit method defined by this structure is invoked as 5401** part of system initialization by the sqlite3_initialize() function. |
4796** ^The xMutexInit routine is calle by SQLite exactly once for each | 5402** ^The xMutexInit routine is called by SQLite exactly once for each |
4797** effective call to [sqlite3_initialize()]. 4798** 4799** ^The xMutexEnd method defined by this structure is invoked as 4800** part of system shutdown by the sqlite3_shutdown() function. The 4801** implementation of this method is expected to release all outstanding 4802** resources obtained by the mutex methods implementation, especially 4803** those obtained by the xMutexInit method. ^The xMutexEnd() 4804** interface is invoked exactly once for each call to [sqlite3_shutdown()]. --- 16 unchanged lines hidden (view full) --- 4821** above silently ignore any invocations that pass a NULL pointer instead 4822** of a valid mutex handle. The implementations of the methods defined 4823** by this structure are not required to handle this case, the results 4824** of passing a NULL pointer instead of a valid mutex handle are undefined 4825** (i.e. it is acceptable to provide an implementation that segfaults if 4826** it is passed a NULL pointer). 4827** 4828** The xMutexInit() method must be threadsafe. ^It must be harmless to | 5403** effective call to [sqlite3_initialize()]. 5404** 5405** ^The xMutexEnd method defined by this structure is invoked as 5406** part of system shutdown by the sqlite3_shutdown() function. The 5407** implementation of this method is expected to release all outstanding 5408** resources obtained by the mutex methods implementation, especially 5409** those obtained by the xMutexInit method. ^The xMutexEnd() 5410** interface is invoked exactly once for each call to [sqlite3_shutdown()]. --- 16 unchanged lines hidden (view full) --- 5427** above silently ignore any invocations that pass a NULL pointer instead 5428** of a valid mutex handle. The implementations of the methods defined 5429** by this structure are not required to handle this case, the results 5430** of passing a NULL pointer instead of a valid mutex handle are undefined 5431** (i.e. it is acceptable to provide an implementation that segfaults if 5432** it is passed a NULL pointer). 5433** 5434** The xMutexInit() method must be threadsafe. ^It must be harmless to |
4829** invoke xMutexInit() mutiple times within the same process and without | 5435** invoke xMutexInit() multiple times within the same process and without |
4830** intervening calls to xMutexEnd(). Second and subsequent calls to 4831** xMutexInit() must be no-ops. 4832** 4833** ^xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()] 4834** and its associates). ^Similarly, xMutexAlloc() must not use SQLite memory 4835** allocation for a static mutex. ^However xMutexAlloc() may use SQLite 4836** memory allocation for a fast or recursive mutex. 4837** --- 32 unchanged lines hidden (view full) --- 4870** 4871** ^The implementation is not required to provided versions of these 4872** routines that actually work. If the implementation does not provide working 4873** versions of these routines, it should at least provide stubs that always 4874** return true so that one does not get spurious assertion failures. 4875** 4876** ^If the argument to sqlite3_mutex_held() is a NULL pointer then 4877** the routine should return 1. This seems counter-intuitive since | 5436** intervening calls to xMutexEnd(). Second and subsequent calls to 5437** xMutexInit() must be no-ops. 5438** 5439** ^xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()] 5440** and its associates). ^Similarly, xMutexAlloc() must not use SQLite memory 5441** allocation for a static mutex. ^However xMutexAlloc() may use SQLite 5442** memory allocation for a fast or recursive mutex. 5443** --- 32 unchanged lines hidden (view full) --- 5476** 5477** ^The implementation is not required to provided versions of these 5478** routines that actually work. If the implementation does not provide working 5479** versions of these routines, it should at least provide stubs that always 5480** return true so that one does not get spurious assertion failures. 5481** 5482** ^If the argument to sqlite3_mutex_held() is a NULL pointer then 5483** the routine should return 1. This seems counter-intuitive since |
4878** clearly the mutex cannot be held if it does not exist. But the | 5484** clearly the mutex cannot be held if it does not exist. But |
4879** the reason the mutex does not exist is because the build is not 4880** using mutexes. And we do not want the assert() containing the 4881** call to sqlite3_mutex_held() to fail, so a non-zero return is 4882** the appropriate thing to do. ^The sqlite3_mutex_notheld() 4883** interface should also return 1 when given a NULL pointer. 4884*/ 4885#ifndef NDEBUG 4886SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*); --- 13 unchanged lines hidden (view full) --- 4900#define SQLITE_MUTEX_FAST 0 4901#define SQLITE_MUTEX_RECURSIVE 1 4902#define SQLITE_MUTEX_STATIC_MASTER 2 4903#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ 4904#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */ 4905#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ 4906#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ 4907#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ | 5485** the reason the mutex does not exist is because the build is not 5486** using mutexes. And we do not want the assert() containing the 5487** call to sqlite3_mutex_held() to fail, so a non-zero return is 5488** the appropriate thing to do. ^The sqlite3_mutex_notheld() 5489** interface should also return 1 when given a NULL pointer. 5490*/ 5491#ifndef NDEBUG 5492SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*); --- 13 unchanged lines hidden (view full) --- 5506#define SQLITE_MUTEX_FAST 0 5507#define SQLITE_MUTEX_RECURSIVE 1 5508#define SQLITE_MUTEX_STATIC_MASTER 2 5509#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ 5510#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */ 5511#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ 5512#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ 5513#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ |
4908#define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */ | 5514#define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */ 5515#define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */ |
4909 4910/* 4911** CAPI3REF: Retrieve the mutex for a database connection 4912** | 5516 5517/* 5518** CAPI3REF: Retrieve the mutex for a database connection 5519** |
4913** ^This interface returns a pointer the [sqlite3_mutex] object that | 5520** ^This interface returns a pointer the [sqlite3_mutex] object that |
4914** serializes access to the [database connection] given in the argument 4915** when the [threading mode] is Serialized. 4916** ^If the [threading mode] is Single-thread or Multi-thread then this 4917** routine returns a NULL pointer. 4918*/ 4919SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*); 4920 4921/* 4922** CAPI3REF: Low-Level Control Of Database Files 4923** 4924** ^The [sqlite3_file_control()] interface makes a direct call to the 4925** xFileControl method for the [sqlite3_io_methods] object associated 4926** with a particular database identified by the second argument. ^The | 5521** serializes access to the [database connection] given in the argument 5522** when the [threading mode] is Serialized. 5523** ^If the [threading mode] is Single-thread or Multi-thread then this 5524** routine returns a NULL pointer. 5525*/ 5526SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*); 5527 5528/* 5529** CAPI3REF: Low-Level Control Of Database Files 5530** 5531** ^The [sqlite3_file_control()] interface makes a direct call to the 5532** xFileControl method for the [sqlite3_io_methods] object associated 5533** with a particular database identified by the second argument. ^The |
4927** name of the database "main" for the main database or "temp" for the | 5534** name of the database is "main" for the main database or "temp" for the |
4928** TEMP database, or the name that appears after the AS keyword for 4929** databases that are added using the [ATTACH] SQL command. 4930** ^A NULL pointer can be used in place of "main" to refer to the 4931** main database file. 4932** ^The third and fourth parameters to this routine 4933** are passed directly through to the second and third parameters of 4934** the xFileControl method. ^The return value of the xFileControl 4935** method becomes the return value of this routine. 4936** | 5535** TEMP database, or the name that appears after the AS keyword for 5536** databases that are added using the [ATTACH] SQL command. 5537** ^A NULL pointer can be used in place of "main" to refer to the 5538** main database file. 5539** ^The third and fourth parameters to this routine 5540** are passed directly through to the second and third parameters of 5541** the xFileControl method. ^The return value of the xFileControl 5542** method becomes the return value of this routine. 5543** |
5544** ^The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes 5545** a pointer to the underlying [sqlite3_file] object to be written into 5546** the space pointed to by the 4th parameter. ^The SQLITE_FCNTL_FILE_POINTER 5547** case is a short-circuit path which does not actually invoke the 5548** underlying sqlite3_io_methods.xFileControl method. 5549** |
|
4937** ^If the second parameter (zDbName) does not match the name of any 4938** open database file, then SQLITE_ERROR is returned. ^This error 4939** code is not remembered and will not be recalled by [sqlite3_errcode()] 4940** or [sqlite3_errmsg()]. The underlying xFileControl method might 4941** also return SQLITE_ERROR. There is no way to distinguish between 4942** an incorrect zDbName and an SQLITE_ERROR return from the underlying 4943** xFileControl method. 4944** --- 39 unchanged lines hidden (view full) --- 4984#define SQLITE_TESTCTRL_FAULT_INSTALL 9 4985#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 4986#define SQLITE_TESTCTRL_PENDING_BYTE 11 4987#define SQLITE_TESTCTRL_ASSERT 12 4988#define SQLITE_TESTCTRL_ALWAYS 13 4989#define SQLITE_TESTCTRL_RESERVE 14 4990#define SQLITE_TESTCTRL_OPTIMIZATIONS 15 4991#define SQLITE_TESTCTRL_ISKEYWORD 16 | 5550** ^If the second parameter (zDbName) does not match the name of any 5551** open database file, then SQLITE_ERROR is returned. ^This error 5552** code is not remembered and will not be recalled by [sqlite3_errcode()] 5553** or [sqlite3_errmsg()]. The underlying xFileControl method might 5554** also return SQLITE_ERROR. There is no way to distinguish between 5555** an incorrect zDbName and an SQLITE_ERROR return from the underlying 5556** xFileControl method. 5557** --- 39 unchanged lines hidden (view full) --- 5597#define SQLITE_TESTCTRL_FAULT_INSTALL 9 5598#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 5599#define SQLITE_TESTCTRL_PENDING_BYTE 11 5600#define SQLITE_TESTCTRL_ASSERT 12 5601#define SQLITE_TESTCTRL_ALWAYS 13 5602#define SQLITE_TESTCTRL_RESERVE 14 5603#define SQLITE_TESTCTRL_OPTIMIZATIONS 15 5604#define SQLITE_TESTCTRL_ISKEYWORD 16 |
4992#define SQLITE_TESTCTRL_LAST 16 | 5605#define SQLITE_TESTCTRL_PGHDRSZ 17 5606#define SQLITE_TESTCTRL_SCRATCHMALLOC 18 5607#define SQLITE_TESTCTRL_LOCALTIME_FAULT 19 5608#define SQLITE_TESTCTRL_LAST 19 |
4993 4994/* 4995** CAPI3REF: SQLite Runtime Status | 5609 5610/* 5611** CAPI3REF: SQLite Runtime Status |
4996** EXPERIMENTAL | |
4997** 4998** ^This interface is used to retrieve runtime status information | 5612** 5613** ^This interface is used to retrieve runtime status information |
4999** about the preformance of SQLite, and optionally to reset various | 5614** about the performance of SQLite, and optionally to reset various |
5000** highwater marks. ^The first argument is an integer code for 5001** the specific parameter to measure. ^(Recognized integer codes | 5615** highwater marks. ^The first argument is an integer code for 5616** the specific parameter to measure. ^(Recognized integer codes |
5002** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...].)^ | 5617** are of the form [status parameters | SQLITE_STATUS_...].)^ |
5003** ^The current value of the parameter is returned into *pCurrent. 5004** ^The highest recorded value is returned in *pHighwater. ^If the 5005** resetFlag is true, then the highest record value is reset after 5006** *pHighwater is written. ^(Some parameters do not record the highest 5007** value. For those parameters 5008** nothing is written into *pHighwater and the resetFlag is ignored.)^ 5009** ^(Other parameters record only the highwater mark and not the current 5010** value. For these latter parameters nothing is written into *pCurrent.)^ 5011** | 5618** ^The current value of the parameter is returned into *pCurrent. 5619** ^The highest recorded value is returned in *pHighwater. ^If the 5620** resetFlag is true, then the highest record value is reset after 5621** *pHighwater is written. ^(Some parameters do not record the highest 5622** value. For those parameters 5623** nothing is written into *pHighwater and the resetFlag is ignored.)^ 5624** ^(Other parameters record only the highwater mark and not the current 5625** value. For these latter parameters nothing is written into *pCurrent.)^ 5626** |
5012** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a | 5627** ^The sqlite3_status() routine returns SQLITE_OK on success and a |
5013** non-zero [error code] on failure. 5014** 5015** This routine is threadsafe but is not atomic. This routine can be 5016** called while other threads are running the same or different SQLite 5017** interfaces. However the values returned in *pCurrent and 5018** *pHighwater reflect the status of SQLite at different points in time 5019** and it is possible that another thread might change the parameter 5020** in between the times when *pCurrent and *pHighwater are written. 5021** 5022** See also: [sqlite3_db_status()] 5023*/ | 5628** non-zero [error code] on failure. 5629** 5630** This routine is threadsafe but is not atomic. This routine can be 5631** called while other threads are running the same or different SQLite 5632** interfaces. However the values returned in *pCurrent and 5633** *pHighwater reflect the status of SQLite at different points in time 5634** and it is possible that another thread might change the parameter 5635** in between the times when *pCurrent and *pHighwater are written. 5636** 5637** See also: [sqlite3_db_status()] 5638*/ |
5024SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); | 5639SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); |
5025 5026 5027/* 5028** CAPI3REF: Status Parameters | 5640 5641 5642/* 5643** CAPI3REF: Status Parameters |
5029** EXPERIMENTAL | 5644** KEYWORDS: {status parameters} |
5030** 5031** These integer constants designate various run-time status parameters 5032** that can be returned by [sqlite3_status()]. 5033** 5034** <dl> | 5645** 5646** These integer constants designate various run-time status parameters 5647** that can be returned by [sqlite3_status()]. 5648** 5649** <dl> |
5035** ^( | 5650** [[SQLITE_STATUS_MEMORY_USED]] ^(<dt>SQLITE_STATUS_MEMORY_USED</dt> |
5036** <dd>This parameter is the current amount of memory checked out 5037** using [sqlite3_malloc()], either directly or indirectly. The 5038** figure includes calls made to [sqlite3_malloc()] by the application 5039** and internal memory usage by the SQLite library. Scratch memory 5040** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache 5041** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in 5042** this parameter. The amount returned is the sum of the allocation 5043** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^ 5044** | 5651** <dd>This parameter is the current amount of memory checked out 5652** using [sqlite3_malloc()], either directly or indirectly. The 5653** figure includes calls made to [sqlite3_malloc()] by the application 5654** and internal memory usage by the SQLite library. Scratch memory 5655** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache 5656** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in 5657** this parameter. The amount returned is the sum of the allocation 5658** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^ 5659** |
5045** ^( | 5660** [[SQLITE_STATUS_MALLOC_SIZE]] ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt> |
5046** <dd>This parameter records the largest memory allocation request 5047** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their 5048** internal equivalents). Only the value returned in the | 5661** <dd>This parameter records the largest memory allocation request 5662** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their 5663** internal equivalents). Only the value returned in the |
5049** *pHighwater parameter to [sqlite3_status()] is of interest. | 5664** *pHighwater parameter to [sqlite3_status()] is of interest. |
5050** The value written into the *pCurrent parameter is undefined.</dd>)^ 5051** | 5665** The value written into the *pCurrent parameter is undefined.</dd>)^ 5666** |
5052** ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt> | 5667** [[SQLITE_STATUS_MALLOC_COUNT]] ^(<dt>SQLITE_STATUS_MALLOC_COUNT</dt> 5668** <dd>This parameter records the number of separate memory allocations 5669** currently checked out.</dd>)^ 5670** 5671** [[SQLITE_STATUS_PAGECACHE_USED]] ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt> |
5053** <dd>This parameter returns the number of pages used out of the | 5672** <dd>This parameter returns the number of pages used out of the |
5054** [pagecache memory allocator] that was configured using | 5673** [pagecache memory allocator] that was configured using |
5055** [SQLITE_CONFIG_PAGECACHE]. The 5056** value returned is in pages, not in bytes.</dd>)^ 5057** | 5674** [SQLITE_CONFIG_PAGECACHE]. The 5675** value returned is in pages, not in bytes.</dd>)^ 5676** |
5677** [[SQLITE_STATUS_PAGECACHE_OVERFLOW]] |
|
5058** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt> 5059** <dd>This parameter returns the number of bytes of page cache | 5678** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt> 5679** <dd>This parameter returns the number of bytes of page cache |
5060** allocation which could not be statisfied by the [SQLITE_CONFIG_PAGECACHE] | 5680** allocation which could not be satisfied by the [SQLITE_CONFIG_PAGECACHE] |
5061** buffer and where forced to overflow to [sqlite3_malloc()]. The 5062** returned value includes allocations that overflowed because they 5063** where too large (they were larger than the "sz" parameter to 5064** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because 5065** no space was left in the page cache.</dd>)^ 5066** | 5681** buffer and where forced to overflow to [sqlite3_malloc()]. The 5682** returned value includes allocations that overflowed because they 5683** where too large (they were larger than the "sz" parameter to 5684** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because 5685** no space was left in the page cache.</dd>)^ 5686** |
5067** ^( | 5687** [[SQLITE_STATUS_PAGECACHE_SIZE]] ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt> |
5068** <dd>This parameter records the largest memory allocation request 5069** handed to [pagecache memory allocator]. Only the value returned in the | 5688** <dd>This parameter records the largest memory allocation request 5689** handed to [pagecache memory allocator]. Only the value returned in the |
5070** *pHighwater parameter to [sqlite3_status()] is of interest. | 5690** *pHighwater parameter to [sqlite3_status()] is of interest. |
5071** The value written into the *pCurrent parameter is undefined.</dd>)^ 5072** | 5691** The value written into the *pCurrent parameter is undefined.</dd>)^ 5692** |
5073** ^( | 5693** [[SQLITE_STATUS_SCRATCH_USED]] ^(<dt>SQLITE_STATUS_SCRATCH_USED</dt> |
5074** <dd>This parameter returns the number of allocations used out of the 5075** [scratch memory allocator] configured using 5076** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not 5077** in bytes. Since a single thread may only have one scratch allocation 5078** outstanding at time, this parameter also reports the number of threads 5079** using scratch memory at the same time.</dd>)^ 5080** | 5694** <dd>This parameter returns the number of allocations used out of the 5695** [scratch memory allocator] configured using 5696** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not 5697** in bytes. Since a single thread may only have one scratch allocation 5698** outstanding at time, this parameter also reports the number of threads 5699** using scratch memory at the same time.</dd>)^ 5700** |
5081** ^( | 5701** [[SQLITE_STATUS_SCRATCH_OVERFLOW]] ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt> |
5082** <dd>This parameter returns the number of bytes of scratch memory | 5702** <dd>This parameter returns the number of bytes of scratch memory |
5083** allocation which could not be statisfied by the [SQLITE_CONFIG_SCRATCH] | 5703** allocation which could not be satisfied by the [SQLITE_CONFIG_SCRATCH] |
5084** buffer and where forced to overflow to [sqlite3_malloc()]. The values 5085** returned include overflows because the requested allocation was too 5086** larger (that is, because the requested allocation was larger than the 5087** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer 5088** slots were available. 5089** </dd>)^ 5090** | 5704** buffer and where forced to overflow to [sqlite3_malloc()]. The values 5705** returned include overflows because the requested allocation was too 5706** larger (that is, because the requested allocation was larger than the 5707** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer 5708** slots were available. 5709** </dd>)^ 5710** |
5091** ^( | 5711** [[SQLITE_STATUS_SCRATCH_SIZE]] ^(<dt>SQLITE_STATUS_SCRATCH_SIZE</dt> |
5092** <dd>This parameter records the largest memory allocation request 5093** handed to [scratch memory allocator]. Only the value returned in the | 5712** <dd>This parameter records the largest memory allocation request 5713** handed to [scratch memory allocator]. Only the value returned in the |
5094** *pHighwater parameter to [sqlite3_status()] is of interest. | 5714** *pHighwater parameter to [sqlite3_status()] is of interest. |
5095** The value written into the *pCurrent parameter is undefined.</dd>)^ 5096** | 5715** The value written into the *pCurrent parameter is undefined.</dd>)^ 5716** |
5097** ^( | 5717** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt> |
5098** <dd>This parameter records the deepest parser stack. It is only 5099** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^ 5100** </dl> 5101** 5102** New status parameters may be added from time to time. 5103*/ 5104#define SQLITE_STATUS_MEMORY_USED 0 5105#define SQLITE_STATUS_PAGECACHE_USED 1 5106#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2 5107#define SQLITE_STATUS_SCRATCH_USED 3 5108#define SQLITE_STATUS_SCRATCH_OVERFLOW 4 5109#define SQLITE_STATUS_MALLOC_SIZE 5 5110#define SQLITE_STATUS_PARSER_STACK 6 5111#define SQLITE_STATUS_PAGECACHE_SIZE 7 5112#define SQLITE_STATUS_SCRATCH_SIZE 8 | 5718** <dd>This parameter records the deepest parser stack. It is only 5719** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^ 5720** </dl> 5721** 5722** New status parameters may be added from time to time. 5723*/ 5724#define SQLITE_STATUS_MEMORY_USED 0 5725#define SQLITE_STATUS_PAGECACHE_USED 1 5726#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2 5727#define SQLITE_STATUS_SCRATCH_USED 3 5728#define SQLITE_STATUS_SCRATCH_OVERFLOW 4 5729#define SQLITE_STATUS_MALLOC_SIZE 5 5730#define SQLITE_STATUS_PARSER_STACK 6 5731#define SQLITE_STATUS_PAGECACHE_SIZE 7 5732#define SQLITE_STATUS_SCRATCH_SIZE 8 |
5733#define SQLITE_STATUS_MALLOC_COUNT 9 |
|
5113 5114/* 5115** CAPI3REF: Database Connection Status | 5734 5735/* 5736** CAPI3REF: Database Connection Status |
5116** EXPERIMENTAL | |
5117** | 5737** |
5118** ^This interface is used to retrieve runtime status information | 5738** ^This interface is used to retrieve runtime status information |
5119** about a single [database connection]. ^The first argument is the 5120** database connection object to be interrogated. ^The second argument | 5739** about a single [database connection]. ^The first argument is the 5740** database connection object to be interrogated. ^The second argument |
5121** is the parameter to interrogate. ^Currently, the only allowed value 5122** for the second parameter is [SQLITE_DBSTATUS_LOOKASIDE_USED]. 5123** Additional options will likely appear in future releases of SQLite. | 5741** is an integer constant, taken from the set of 5742** [SQLITE_DBSTATUS options], that 5743** determines the parameter to interrogate. The set of 5744** [SQLITE_DBSTATUS options] is likely 5745** to grow in future releases of SQLite. |
5124** 5125** ^The current value of the requested parameter is written into *pCur 5126** and the highest instantaneous value is written into *pHiwtr. ^If 5127** the resetFlg is true, then the highest instantaneous value is 5128** reset back down to the current value. 5129** | 5746** 5747** ^The current value of the requested parameter is written into *pCur 5748** and the highest instantaneous value is written into *pHiwtr. ^If 5749** the resetFlg is true, then the highest instantaneous value is 5750** reset back down to the current value. 5751** |
5752** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a 5753** non-zero [error code] on failure. 5754** |
|
5130** See also: [sqlite3_status()] and [sqlite3_stmt_status()]. 5131*/ | 5755** See also: [sqlite3_status()] and [sqlite3_stmt_status()]. 5756*/ |
5132SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg); | 5757SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg); |
5133 5134/* 5135** CAPI3REF: Status Parameters for database connections | 5758 5759/* 5760** CAPI3REF: Status Parameters for database connections |
5136** EXPERIMENTAL | 5761** KEYWORDS: {SQLITE_DBSTATUS options} |
5137** 5138** These constants are the available integer "verbs" that can be passed as 5139** the second argument to the [sqlite3_db_status()] interface. 5140** 5141** New verbs may be added in future releases of SQLite. Existing verbs 5142** might be discontinued. Applications should check the return code from 5143** [sqlite3_db_status()] to make sure that the call worked. 5144** The [sqlite3_db_status()] interface will return a non-zero error code 5145** if a discontinued or unsupported verb is invoked. 5146** 5147** <dl> | 5762** 5763** These constants are the available integer "verbs" that can be passed as 5764** the second argument to the [sqlite3_db_status()] interface. 5765** 5766** New verbs may be added in future releases of SQLite. Existing verbs 5767** might be discontinued. Applications should check the return code from 5768** [sqlite3_db_status()] to make sure that the call worked. 5769** The [sqlite3_db_status()] interface will return a non-zero error code 5770** if a discontinued or unsupported verb is invoked. 5771** 5772** <dl> |
5148** ^( | 5773** [[SQLITE_DBSTATUS_LOOKASIDE_USED]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt> |
5149** <dd>This parameter returns the number of lookaside memory slots currently 5150** checked out.</dd>)^ | 5774** <dd>This parameter returns the number of lookaside memory slots currently 5775** checked out.</dd>)^ |
5776** 5777** [[SQLITE_DBSTATUS_LOOKASIDE_HIT]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_HIT</dt> 5778** <dd>This parameter returns the number malloc attempts that were 5779** satisfied using lookaside memory. Only the high-water value is meaningful; 5780** the current value is always zero.)^ 5781** 5782** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE]] 5783** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</dt> 5784** <dd>This parameter returns the number malloc attempts that might have 5785** been satisfied using lookaside memory but failed due to the amount of 5786** memory requested being larger than the lookaside slot size. 5787** Only the high-water value is meaningful; 5788** the current value is always zero.)^ 5789** 5790** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL]] 5791** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</dt> 5792** <dd>This parameter returns the number malloc attempts that might have 5793** been satisfied using lookaside memory but failed due to all lookaside 5794** memory already being in use. 5795** Only the high-water value is meaningful; 5796** the current value is always zero.)^ 5797** 5798** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt> 5799** <dd>This parameter returns the approximate number of of bytes of heap 5800** memory used by all pager caches associated with the database connection.)^ 5801** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0. 5802** 5803** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt> 5804** <dd>This parameter returns the approximate number of of bytes of heap 5805** memory used to store the schema for all databases associated 5806** with the connection - main, temp, and any [ATTACH]-ed databases.)^ 5807** ^The full amount of memory used by the schemas is reported, even if the 5808** schema memory is shared with other database connections due to 5809** [shared cache mode] being enabled. 5810** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0. 5811** 5812** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt> 5813** <dd>This parameter returns the approximate number of of bytes of heap 5814** and lookaside memory used by all prepared statements associated with 5815** the database connection.)^ 5816** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0. 5817** </dd> |
|
5151** </dl> 5152*/ | 5818** </dl> 5819*/ |
5153#define SQLITE_DBSTATUS_LOOKASIDE_USED 0 | 5820#define SQLITE_DBSTATUS_LOOKASIDE_USED 0 5821#define SQLITE_DBSTATUS_CACHE_USED 1 5822#define SQLITE_DBSTATUS_SCHEMA_USED 2 5823#define SQLITE_DBSTATUS_STMT_USED 3 5824#define SQLITE_DBSTATUS_LOOKASIDE_HIT 4 5825#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5 5826#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6 5827#define SQLITE_DBSTATUS_MAX 6 /* Largest defined DBSTATUS */ |
5154 5155 5156/* 5157** CAPI3REF: Prepared Statement Status | 5828 5829 5830/* 5831** CAPI3REF: Prepared Statement Status |
5158** EXPERIMENTAL | |
5159** 5160** ^(Each prepared statement maintains various | 5832** 5833** ^(Each prepared statement maintains various |
5161** [SQLITE_STMTSTATUS_SORT | counters] that measure the number | 5834** [SQLITE_STMTSTATUS counters] that measure the number |
5162** of times it has performed specific operations.)^ These counters can 5163** be used to monitor the performance characteristics of the prepared 5164** statements. For example, if the number of table steps greatly exceeds 5165** the number of table searches or result rows, that would tend to indicate 5166** that the prepared statement is using a full table scan rather than | 5835** of times it has performed specific operations.)^ These counters can 5836** be used to monitor the performance characteristics of the prepared 5837** statements. For example, if the number of table steps greatly exceeds 5838** the number of table searches or result rows, that would tend to indicate 5839** that the prepared statement is using a full table scan rather than |
5167** an index. | 5840** an index. |
5168** 5169** ^(This interface is used to retrieve and reset counter values from 5170** a [prepared statement]. The first argument is the prepared statement 5171** object to be interrogated. The second argument | 5841** 5842** ^(This interface is used to retrieve and reset counter values from 5843** a [prepared statement]. The first argument is the prepared statement 5844** object to be interrogated. The second argument |
5172** is an integer code for a specific [SQLITE_STMTSTATUS_SORT | counter] | 5845** is an integer code for a specific [SQLITE_STMTSTATUS counter] |
5173** to be interrogated.)^ 5174** ^The current value of the requested counter is returned. 5175** ^If the resetFlg is true, then the counter is reset to zero after this 5176** interface call returns. 5177** 5178** See also: [sqlite3_status()] and [sqlite3_db_status()]. 5179*/ | 5846** to be interrogated.)^ 5847** ^The current value of the requested counter is returned. 5848** ^If the resetFlg is true, then the counter is reset to zero after this 5849** interface call returns. 5850** 5851** See also: [sqlite3_status()] and [sqlite3_db_status()]. 5852*/ |
5180SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg); | 5853SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg); |
5181 5182/* 5183** CAPI3REF: Status Parameters for prepared statements | 5854 5855/* 5856** CAPI3REF: Status Parameters for prepared statements |
5184** EXPERIMENTAL | 5857** KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters} |
5185** 5186** These preprocessor macros define integer codes that name counter 5187** values associated with the [sqlite3_stmt_status()] interface. 5188** The meanings of the various counters are as follows: 5189** 5190** <dl> | 5858** 5859** These preprocessor macros define integer codes that name counter 5860** values associated with the [sqlite3_stmt_status()] interface. 5861** The meanings of the various counters are as follows: 5862** 5863** <dl> |
5191** | 5864** [[SQLITE_STMTSTATUS_FULLSCAN_STEP]] <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt> |
5192** <dd>^This is the number of times that SQLite has stepped forward in 5193** a table as part of a full table scan. Large numbers for this counter | 5865** <dd>^This is the number of times that SQLite has stepped forward in 5866** a table as part of a full table scan. Large numbers for this counter |
5194** may indicate opportunities for performance improvement through | 5867** may indicate opportunities for performance improvement through |
5195** careful use of indices.</dd> 5196** | 5868** careful use of indices.</dd> 5869** |
5197** | 5870** [[SQLITE_STMTSTATUS_SORT]] <dt>SQLITE_STMTSTATUS_SORT</dt> |
5198** <dd>^This is the number of sort operations that have occurred. 5199** A non-zero value in this counter may indicate an opportunity to 5200** improvement performance through careful use of indices.</dd> 5201** | 5871** <dd>^This is the number of sort operations that have occurred. 5872** A non-zero value in this counter may indicate an opportunity to 5873** improvement performance through careful use of indices.</dd> 5874** |
5875** [[SQLITE_STMTSTATUS_AUTOINDEX]] <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt> 5876** <dd>^This is the number of rows inserted into transient indices that 5877** were created automatically in order to help joins run faster. 5878** A non-zero value in this counter may indicate an opportunity to 5879** improvement performance by adding permanent indices that do not 5880** need to be reinitialized each time the statement is run.</dd> 5881** |
|
5202** </dl> 5203*/ 5204#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1 5205#define SQLITE_STMTSTATUS_SORT 2 | 5882** </dl> 5883*/ 5884#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1 5885#define SQLITE_STMTSTATUS_SORT 2 |
5886#define SQLITE_STMTSTATUS_AUTOINDEX 3 |
|
5206 5207/* 5208** CAPI3REF: Custom Page Cache Object | 5887 5888/* 5889** CAPI3REF: Custom Page Cache Object |
5209** EXPERIMENTAL | |
5210** 5211** The sqlite3_pcache type is opaque. It is implemented by 5212** the pluggable module. The SQLite core has no knowledge of 5213** its size or internal structure and never deals with the 5214** sqlite3_pcache object except by holding and passing pointers 5215** to the object. 5216** 5217** See [sqlite3_pcache_methods] for additional information. 5218*/ 5219typedef struct sqlite3_pcache sqlite3_pcache; 5220 5221/* 5222** CAPI3REF: Application Defined Page Cache. 5223** KEYWORDS: {page cache} | 5890** 5891** The sqlite3_pcache type is opaque. It is implemented by 5892** the pluggable module. The SQLite core has no knowledge of 5893** its size or internal structure and never deals with the 5894** sqlite3_pcache object except by holding and passing pointers 5895** to the object. 5896** 5897** See [sqlite3_pcache_methods] for additional information. 5898*/ 5899typedef struct sqlite3_pcache sqlite3_pcache; 5900 5901/* 5902** CAPI3REF: Application Defined Page Cache. 5903** KEYWORDS: {page cache} |
5224** EXPERIMENTAL | |
5225** 5226** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can | 5904** 5905** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can |
5227** register an alternative page cache implementation by passing in an 5228** instance of the sqlite3_pcache_methods structure.)^ The majority of the 5229** heap memory used by SQLite is used by the page cache to cache data read 5230** from, or ready to be written to, the database file. By implementing a 5231** custom page cache using this API, an application can control more 5232** precisely the amount of memory consumed by SQLite, the way in which 5233** that memory is allocated and released, and the policies used to 5234** determine exactly which parts of a database file are cached and for | 5906** register an alternative page cache implementation by passing in an 5907** instance of the sqlite3_pcache_methods structure.)^ 5908** In many applications, most of the heap memory allocated by 5909** SQLite is used for the page cache. 5910** By implementing a 5911** custom page cache using this API, an application can better control 5912** the amount of memory consumed by SQLite, the way in which 5913** that memory is allocated and released, and the policies used to 5914** determine exactly which parts of a database file are cached and for |
5235** how long. 5236** | 5915** how long. 5916** |
5917** The alternative page cache mechanism is an 5918** extreme measure that is only needed by the most demanding applications. 5919** The built-in page cache is recommended for most uses. 5920** |
|
5237** ^(The contents of the sqlite3_pcache_methods structure are copied to an 5238** internal buffer by SQLite within the call to [sqlite3_config]. Hence 5239** the application may discard the parameter after the call to 5240** [sqlite3_config()] returns.)^ 5241** | 5921** ^(The contents of the sqlite3_pcache_methods structure are copied to an 5922** internal buffer by SQLite within the call to [sqlite3_config]. Hence 5923** the application may discard the parameter after the call to 5924** [sqlite3_config()] returns.)^ 5925** |
5242** ^The xInit() method is called once for each call to [sqlite3_initialize()] | 5926** [[the xInit() page cache method]] 5927** ^(The xInit() method is called once for each effective 5928** call to [sqlite3_initialize()])^ |
5243** (usually only once during the lifetime of the process). ^(The xInit() 5244** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^ | 5929** (usually only once during the lifetime of the process). ^(The xInit() 5930** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^ |
5245** ^The xInit() method can set up up global structures and/or any mutexes 5246** required by the custom page cache implementation. | 5931** The intent of the xInit() method is to set up global data structures 5932** required by the custom page cache implementation. 5933** ^(If the xInit() method is NULL, then the 5934** built-in default page cache is used instead of the application defined 5935** page cache.)^ |
5247** | 5936** |
5248** ^The xShutdown() method is called from within [sqlite3_shutdown()], 5249** if the application invokes this API. It can be used to clean up | 5937** [[the xShutdown() page cache method]] 5938** ^The xShutdown() method is called by [sqlite3_shutdown()]. 5939** It can be used to clean up |
5250** any outstanding resources before process shutdown, if required. | 5940** any outstanding resources before process shutdown, if required. |
5941** ^The xShutdown() method may be NULL. |
|
5251** | 5942** |
5252** ^SQLite holds a [SQLITE_MUTEX_RECURSIVE] mutex when it invokes 5253** the xInit method, so the xInit method need not be threadsafe. ^The | 5943** ^SQLite automatically serializes calls to the xInit method, 5944** so the xInit method need not be threadsafe. ^The |
5254** xShutdown method is only called from [sqlite3_shutdown()] so it does 5255** not need to be threadsafe either. All other methods must be threadsafe 5256** in multithreaded applications. 5257** 5258** ^SQLite will never invoke xInit() more than once without an intervening 5259** call to xShutdown(). 5260** | 5945** xShutdown method is only called from [sqlite3_shutdown()] so it does 5946** not need to be threadsafe either. All other methods must be threadsafe 5947** in multithreaded applications. 5948** 5949** ^SQLite will never invoke xInit() more than once without an intervening 5950** call to xShutdown(). 5951** |
5261** ^The xCreate() method is used to construct a new cache instance. SQLite 5262** will typically create one cache instance for each open database file, | 5952** [[the xCreate() page cache methods]] 5953** ^SQLite invokes the xCreate() method to construct a new cache instance. 5954** SQLite will typically create one cache instance for each open database file, |
5263** though this is not guaranteed. ^The 5264** first parameter, szPage, is the size in bytes of the pages that must 5265** be allocated by the cache. ^szPage will not be a power of two. ^szPage 5266** will the page size of the database file that is to be cached plus an | 5955** though this is not guaranteed. ^The 5956** first parameter, szPage, is the size in bytes of the pages that must 5957** be allocated by the cache. ^szPage will not be a power of two. ^szPage 5958** will the page size of the database file that is to be cached plus an |
5267** increment (here called "R") of about 100 or 200. ^SQLite will use the | 5959** increment (here called "R") of less than 250. SQLite will use the |
5268** extra R bytes on each page to store metadata about the underlying 5269** database page on disk. The value of R depends 5270** on the SQLite version, the target platform, and how SQLite was compiled. | 5960** extra R bytes on each page to store metadata about the underlying 5961** database page on disk. The value of R depends 5962** on the SQLite version, the target platform, and how SQLite was compiled. |
5271** ^R is constant for a particular build of SQLite. ^The second argument to | 5963** ^(R is constant for a particular build of SQLite. Except, there are two 5964** distinct values of R when SQLite is compiled with the proprietary 5965** ZIPVFS extension.)^ ^The second argument to |
5272** xCreate(), bPurgeable, is true if the cache being created will 5273** be used to cache database pages of a file stored on disk, or | 5966** xCreate(), bPurgeable, is true if the cache being created will 5967** be used to cache database pages of a file stored on disk, or |
5274** false if it is used for an in-memory database. ^The cache implementation | 5968** false if it is used for an in-memory database. The cache implementation |
5275** does not have to do anything special based with the value of bPurgeable; 5276** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will 5277** never invoke xUnpin() except to deliberately delete a page. | 5969** does not have to do anything special based with the value of bPurgeable; 5970** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will 5971** never invoke xUnpin() except to deliberately delete a page. |
5278** ^In other words, a cache created with bPurgeable set to false will | 5972** ^In other words, calls to xUnpin() on a cache with bPurgeable set to 5973** false will always have the "discard" flag set to true. 5974** ^Hence, a cache created with bPurgeable false will |
5279** never contain any unpinned pages. 5280** | 5975** never contain any unpinned pages. 5976** |
5977** [[the xCachesize() page cache method]] |
|
5281** ^(The xCachesize() method may be called at any time by SQLite to set the 5282** suggested maximum cache-size (number of pages stored by) the cache 5283** instance passed as the first argument. This is the value configured using | 5978** ^(The xCachesize() method may be called at any time by SQLite to set the 5979** suggested maximum cache-size (number of pages stored by) the cache 5980** instance passed as the first argument. This is the value configured using |
5284** the SQLite "[PRAGMA cache_size]" command.)^ ^As with the bPurgeable | 5981** the SQLite "[PRAGMA cache_size]" command.)^ As with the bPurgeable |
5285** parameter, the implementation is not required to do anything with this 5286** value; it is advisory only. 5287** | 5982** parameter, the implementation is not required to do anything with this 5983** value; it is advisory only. 5984** |
5288** ^The xPagecount() method should return the number of pages currently 5289** stored in the cache. 5290** 5291** ^The xFetch() method is used to fetch a page and return a pointer to it. 5292** ^A 'page', in this context, is a buffer of szPage bytes aligned at an 5293** 8-byte boundary. ^The page to be fetched is determined by the key. ^The 5294** mimimum key value is 1. After it has been retrieved using xFetch, the page | 5985** [[the xPagecount() page cache methods]] 5986** The xPagecount() method must return the number of pages currently 5987** stored in the cache, both pinned and unpinned. 5988** 5989** [[the xFetch() page cache methods]] 5990** The xFetch() method locates a page in the cache and returns a pointer to 5991** the page, or a NULL pointer. 5992** A "page", in this context, means a buffer of szPage bytes aligned at an 5993** 8-byte boundary. The page to be fetched is determined by the key. ^The 5994** minimum key value is 1. After it has been retrieved using xFetch, the page |
5295** is considered to be "pinned". 5296** | 5995** is considered to be "pinned". 5996** |
5297** ^If the requested page is already in the page cache, then the page cache | 5997** If the requested page is already in the page cache, then the page cache |
5298** implementation must return a pointer to the page buffer with its content | 5998** implementation must return a pointer to the page buffer with its content |
5299** intact. ^(If the requested page is not already in the cache, then the 5300** behavior of the cache implementation is determined by the value of the 5301** createFlag parameter passed to xFetch, according to the following table: | 5999** intact. If the requested page is not already in the cache, then the 6000** cache implementation should use the value of the createFlag 6001** parameter to help it determined what action to take: |
5302** 5303** <table border=1 width=85% align=center> 5304** <tr><th> createFlag <th> Behaviour when page is not already in cache 5305** <tr><td> 0 <td> Do not allocate a new page. Return NULL. 5306** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so. 5307** Otherwise return NULL. 5308** <tr><td> 2 <td> Make every effort to allocate a new page. Only return 5309** NULL if allocating a new page is effectively impossible. | 6002** 6003** <table border=1 width=85% align=center> 6004** <tr><th> createFlag <th> Behaviour when page is not already in cache 6005** <tr><td> 0 <td> Do not allocate a new page. Return NULL. 6006** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so. 6007** Otherwise return NULL. 6008** <tr><td> 2 <td> Make every effort to allocate a new page. Only return 6009** NULL if allocating a new page is effectively impossible. |
5310** </table>)^ | 6010** |
5313** a call to xFetch() with createFlag==1 returns NULL, then SQLite will
6013** will only use a createFlag of 2 after a prior call with a createFlag of 1
6014** failed.)^ In between the to xFetch() calls, SQLite may
5316** attempting to unpin pages, the xFetch() method will be invoked again with
5317** a createFlag of 2.
5321** then the page should be evicted from the cache. In this case SQLite
5322** assumes that the next time the page is retrieved from the cache using
5323** the xFetch() method, it will be zeroed.)^ ^If the discard parameter is
5324** zero, then the page is considered to be unpinned. ^The cache implementation
6021** then the page must be evicted from the cache.
6022** ^If the discard parameter is
6023** zero, then the page may be discarded or retained at the discretion of
6024** page cache implementation. ^The page cache implementation
5326**
6026**
5328** call to xUnpin() unpins the page regardless of the number of prior calls
5329** to xFetch().)^
6028** call to xUnpin() unpins the page regardless of the number of prior calls
6029** to xFetch().
5332** page passed as the second argument from oldKey to newKey. ^If the cache
5333** previously contains an entry associated with newKey, it should be
6032** The xRekey() method is used to change the key value associated with the
6033** page passed as the second argument. If the cache
6034** previously contains an entry associated with newKey, it must be
5335** to be pinned.
5336**
6036** to be pinned.
6037**
5341** they can be safely discarded.
5342**
6042** they can be safely discarded.
6043**
5344** All resources associated with the specified cache should be freed. ^After
5345** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
5346** handle invalid, and will not use it with any other sqlite3_pcache_methods
5347** functions.
5348*/
5349typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
5350struct sqlite3_pcache_methods {
--- 7 unchanged lines hidden (view full) ---
5358 void (*xUnpin)(sqlite3_pcache*, void*, int discard);
5359 void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
5360 void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
5361 void (*xDestroy)(sqlite3_pcache*);
5362};
5363
5364/*
5365** CAPI3REF: Online Backup Object
6046** All resources associated with the specified cache should be freed. ^After
6047** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
6048** handle invalid, and will not use it with any other sqlite3_pcache_methods
6049** functions.
6050*/
6051typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
6052struct sqlite3_pcache_methods {
--- 7 unchanged lines hidden (view full) ---
6060 void (*xUnpin)(sqlite3_pcache*, void*, int discard);
6061 void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
6062 void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
6063 void (*xDestroy)(sqlite3_pcache*);
6064};
6065
6066/*
6067** CAPI3REF: Online Backup Object
5368** The sqlite3_backup object records state information about an ongoing
5369** online backup operation. ^The sqlite3_backup object is created by
5370** a call to [sqlite3_backup_init()] and is destroyed by a call to
5371** [sqlite3_backup_finish()].
5372**
5373** See Also: [Using the SQLite Online Backup API]
5374*/
5375typedef struct sqlite3_backup sqlite3_backup;
5376
5377/*
5378** CAPI3REF: Online Backup API.
6069** The sqlite3_backup object records state information about an ongoing
6070** online backup operation. ^The sqlite3_backup object is created by
6071** a call to [sqlite3_backup_init()] and is destroyed by a call to
6072** [sqlite3_backup_finish()].
6073**
6074** See Also: [Using the SQLite Online Backup API]
6075*/
6076typedef struct sqlite3_backup sqlite3_backup;
6077
6078/*
6079** CAPI3REF: Online Backup API.
5381** The backup API copies the content of one database into another.
5382** It is useful either for creating backups of databases or
6081** The backup API copies the content of one database into another.
6082** It is useful either for creating backups of databases or
5385** See Also: [Using the SQLite Online Backup API]
5386**
6085** See Also: [Using the SQLite Online Backup API]
6086**
5388** duration of the operation. ^However the source database is only
5389** read-locked while it is actually being read; it is not locked
5390** continuously for the entire backup operation. ^Thus, the backup may be
5391** performed on a live source database without preventing other users from
6088** for the duration of the backup operation.
6089** ^The source database is read-locked only while it is being read;
6090** it is not locked continuously for the entire backup operation.
6091** ^Thus, the backup may be performed on a live source database without
6092** preventing other database connections from
5394** ^(To perform a backup operation:
6095** ^(To perform a backup operation:
5396** <li><b>sqlite3_backup_init()</b> is called once to initialize the
6097** <li><b>sqlite3_backup_init()</b> is called once to initialize the
5398**
6099** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
5401** associated with the backup operation.
6102** associated with the backup operation.
5403** There should be exactly one call to sqlite3_backup_finish() for each
5404** successful call to sqlite3_backup_init().
5405**
6104** There should be exactly one call to sqlite3_backup_finish() for each
6105** successful call to sqlite3_backup_init().
6106**
5409** [database connection] associated with the destination database
6110** [database connection] associated with the destination database
5411** ^The database name is "main" for the main database, "temp" for the
5412** temporary database, or the name specified after the AS keyword in
5413** an [ATTACH] statement for an attached database.
6112** ^The database name is "main" for the main database, "temp" for the
6113** temporary database, or the name specified after the AS keyword in
6114** an [ATTACH] statement for an attached database.
5416** and database name of the source database, respectively.
5417** ^The source and destination [database connections] (parameters S and D)
6117** and database name of the source database, respectively.
6118** ^The source and destination [database connections] (parameters S and D)
5420**
5421** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
6121**
6122** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
5424** ^The error code and message for the failed call to sqlite3_backup_init()
5425** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
5426** [sqlite3_errmsg16()] functions.
5427** ^A successful call to sqlite3_backup_init() returns a pointer to an
5428** [sqlite3_backup] object.
5429** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
6125** ^The error code and message for the failed call to sqlite3_backup_init()
6126** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
6127** [sqlite3_errmsg16()] functions.
6128** ^A successful call to sqlite3_backup_init() returns a pointer to an
6129** [sqlite3_backup] object.
6130** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
5432**
6133**
5441** from source to destination, then it returns [SQLITE_DONE].
5442** ^If an error occurs while running sqlite3_backup_step(B,N),
5443** then an [error code] is returned. ^As well as [SQLITE_OK] and
5444** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
5445** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
5446** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
5447**
6142** from source to destination, then it returns [SQLITE_DONE].
6143** ^If an error occurs while running sqlite3_backup_step(B,N),
6144** then an [error code] is returned. ^As well as [SQLITE_OK] and
6145** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
6146** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
6147** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
6148**
5449** database was opened read-only or if
5450** the destination is an in-memory database with a different page size
5451** from the source database.
6150** <ol>
6151** <li> the destination database was opened read-only, or
6152** <li> the destination database is using write-ahead-log journaling
6153** and the destination and source page sizes differ, or
6154** <li> the destination database is an in-memory database and the
6155** destination and source page sizes differ.
6156** </ol>)^
5453** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
5454** the [sqlite3_busy_handler | busy-handler function]
6158** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
6159** the [sqlite3_busy_handler | busy-handler function]
5456** busy-handler returns non-zero before the lock is available, then
6161** busy-handler returns non-zero before the lock is available, then
5458** sqlite3_backup_step() can be retried later. ^If the source
5459** [database connection]
5460** is being used to write to the source database when sqlite3_backup_step()
5461** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
5462** case the call to sqlite3_backup_step() can be retried later on. ^(If
5463** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
6163** sqlite3_backup_step() can be retried later. ^If the source
6164** [database connection]
6165** is being used to write to the source database when sqlite3_backup_step()
6166** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
6167** case the call to sqlite3_backup_step() can be retried later on. ^(If
6168** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
5465** there is no point in retrying the call to sqlite3_backup_step(). These
5466** errors are considered fatal.)^ The application must accept
5467** that the backup operation has failed and pass the backup operation handle
6170** there is no point in retrying the call to sqlite3_backup_step(). These
6171** errors are considered fatal.)^ The application must accept
6172** that the backup operation has failed and pass the backup operation handle
5469**
5470** ^The first call to sqlite3_backup_step() obtains an exclusive lock
6174**
6175** ^The first call to sqlite3_backup_step() obtains an exclusive lock
5472** sqlite3_backup_finish() is called or the backup operation is complete
6177** sqlite3_backup_finish() is called or the backup operation is complete
5474** sqlite3_backup_step() obtains a [shared lock] on the source database that
5475** lasts for the duration of the sqlite3_backup_step() call.
5476** ^Because the source database is not locked between calls to
5477** sqlite3_backup_step(), the source database may be modified mid-way
5478** through the backup process. ^If the source database is modified by an
5479** external process or via a database connection other than the one being
5480** used by the backup operation, then the backup will be automatically
6179** sqlite3_backup_step() obtains a [shared lock] on the source database that
6180** lasts for the duration of the sqlite3_backup_step() call.
6181** ^Because the source database is not locked between calls to
6182** sqlite3_backup_step(), the source database may be modified mid-way
6183** through the backup process. ^If the source database is modified by an
6184** external process or via a database connection other than the one being
6185** used by the backup operation, then the backup will be automatically
5483** by the backup operation, then the backup database is automatically
5484** updated at the same time.
5485**
6188** by the backup operation, then the backup database is automatically
6189** updated at the same time.
6190**
5490** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
5491** ^The sqlite3_backup_finish() interfaces releases all
6195** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
6196** ^The sqlite3_backup_finish() interfaces releases all
5494** active write-transaction on the destination database is rolled back.
5495** The [sqlite3_backup] object is invalid
5496** and may not be used following a call to sqlite3_backup_finish().
5497**
5498** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
5499** sqlite3_backup_step() errors occurred, regardless or whether or not
5500** sqlite3_backup_step() completed.
5501** ^If an out-of-memory condition or IO error occurred during any prior
5502** sqlite3_backup_step() call on the same [sqlite3_backup] object, then
5503** sqlite3_backup_finish() returns the corresponding [error code].
5504**
5505** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
5506** is not a permanent error and does not affect the return value of
5507** sqlite3_backup_finish().
5508**
6199** active write-transaction on the destination database is rolled back.
6200** The [sqlite3_backup] object is invalid
6201** and may not be used following a call to sqlite3_backup_finish().
6202**
6203** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
6204** sqlite3_backup_step() errors occurred, regardless or whether or not
6205** sqlite3_backup_step() completed.
6206** ^If an out-of-memory condition or IO error occurred during any prior
6207** sqlite3_backup_step() call on the same [sqlite3_backup] object, then
6208** sqlite3_backup_finish() returns the corresponding [error code].
6209**
6210** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
6211** is not a permanent error and does not affect the return value of
6212** sqlite3_backup_finish().
6213**
6215** <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b>
5511** ^Each call to sqlite3_backup_step() sets two values inside
5512** the [sqlite3_backup] object: the number of pages still to be backed
6217** ^Each call to sqlite3_backup_step() sets two values inside
6218** the [sqlite3_backup] object: the number of pages still to be backed
5515** retrieve these two values, respectively.
5516**
5517** ^The values returned by these functions are only updated by
5518** sqlite3_backup_step(). ^If the source database is modified during a backup
5519** operation, then the values are not updated to account for any extra
5520** pages that need to be updated or the size of the source database file
5521** changing.
5522**
5523** <b>Concurrent Usage of Database Handles</b>
5524**
5525** ^The source [database connection] may be used by the application for other
5526** purposes while a backup operation is underway or being initialized.
5527** ^If SQLite is compiled and configured to support threadsafe database
5528** connections, then the source database connection may be used concurrently
5529** from within other threads.
5530**
6221** retrieve these two values, respectively.
6222**
6223** ^The values returned by these functions are only updated by
6224** sqlite3_backup_step(). ^If the source database is modified during a backup
6225** operation, then the values are not updated to account for any extra
6226** pages that need to be updated or the size of the source database file
6227** changing.
6228**
6229** <b>Concurrent Usage of Database Handles</b>
6230**
6231** ^The source [database connection] may be used by the application for other
6232** purposes while a backup operation is underway or being initialized.
6233** ^If SQLite is compiled and configured to support threadsafe database
6234** connections, then the source database connection may be used concurrently
6235** from within other threads.
6236**
5532** [database connection] is not passed to any other API (by any thread) after
6238** [database connection] is not passed to any other API (by any thread) after
5534** sqlite3_backup_finish(). SQLite does not currently check to see
5535** if the application incorrectly accesses the destination [database connection]
5536** and so no error code is reported, but the operations may malfunction
5537** nevertheless. Use of the destination database connection while a
5538** backup is in progress might also also cause a mutex deadlock.
5539**
5540** If running in [shared cache mode], the application must
5541** guarantee that the shared cache used by the destination database
5542** is not accessed while the backup is running. In practice this means
6240** sqlite3_backup_finish(). SQLite does not currently check to see
6241** if the application incorrectly accesses the destination [database connection]
6242** and so no error code is reported, but the operations may malfunction
6243** nevertheless. Use of the destination database connection while a
6244** backup is in progress might also also cause a mutex deadlock.
6245**
6246** If running in [shared cache mode], the application must
6247** guarantee that the shared cache used by the destination database
6248** is not accessed while the backup is running. In practice this means
5545** not just the specific connection that was passed to sqlite3_backup_init().
5546**
6251** not just the specific connection that was passed to sqlite3_backup_init().
6252**
5549** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
5550** APIs are not strictly speaking threadsafe. If they are invoked at the
5551** same time as another thread is invoking sqlite3_backup_step() it is
5552** possible that they return invalid values.
5553*/
5554SQLITE_API sqlite3_backup *sqlite3_backup_init(
5555 sqlite3 *pDest, /* Destination database handle */
5556 const char *zDestName, /* Destination database name */
5557 sqlite3 *pSource, /* Source database handle */
5558 const char *zSourceName /* Source database name */
5559);
5560SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
5561SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
5562SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
5563SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
5564
5565/*
5566** CAPI3REF: Unlock Notification
6255** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
6256** APIs are not strictly speaking threadsafe. If they are invoked at the
6257** same time as another thread is invoking sqlite3_backup_step() it is
6258** possible that they return invalid values.
6259*/
6260SQLITE_API sqlite3_backup *sqlite3_backup_init(
6261 sqlite3 *pDest, /* Destination database handle */
6262 const char *zDestName, /* Destination database name */
6263 sqlite3 *pSource, /* Source database handle */
6264 const char *zSourceName /* Source database name */
6265);
6266SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
6267SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
6268SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
6269SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
6270
6271/*
6272** CAPI3REF: Unlock Notification
5569** ^When running in shared-cache mode, a database operation may fail with
5570** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
5571** individual tables within the shared-cache cannot be obtained. See
6274** ^When running in shared-cache mode, a database operation may fail with
6275** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
6276** individual tables within the shared-cache cannot be obtained. See
5573** ^This API may be used to register a callback that SQLite will invoke
6278** ^This API may be used to register a callback that SQLite will invoke
5575** ^This API is only available if the library was compiled with the
5576** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
5577**
5578** See Also: [Using the SQLite Unlock Notification Feature].
5579**
5580** ^Shared-cache locks are released when a database connection concludes
6280** ^This API is only available if the library was compiled with the
6281** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
6282**
6283** See Also: [Using the SQLite Unlock Notification Feature].
6284**
6285** ^Shared-cache locks are released when a database connection concludes
5583** ^When a connection (known as the blocked connection) fails to obtain a
5584** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
5585** identity of the database connection (the blocking connection) that
6288** ^When a connection (known as the blocked connection) fails to obtain a
6289** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
6290** identity of the database connection (the blocking connection) that
5590** when the blocking connections current transaction is concluded. ^The
5591** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
5592** call that concludes the blocking connections transaction.
5593**
5594** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
5595** there is a chance that the blocking connection will have already
5596** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
5597** If this happens, then the specified callback is invoked immediately,
5598** from within the call to sqlite3_unlock_notify().)^
5599**
5600** ^If the blocked connection is attempting to obtain a write-lock on a
5601** shared-cache table, and more than one other connection currently holds
6295** when the blocking connections current transaction is concluded. ^The
6296** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
6297** call that concludes the blocking connections transaction.
6298**
6299** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
6300** there is a chance that the blocking connection will have already
6301** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
6302** If this happens, then the specified callback is invoked immediately,
6303** from within the call to sqlite3_unlock_notify().)^
6304**
6305** ^If the blocked connection is attempting to obtain a write-lock on a
6306** shared-cache table, and more than one other connection currently holds
5604**
6309**
5607** blocked connection already has a registered unlock-notify callback,
5608** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
5609** called with a NULL pointer as its second argument, then any existing
6312** blocked connection already has a registered unlock-notify callback,
6313** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
6314** called with a NULL pointer as its second argument, then any existing
5612** connection using [sqlite3_close()].
5613**
5614** The unlock-notify callback is not reentrant. If an application invokes
5615** any sqlite3_xxx API functions from within an unlock-notify callback, a
5616** crash or deadlock may be the result.
5617**
5618** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
5619** returns SQLITE_OK.
5620**
5621** <b>Callback Invocation Details</b>
5622**
6317** connection using [sqlite3_close()].
6318**
6319** The unlock-notify callback is not reentrant. If an application invokes
6320** any sqlite3_xxx API functions from within an unlock-notify callback, a
6321** crash or deadlock may be the result.
6322**
6323** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
6324** returns SQLITE_OK.
6325**
6326** <b>Callback Invocation Details</b>
6327**
5625** However, the signature of the callback function allows SQLite to pass
5626** it an array of void* context pointers. The first argument passed to
5627** an unlock-notify callback is a pointer to an array of void* pointers,
5628** and the second is the number of entries in the array.
5629**
5630** When a blocking connections transaction is concluded, there may be
5631** more than one blocked connection that has registered for an unlock-notify
5632** callback. ^If two or more such blocked connections have specified the
5633** same callback function, then instead of invoking the callback function
5634** multiple times, it is invoked once with the set of void* context pointers
5635** specified by the blocked connections bundled together into an array.
6330** However, the signature of the callback function allows SQLite to pass
6331** it an array of void* context pointers. The first argument passed to
6332** an unlock-notify callback is a pointer to an array of void* pointers,
6333** and the second is the number of entries in the array.
6334**
6335** When a blocking connections transaction is concluded, there may be
6336** more than one blocked connection that has registered for an unlock-notify
6337** callback. ^If two or more such blocked connections have specified the
6338** same callback function, then instead of invoking the callback function
6339** multiple times, it is invoked once with the set of void* context pointers
6340** specified by the blocked connections bundled together into an array.
5638**
5639** <b>Deadlock Detection</b>
5640**
6343**
6344** <b>Deadlock Detection</b>
6345**
5643** action (a reasonable assumption), then using this API may cause the
5644** application to deadlock. For example, if connection X is waiting for
5645** connection Y's transaction to be concluded, and similarly connection
5646** Y is waiting on connection X's transaction, then neither connection
5647** will proceed and the system may remain deadlocked indefinitely.
5648**
5649** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
--- 6 unchanged lines hidden (view full) ---
5656** A's transaction is concluded. ^Indirect deadlock is also detected, so
5657** the system is also considered to be deadlocked if connection B has
5658** registered for an unlock-notify callback on the conclusion of connection
5659** C's transaction, where connection C is waiting on connection A. ^Any
5660** number of levels of indirection are allowed.
5661**
5662** <b>The "DROP TABLE" Exception</b>
5663**
6348** action (a reasonable assumption), then using this API may cause the
6349** application to deadlock. For example, if connection X is waiting for
6350** connection Y's transaction to be concluded, and similarly connection
6351** Y is waiting on connection X's transaction, then neither connection
6352** will proceed and the system may remain deadlocked indefinitely.
6353**
6354** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
--- 6 unchanged lines hidden (view full) ---
6361** A's transaction is concluded. ^Indirect deadlock is also detected, so
6362** the system is also considered to be deadlocked if connection B has
6363** registered for an unlock-notify callback on the conclusion of connection
6364** C's transaction, where connection C is waiting on connection A. ^Any
6365** number of levels of indirection are allowed.
6366**
6367** <b>The "DROP TABLE" Exception</b>
6368**
5666** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
5667** SQLite checks if there are any currently executing SELECT statements
5668** that belong to the same connection. If there are, SQLITE_LOCKED is
5669** returned. In this case there is no "blocking connection", so invoking
5670** sqlite3_unlock_notify() results in the unlock-notify callback being
5671** invoked immediately. If the application then re-attempts the "DROP TABLE"
5672** or "DROP INDEX" query, an infinite loop might be the result.
5673**
5674** One way around this problem is to check the extended error code returned
5675** by an sqlite3_step() call. ^(If there is a blocking connection, then the
5676** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
6371** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
6372** SQLite checks if there are any currently executing SELECT statements
6373** that belong to the same connection. If there are, SQLITE_LOCKED is
6374** returned. In this case there is no "blocking connection", so invoking
6375** sqlite3_unlock_notify() results in the unlock-notify callback being
6376** invoked immediately. If the application then re-attempts the "DROP TABLE"
6377** or "DROP INDEX" query, an infinite loop might be the result.
6378**
6379** One way around this problem is to check the extended error code returned
6380** by an sqlite3_step() call. ^(If there is a blocking connection, then the
6381** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
5679*/
5680SQLITE_API int sqlite3_unlock_notify(
5681 sqlite3 *pBlocked, /* Waiting connection */
5682 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
5683 void *pNotifyArg /* Argument to pass to xNotify */
5684);
5685
5686
5687/*
5688** CAPI3REF: String Comparison
6384*/
6385SQLITE_API int sqlite3_unlock_notify(
6386 sqlite3 *pBlocked, /* Waiting connection */
6387 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
6388 void *pNotifyArg /* Argument to pass to xNotify */
6389);
6390
6391
6392/*
6393** CAPI3REF: String Comparison
5691** ^The [sqlite3_strnicmp()] API allows applications and extensions to
5692** compare the contents of two buffers containing UTF-8 strings in a
6395** ^The [sqlite3_strnicmp()] API allows applications and extensions to
6396** compare the contents of two buffers containing UTF-8 strings in a
5695*/
5696SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
5697
5698/*
5699** CAPI3REF: Error Logging Interface
6399*/
6400SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
6401
6402/*
6403** CAPI3REF: Error Logging Interface
5702** ^The [sqlite3_log()] interface writes a message into the error log
5703** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
5704** ^If logging is enabled, the zFormat string and subsequent arguments are
6405** ^The [sqlite3_log()] interface writes a message into the error log
6406** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
6407** ^If logging is enabled, the zFormat string and subsequent arguments are
5707** The sqlite3_log() interface is intended for use by extensions such as
5708** virtual tables, collating functions, and SQL functions. While there is
5709** nothing to prevent an application from calling sqlite3_log(), doing so
5710** is considered bad form.
5711**
5712** The zFormat string must not be NULL.
5713**
5714** To avoid deadlocks and other threading problems, the sqlite3_log() routine
5715** will not use dynamically allocated memory. The log message is stored in
5716** a fixed-length buffer on the stack. If the log message is longer than
5717** a few hundred characters, it will be truncated to the length of the
5718** buffer.
5719*/
5720SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
5721
5722/*
6410** The sqlite3_log() interface is intended for use by extensions such as
6411** virtual tables, collating functions, and SQL functions. While there is
6412** nothing to prevent an application from calling sqlite3_log(), doing so
6413** is considered bad form.
6414**
6415** The zFormat string must not be NULL.
6416**
6417** To avoid deadlocks and other threading problems, the sqlite3_log() routine
6418** will not use dynamically allocated memory. The log message is stored in
6419** a fixed-length buffer on the stack. If the log message is longer than
6420** a few hundred characters, it will be truncated to the length of the
6421** buffer.
6422*/
6423SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
6424
6425/*
6427**
6428** ^The [sqlite3_wal_hook()] function is used to register a callback that
6429** will be invoked each time a database connection commits data to a
6430** [write-ahead log] (i.e. whenever a transaction is committed in
6431** [journal_mode | journal_mode=WAL mode]).
6432**
6433** ^The callback is invoked by SQLite after the commit has taken place and
6434** the associated write-lock on the database released, so the implementation
6435** may read, write or [checkpoint] the database as required.
6436**
6437** ^The first parameter passed to the callback function when it is invoked
6438** is a copy of the third parameter passed to sqlite3_wal_hook() when
6439** registering the callback. ^The second is a copy of the database handle.
6440** ^The third parameter is the name of the database that was written to -
6441** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter
6442** is the number of pages currently in the write-ahead log file,
6443** including those that were just committed.
6444**
6445** The callback function should normally return [SQLITE_OK]. ^If an error
6446** code is returned, that error will propagate back up through the
6447** SQLite code base to cause the statement that provoked the callback
6448** to report an error, though the commit will have still occurred. If the
6449** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value
6450** that does not correspond to any valid SQLite error code, the results
6451** are undefined.
6452**
6453** A single database handle may have at most a single write-ahead log callback
6454** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any
6455** previously registered write-ahead log callback. ^Note that the
6456** [sqlite3_wal_autocheckpoint()] interface and the
6457** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
6458** those overwrite any prior [sqlite3_wal_hook()] settings.
6459*/
6460SQLITE_API void *sqlite3_wal_hook(
6461 sqlite3*,
6462 int(*)(void *,sqlite3*,const char*,int),
6463 void*
6464);
6465
6466/*
6467** CAPI3REF: Configure an auto-checkpoint
6468**
6469** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
6470** [sqlite3_wal_hook()] that causes any database on [database connection] D
6471** to automatically [checkpoint]
6472** after committing a transaction if there are N or
6473** more frames in the [write-ahead log] file. ^Passing zero or
6474** a negative value as the nFrame parameter disables automatic
6475** checkpoints entirely.
6476**
6477** ^The callback registered by this function replaces any existing callback
6478** registered using [sqlite3_wal_hook()]. ^Likewise, registering a callback
6479** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism
6480** configured by this function.
6481**
6482** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
6483** from SQL.
6484**
6485** ^Every new [database connection] defaults to having the auto-checkpoint
6486** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]
6487** pages. The use of this interface
6488** is only necessary if the default setting is found to be suboptimal
6489** for a particular application.
6490*/
6491SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
6492
6493/*
6494** CAPI3REF: Checkpoint a database
6495**
6496** ^The [sqlite3_wal_checkpoint(D,X)] interface causes database named X
6497** on [database connection] D to be [checkpointed]. ^If X is NULL or an
6498** empty string, then a checkpoint is run on all databases of
6499** connection D. ^If the database connection D is not in
6500** [WAL | write-ahead log mode] then this interface is a harmless no-op.
6501**
6502** ^The [wal_checkpoint pragma] can be used to invoke this interface
6503** from SQL. ^The [sqlite3_wal_autocheckpoint()] interface and the
6504** [wal_autocheckpoint pragma] can be used to cause this interface to be
6505** run whenever the WAL reaches a certain size threshold.
6506**
6507** See also: [sqlite3_wal_checkpoint_v2()]
6508*/
6509SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
6510
6511/*
6512** CAPI3REF: Checkpoint a database
6513**
6514** Run a checkpoint operation on WAL database zDb attached to database
6515** handle db. The specific operation is determined by the value of the
6516** eMode parameter:
6517**
6518** <dl>
6519** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
6520** Checkpoint as many frames as possible without waiting for any database
6521** readers or writers to finish. Sync the db file if all frames in the log
6522** are checkpointed. This mode is the same as calling
6523** sqlite3_wal_checkpoint(). The busy-handler callback is never invoked.
6524**
6525** <dt>SQLITE_CHECKPOINT_FULL<dd>
6526** This mode blocks (calls the busy-handler callback) until there is no
6527** database writer and all readers are reading from the most recent database
6528** snapshot. It then checkpoints all frames in the log file and syncs the
6529** database file. This call blocks database writers while it is running,
6530** but not database readers.
6531**
6532** <dt>SQLITE_CHECKPOINT_RESTART<dd>
6533** This mode works the same way as SQLITE_CHECKPOINT_FULL, except after
6534** checkpointing the log file it blocks (calls the busy-handler callback)
6535** until all readers are reading from the database file only. This ensures
6536** that the next client to write to the database file restarts the log file
6537** from the beginning. This call blocks database writers while it is running,
6538** but not database readers.
6539** </dl>
6540**
6541** If pnLog is not NULL, then *pnLog is set to the total number of frames in
6542** the log file before returning. If pnCkpt is not NULL, then *pnCkpt is set to
6543** the total number of checkpointed frames (including any that were already
6544** checkpointed when this function is called). *pnLog and *pnCkpt may be
6545** populated even if sqlite3_wal_checkpoint_v2() returns other than SQLITE_OK.
6546** If no values are available because of an error, they are both set to -1
6547** before returning to communicate this to the caller.
6548**
6549** All calls obtain an exclusive "checkpoint" lock on the database file. If
6550** any other process is running a checkpoint operation at the same time, the
6551** lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a
6552** busy-handler configured, it will not be invoked in this case.
6553**
6554** The SQLITE_CHECKPOINT_FULL and RESTART modes also obtain the exclusive
6555** "writer" lock on the database file. If the writer lock cannot be obtained
6556** immediately, and a busy-handler is configured, it is invoked and the writer
6557** lock retried until either the busy-handler returns 0 or the lock is
6558** successfully obtained. The busy-handler is also invoked while waiting for
6559** database readers as described above. If the busy-handler returns 0 before
6560** the writer lock is obtained or while waiting for database readers, the
6561** checkpoint operation proceeds from that point in the same way as
6562** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
6563** without blocking any further. SQLITE_BUSY is returned in this case.
6564**
6565** If parameter zDb is NULL or points to a zero length string, then the
6566** specified operation is attempted on all WAL databases. In this case the
6567** values written to output parameters *pnLog and *pnCkpt are undefined. If
6568** an SQLITE_BUSY error is encountered when processing one or more of the
6569** attached WAL databases, the operation is still attempted on any remaining
6570** attached databases and SQLITE_BUSY is returned to the caller. If any other
6571** error occurs while processing an attached database, processing is abandoned
6572** and the error code returned to the caller immediately. If no error
6573** (SQLITE_BUSY or otherwise) is encountered while processing the attached
6574** databases, SQLITE_OK is returned.
6575**
6576** If database zDb is the name of an attached database that is not in WAL
6577** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If
6578** zDb is not NULL (or a zero length string) and is not the name of any
6579** attached database, SQLITE_ERROR is returned to the caller.
6580*/
6581SQLITE_API int sqlite3_wal_checkpoint_v2(
6582 sqlite3 *db, /* Database handle */
6583 const char *zDb, /* Name of attached database (or NULL) */
6584 int eMode, /* SQLITE_CHECKPOINT_* value */
6585 int *pnLog, /* OUT: Size of WAL log in frames */
6586 int *pnCkpt /* OUT: Total number of frames checkpointed */
6587);
6588
6589/*
6590** CAPI3REF: Checkpoint operation parameters
6591**
6592** These constants can be used as the 3rd parameter to
6593** [sqlite3_wal_checkpoint_v2()]. See the [sqlite3_wal_checkpoint_v2()]
6594** documentation for additional information about the meaning and use of
6595** each of these values.
6596*/
6597#define SQLITE_CHECKPOINT_PASSIVE 0
6598#define SQLITE_CHECKPOINT_FULL 1
6599#define SQLITE_CHECKPOINT_RESTART 2
6600
6601/*
6602** CAPI3REF: Virtual Table Interface Configuration
6603**
6604** This function may be called by either the [xConnect] or [xCreate] method
6605** of a [virtual table] implementation to configure
6606** various facets of the virtual table interface.
6607**
6608** If this interface is invoked outside the context of an xConnect or
6609** xCreate virtual table method then the behavior is undefined.
6610**
6611** At present, there is only one option that may be configured using
6612** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].) Further options
6613** may be added in the future.
6614*/
6615SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);
6616
6617/*
6618** CAPI3REF: Virtual Table Configuration Options
6619**
6620** These macros define the various options to the
6621** [sqlite3_vtab_config()] interface that [virtual table] implementations
6622** can use to customize and optimize their behavior.
6623**
6624** <dl>
6625** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT
6626** <dd>Calls of the form
6627** [sqlite3_vtab_config](db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported,
6628** where X is an integer. If X is zero, then the [virtual table] whose
6629** [xCreate] or [xConnect] method invoked [sqlite3_vtab_config()] does not
6630** support constraints. In this configuration (which is the default) if
6631** a call to the [xUpdate] method returns [SQLITE_CONSTRAINT], then the entire
6632** statement is rolled back as if [ON CONFLICT | OR ABORT] had been
6633** specified as part of the users SQL statement, regardless of the actual
6634** ON CONFLICT mode specified.
6635**
6636** If X is non-zero, then the virtual table implementation guarantees
6637** that if [xUpdate] returns [SQLITE_CONSTRAINT], it will do so before
6638** any modifications to internal or persistent data structures have been made.
6639** If the [ON CONFLICT] mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite
6640** is able to roll back a statement or database transaction, and abandon
6641** or continue processing the current SQL statement as appropriate.
6642** If the ON CONFLICT mode is REPLACE and the [xUpdate] method returns
6643** [SQLITE_CONSTRAINT], SQLite handles this as if the ON CONFLICT mode
6644** had been ABORT.
6645**
6646** Virtual table implementations that are required to handle OR REPLACE
6647** must do so within the [xUpdate] method. If a call to the
6648** [sqlite3_vtab_on_conflict()] function indicates that the current ON
6649** CONFLICT policy is REPLACE, the virtual table implementation should
6650** silently replace the appropriate rows within the xUpdate callback and
6651** return SQLITE_OK. Or, if this is not possible, it may return
6652** SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT
6653** constraint handling.
6654** </dl>
6655*/
6656#define SQLITE_VTAB_CONSTRAINT_SUPPORT 1
6657
6658/*
6659** CAPI3REF: Determine The Virtual Table Conflict Policy
6660**
6661** This function may only be called from within a call to the [xUpdate] method
6662** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The
6663** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL],
6664** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode
6665** of the SQL statement that triggered the call to the [xUpdate] method of the
6666** [virtual table].
6667*/
6668SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
6669
6670/*
6671** CAPI3REF: Conflict resolution modes
6672**
6673** These constants are returned by [sqlite3_vtab_on_conflict()] to
6674** inform a [virtual table] implementation what the [ON CONFLICT] mode
6675** is for the SQL statement being evaluated.
6676**
6677** Note that the [SQLITE_IGNORE] constant is also used as a potential
6678** return value from the [sqlite3_set_authorizer()] callback and that
6679** [SQLITE_ABORT] is also a [result code].
6680*/
6681#define SQLITE_ROLLBACK 1
6682/* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */
6683#define SQLITE_FAIL 3
6684/* #define SQLITE_ABORT 4 // Also an error code */
6685#define SQLITE_REPLACE 5
6686
6687
6688
6689/*
5724** builds on processors without floating point support.
5725*/
5726#ifdef SQLITE_OMIT_FLOATING_POINT
5727# undef double
5728#endif
5729
5730#ifdef __cplusplus
5731} /* End of the 'extern "C"' block */
5732#endif
5733#endif
5734
6691** builds on processors without floating point support.
6692*/
6693#ifdef SQLITE_OMIT_FLOATING_POINT
6694# undef double
6695#endif
6696
6697#ifdef __cplusplus
6698} /* End of the 'extern "C"' block */
6699#endif
6700#endif
6701
6703** 2010 August 30
6704**
6705** The author disclaims copyright to this source code. In place of
6706** a legal notice, here is a blessing:
6707**
6708** May you do good and not evil.
6709** May you find forgiveness for yourself and forgive others.
6710** May you share freely, never taking more than you give.
6711**
6712*************************************************************************
6713*/
6714
6715#ifndef _SQLITE3RTREE_H_
6716#define _SQLITE3RTREE_H_
6717
6718
6719#ifdef __cplusplus
6720extern "C" {
6721#endif
6722
6723typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
6724
6725/*
6726** Register a geometry callback named zGeom that can be used as part of an
6727** R-Tree geometry query as follows:
6728**
6729** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...)
6730*/
6731SQLITE_API int sqlite3_rtree_geometry_callback(
6732 sqlite3 *db,
6733 const char *zGeom,
6734 int (*xGeom)(sqlite3_rtree_geometry *, int nCoord, double *aCoord, int *pRes),
6735 void *pContext
6736);
6737
6738
6739/*
6740** A pointer to a structure of the following type is passed as the first
6741** argument to callbacks registered using rtree_geometry_callback().
6742*/
6743struct sqlite3_rtree_geometry {
6744 void *pContext; /* Copy of pContext passed to s_r_g_c() */
6745 int nParam; /* Size of array aParam[] */
6746 double *aParam; /* Parameters passed to SQL geom function */
6747 void *pUser; /* Callback implementation user data */
6748 void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */
6749};
6750
6751
6752#ifdef __cplusplus
6753} /* end of the 'extern "C"' block */
6754#endif
6755
6756#endif /* ifndef _SQLITE3RTREE_H_ */
6757