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. 9** May you share freely, never taking more than you give. 10** 11************************************************************************* 12** This header file defines the interface that the SQLite library 13** presents to client programs. If a C-function, structure, datatype, 14** or constant definition does not appear in this file, then it is 15** not a published API of SQLite, is subject to change without 16** notice, and should not be referenced by programs that use SQLite. 17** 18** Some of the definitions that are in this file are marked as 19** "experimental". Experimental interfaces are normally new 20** features recently added to SQLite. We do not anticipate changes 21** to experimental interfaces but reserve the right to make minor changes 22** if experience from use "in the wild" suggest such changes are prudent. 23** 24** The official C-language API documentation for SQLite is derived 25** from comments in this file. This file is the authoritative source 26** on how SQLite interfaces are suppose to operate. 27** 28** The name of this file under configuration management is "sqlite.h.in". 29** The makefile makes some minor changes to this file (such as inserting 30** the version number) and changes its name to "sqlite3.h" as 31** part of the build process. 32*/ 33#ifndef _SQLITE3_H_ 34#define _SQLITE3_H_ 35#include <stdarg.h> /* Needed for the definition of va_list */ 36 37/* 38** Make sure we can call this stuff from C++. 39*/ 40#ifdef __cplusplus 41extern "C" { 42#endif 43 44 45/* 46** Add the ability to override 'extern' 47*/ 48#ifndef SQLITE_EXTERN 49# define SQLITE_EXTERN extern 50#endif 51 52/* 53** These no-op macros are used in front of interfaces to mark those 54** interfaces as either deprecated or experimental. New applications 55** should not use deprecated interfaces - they are support for backwards 56** compatibility only. Application writers should be aware that 57** experimental interfaces are subject to change in point releases. 58** 59** These macros used to resolve to various kinds of compiler magic that 60** would generate warning messages when they were used. But that 61** compiler magic ended up generating such a flurry of bug reports 62** that we have taken it all out and gone back to using simple 63** noop macros. 64*/ 65#define SQLITE_DEPRECATED 66#define SQLITE_EXPERIMENTAL 67 68/* 69** Ensure these symbols were not defined by some previous header file. 70*/ 71#ifdef SQLITE_VERSION 72# undef SQLITE_VERSION 73#endif 74#ifdef SQLITE_VERSION_NUMBER 75# undef SQLITE_VERSION_NUMBER 76#endif 77 78/* 79** CAPI3REF: Compile-Time Library Version Numbers 80** 81** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header 82** evaluates to a string literal that is the SQLite version in the 83** format "X.Y.Z" where X is the major version number (always 3 for 84** SQLite3) and Y is the minor version number and Z is the release number.)^ 85** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer 86** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same 87** numbers used in [SQLITE_VERSION].)^ 88** The SQLITE_VERSION_NUMBER for any given release of SQLite will also 89** be larger than the release from which it is derived. Either Y will 90** be held constant and Z will be incremented or else Y will be incremented 91** and Z will be reset to zero. 92** 93** Since version 3.6.18, SQLite source code has been stored in the 94** <a href="http://www.fossil-scm.org/">Fossil configuration management 95** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to 96** a string which identifies a particular check-in of SQLite 97** within its configuration management system. ^The SQLITE_SOURCE_ID 98** string contains the date and time of the check-in (UTC) and an SHA1 99** hash of the entire source tree. 100** 101** See also: [sqlite3_libversion()], 102** [sqlite3_libversion_number()], [sqlite3_sourceid()], 103** [sqlite_version()] and [sqlite_source_id()]. 104*/ 105#define SQLITE_VERSION "--VERS--" 106#define SQLITE_VERSION_NUMBER --VERSION-NUMBER-- 107#define SQLITE_SOURCE_ID "--SOURCE-ID--" 108 109/* 110** CAPI3REF: Run-Time Library Version Numbers 111** KEYWORDS: sqlite3_version, sqlite3_sourceid 112** 113** These interfaces provide the same information as the [SQLITE_VERSION], 114** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros 115** but are associated with the library instead of the header file. ^(Cautious 116** programmers might include assert() statements in their application to 117** verify that values returned by these interfaces match the macros in 118** the header, and thus insure that the application is 119** compiled with matching library and header files. 120** 121** <blockquote><pre> 122** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER ); 123** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 ); 124** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 ); 125** </pre></blockquote>)^ 126** 127** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION] 128** macro. ^The sqlite3_libversion() function returns a pointer to the 129** to the sqlite3_version[] string constant. The sqlite3_libversion() 130** function is provided for use in DLLs since DLL users usually do not have 131** direct access to string constants within the DLL. ^The 132** sqlite3_libversion_number() function returns an integer equal to 133** [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns 134** a pointer to a string constant whose value is the same as the 135** [SQLITE_SOURCE_ID] C preprocessor macro. 136** 137** See also: [sqlite_version()] and [sqlite_source_id()]. 138*/ 139SQLITE_EXTERN const char sqlite3_version[]; 140const char *sqlite3_libversion(void); 141const char *sqlite3_sourceid(void); 142int sqlite3_libversion_number(void); 143 144/* 145** CAPI3REF: Run-Time Library Compilation Options Diagnostics 146** 147** ^The sqlite3_compileoption_used() function returns 0 or 1 148** indicating whether the specified option was defined at 149** compile time. ^The SQLITE_ prefix may be omitted from the 150** option name passed to sqlite3_compileoption_used(). 151** 152** ^The sqlite3_compileoption_get() function allows iterating 153** over the list of options that were defined at compile time by 154** returning the N-th compile time option string. ^If N is out of range, 155** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_ 156** prefix is omitted from any strings returned by 157** sqlite3_compileoption_get(). 158** 159** ^Support for the diagnostic functions sqlite3_compileoption_used() 160** and sqlite3_compileoption_get() may be omitted by specifying the 161** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time. 162** 163** See also: SQL functions [sqlite_compileoption_used()] and 164** [sqlite_compileoption_get()] and the [compile_options pragma]. 165*/ 166#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS 167int sqlite3_compileoption_used(const char *zOptName); 168const char *sqlite3_compileoption_get(int N); 169#endif 170 171/* 172** CAPI3REF: Test To See If The Library Is Threadsafe 173** 174** ^The sqlite3_threadsafe() function returns zero if and only if 175** SQLite was compiled mutexing code omitted due to the 176** [SQLITE_THREADSAFE] compile-time option being set to 0. 177** 178** SQLite can be compiled with or without mutexes. When 179** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes 180** are enabled and SQLite is threadsafe. When the 181** [SQLITE_THREADSAFE] macro is 0, 182** the mutexes are omitted. Without the mutexes, it is not safe 183** to use SQLite concurrently from more than one thread. 184** 185** Enabling mutexes incurs a measurable performance penalty. 186** So if speed is of utmost importance, it makes sense to disable 187** the mutexes. But for maximum safety, mutexes should be enabled. 188** ^The default behavior is for mutexes to be enabled. 189** 190** This interface can be used by an application to make sure that the 191** version of SQLite that it is linking against was compiled with 192** the desired setting of the [SQLITE_THREADSAFE] macro. 193** 194** This interface only reports on the compile-time mutex setting 195** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with 196** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but 197** can be fully or partially disabled using a call to [sqlite3_config()] 198** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD], 199** or [SQLITE_CONFIG_MUTEX]. ^(The return value of the 200** sqlite3_threadsafe() function shows only the compile-time setting of 201** thread safety, not any run-time changes to that setting made by 202** sqlite3_config(). In other words, the return value from sqlite3_threadsafe() 203** is unchanged by calls to sqlite3_config().)^ 204** 205** See the [threading mode] documentation for additional information. 206*/ 207int sqlite3_threadsafe(void); 208 209/* 210** CAPI3REF: Database Connection Handle 211** KEYWORDS: {database connection} {database connections} 212** 213** Each open SQLite database is represented by a pointer to an instance of 214** the opaque structure named "sqlite3". It is useful to think of an sqlite3 215** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and 216** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()] 217** is its destructor. There are many other interfaces (such as 218** [sqlite3_prepare_v2()], [sqlite3_create_function()], and 219** [sqlite3_busy_timeout()] to name but three) that are methods on an 220** sqlite3 object. 221*/ 222typedef struct sqlite3 sqlite3; 223 224/* 225** CAPI3REF: 64-Bit Integer Types 226** KEYWORDS: sqlite_int64 sqlite_uint64 227** 228** Because there is no cross-platform way to specify 64-bit integer types 229** SQLite includes typedefs for 64-bit signed and unsigned integers. 230** 231** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions. 232** The sqlite_int64 and sqlite_uint64 types are supported for backwards 233** compatibility only. 234** 235** ^The sqlite3_int64 and sqlite_int64 types can store integer values 236** between -9223372036854775808 and +9223372036854775807 inclusive. ^The 237** sqlite3_uint64 and sqlite_uint64 types can store integer values 238** between 0 and +18446744073709551615 inclusive. 239*/ 240#ifdef SQLITE_INT64_TYPE 241 typedef SQLITE_INT64_TYPE sqlite_int64; 242 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; 243#elif defined(_MSC_VER) || defined(__BORLANDC__) 244 typedef __int64 sqlite_int64; 245 typedef unsigned __int64 sqlite_uint64; 246#else 247 typedef long long int sqlite_int64; 248 typedef unsigned long long int sqlite_uint64; 249#endif 250typedef sqlite_int64 sqlite3_int64; 251typedef sqlite_uint64 sqlite3_uint64; 252 253/* 254** If compiling for a processor that lacks floating point support, 255** substitute integer for floating-point. 256*/ 257#ifdef SQLITE_OMIT_FLOATING_POINT 258# define double sqlite3_int64 259#endif 260 261/* 262** CAPI3REF: Closing A Database Connection 263** 264** ^The sqlite3_close() routine is the destructor for the [sqlite3] object. 265** ^Calls to sqlite3_close() return SQLITE_OK if the [sqlite3] object is 266** successfully destroyed and all associated resources are deallocated. 267** 268** Applications must [sqlite3_finalize | finalize] all [prepared statements] 269** and [sqlite3_blob_close | close] all [BLOB handles] associated with 270** the [sqlite3] object prior to attempting to close the object. ^If 271** sqlite3_close() is called on a [database connection] that still has 272** outstanding [prepared statements] or [BLOB handles], then it returns 273** SQLITE_BUSY. 274** 275** ^If [sqlite3_close()] is invoked while a transaction is open, 276** the transaction is automatically rolled back. 277** 278** The C parameter to [sqlite3_close(C)] must be either a NULL 279** pointer or an [sqlite3] object pointer obtained 280** from [sqlite3_open()], [sqlite3_open16()], or 281** [sqlite3_open_v2()], and not previously closed. 282** ^Calling sqlite3_close() with a NULL pointer argument is a 283** harmless no-op. 284*/ 285int sqlite3_close(sqlite3 *); 286 287/* 288** The type for a callback function. 289** This is legacy and deprecated. It is included for historical 290** compatibility and is not documented. 291*/ 292typedef int (*sqlite3_callback)(void*,int,char**, char**); 293 294/* 295** CAPI3REF: One-Step Query Execution Interface 296** 297** The sqlite3_exec() interface is a convenience wrapper around 298** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()], 299** that allows an application to run multiple statements of SQL 300** without having to use a lot of C code. 301** 302** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded, 303** semicolon-separate SQL statements passed into its 2nd argument, 304** in the context of the [database connection] passed in as its 1st 305** argument. ^If the callback function of the 3rd argument to 306** sqlite3_exec() is not NULL, then it is invoked for each result row 307** coming out of the evaluated SQL statements. ^The 4th argument to 308** to sqlite3_exec() is relayed through to the 1st argument of each 309** callback invocation. ^If the callback pointer to sqlite3_exec() 310** is NULL, then no callback is ever invoked and result rows are 311** ignored. 312** 313** ^If an error occurs while evaluating the SQL statements passed into 314** sqlite3_exec(), then execution of the current statement stops and 315** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec() 316** is not NULL then any error message is written into memory obtained 317** from [sqlite3_malloc()] and passed back through the 5th parameter. 318** To avoid memory leaks, the application should invoke [sqlite3_free()] 319** on error message strings returned through the 5th parameter of 320** of sqlite3_exec() after the error message string is no longer needed. 321** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors 322** occur, then sqlite3_exec() sets the pointer in its 5th parameter to 323** NULL before returning. 324** 325** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec() 326** routine returns SQLITE_ABORT without invoking the callback again and 327** without running any subsequent SQL statements. 328** 329** ^The 2nd argument to the sqlite3_exec() callback function is the 330** number of columns in the result. ^The 3rd argument to the sqlite3_exec() 331** callback is an array of pointers to strings obtained as if from 332** [sqlite3_column_text()], one for each column. ^If an element of a 333** result row is NULL then the corresponding string pointer for the 334** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the 335** sqlite3_exec() callback is an array of pointers to strings where each 336** entry represents the name of corresponding result column as obtained 337** from [sqlite3_column_name()]. 338** 339** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer 340** to an empty string, or a pointer that contains only whitespace and/or 341** SQL comments, then no SQL statements are evaluated and the database 342** is not changed. 343** 344** Restrictions: 345** 346** <ul> 347** <li> The application must insure that the 1st parameter to sqlite3_exec() 348** is a valid and open [database connection]. 349** <li> The application must not close [database connection] specified by 350** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running. 351** <li> The application must not modify the SQL statement text passed into 352** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running. 353** </ul> 354*/ 355int sqlite3_exec( 356 sqlite3*, /* An open database */ 357 const char *sql, /* SQL to be evaluated */ 358 int (*callback)(void*,int,char**,char**), /* Callback function */ 359 void *, /* 1st argument to callback */ 360 char **errmsg /* Error msg written here */ 361); 362 363/* 364** CAPI3REF: Result Codes 365** KEYWORDS: SQLITE_OK {error code} {error codes} 366** KEYWORDS: {result code} {result codes} 367** 368** Many SQLite functions return an integer result code from the set shown 369** here in order to indicates success or failure. 370** 371** New error codes may be added in future versions of SQLite. 372** 373** See also: [SQLITE_IOERR_READ | extended result codes] 374*/ 375#define SQLITE_OK 0 /* Successful result */ 376/* beginning-of-error-codes */ 377#define SQLITE_ERROR 1 /* SQL error or missing database */ 378#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */ 379#define SQLITE_PERM 3 /* Access permission denied */ 380#define SQLITE_ABORT 4 /* Callback routine requested an abort */ 381#define SQLITE_BUSY 5 /* The database file is locked */ 382#define SQLITE_LOCKED 6 /* A table in the database is locked */ 383#define SQLITE_NOMEM 7 /* A malloc() failed */ 384#define SQLITE_READONLY 8 /* Attempt to write a readonly database */ 385#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ 386#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ 387#define SQLITE_CORRUPT 11 /* The database disk image is malformed */ 388#define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */ 389#define SQLITE_FULL 13 /* Insertion failed because database is full */ 390#define SQLITE_CANTOPEN 14 /* Unable to open the database file */ 391#define SQLITE_PROTOCOL 15 /* Database lock protocol error */ 392#define SQLITE_EMPTY 16 /* Database is empty */ 393#define SQLITE_SCHEMA 17 /* The database schema changed */ 394#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */ 395#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */ 396#define SQLITE_MISMATCH 20 /* Data type mismatch */ 397#define SQLITE_MISUSE 21 /* Library used incorrectly */ 398#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ 399#define SQLITE_AUTH 23 /* Authorization denied */ 400#define SQLITE_FORMAT 24 /* Auxiliary database format error */ 401#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ 402#define SQLITE_NOTADB 26 /* File opened that is not a database file */ 403#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ 404#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ 405/* end-of-error-codes */ 406 407/* 408** CAPI3REF: Extended Result Codes 409** KEYWORDS: {extended error code} {extended error codes} 410** KEYWORDS: {extended result code} {extended result codes} 411** 412** In its default configuration, SQLite API routines return one of 26 integer 413** [SQLITE_OK | result codes]. However, experience has shown that many of 414** these result codes are too coarse-grained. They do not provide as 415** much information about problems as programmers might like. In an effort to 416** address this, newer versions of SQLite (version 3.3.8 and later) include 417** support for additional result codes that provide more detailed information 418** about errors. The extended result codes are enabled or disabled 419** on a per database connection basis using the 420** [sqlite3_extended_result_codes()] API. 421** 422** Some of the available extended result codes are listed here. 423** One may expect the number of extended result codes will be expand 424** over time. Software that uses extended result codes should expect 425** to see new result codes in future releases of SQLite. 426** 427** The SQLITE_OK result code will never be extended. It will always 428** be exactly zero. 429*/ 430#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) 431#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) 432#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) 433#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) 434#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) 435#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) 436#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) 437#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) 438#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) 439#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) 440#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) 441#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) 442#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8)) 443#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8)) 444#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8)) 445#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8)) 446#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8)) 447#define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8)) 448#define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8)) 449#define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8)) 450#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8)) 451#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8)) 452#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<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 459** in the 4th parameter to the xOpen method of the 460** [sqlite3_vfs] object. 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 */ 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_WAL 0x00080000 /* VFS only */ 480 481/* 482** CAPI3REF: Device Characteristics 483** 484** The xDeviceCharacteristics method of the [sqlite3_io_methods] 485** object returns an integer which is a vector of the these 486** bit values expressing I/O characteristics of the mass storage 487** device that holds the file that the [sqlite3_io_methods] 488** refers to. 489** 490** The SQLITE_IOCAP_ATOMIC property means that all writes of 491** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values 492** mean that writes of blocks that are nnn bytes in size and 493** are aligned to an address which is an integer multiple of 494** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means 495** that when data is appended to a file, the data is appended 496** first then the size of the file is extended, never the other 497** way around. The SQLITE_IOCAP_SEQUENTIAL property means that 498** information is written to disk in the same order as calls 499** to xWrite(). 500*/ 501#define SQLITE_IOCAP_ATOMIC 0x00000001 502#define SQLITE_IOCAP_ATOMIC512 0x00000002 503#define SQLITE_IOCAP_ATOMIC1K 0x00000004 504#define SQLITE_IOCAP_ATOMIC2K 0x00000008 505#define SQLITE_IOCAP_ATOMIC4K 0x00000010 506#define SQLITE_IOCAP_ATOMIC8K 0x00000020 507#define SQLITE_IOCAP_ATOMIC16K 0x00000040 508#define SQLITE_IOCAP_ATOMIC32K 0x00000080 509#define SQLITE_IOCAP_ATOMIC64K 0x00000100 510#define SQLITE_IOCAP_SAFE_APPEND 0x00000200 511#define SQLITE_IOCAP_SEQUENTIAL 0x00000400 512#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800 513 514/* 515** CAPI3REF: File Locking Levels 516** 517** SQLite uses one of these integer values as the second 518** argument to calls it makes to the xLock() and xUnlock() methods 519** of an [sqlite3_io_methods] object. 520*/ 521#define SQLITE_LOCK_NONE 0 522#define SQLITE_LOCK_SHARED 1 523#define SQLITE_LOCK_RESERVED 2 524#define SQLITE_LOCK_PENDING 3 525#define SQLITE_LOCK_EXCLUSIVE 4 526 527/* 528** CAPI3REF: Synchronization Type Flags 529** 530** When SQLite invokes the xSync() method of an 531** [sqlite3_io_methods] object it uses a combination of 532** these integer values as the second argument. 533** 534** When the SQLITE_SYNC_DATAONLY flag is used, it means that the 535** sync operation only needs to flush data to mass storage. Inode 536** information need not be flushed. If the lower four bits of the flag 537** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics. 538** If the lower four bits equal SQLITE_SYNC_FULL, that means 539** to use Mac OS X style fullsync instead of fsync(). 540*/ 541#define SQLITE_SYNC_NORMAL 0x00002 542#define SQLITE_SYNC_FULL 0x00003 543#define SQLITE_SYNC_DATAONLY 0x00010 544 545/* 546** CAPI3REF: OS Interface Open File Handle 547** 548** An [sqlite3_file] object represents an open file in the 549** [sqlite3_vfs | OS interface layer]. Individual OS interface 550** implementations will 551** want to subclass this object by appending additional fields 552** for their own use. The pMethods entry is a pointer to an 553** [sqlite3_io_methods] object that defines methods for performing 554** I/O operations on the open file. 555*/ 556typedef struct sqlite3_file sqlite3_file; 557struct sqlite3_file { 558 const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ 559}; 560 561/* 562** CAPI3REF: OS Interface File Virtual Methods Object 563** 564** Every file opened by the [sqlite3_vfs] xOpen method populates an 565** [sqlite3_file] object (or, more commonly, a subclass of the 566** [sqlite3_file] object) with a pointer to an instance of this object. 567** This object defines the methods used to perform various operations 568** against the open file represented by the [sqlite3_file] object. 569** 570** If the xOpen method sets the sqlite3_file.pMethods element 571** to a non-NULL pointer, then the sqlite3_io_methods.xClose method 572** may be invoked even if the xOpen reported that it failed. The 573** only way to prevent a call to xClose following a failed xOpen 574** is for the xOpen to set the sqlite3_file.pMethods element to NULL. 575** 576** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or 577** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). 578** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY] 579** flag may be ORed in to indicate that only the data of the file 580** and not its inode needs to be synced. 581** 582** The integer values to xLock() and xUnlock() are one of 583** <ul> 584** <li> [SQLITE_LOCK_NONE], 585** <li> [SQLITE_LOCK_SHARED], 586** <li> [SQLITE_LOCK_RESERVED], 587** <li> [SQLITE_LOCK_PENDING], or 588** <li> [SQLITE_LOCK_EXCLUSIVE]. 589** </ul> 590** xLock() increases the lock. xUnlock() decreases the lock. 591** The xCheckReservedLock() method checks whether any database connection, 592** either in this process or in some other process, is holding a RESERVED, 593** PENDING, or EXCLUSIVE lock on the file. It returns true 594** if such a lock exists and false otherwise. 595** 596** The xFileControl() method is a generic interface that allows custom 597** VFS implementations to directly control an open file using the 598** [sqlite3_file_control()] interface. The second "op" argument is an 599** integer opcode. The third argument is a generic pointer intended to 600** point to a structure that may contain arguments or space in which to 601** write return values. Potential uses for xFileControl() might be 602** functions to enable blocking locks with timeouts, to change the 603** locking strategy (for example to use dot-file locks), to inquire 604** about the status of a lock, or to break stale locks. The SQLite 605** core reserves all opcodes less than 100 for its own use. 606** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. 607** Applications that define a custom xFileControl method should use opcodes 608** greater than 100 to avoid conflicts. 609** 610** The xSectorSize() method returns the sector size of the 611** device that underlies the file. The sector size is the 612** minimum write that can be performed without disturbing 613** other bytes in the file. The xDeviceCharacteristics() 614** method returns a bit vector describing behaviors of the 615** underlying device: 616** 617** <ul> 618** <li> [SQLITE_IOCAP_ATOMIC] 619** <li> [SQLITE_IOCAP_ATOMIC512] 620** <li> [SQLITE_IOCAP_ATOMIC1K] 621** <li> [SQLITE_IOCAP_ATOMIC2K] 622** <li> [SQLITE_IOCAP_ATOMIC4K] 623** <li> [SQLITE_IOCAP_ATOMIC8K] 624** <li> [SQLITE_IOCAP_ATOMIC16K] 625** <li> [SQLITE_IOCAP_ATOMIC32K] 626** <li> [SQLITE_IOCAP_ATOMIC64K] 627** <li> [SQLITE_IOCAP_SAFE_APPEND] 628** <li> [SQLITE_IOCAP_SEQUENTIAL] 629** </ul> 630** 631** The SQLITE_IOCAP_ATOMIC property means that all writes of 632** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values 633** mean that writes of blocks that are nnn bytes in size and 634** are aligned to an address which is an integer multiple of 635** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means 636** that when data is appended to a file, the data is appended 637** first then the size of the file is extended, never the other 638** way around. The SQLITE_IOCAP_SEQUENTIAL property means that 639** information is written to disk in the same order as calls 640** to xWrite(). 641** 642** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill 643** in the unread portions of the buffer with zeros. A VFS that 644** fails to zero-fill short reads might seem to work. However, 645** failure to zero-fill short reads will eventually lead to 646** database corruption. 647*/ 648typedef struct sqlite3_io_methods sqlite3_io_methods; 649struct sqlite3_io_methods { 650 int iVersion; 651 int (*xClose)(sqlite3_file*); 652 int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst); 653 int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst); 654 int (*xTruncate)(sqlite3_file*, sqlite3_int64 size); 655 int (*xSync)(sqlite3_file*, int flags); 656 int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); 657 int (*xLock)(sqlite3_file*, int); 658 int (*xUnlock)(sqlite3_file*, int); 659 int (*xCheckReservedLock)(sqlite3_file*, int *pResOut); 660 int (*xFileControl)(sqlite3_file*, int op, void *pArg); 661 int (*xSectorSize)(sqlite3_file*); 662 int (*xDeviceCharacteristics)(sqlite3_file*); 663 /* Methods above are valid for version 1 */ 664 int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**); 665 int (*xShmLock)(sqlite3_file*, int offset, int n, int flags); 666 void (*xShmBarrier)(sqlite3_file*); 667 int (*xShmUnmap)(sqlite3_file*, int deleteFlag); 668 /* Methods above are valid for version 2 */ 669 /* Additional methods may be added in future releases */ 670}; 671 672/* 673** CAPI3REF: Standard File Control Opcodes 674** 675** These integer constants are opcodes for the xFileControl method 676** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()] 677** interface. 678** 679** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This 680** opcode causes the xFileControl method to write the current state of 681** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED], 682** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE]) 683** into an integer that the pArg argument points to. This capability 684** is used during testing and only needs to be supported when SQLITE_TEST 685** is defined. 686** 687** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS 688** layer a hint of how large the database file will grow to be during the 689** current transaction. This hint is not guaranteed to be accurate but it 690** is often close. The underlying VFS might choose to preallocate database 691** file space based on this hint in order to help writes to the database 692** file run faster. 693** 694** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS 695** extends and truncates the database file in chunks of a size specified 696** by the user. The fourth argument to [sqlite3_file_control()] should 697** point to an integer (type int) containing the new chunk-size to use 698** for the nominated database. Allocating database file space in large 699** chunks (say 1MB at a time), may reduce file-system fragmentation and 700** improve performance on some systems. 701*/ 702#define SQLITE_FCNTL_LOCKSTATE 1 703#define SQLITE_GET_LOCKPROXYFILE 2 704#define SQLITE_SET_LOCKPROXYFILE 3 705#define SQLITE_LAST_ERRNO 4 706#define SQLITE_FCNTL_SIZE_HINT 5 707#define SQLITE_FCNTL_CHUNK_SIZE 6 708 709/* 710** CAPI3REF: Mutex Handle 711** 712** The mutex module within SQLite defines [sqlite3_mutex] to be an 713** abstract type for a mutex object. The SQLite core never looks 714** at the internal representation of an [sqlite3_mutex]. It only 715** deals with pointers to the [sqlite3_mutex] object. 716** 717** Mutexes are created using [sqlite3_mutex_alloc()]. 718*/ 719typedef struct sqlite3_mutex sqlite3_mutex; 720 721/* 722** CAPI3REF: OS Interface Object 723** 724** An instance of the sqlite3_vfs object defines the interface between 725** the SQLite core and the underlying operating system. The "vfs" 726** in the name of the object stands for "virtual file system". 727** 728** The value of the iVersion field is initially 1 but may be larger in 729** future versions of SQLite. Additional fields may be appended to this 730** object when the iVersion value is increased. Note that the structure 731** of the sqlite3_vfs object changes in the transaction between 732** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not 733** modified. 734** 735** The szOsFile field is the size of the subclassed [sqlite3_file] 736** structure used by this VFS. mxPathname is the maximum length of 737** a pathname in this VFS. 738** 739** Registered sqlite3_vfs objects are kept on a linked list formed by 740** the pNext pointer. The [sqlite3_vfs_register()] 741** and [sqlite3_vfs_unregister()] interfaces manage this list 742** in a thread-safe way. The [sqlite3_vfs_find()] interface 743** searches the list. Neither the application code nor the VFS 744** implementation should use the pNext pointer. 745** 746** The pNext field is the only field in the sqlite3_vfs 747** structure that SQLite will ever modify. SQLite will only access 748** or modify this field while holding a particular static mutex. 749** The application should never modify anything within the sqlite3_vfs 750** object once the object has been registered. 751** 752** The zName field holds the name of the VFS module. The name must 753** be unique across all VFS modules. 754** 755** ^SQLite guarantees that the zFilename parameter to xOpen 756** is either a NULL pointer or string obtained 757** from xFullPathname() with an optional suffix added. 758** ^If a suffix is added to the zFilename parameter, it will 759** consist of a single "-" character followed by no more than 760** 10 alphanumeric and/or "-" characters. 761** ^SQLite further guarantees that 762** the string will be valid and unchanged until xClose() is 763** called. Because of the previous sentence, 764** the [sqlite3_file] can safely store a pointer to the 765** filename if it needs to remember the filename for some reason. 766** If the zFilename parameter to xOpen is a NULL pointer then xOpen 767** must invent its own temporary name for the file. ^Whenever the 768** xFilename parameter is NULL it will also be the case that the 769** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE]. 770** 771** The flags argument to xOpen() includes all bits set in 772** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()] 773** or [sqlite3_open16()] is used, then flags includes at least 774** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. 775** If xOpen() opens a file read-only then it sets *pOutFlags to 776** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set. 777** 778** ^(SQLite will also add one of the following flags to the xOpen() 779** call, depending on the object being opened: 780** 781** <ul> 782** <li> [SQLITE_OPEN_MAIN_DB] 783** <li> [SQLITE_OPEN_MAIN_JOURNAL] 784** <li> [SQLITE_OPEN_TEMP_DB] 785** <li> [SQLITE_OPEN_TEMP_JOURNAL] 786** <li> [SQLITE_OPEN_TRANSIENT_DB] 787** <li> [SQLITE_OPEN_SUBJOURNAL] 788** <li> [SQLITE_OPEN_MASTER_JOURNAL] 789** <li> [SQLITE_OPEN_WAL] 790** </ul>)^ 791** 792** The file I/O implementation can use the object type flags to 793** change the way it deals with files. For example, an application 794** that does not care about crash recovery or rollback might make 795** the open of a journal file a no-op. Writes to this journal would 796** also be no-ops, and any attempt to read the journal would return 797** SQLITE_IOERR. Or the implementation might recognize that a database 798** file will be doing page-aligned sector reads and writes in a random 799** order and set up its I/O subsystem accordingly. 800** 801** SQLite might also add one of the following flags to the xOpen method: 802** 803** <ul> 804** <li> [SQLITE_OPEN_DELETEONCLOSE] 805** <li> [SQLITE_OPEN_EXCLUSIVE] 806** </ul> 807** 808** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be 809** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE] 810** will be set for TEMP databases and their journals, transient 811** databases, and subjournals. 812** 813** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction 814** with the [SQLITE_OPEN_CREATE] flag, which are both directly 815** analogous to the O_EXCL and O_CREAT flags of the POSIX open() 816** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the 817** SQLITE_OPEN_CREATE, is used to indicate that file should always 818** be created, and that it is an error if it already exists. 819** It is <i>not</i> used to indicate the file should be opened 820** for exclusive access. 821** 822** ^At least szOsFile bytes of memory are allocated by SQLite 823** to hold the [sqlite3_file] structure passed as the third 824** argument to xOpen. The xOpen method does not have to 825** allocate the structure; it should just fill it in. Note that 826** the xOpen method must set the sqlite3_file.pMethods to either 827** a valid [sqlite3_io_methods] object or to NULL. xOpen must do 828** this even if the open fails. SQLite expects that the sqlite3_file.pMethods 829** element will be valid after xOpen returns regardless of the success 830** or failure of the xOpen call. 831** 832** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] 833** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to 834** test whether a file is readable and writable, or [SQLITE_ACCESS_READ] 835** to test whether a file is at least readable. The file can be a 836** directory. 837** 838** ^SQLite will always allocate at least mxPathname+1 bytes for the 839** output buffer xFullPathname. The exact size of the output buffer 840** is also passed as a parameter to both methods. If the output buffer 841** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is 842** handled as a fatal error by SQLite, vfs implementations should endeavor 843** to prevent this by setting mxPathname to a sufficiently large value. 844** 845** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64() 846** interfaces are not strictly a part of the filesystem, but they are 847** included in the VFS structure for completeness. 848** The xRandomness() function attempts to return nBytes bytes 849** of good-quality randomness into zOut. The return value is 850** the actual number of bytes of randomness obtained. 851** The xSleep() method causes the calling thread to sleep for at 852** least the number of microseconds given. ^The xCurrentTime() 853** method returns a Julian Day Number for the current date and time as 854** a floating point value. 855** ^The xCurrentTimeInt64() method returns, as an integer, the Julian 856** Day Number multipled by 86400000 (the number of milliseconds in 857** a 24-hour day). 858** ^SQLite will use the xCurrentTimeInt64() method to get the current 859** date and time if that method is available (if iVersion is 2 or 860** greater and the function pointer is not NULL) and will fall back 861** to xCurrentTime() if xCurrentTimeInt64() is unavailable. 862*/ 863typedef struct sqlite3_vfs sqlite3_vfs; 864struct sqlite3_vfs { 865 int iVersion; /* Structure version number (currently 2) */ 866 int szOsFile; /* Size of subclassed sqlite3_file */ 867 int mxPathname; /* Maximum file pathname length */ 868 sqlite3_vfs *pNext; /* Next registered VFS */ 869 const char *zName; /* Name of this virtual file system */ 870 void *pAppData; /* Pointer to application-specific data */ 871 int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*, 872 int flags, int *pOutFlags); 873 int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir); 874 int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut); 875 int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut); 876 void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); 877 void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); 878 void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void); 879 void (*xDlClose)(sqlite3_vfs*, void*); 880 int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); 881 int (*xSleep)(sqlite3_vfs*, int microseconds); 882 int (*xCurrentTime)(sqlite3_vfs*, double*); 883 int (*xGetLastError)(sqlite3_vfs*, int, char *); 884 /* 885 ** The methods above are in version 1 of the sqlite_vfs object 886 ** definition. Those that follow are added in version 2 or later 887 */ 888 int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*); 889 /* 890 ** The methods above are in versions 1 and 2 of the sqlite_vfs object. 891 ** New fields may be appended in figure versions. The iVersion 892 ** value will increment whenever this happens. 893 */ 894}; 895 896/* 897** CAPI3REF: Flags for the xAccess VFS method 898** 899** These integer constants can be used as the third parameter to 900** the xAccess method of an [sqlite3_vfs] object. They determine 901** what kind of permissions the xAccess method is looking for. 902** With SQLITE_ACCESS_EXISTS, the xAccess method 903** simply checks whether the file exists. 904** With SQLITE_ACCESS_READWRITE, the xAccess method 905** checks whether the named directory is both readable and writable 906** (in other words, if files can be added, removed, and renamed within 907** the directory). 908** The SQLITE_ACCESS_READWRITE constant is currently used only by the 909** [temp_store_directory pragma], though this could change in a future 910** release of SQLite. 911** With SQLITE_ACCESS_READ, the xAccess method 912** checks whether the file is readable. The SQLITE_ACCESS_READ constant is 913** currently unused, though it might be used in a future release of 914** SQLite. 915*/ 916#define SQLITE_ACCESS_EXISTS 0 917#define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */ 918#define SQLITE_ACCESS_READ 2 /* Unused */ 919 920/* 921** CAPI3REF: Flags for the xShmLock VFS method 922** 923** These integer constants define the various locking operations 924** allowed by the xShmLock method of [sqlite3_io_methods]. The 925** following are the only legal combinations of flags to the 926** xShmLock method: 927** 928** <ul> 929** <li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED 930** <li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE 931** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED 932** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE 933** </ul> 934** 935** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as 936** was given no the corresponding lock. 937** 938** The xShmLock method can transition between unlocked and SHARED or 939** between unlocked and EXCLUSIVE. It cannot transition between SHARED 940** and EXCLUSIVE. 941*/ 942#define SQLITE_SHM_UNLOCK 1 943#define SQLITE_SHM_LOCK 2 944#define SQLITE_SHM_SHARED 4 945#define SQLITE_SHM_EXCLUSIVE 8 946 947/* 948** CAPI3REF: Maximum xShmLock index 949** 950** The xShmLock method on [sqlite3_io_methods] may use values 951** between 0 and this upper bound as its "offset" argument. 952** The SQLite core will never attempt to acquire or release a 953** lock outside of this range 954*/ 955#define SQLITE_SHM_NLOCK 8 956 957 958/* 959** CAPI3REF: Initialize The SQLite Library 960** 961** ^The sqlite3_initialize() routine initializes the 962** SQLite library. ^The sqlite3_shutdown() routine 963** deallocates any resources that were allocated by sqlite3_initialize(). 964** These routines are designed to aid in process initialization and 965** shutdown on embedded systems. Workstation applications using 966** SQLite normally do not need to invoke either of these routines. 967** 968** A call to sqlite3_initialize() is an "effective" call if it is 969** the first time sqlite3_initialize() is invoked during the lifetime of 970** the process, or if it is the first time sqlite3_initialize() is invoked 971** following a call to sqlite3_shutdown(). ^(Only an effective call 972** of sqlite3_initialize() does any initialization. All other calls 973** are harmless no-ops.)^ 974** 975** A call to sqlite3_shutdown() is an "effective" call if it is the first 976** call to sqlite3_shutdown() since the last sqlite3_initialize(). ^(Only 977** an effective call to sqlite3_shutdown() does any deinitialization. 978** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^ 979** 980** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown() 981** is not. The sqlite3_shutdown() interface must only be called from a 982** single thread. All open [database connections] must be closed and all 983** other SQLite resources must be deallocated prior to invoking 984** sqlite3_shutdown(). 985** 986** Among other things, ^sqlite3_initialize() will invoke 987** sqlite3_os_init(). Similarly, ^sqlite3_shutdown() 988** will invoke sqlite3_os_end(). 989** 990** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success. 991** ^If for some reason, sqlite3_initialize() is unable to initialize 992** the library (perhaps it is unable to allocate a needed resource such 993** as a mutex) it returns an [error code] other than [SQLITE_OK]. 994** 995** ^The sqlite3_initialize() routine is called internally by many other 996** SQLite interfaces so that an application usually does not need to 997** invoke sqlite3_initialize() directly. For example, [sqlite3_open()] 998** calls sqlite3_initialize() so the SQLite library will be automatically 999** initialized when [sqlite3_open()] is called if it has not be initialized 1000** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT] 1001** compile-time option, then the automatic calls to sqlite3_initialize() 1002** are omitted and the application must call sqlite3_initialize() directly 1003** prior to using any other SQLite interface. For maximum portability, 1004** it is recommended that applications always invoke sqlite3_initialize() 1005** directly prior to using any other SQLite interface. Future releases 1006** of SQLite may require this. In other words, the behavior exhibited 1007** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the 1008** default behavior in some future release of SQLite. 1009** 1010** The sqlite3_os_init() routine does operating-system specific 1011** initialization of the SQLite library. The sqlite3_os_end() 1012** routine undoes the effect of sqlite3_os_init(). Typical tasks 1013** performed by these routines include allocation or deallocation 1014** of static resources, initialization of global variables, 1015** setting up a default [sqlite3_vfs] module, or setting up 1016** a default configuration using [sqlite3_config()]. 1017** 1018** The application should never invoke either sqlite3_os_init() 1019** or sqlite3_os_end() directly. The application should only invoke 1020** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init() 1021** interface is called automatically by sqlite3_initialize() and 1022** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate 1023** implementations for sqlite3_os_init() and sqlite3_os_end() 1024** are built into SQLite when it is compiled for Unix, Windows, or OS/2. 1025** When [custom builds | built for other platforms] 1026** (using the [SQLITE_OS_OTHER=1] compile-time 1027** option) the application must supply a suitable implementation for 1028** sqlite3_os_init() and sqlite3_os_end(). An application-supplied 1029** implementation of sqlite3_os_init() or sqlite3_os_end() 1030** must return [SQLITE_OK] on success and some other [error code] upon 1031** failure. 1032*/ 1033int sqlite3_initialize(void); 1034int sqlite3_shutdown(void); 1035int sqlite3_os_init(void); 1036int sqlite3_os_end(void); 1037 1038/* 1039** CAPI3REF: Configuring The SQLite Library 1040** 1041** The sqlite3_config() interface is used to make global configuration 1042** changes to SQLite in order to tune SQLite to the specific needs of 1043** the application. The default configuration is recommended for most 1044** applications and so this routine is usually not necessary. It is 1045** provided to support rare applications with unusual needs. 1046** 1047** The sqlite3_config() interface is not threadsafe. The application 1048** must insure that no other SQLite interfaces are invoked by other 1049** threads while sqlite3_config() is running. Furthermore, sqlite3_config() 1050** may only be invoked prior to library initialization using 1051** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()]. 1052** ^If sqlite3_config() is called after [sqlite3_initialize()] and before 1053** [sqlite3_shutdown()] then it will return SQLITE_MISUSE. 1054** Note, however, that ^sqlite3_config() can be called as part of the 1055** implementation of an application-defined [sqlite3_os_init()]. 1056** 1057** The first argument to sqlite3_config() is an integer 1058** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines 1059** what property of SQLite is to be configured. Subsequent arguments 1060** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option] 1061** in the first argument. 1062** 1063** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK]. 1064** ^If the option is unknown or SQLite is unable to set the option 1065** then this routine returns a non-zero [error code]. 1066*/ 1067int sqlite3_config(int, ...); 1068 1069/* 1070** CAPI3REF: Configure database connections 1071** 1072** The sqlite3_db_config() interface is used to make configuration 1073** changes to a [database connection]. The interface is similar to 1074** [sqlite3_config()] except that the changes apply to a single 1075** [database connection] (specified in the first argument). The 1076** sqlite3_db_config() interface should only be used immediately after 1077** the database connection is created using [sqlite3_open()], 1078** [sqlite3_open16()], or [sqlite3_open_v2()]. 1079** 1080** The second argument to sqlite3_db_config(D,V,...) is the 1081** configuration verb - an integer code that indicates what 1082** aspect of the [database connection] is being configured. 1083** The only choice for this value is [SQLITE_DBCONFIG_LOOKASIDE]. 1084** New verbs are likely to be added in future releases of SQLite. 1085** Additional arguments depend on the verb. 1086** 1087** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if 1088** the call is considered successful. 1089*/ 1090int sqlite3_db_config(sqlite3*, int op, ...); 1091 1092/* 1093** CAPI3REF: Memory Allocation Routines 1094** 1095** An instance of this object defines the interface between SQLite 1096** and low-level memory allocation routines. 1097** 1098** This object is used in only one place in the SQLite interface. 1099** A pointer to an instance of this object is the argument to 1100** [sqlite3_config()] when the configuration option is 1101** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC]. 1102** By creating an instance of this object 1103** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC]) 1104** during configuration, an application can specify an alternative 1105** memory allocation subsystem for SQLite to use for all of its 1106** dynamic memory needs. 1107** 1108** Note that SQLite comes with several [built-in memory allocators] 1109** that are perfectly adequate for the overwhelming majority of applications 1110** and that this object is only useful to a tiny minority of applications 1111** with specialized memory allocation requirements. This object is 1112** also used during testing of SQLite in order to specify an alternative 1113** memory allocator that simulates memory out-of-memory conditions in 1114** order to verify that SQLite recovers gracefully from such 1115** conditions. 1116** 1117** The xMalloc and xFree methods must work like the 1118** malloc() and free() functions from the standard C library. 1119** The xRealloc method must work like realloc() from the standard C library 1120** with the exception that if the second argument to xRealloc is zero, 1121** xRealloc must be a no-op - it must not perform any allocation or 1122** deallocation. ^SQLite guarantees that the second argument to 1123** xRealloc is always a value returned by a prior call to xRoundup. 1124** And so in cases where xRoundup always returns a positive number, 1125** xRealloc can perform exactly as the standard library realloc() and 1126** still be in compliance with this specification. 1127** 1128** xSize should return the allocated size of a memory allocation 1129** previously obtained from xMalloc or xRealloc. The allocated size 1130** is always at least as big as the requested size but may be larger. 1131** 1132** The xRoundup method returns what would be the allocated size of 1133** a memory allocation given a particular requested size. Most memory 1134** allocators round up memory allocations at least to the next multiple 1135** of 8. Some allocators round up to a larger multiple or to a power of 2. 1136** Every memory allocation request coming in through [sqlite3_malloc()] 1137** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0, 1138** that causes the corresponding memory allocation to fail. 1139** 1140** The xInit method initializes the memory allocator. (For example, 1141** it might allocate any require mutexes or initialize internal data 1142** structures. The xShutdown method is invoked (indirectly) by 1143** [sqlite3_shutdown()] and should deallocate any resources acquired 1144** by xInit. The pAppData pointer is used as the only parameter to 1145** xInit and xShutdown. 1146** 1147** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes 1148** the xInit method, so the xInit method need not be threadsafe. The 1149** xShutdown method is only called from [sqlite3_shutdown()] so it does 1150** not need to be threadsafe either. For all other methods, SQLite 1151** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the 1152** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which 1153** it is by default) and so the methods are automatically serialized. 1154** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other 1155** methods must be threadsafe or else make their own arrangements for 1156** serialization. 1157** 1158** SQLite will never invoke xInit() more than once without an intervening 1159** call to xShutdown(). 1160*/ 1161typedef struct sqlite3_mem_methods sqlite3_mem_methods; 1162struct sqlite3_mem_methods { 1163 void *(*xMalloc)(int); /* Memory allocation function */ 1164 void (*xFree)(void*); /* Free a prior allocation */ 1165 void *(*xRealloc)(void*,int); /* Resize an allocation */ 1166 int (*xSize)(void*); /* Return the size of an allocation */ 1167 int (*xRoundup)(int); /* Round up request size to allocation size */ 1168 int (*xInit)(void*); /* Initialize the memory allocator */ 1169 void (*xShutdown)(void*); /* Deinitialize the memory allocator */ 1170 void *pAppData; /* Argument to xInit() and xShutdown() */ 1171}; 1172 1173/* 1174** CAPI3REF: Configuration Options 1175** 1176** These constants are the available integer configuration options that 1177** can be passed as the first argument to the [sqlite3_config()] interface. 1178** 1179** New configuration options may be added in future releases of SQLite. 1180** Existing configuration options might be discontinued. Applications 1181** should check the return code from [sqlite3_config()] to make sure that 1182** the call worked. The [sqlite3_config()] interface will return a 1183** non-zero [error code] if a discontinued or unsupported configuration option 1184** is invoked. 1185** 1186** <dl> 1187** <dt>SQLITE_CONFIG_SINGLETHREAD</dt> 1188** <dd>There are no arguments to this option. ^This option sets the 1189** [threading mode] to Single-thread. In other words, it disables 1190** all mutexing and puts SQLite into a mode where it can only be used 1191** by a single thread. ^If SQLite is compiled with 1192** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1193** it is not possible to change the [threading mode] from its default 1194** value of Single-thread and so [sqlite3_config()] will return 1195** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD 1196** configuration option.</dd> 1197** 1198** <dt>SQLITE_CONFIG_MULTITHREAD</dt> 1199** <dd>There are no arguments to this option. ^This option sets the 1200** [threading mode] to Multi-thread. In other words, it disables 1201** mutexing on [database connection] and [prepared statement] objects. 1202** The application is responsible for serializing access to 1203** [database connections] and [prepared statements]. But other mutexes 1204** are enabled so that SQLite will be safe to use in a multi-threaded 1205** environment as long as no two threads attempt to use the same 1206** [database connection] at the same time. ^If SQLite is compiled with 1207** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1208** it is not possible to set the Multi-thread [threading mode] and 1209** [sqlite3_config()] will return [SQLITE_ERROR] if called with the 1210** SQLITE_CONFIG_MULTITHREAD configuration option.</dd> 1211** 1212** <dt>SQLITE_CONFIG_SERIALIZED</dt> 1213** <dd>There are no arguments to this option. ^This option sets the 1214** [threading mode] to Serialized. In other words, this option enables 1215** all mutexes including the recursive 1216** mutexes on [database connection] and [prepared statement] objects. 1217** In this mode (which is the default when SQLite is compiled with 1218** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access 1219** to [database connections] and [prepared statements] so that the 1220** application is free to use the same [database connection] or the 1221** same [prepared statement] in different threads at the same time. 1222** ^If SQLite is compiled with 1223** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1224** it is not possible to set the Serialized [threading mode] and 1225** [sqlite3_config()] will return [SQLITE_ERROR] if called with the 1226** SQLITE_CONFIG_SERIALIZED configuration option.</dd> 1227** 1228** <dt>SQLITE_CONFIG_MALLOC</dt> 1229** <dd> ^(This option takes a single argument which is a pointer to an 1230** instance of the [sqlite3_mem_methods] structure. The argument specifies 1231** alternative low-level memory allocation routines to be used in place of 1232** the memory allocation routines built into SQLite.)^ ^SQLite makes 1233** its own private copy of the content of the [sqlite3_mem_methods] structure 1234** before the [sqlite3_config()] call returns.</dd> 1235** 1236** <dt>SQLITE_CONFIG_GETMALLOC</dt> 1237** <dd> ^(This option takes a single argument which is a pointer to an 1238** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods] 1239** structure is filled with the currently defined memory allocation routines.)^ 1240** This option can be used to overload the default memory allocation 1241** routines with a wrapper that simulations memory allocation failure or 1242** tracks memory usage, for example. </dd> 1243** 1244** <dt>SQLITE_CONFIG_MEMSTATUS</dt> 1245** <dd> ^This option takes single argument of type int, interpreted as a 1246** boolean, which enables or disables the collection of memory allocation 1247** statistics. ^(When memory allocation statistics are disabled, the 1248** following SQLite interfaces become non-operational: 1249** <ul> 1250** <li> [sqlite3_memory_used()] 1251** <li> [sqlite3_memory_highwater()] 1252** <li> [sqlite3_soft_heap_limit64()] 1253** <li> [sqlite3_status()] 1254** </ul>)^ 1255** ^Memory allocation statistics are enabled by default unless SQLite is 1256** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory 1257** allocation statistics are disabled by default. 1258** </dd> 1259** 1260** <dt>SQLITE_CONFIG_SCRATCH</dt> 1261** <dd> ^This option specifies a static memory buffer that SQLite can use for 1262** scratch memory. There are three arguments: A pointer an 8-byte 1263** aligned memory buffer from which the scrach allocations will be 1264** drawn, the size of each scratch allocation (sz), 1265** and the maximum number of scratch allocations (N). The sz 1266** argument must be a multiple of 16. 1267** The first argument must be a pointer to an 8-byte aligned buffer 1268** of at least sz*N bytes of memory. 1269** ^SQLite will use no more than two scratch buffers per thread. So 1270** N should be set to twice the expected maximum number of threads. 1271** ^SQLite will never require a scratch buffer that is more than 6 1272** times the database page size. ^If SQLite needs needs additional 1273** scratch memory beyond what is provided by this configuration option, then 1274** [sqlite3_malloc()] will be used to obtain the memory needed.</dd> 1275** 1276** <dt>SQLITE_CONFIG_PAGECACHE</dt> 1277** <dd> ^This option specifies a static memory buffer that SQLite can use for 1278** the database page cache with the default page cache implemenation. 1279** This configuration should not be used if an application-define page 1280** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option. 1281** There are three arguments to this option: A pointer to 8-byte aligned 1282** memory, the size of each page buffer (sz), and the number of pages (N). 1283** The sz argument should be the size of the largest database page 1284** (a power of two between 512 and 32768) plus a little extra for each 1285** page header. ^The page header size is 20 to 40 bytes depending on 1286** the host architecture. ^It is harmless, apart from the wasted memory, 1287** to make sz a little too large. The first 1288** argument should point to an allocation of at least sz*N bytes of memory. 1289** ^SQLite will use the memory provided by the first argument to satisfy its 1290** memory needs for the first N pages that it adds to cache. ^If additional 1291** page cache memory is needed beyond what is provided by this option, then 1292** SQLite goes to [sqlite3_malloc()] for the additional storage space. 1293** The pointer in the first argument must 1294** be aligned to an 8-byte boundary or subsequent behavior of SQLite 1295** will be undefined.</dd> 1296** 1297** <dt>SQLITE_CONFIG_HEAP</dt> 1298** <dd> ^This option specifies a static memory buffer that SQLite will use 1299** for all of its dynamic memory allocation needs beyond those provided 1300** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE]. 1301** There are three arguments: An 8-byte aligned pointer to the memory, 1302** the number of bytes in the memory buffer, and the minimum allocation size. 1303** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts 1304** to using its default memory allocator (the system malloc() implementation), 1305** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the 1306** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or 1307** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory 1308** allocator is engaged to handle all of SQLites memory allocation needs. 1309** The first pointer (the memory pointer) must be aligned to an 8-byte 1310** boundary or subsequent behavior of SQLite will be undefined.</dd> 1311** 1312** <dt>SQLITE_CONFIG_MUTEX</dt> 1313** <dd> ^(This option takes a single argument which is a pointer to an 1314** instance of the [sqlite3_mutex_methods] structure. The argument specifies 1315** alternative low-level mutex routines to be used in place 1316** the mutex routines built into SQLite.)^ ^SQLite makes a copy of the 1317** content of the [sqlite3_mutex_methods] structure before the call to 1318** [sqlite3_config()] returns. ^If SQLite is compiled with 1319** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1320** the entire mutexing subsystem is omitted from the build and hence calls to 1321** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will 1322** return [SQLITE_ERROR].</dd> 1323** 1324** <dt>SQLITE_CONFIG_GETMUTEX</dt> 1325** <dd> ^(This option takes a single argument which is a pointer to an 1326** instance of the [sqlite3_mutex_methods] structure. The 1327** [sqlite3_mutex_methods] 1328** structure is filled with the currently defined mutex routines.)^ 1329** This option can be used to overload the default mutex allocation 1330** routines with a wrapper used to track mutex usage for performance 1331** profiling or testing, for example. ^If SQLite is compiled with 1332** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then 1333** the entire mutexing subsystem is omitted from the build and hence calls to 1334** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will 1335** return [SQLITE_ERROR].</dd> 1336** 1337** <dt>SQLITE_CONFIG_LOOKASIDE</dt> 1338** <dd> ^(This option takes two arguments that determine the default 1339** memory allocation for the lookaside memory allocator on each 1340** [database connection]. The first argument is the 1341** size of each lookaside buffer slot and the second is the number of 1342** slots allocated to each database connection.)^ ^(This option sets the 1343** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE] 1344** verb to [sqlite3_db_config()] can be used to change the lookaside 1345** configuration on individual connections.)^ </dd> 1346** 1347** <dt>SQLITE_CONFIG_PCACHE</dt> 1348** <dd> ^(This option takes a single argument which is a pointer to 1349** an [sqlite3_pcache_methods] object. This object specifies the interface 1350** to a custom page cache implementation.)^ ^SQLite makes a copy of the 1351** object and uses it for page cache memory allocations.</dd> 1352** 1353** <dt>SQLITE_CONFIG_GETPCACHE</dt> 1354** <dd> ^(This option takes a single argument which is a pointer to an 1355** [sqlite3_pcache_methods] object. SQLite copies of the current 1356** page cache implementation into that object.)^ </dd> 1357** 1358** <dt>SQLITE_CONFIG_LOG</dt> 1359** <dd> ^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a 1360** function with a call signature of void(*)(void*,int,const char*), 1361** and a pointer to void. ^If the function pointer is not NULL, it is 1362** invoked by [sqlite3_log()] to process each logging event. ^If the 1363** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op. 1364** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is 1365** passed through as the first parameter to the application-defined logger 1366** function whenever that function is invoked. ^The second parameter to 1367** the logger function is a copy of the first parameter to the corresponding 1368** [sqlite3_log()] call and is intended to be a [result code] or an 1369** [extended result code]. ^The third parameter passed to the logger is 1370** log message after formatting via [sqlite3_snprintf()]. 1371** The SQLite logging interface is not reentrant; the logger function 1372** supplied by the application must not invoke any SQLite interface. 1373** In a multi-threaded application, the application-defined logger 1374** function must be threadsafe. </dd> 1375** 1376** </dl> 1377*/ 1378#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ 1379#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ 1380#define SQLITE_CONFIG_SERIALIZED 3 /* nil */ 1381#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ 1382#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ 1383#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ 1384#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ 1385#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ 1386#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ 1387#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ 1388#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ 1389/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ 1390#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ 1391#define SQLITE_CONFIG_PCACHE 14 /* sqlite3_pcache_methods* */ 1392#define SQLITE_CONFIG_GETPCACHE 15 /* sqlite3_pcache_methods* */ 1393#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */ 1394 1395/* 1396** CAPI3REF: Database Connection Configuration Options 1397** 1398** These constants are the available integer configuration options that 1399** can be passed as the second argument to the [sqlite3_db_config()] interface. 1400** 1401** New configuration options may be added in future releases of SQLite. 1402** Existing configuration options might be discontinued. Applications 1403** should check the return code from [sqlite3_db_config()] to make sure that 1404** the call worked. ^The [sqlite3_db_config()] interface will return a 1405** non-zero [error code] if a discontinued or unsupported configuration option 1406** is invoked. 1407** 1408** <dl> 1409** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt> 1410** <dd> ^This option takes three additional arguments that determine the 1411** [lookaside memory allocator] configuration for the [database connection]. 1412** ^The first argument (the third parameter to [sqlite3_db_config()] is a 1413** pointer to an memory buffer to use for lookaside memory. 1414** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb 1415** may be NULL in which case SQLite will allocate the 1416** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the 1417** size of each lookaside buffer slot. ^The third argument is the number of 1418** slots. The size of the buffer in the first argument must be greater than 1419** or equal to the product of the second and third arguments. The buffer 1420** must be aligned to an 8-byte boundary. ^If the second argument to 1421** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally 1422** rounded down to the next smaller multiple of 8. ^(The lookaside memory 1423** configuration for a database connection can only be changed when that 1424** connection is not currently using lookaside memory, or in other words 1425** when the "current value" returned by 1426** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero. 1427** Any attempt to change the lookaside memory configuration when lookaside 1428** memory is in use leaves the configuration unchanged and returns 1429** [SQLITE_BUSY].)^</dd> 1430** 1431** </dl> 1432*/ 1433#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ 1434 1435 1436/* 1437** CAPI3REF: Enable Or Disable Extended Result Codes 1438** 1439** ^The sqlite3_extended_result_codes() routine enables or disables the 1440** [extended result codes] feature of SQLite. ^The extended result 1441** codes are disabled by default for historical compatibility. 1442*/ 1443int sqlite3_extended_result_codes(sqlite3*, int onoff); 1444 1445/* 1446** CAPI3REF: Last Insert Rowid 1447** 1448** ^Each entry in an SQLite table has a unique 64-bit signed 1449** integer key called the [ROWID | "rowid"]. ^The rowid is always available 1450** as an undeclared column named ROWID, OID, or _ROWID_ as long as those 1451** names are not also used by explicitly declared columns. ^If 1452** the table has a column of type [INTEGER PRIMARY KEY] then that column 1453** is another alias for the rowid. 1454** 1455** ^This routine returns the [rowid] of the most recent 1456** successful [INSERT] into the database from the [database connection] 1457** in the first argument. ^If no successful [INSERT]s 1458** have ever occurred on that database connection, zero is returned. 1459** 1460** ^(If an [INSERT] occurs within a trigger, then the [rowid] of the inserted 1461** row is returned by this routine as long as the trigger is running. 1462** But once the trigger terminates, the value returned by this routine 1463** reverts to the last value inserted before the trigger fired.)^ 1464** 1465** ^An [INSERT] that fails due to a constraint violation is not a 1466** successful [INSERT] and does not change the value returned by this 1467** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, 1468** and INSERT OR ABORT make no changes to the return value of this 1469** routine when their insertion fails. ^(When INSERT OR REPLACE 1470** encounters a constraint violation, it does not fail. The 1471** INSERT continues to completion after deleting rows that caused 1472** the constraint problem so INSERT OR REPLACE will always change 1473** the return value of this interface.)^ 1474** 1475** ^For the purposes of this routine, an [INSERT] is considered to 1476** be successful even if it is subsequently rolled back. 1477** 1478** This function is accessible to SQL statements via the 1479** [last_insert_rowid() SQL function]. 1480** 1481** If a separate thread performs a new [INSERT] on the same 1482** database connection while the [sqlite3_last_insert_rowid()] 1483** function is running and thus changes the last insert [rowid], 1484** then the value returned by [sqlite3_last_insert_rowid()] is 1485** unpredictable and might not equal either the old or the new 1486** last insert [rowid]. 1487*/ 1488sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); 1489 1490/* 1491** CAPI3REF: Count The Number Of Rows Modified 1492** 1493** ^This function returns the number of database rows that were changed 1494** or inserted or deleted by the most recently completed SQL statement 1495** on the [database connection] specified by the first parameter. 1496** ^(Only changes that are directly specified by the [INSERT], [UPDATE], 1497** or [DELETE] statement are counted. Auxiliary changes caused by 1498** triggers or [foreign key actions] are not counted.)^ Use the 1499** [sqlite3_total_changes()] function to find the total number of changes 1500** including changes caused by triggers and foreign key actions. 1501** 1502** ^Changes to a view that are simulated by an [INSTEAD OF trigger] 1503** are not counted. Only real table changes are counted. 1504** 1505** ^(A "row change" is a change to a single row of a single table 1506** caused by an INSERT, DELETE, or UPDATE statement. Rows that 1507** are changed as side effects of [REPLACE] constraint resolution, 1508** rollback, ABORT processing, [DROP TABLE], or by any other 1509** mechanisms do not count as direct row changes.)^ 1510** 1511** A "trigger context" is a scope of execution that begins and 1512** ends with the script of a [CREATE TRIGGER | trigger]. 1513** Most SQL statements are 1514** evaluated outside of any trigger. This is the "top level" 1515** trigger context. If a trigger fires from the top level, a 1516** new trigger context is entered for the duration of that one 1517** trigger. Subtriggers create subcontexts for their duration. 1518** 1519** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does 1520** not create a new trigger context. 1521** 1522** ^This function returns the number of direct row changes in the 1523** most recent INSERT, UPDATE, or DELETE statement within the same 1524** trigger context. 1525** 1526** ^Thus, when called from the top level, this function returns the 1527** number of changes in the most recent INSERT, UPDATE, or DELETE 1528** that also occurred at the top level. ^(Within the body of a trigger, 1529** the sqlite3_changes() interface can be called to find the number of 1530** changes in the most recently completed INSERT, UPDATE, or DELETE 1531** statement within the body of the same trigger. 1532** However, the number returned does not include changes 1533** caused by subtriggers since those have their own context.)^ 1534** 1535** See also the [sqlite3_total_changes()] interface, the 1536** [count_changes pragma], and the [changes() SQL function]. 1537** 1538** If a separate thread makes changes on the same database connection 1539** while [sqlite3_changes()] is running then the value returned 1540** is unpredictable and not meaningful. 1541*/ 1542int sqlite3_changes(sqlite3*); 1543 1544/* 1545** CAPI3REF: Total Number Of Rows Modified 1546** 1547** ^This function returns the number of row changes caused by [INSERT], 1548** [UPDATE] or [DELETE] statements since the [database connection] was opened. 1549** ^(The count returned by sqlite3_total_changes() includes all changes 1550** from all [CREATE TRIGGER | trigger] contexts and changes made by 1551** [foreign key actions]. However, 1552** the count does not include changes used to implement [REPLACE] constraints, 1553** do rollbacks or ABORT processing, or [DROP TABLE] processing. The 1554** count does not include rows of views that fire an [INSTEAD OF trigger], 1555** though if the INSTEAD OF trigger makes changes of its own, those changes 1556** are counted.)^ 1557** ^The sqlite3_total_changes() function counts the changes as soon as 1558** the statement that makes them is completed (when the statement handle 1559** is passed to [sqlite3_reset()] or [sqlite3_finalize()]). 1560** 1561** See also the [sqlite3_changes()] interface, the 1562** [count_changes pragma], and the [total_changes() SQL function]. 1563** 1564** If a separate thread makes changes on the same database connection 1565** while [sqlite3_total_changes()] is running then the value 1566** returned is unpredictable and not meaningful. 1567*/ 1568int sqlite3_total_changes(sqlite3*); 1569 1570/* 1571** CAPI3REF: Interrupt A Long-Running Query 1572** 1573** ^This function causes any pending database operation to abort and 1574** return at its earliest opportunity. This routine is typically 1575** called in response to a user action such as pressing "Cancel" 1576** or Ctrl-C where the user wants a long query operation to halt 1577** immediately. 1578** 1579** ^It is safe to call this routine from a thread different from the 1580** thread that is currently running the database operation. But it 1581** is not safe to call this routine with a [database connection] that 1582** is closed or might close before sqlite3_interrupt() returns. 1583** 1584** ^If an SQL operation is very nearly finished at the time when 1585** sqlite3_interrupt() is called, then it might not have an opportunity 1586** to be interrupted and might continue to completion. 1587** 1588** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT]. 1589** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE 1590** that is inside an explicit transaction, then the entire transaction 1591** will be rolled back automatically. 1592** 1593** ^The sqlite3_interrupt(D) call is in effect until all currently running 1594** SQL statements on [database connection] D complete. ^Any new SQL statements 1595** that are started after the sqlite3_interrupt() call and before the 1596** running statements reaches zero are interrupted as if they had been 1597** running prior to the sqlite3_interrupt() call. ^New SQL statements 1598** that are started after the running statement count reaches zero are 1599** not effected by the sqlite3_interrupt(). 1600** ^A call to sqlite3_interrupt(D) that occurs when there are no running 1601** SQL statements is a no-op and has no effect on SQL statements 1602** that are started after the sqlite3_interrupt() call returns. 1603** 1604** If the database connection closes while [sqlite3_interrupt()] 1605** is running then bad things will likely happen. 1606*/ 1607void sqlite3_interrupt(sqlite3*); 1608 1609/* 1610** CAPI3REF: Determine If An SQL Statement Is Complete 1611** 1612** These routines are useful during command-line input to determine if the 1613** currently entered text seems to form a complete SQL statement or 1614** if additional input is needed before sending the text into 1615** SQLite for parsing. ^These routines return 1 if the input string 1616** appears to be a complete SQL statement. ^A statement is judged to be 1617** complete if it ends with a semicolon token and is not a prefix of a 1618** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within 1619** string literals or quoted identifier names or comments are not 1620** independent tokens (they are part of the token in which they are 1621** embedded) and thus do not count as a statement terminator. ^Whitespace 1622** and comments that follow the final semicolon are ignored. 1623** 1624** ^These routines return 0 if the statement is incomplete. ^If a 1625** memory allocation fails, then SQLITE_NOMEM is returned. 1626** 1627** ^These routines do not parse the SQL statements thus 1628** will not detect syntactically incorrect SQL. 1629** 1630** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior 1631** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked 1632** automatically by sqlite3_complete16(). If that initialization fails, 1633** then the return value from sqlite3_complete16() will be non-zero 1634** regardless of whether or not the input SQL is complete.)^ 1635** 1636** The input to [sqlite3_complete()] must be a zero-terminated 1637** UTF-8 string. 1638** 1639** The input to [sqlite3_complete16()] must be a zero-terminated 1640** UTF-16 string in native byte order. 1641*/ 1642int sqlite3_complete(const char *sql); 1643int sqlite3_complete16(const void *sql); 1644 1645/* 1646** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors 1647** 1648** ^This routine sets a callback function that might be invoked whenever 1649** an attempt is made to open a database table that another thread 1650** or process has locked. 1651** 1652** ^If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] 1653** is returned immediately upon encountering the lock. ^If the busy callback 1654** is not NULL, then the callback might be invoked with two arguments. 1655** 1656** ^The first argument to the busy handler is a copy of the void* pointer which 1657** is the third argument to sqlite3_busy_handler(). ^The second argument to 1658** the busy handler callback is the number of times that the busy handler has 1659** been invoked for this locking event. ^If the 1660** busy callback returns 0, then no additional attempts are made to 1661** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. 1662** ^If the callback returns non-zero, then another attempt 1663** is made to open the database for reading and the cycle repeats. 1664** 1665** The presence of a busy handler does not guarantee that it will be invoked 1666** when there is lock contention. ^If SQLite determines that invoking the busy 1667** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY] 1668** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler. 1669** Consider a scenario where one process is holding a read lock that 1670** it is trying to promote to a reserved lock and 1671** a second process is holding a reserved lock that it is trying 1672** to promote to an exclusive lock. The first process cannot proceed 1673** because it is blocked by the second and the second process cannot 1674** proceed because it is blocked by the first. If both processes 1675** invoke the busy handlers, neither will make any progress. Therefore, 1676** SQLite returns [SQLITE_BUSY] for the first process, hoping that this 1677** will induce the first process to release its read lock and allow 1678** the second process to proceed. 1679** 1680** ^The default busy callback is NULL. 1681** 1682** ^The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] 1683** when SQLite is in the middle of a large transaction where all the 1684** changes will not fit into the in-memory cache. SQLite will 1685** already hold a RESERVED lock on the database file, but it needs 1686** to promote this lock to EXCLUSIVE so that it can spill cache 1687** pages into the database file without harm to concurrent 1688** readers. ^If it is unable to promote the lock, then the in-memory 1689** cache will be left in an inconsistent state and so the error 1690** code is promoted from the relatively benign [SQLITE_BUSY] to 1691** the more severe [SQLITE_IOERR_BLOCKED]. ^This error code promotion 1692** forces an automatic rollback of the changes. See the 1693** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError"> 1694** CorruptionFollowingBusyError</a> wiki page for a discussion of why 1695** this is important. 1696** 1697** ^(There can only be a single busy handler defined for each 1698** [database connection]. Setting a new busy handler clears any 1699** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()] 1700** will also set or clear the busy handler. 1701** 1702** The busy callback should not take any actions which modify the 1703** database connection that invoked the busy handler. Any such actions 1704** result in undefined behavior. 1705** 1706** A busy handler must not close the database connection 1707** or [prepared statement] that invoked the busy handler. 1708*/ 1709int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); 1710 1711/* 1712** CAPI3REF: Set A Busy Timeout 1713** 1714** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps 1715** for a specified amount of time when a table is locked. ^The handler 1716** will sleep multiple times until at least "ms" milliseconds of sleeping 1717** have accumulated. ^After at least "ms" milliseconds of sleeping, 1718** the handler returns 0 which causes [sqlite3_step()] to return 1719** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. 1720** 1721** ^Calling this routine with an argument less than or equal to zero 1722** turns off all busy handlers. 1723** 1724** ^(There can only be a single busy handler for a particular 1725** [database connection] any any given moment. If another busy handler 1726** was defined (using [sqlite3_busy_handler()]) prior to calling 1727** this routine, that other busy handler is cleared.)^ 1728*/ 1729int sqlite3_busy_timeout(sqlite3*, int ms); 1730 1731/* 1732** CAPI3REF: Convenience Routines For Running Queries 1733** 1734** This is a legacy interface that is preserved for backwards compatibility. 1735** Use of this interface is not recommended. 1736** 1737** Definition: A <b>result table</b> is memory data structure created by the 1738** [sqlite3_get_table()] interface. A result table records the 1739** complete query results from one or more queries. 1740** 1741** The table conceptually has a number of rows and columns. But 1742** these numbers are not part of the result table itself. These 1743** numbers are obtained separately. Let N be the number of rows 1744** and M be the number of columns. 1745** 1746** A result table is an array of pointers to zero-terminated UTF-8 strings. 1747** There are (N+1)*M elements in the array. The first M pointers point 1748** to zero-terminated strings that contain the names of the columns. 1749** The remaining entries all point to query results. NULL values result 1750** in NULL pointers. All other values are in their UTF-8 zero-terminated 1751** string representation as returned by [sqlite3_column_text()]. 1752** 1753** A result table might consist of one or more memory allocations. 1754** It is not safe to pass a result table directly to [sqlite3_free()]. 1755** A result table should be deallocated using [sqlite3_free_table()]. 1756** 1757** ^(As an example of the result table format, suppose a query result 1758** is as follows: 1759** 1760** <blockquote><pre> 1761** Name | Age 1762** ----------------------- 1763** Alice | 43 1764** Bob | 28 1765** Cindy | 21 1766** </pre></blockquote> 1767** 1768** There are two column (M==2) and three rows (N==3). Thus the 1769** result table has 8 entries. Suppose the result table is stored 1770** in an array names azResult. Then azResult holds this content: 1771** 1772** <blockquote><pre> 1773** azResult[0] = "Name"; 1774** azResult[1] = "Age"; 1775** azResult[2] = "Alice"; 1776** azResult[3] = "43"; 1777** azResult[4] = "Bob"; 1778** azResult[5] = "28"; 1779** azResult[6] = "Cindy"; 1780** azResult[7] = "21"; 1781** </pre></blockquote>)^ 1782** 1783** ^The sqlite3_get_table() function evaluates one or more 1784** semicolon-separated SQL statements in the zero-terminated UTF-8 1785** string of its 2nd parameter and returns a result table to the 1786** pointer given in its 3rd parameter. 1787** 1788** After the application has finished with the result from sqlite3_get_table(), 1789** it must pass the result table pointer to sqlite3_free_table() in order to 1790** release the memory that was malloced. Because of the way the 1791** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling 1792** function must not try to call [sqlite3_free()] directly. Only 1793** [sqlite3_free_table()] is able to release the memory properly and safely. 1794** 1795** The sqlite3_get_table() interface is implemented as a wrapper around 1796** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access 1797** to any internal data structures of SQLite. It uses only the public 1798** interface defined here. As a consequence, errors that occur in the 1799** wrapper layer outside of the internal [sqlite3_exec()] call are not 1800** reflected in subsequent calls to [sqlite3_errcode()] or 1801** [sqlite3_errmsg()]. 1802*/ 1803int sqlite3_get_table( 1804 sqlite3 *db, /* An open database */ 1805 const char *zSql, /* SQL to be evaluated */ 1806 char ***pazResult, /* Results of the query */ 1807 int *pnRow, /* Number of result rows written here */ 1808 int *pnColumn, /* Number of result columns written here */ 1809 char **pzErrmsg /* Error msg written here */ 1810); 1811void sqlite3_free_table(char **result); 1812 1813/* 1814** CAPI3REF: Formatted String Printing Functions 1815** 1816** These routines are work-alikes of the "printf()" family of functions 1817** from the standard C library. 1818** 1819** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their 1820** results into memory obtained from [sqlite3_malloc()]. 1821** The strings returned by these two routines should be 1822** released by [sqlite3_free()]. ^Both routines return a 1823** NULL pointer if [sqlite3_malloc()] is unable to allocate enough 1824** memory to hold the resulting string. 1825** 1826** ^(In sqlite3_snprintf() routine is similar to "snprintf()" from 1827** the standard C library. The result is written into the 1828** buffer supplied as the second parameter whose size is given by 1829** the first parameter. Note that the order of the 1830** first two parameters is reversed from snprintf().)^ This is an 1831** historical accident that cannot be fixed without breaking 1832** backwards compatibility. ^(Note also that sqlite3_snprintf() 1833** returns a pointer to its buffer instead of the number of 1834** characters actually written into the buffer.)^ We admit that 1835** the number of characters written would be a more useful return 1836** value but we cannot change the implementation of sqlite3_snprintf() 1837** now without breaking compatibility. 1838** 1839** ^As long as the buffer size is greater than zero, sqlite3_snprintf() 1840** guarantees that the buffer is always zero-terminated. ^The first 1841** parameter "n" is the total size of the buffer, including space for 1842** the zero terminator. So the longest string that can be completely 1843** written will be n-1 characters. 1844** 1845** These routines all implement some additional formatting 1846** options that are useful for constructing SQL statements. 1847** All of the usual printf() formatting options apply. In addition, there 1848** is are "%q", "%Q", and "%z" options. 1849** 1850** ^(The %q option works like %s in that it substitutes a null-terminated 1851** string from the argument list. But %q also doubles every '\'' character. 1852** %q is designed for use inside a string literal.)^ By doubling each '\'' 1853** character it escapes that character and allows it to be inserted into 1854** the string. 1855** 1856** For example, assume the string variable zText contains text as follows: 1857** 1858** <blockquote><pre> 1859** char *zText = "It's a happy day!"; 1860** </pre></blockquote> 1861** 1862** One can use this text in an SQL statement as follows: 1863** 1864** <blockquote><pre> 1865** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText); 1866** sqlite3_exec(db, zSQL, 0, 0, 0); 1867** sqlite3_free(zSQL); 1868** </pre></blockquote> 1869** 1870** Because the %q format string is used, the '\'' character in zText 1871** is escaped and the SQL generated is as follows: 1872** 1873** <blockquote><pre> 1874** INSERT INTO table1 VALUES('It''s a happy day!') 1875** </pre></blockquote> 1876** 1877** This is correct. Had we used %s instead of %q, the generated SQL 1878** would have looked like this: 1879** 1880** <blockquote><pre> 1881** INSERT INTO table1 VALUES('It's a happy day!'); 1882** </pre></blockquote> 1883** 1884** This second example is an SQL syntax error. As a general rule you should 1885** always use %q instead of %s when inserting text into a string literal. 1886** 1887** ^(The %Q option works like %q except it also adds single quotes around 1888** the outside of the total string. Additionally, if the parameter in the 1889** argument list is a NULL pointer, %Q substitutes the text "NULL" (without 1890** single quotes).)^ So, for example, one could say: 1891** 1892** <blockquote><pre> 1893** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText); 1894** sqlite3_exec(db, zSQL, 0, 0, 0); 1895** sqlite3_free(zSQL); 1896** </pre></blockquote> 1897** 1898** The code above will render a correct SQL statement in the zSQL 1899** variable even if the zText variable is a NULL pointer. 1900** 1901** ^(The "%z" formatting option works like "%s" but with the 1902** addition that after the string has been read and copied into 1903** the result, [sqlite3_free()] is called on the input string.)^ 1904*/ 1905char *sqlite3_mprintf(const char*,...); 1906char *sqlite3_vmprintf(const char*, va_list); 1907char *sqlite3_snprintf(int,char*,const char*, ...); 1908 1909/* 1910** CAPI3REF: Memory Allocation Subsystem 1911** 1912** The SQLite core uses these three routines for all of its own 1913** internal memory allocation needs. "Core" in the previous sentence 1914** does not include operating-system specific VFS implementation. The 1915** Windows VFS uses native malloc() and free() for some operations. 1916** 1917** ^The sqlite3_malloc() routine returns a pointer to a block 1918** of memory at least N bytes in length, where N is the parameter. 1919** ^If sqlite3_malloc() is unable to obtain sufficient free 1920** memory, it returns a NULL pointer. ^If the parameter N to 1921** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns 1922** a NULL pointer. 1923** 1924** ^Calling sqlite3_free() with a pointer previously returned 1925** by sqlite3_malloc() or sqlite3_realloc() releases that memory so 1926** that it might be reused. ^The sqlite3_free() routine is 1927** a no-op if is called with a NULL pointer. Passing a NULL pointer 1928** to sqlite3_free() is harmless. After being freed, memory 1929** should neither be read nor written. Even reading previously freed 1930** memory might result in a segmentation fault or other severe error. 1931** Memory corruption, a segmentation fault, or other severe error 1932** might result if sqlite3_free() is called with a non-NULL pointer that 1933** was not obtained from sqlite3_malloc() or sqlite3_realloc(). 1934** 1935** ^(The sqlite3_realloc() interface attempts to resize a 1936** prior memory allocation to be at least N bytes, where N is the 1937** second parameter. The memory allocation to be resized is the first 1938** parameter.)^ ^ If the first parameter to sqlite3_realloc() 1939** is a NULL pointer then its behavior is identical to calling 1940** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc(). 1941** ^If the second parameter to sqlite3_realloc() is zero or 1942** negative then the behavior is exactly the same as calling 1943** sqlite3_free(P) where P is the first parameter to sqlite3_realloc(). 1944** ^sqlite3_realloc() returns a pointer to a memory allocation 1945** of at least N bytes in size or NULL if sufficient memory is unavailable. 1946** ^If M is the size of the prior allocation, then min(N,M) bytes 1947** of the prior allocation are copied into the beginning of buffer returned 1948** by sqlite3_realloc() and the prior allocation is freed. 1949** ^If sqlite3_realloc() returns NULL, then the prior allocation 1950** is not freed. 1951** 1952** ^The memory returned by sqlite3_malloc() and sqlite3_realloc() 1953** is always aligned to at least an 8 byte boundary, or to a 1954** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time 1955** option is used. 1956** 1957** In SQLite version 3.5.0 and 3.5.1, it was possible to define 1958** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in 1959** implementation of these routines to be omitted. That capability 1960** is no longer provided. Only built-in memory allocators can be used. 1961** 1962** The Windows OS interface layer calls 1963** the system malloc() and free() directly when converting 1964** filenames between the UTF-8 encoding used by SQLite 1965** and whatever filename encoding is used by the particular Windows 1966** installation. Memory allocation errors are detected, but 1967** they are reported back as [SQLITE_CANTOPEN] or 1968** [SQLITE_IOERR] rather than [SQLITE_NOMEM]. 1969** 1970** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] 1971** must be either NULL or else pointers obtained from a prior 1972** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have 1973** not yet been released. 1974** 1975** The application must not read or write any part of 1976** a block of memory after it has been released using 1977** [sqlite3_free()] or [sqlite3_realloc()]. 1978*/ 1979void *sqlite3_malloc(int); 1980void *sqlite3_realloc(void*, int); 1981void sqlite3_free(void*); 1982 1983/* 1984** CAPI3REF: Memory Allocator Statistics 1985** 1986** SQLite provides these two interfaces for reporting on the status 1987** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] 1988** routines, which form the built-in memory allocation subsystem. 1989** 1990** ^The [sqlite3_memory_used()] routine returns the number of bytes 1991** of memory currently outstanding (malloced but not freed). 1992** ^The [sqlite3_memory_highwater()] routine returns the maximum 1993** value of [sqlite3_memory_used()] since the high-water mark 1994** was last reset. ^The values returned by [sqlite3_memory_used()] and 1995** [sqlite3_memory_highwater()] include any overhead 1996** added by SQLite in its implementation of [sqlite3_malloc()], 1997** but not overhead added by the any underlying system library 1998** routines that [sqlite3_malloc()] may call. 1999** 2000** ^The memory high-water mark is reset to the current value of 2001** [sqlite3_memory_used()] if and only if the parameter to 2002** [sqlite3_memory_highwater()] is true. ^The value returned 2003** by [sqlite3_memory_highwater(1)] is the high-water mark 2004** prior to the reset. 2005*/ 2006sqlite3_int64 sqlite3_memory_used(void); 2007sqlite3_int64 sqlite3_memory_highwater(int resetFlag); 2008 2009/* 2010** CAPI3REF: Pseudo-Random Number Generator 2011** 2012** SQLite contains a high-quality pseudo-random number generator (PRNG) used to 2013** select random [ROWID | ROWIDs] when inserting new records into a table that 2014** already uses the largest possible [ROWID]. The PRNG is also used for 2015** the build-in random() and randomblob() SQL functions. This interface allows 2016** applications to access the same PRNG for other purposes. 2017** 2018** ^A call to this routine stores N bytes of randomness into buffer P. 2019** 2020** ^The first time this routine is invoked (either internally or by 2021** the application) the PRNG is seeded using randomness obtained 2022** from the xRandomness method of the default [sqlite3_vfs] object. 2023** ^On all subsequent invocations, the pseudo-randomness is generated 2024** internally and without recourse to the [sqlite3_vfs] xRandomness 2025** method. 2026*/ 2027void sqlite3_randomness(int N, void *P); 2028 2029/* 2030** CAPI3REF: Compile-Time Authorization Callbacks 2031** 2032** ^This routine registers a authorizer callback with a particular 2033** [database connection], supplied in the first argument. 2034** ^The authorizer callback is invoked as SQL statements are being compiled 2035** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], 2036** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. ^At various 2037** points during the compilation process, as logic is being created 2038** to perform various actions, the authorizer callback is invoked to 2039** see if those actions are allowed. ^The authorizer callback should 2040** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the 2041** specific action but allow the SQL statement to continue to be 2042** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be 2043** rejected with an error. ^If the authorizer callback returns 2044** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] 2045** then the [sqlite3_prepare_v2()] or equivalent call that triggered 2046** the authorizer will fail with an error message. 2047** 2048** When the callback returns [SQLITE_OK], that means the operation 2049** requested is ok. ^When the callback returns [SQLITE_DENY], the 2050** [sqlite3_prepare_v2()] or equivalent call that triggered the 2051** authorizer will fail with an error message explaining that 2052** access is denied. 2053** 2054** ^The first parameter to the authorizer callback is a copy of the third 2055** parameter to the sqlite3_set_authorizer() interface. ^The second parameter 2056** to the callback is an integer [SQLITE_COPY | action code] that specifies 2057** the particular action to be authorized. ^The third through sixth parameters 2058** to the callback are zero-terminated strings that contain additional 2059** details about the action to be authorized. 2060** 2061** ^If the action code is [SQLITE_READ] 2062** and the callback returns [SQLITE_IGNORE] then the 2063** [prepared statement] statement is constructed to substitute 2064** a NULL value in place of the table column that would have 2065** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE] 2066** return can be used to deny an untrusted user access to individual 2067** columns of a table. 2068** ^If the action code is [SQLITE_DELETE] and the callback returns 2069** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the 2070** [truncate optimization] is disabled and all rows are deleted individually. 2071** 2072** An authorizer is used when [sqlite3_prepare | preparing] 2073** SQL statements from an untrusted source, to ensure that the SQL statements 2074** do not try to access data they are not allowed to see, or that they do not 2075** try to execute malicious statements that damage the database. For 2076** example, an application may allow a user to enter arbitrary 2077** SQL queries for evaluation by a database. But the application does 2078** not want the user to be able to make arbitrary changes to the 2079** database. An authorizer could then be put in place while the 2080** user-entered SQL is being [sqlite3_prepare | prepared] that 2081** disallows everything except [SELECT] statements. 2082** 2083** Applications that need to process SQL from untrusted sources 2084** might also consider lowering resource limits using [sqlite3_limit()] 2085** and limiting database size using the [max_page_count] [PRAGMA] 2086** in addition to using an authorizer. 2087** 2088** ^(Only a single authorizer can be in place on a database connection 2089** at a time. Each call to sqlite3_set_authorizer overrides the 2090** previous call.)^ ^Disable the authorizer by installing a NULL callback. 2091** The authorizer is disabled by default. 2092** 2093** The authorizer callback must not do anything that will modify 2094** the database connection that invoked the authorizer callback. 2095** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their 2096** database connections for the meaning of "modify" in this paragraph. 2097** 2098** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the 2099** statement might be re-prepared during [sqlite3_step()] due to a 2100** schema change. Hence, the application should ensure that the 2101** correct authorizer callback remains in place during the [sqlite3_step()]. 2102** 2103** ^Note that the authorizer callback is invoked only during 2104** [sqlite3_prepare()] or its variants. Authorization is not 2105** performed during statement evaluation in [sqlite3_step()], unless 2106** as stated in the previous paragraph, sqlite3_step() invokes 2107** sqlite3_prepare_v2() to reprepare a statement after a schema change. 2108*/ 2109int sqlite3_set_authorizer( 2110 sqlite3*, 2111 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), 2112 void *pUserData 2113); 2114 2115/* 2116** CAPI3REF: Authorizer Return Codes 2117** 2118** The [sqlite3_set_authorizer | authorizer callback function] must 2119** return either [SQLITE_OK] or one of these two constants in order 2120** to signal SQLite whether or not the action is permitted. See the 2121** [sqlite3_set_authorizer | authorizer documentation] for additional 2122** information. 2123*/ 2124#define SQLITE_DENY 1 /* Abort the SQL statement with an error */ 2125#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ 2126 2127/* 2128** CAPI3REF: Authorizer Action Codes 2129** 2130** The [sqlite3_set_authorizer()] interface registers a callback function 2131** that is invoked to authorize certain SQL statement actions. The 2132** second parameter to the callback is an integer code that specifies 2133** what action is being authorized. These are the integer action codes that 2134** the authorizer callback may be passed. 2135** 2136** These action code values signify what kind of operation is to be 2137** authorized. The 3rd and 4th parameters to the authorization 2138** callback function will be parameters or NULL depending on which of these 2139** codes is used as the second parameter. ^(The 5th parameter to the 2140** authorizer callback is the name of the database ("main", "temp", 2141** etc.) if applicable.)^ ^The 6th parameter to the authorizer callback 2142** is the name of the inner-most trigger or view that is responsible for 2143** the access attempt or NULL if this access attempt is directly from 2144** top-level SQL code. 2145*/ 2146/******************************************* 3rd ************ 4th ***********/ 2147#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ 2148#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ 2149#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ 2150#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ 2151#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ 2152#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ 2153#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ 2154#define SQLITE_CREATE_VIEW 8 /* View Name NULL */ 2155#define SQLITE_DELETE 9 /* Table Name NULL */ 2156#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ 2157#define SQLITE_DROP_TABLE 11 /* Table Name NULL */ 2158#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ 2159#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ 2160#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ 2161#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ 2162#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ 2163#define SQLITE_DROP_VIEW 17 /* View Name NULL */ 2164#define SQLITE_INSERT 18 /* Table Name NULL */ 2165#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ 2166#define SQLITE_READ 20 /* Table Name Column Name */ 2167#define SQLITE_SELECT 21 /* NULL NULL */ 2168#define SQLITE_TRANSACTION 22 /* Operation NULL */ 2169#define SQLITE_UPDATE 23 /* Table Name Column Name */ 2170#define SQLITE_ATTACH 24 /* Filename NULL */ 2171#define SQLITE_DETACH 25 /* Database Name NULL */ 2172#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */ 2173#define SQLITE_REINDEX 27 /* Index Name NULL */ 2174#define SQLITE_ANALYZE 28 /* Table Name NULL */ 2175#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ 2176#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ 2177#define SQLITE_FUNCTION 31 /* NULL Function Name */ 2178#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ 2179#define SQLITE_COPY 0 /* No longer used */ 2180 2181/* 2182** CAPI3REF: Tracing And Profiling Functions 2183** 2184** These routines register callback functions that can be used for 2185** tracing and profiling the execution of SQL statements. 2186** 2187** ^The callback function registered by sqlite3_trace() is invoked at 2188** various times when an SQL statement is being run by [sqlite3_step()]. 2189** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the 2190** SQL statement text as the statement first begins executing. 2191** ^(Additional sqlite3_trace() callbacks might occur 2192** as each triggered subprogram is entered. The callbacks for triggers 2193** contain a UTF-8 SQL comment that identifies the trigger.)^ 2194** 2195** ^The callback function registered by sqlite3_profile() is invoked 2196** as each SQL statement finishes. ^The profile callback contains 2197** the original statement text and an estimate of wall-clock time 2198** of how long that statement took to run. ^The profile callback 2199** time is in units of nanoseconds, however the current implementation 2200** is only capable of millisecond resolution so the six least significant 2201** digits in the time are meaningless. Future versions of SQLite 2202** might provide greater resolution on the profiler callback. The 2203** sqlite3_profile() function is considered experimental and is 2204** subject to change in future versions of SQLite. 2205*/ 2206void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); 2207SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*, 2208 void(*xProfile)(void*,const char*,sqlite3_uint64), void*); 2209 2210/* 2211** CAPI3REF: Query Progress Callbacks 2212** 2213** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback 2214** function X to be invoked periodically during long running calls to 2215** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for 2216** database connection D. An example use for this 2217** interface is to keep a GUI updated during a large query. 2218** 2219** ^The parameter P is passed through as the only parameter to the 2220** callback function X. ^The parameter N is the number of 2221** [virtual machine instructions] that are evaluated between successive 2222** invocations of the callback X. 2223** 2224** ^Only a single progress handler may be defined at one time per 2225** [database connection]; setting a new progress handler cancels the 2226** old one. ^Setting parameter X to NULL disables the progress handler. 2227** ^The progress handler is also disabled by setting N to a value less 2228** than 1. 2229** 2230** ^If the progress callback returns non-zero, the operation is 2231** interrupted. This feature can be used to implement a 2232** "Cancel" button on a GUI progress dialog box. 2233** 2234** The progress handler callback must not do anything that will modify 2235** the database connection that invoked the progress handler. 2236** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their 2237** database connections for the meaning of "modify" in this paragraph. 2238** 2239*/ 2240void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); 2241 2242/* 2243** CAPI3REF: Opening A New Database Connection 2244** 2245** ^These routines open an SQLite database file whose name is given by the 2246** filename argument. ^The filename argument is interpreted as UTF-8 for 2247** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte 2248** order for sqlite3_open16(). ^(A [database connection] handle is usually 2249** returned in *ppDb, even if an error occurs. The only exception is that 2250** if SQLite is unable to allocate memory to hold the [sqlite3] object, 2251** a NULL will be written into *ppDb instead of a pointer to the [sqlite3] 2252** object.)^ ^(If the database is opened (and/or created) successfully, then 2253** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The 2254** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain 2255** an English language description of the error following a failure of any 2256** of the sqlite3_open() routines. 2257** 2258** ^The default encoding for the database will be UTF-8 if 2259** sqlite3_open() or sqlite3_open_v2() is called and 2260** UTF-16 in the native byte order if sqlite3_open16() is used. 2261** 2262** Whether or not an error occurs when it is opened, resources 2263** associated with the [database connection] handle should be released by 2264** passing it to [sqlite3_close()] when it is no longer required. 2265** 2266** The sqlite3_open_v2() interface works like sqlite3_open() 2267** except that it accepts two additional parameters for additional control 2268** over the new database connection. ^(The flags parameter to 2269** sqlite3_open_v2() can take one of 2270** the following three values, optionally combined with the 2271** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE], 2272** and/or [SQLITE_OPEN_PRIVATECACHE] flags:)^ 2273** 2274** <dl> 2275** ^(<dt>[SQLITE_OPEN_READONLY]</dt> 2276** <dd>The database is opened in read-only mode. If the database does not 2277** already exist, an error is returned.</dd>)^ 2278** 2279** ^(<dt>[SQLITE_OPEN_READWRITE]</dt> 2280** <dd>The database is opened for reading and writing if possible, or reading 2281** only if the file is write protected by the operating system. In either 2282** case the database must already exist, otherwise an error is returned.</dd>)^ 2283** 2284** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt> 2285** <dd>The database is opened for reading and writing, and is creates it if 2286** it does not already exist. This is the behavior that is always used for 2287** sqlite3_open() and sqlite3_open16().</dd>)^ 2288** </dl> 2289** 2290** If the 3rd parameter to sqlite3_open_v2() is not one of the 2291** combinations shown above or one of the combinations shown above combined 2292** with the [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], 2293** [SQLITE_OPEN_SHAREDCACHE] and/or [SQLITE_OPEN_PRIVATECACHE] flags, 2294** then the behavior is undefined. 2295** 2296** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection 2297** opens in the multi-thread [threading mode] as long as the single-thread 2298** mode has not been set at compile-time or start-time. ^If the 2299** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens 2300** in the serialized [threading mode] unless single-thread was 2301** previously selected at compile-time or start-time. 2302** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be 2303** eligible to use [shared cache mode], regardless of whether or not shared 2304** cache is enabled using [sqlite3_enable_shared_cache()]. ^The 2305** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not 2306** participate in [shared cache mode] even if it is enabled. 2307** 2308** ^If the filename is ":memory:", then a private, temporary in-memory database 2309** is created for the connection. ^This in-memory database will vanish when 2310** the database connection is closed. Future versions of SQLite might 2311** make use of additional special filenames that begin with the ":" character. 2312** It is recommended that when a database filename actually does begin with 2313** a ":" character you should prefix the filename with a pathname such as 2314** "./" to avoid ambiguity. 2315** 2316** ^If the filename is an empty string, then a private, temporary 2317** on-disk database will be created. ^This private database will be 2318** automatically deleted as soon as the database connection is closed. 2319** 2320** ^The fourth parameter to sqlite3_open_v2() is the name of the 2321** [sqlite3_vfs] object that defines the operating system interface that 2322** the new database connection should use. ^If the fourth parameter is 2323** a NULL pointer then the default [sqlite3_vfs] object is used. 2324** 2325** <b>Note to Windows users:</b> The encoding used for the filename argument 2326** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever 2327** codepage is currently defined. Filenames containing international 2328** characters must be converted to UTF-8 prior to passing them into 2329** sqlite3_open() or sqlite3_open_v2(). 2330*/ 2331int sqlite3_open( 2332 const char *filename, /* Database filename (UTF-8) */ 2333 sqlite3 **ppDb /* OUT: SQLite db handle */ 2334); 2335int sqlite3_open16( 2336 const void *filename, /* Database filename (UTF-16) */ 2337 sqlite3 **ppDb /* OUT: SQLite db handle */ 2338); 2339int sqlite3_open_v2( 2340 const char *filename, /* Database filename (UTF-8) */ 2341 sqlite3 **ppDb, /* OUT: SQLite db handle */ 2342 int flags, /* Flags */ 2343 const char *zVfs /* Name of VFS module to use */ 2344); 2345 2346/* 2347** CAPI3REF: Error Codes And Messages 2348** 2349** ^The sqlite3_errcode() interface returns the numeric [result code] or 2350** [extended result code] for the most recent failed sqlite3_* API call 2351** associated with a [database connection]. If a prior API call failed 2352** but the most recent API call succeeded, the return value from 2353** sqlite3_errcode() is undefined. ^The sqlite3_extended_errcode() 2354** interface is the same except that it always returns the 2355** [extended result code] even when extended result codes are 2356** disabled. 2357** 2358** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language 2359** text that describes the error, as either UTF-8 or UTF-16 respectively. 2360** ^(Memory to hold the error message string is managed internally. 2361** The application does not need to worry about freeing the result. 2362** However, the error string might be overwritten or deallocated by 2363** subsequent calls to other SQLite interface functions.)^ 2364** 2365** When the serialized [threading mode] is in use, it might be the 2366** case that a second error occurs on a separate thread in between 2367** the time of the first error and the call to these interfaces. 2368** When that happens, the second error will be reported since these 2369** interfaces always report the most recent result. To avoid 2370** this, each thread can obtain exclusive use of the [database connection] D 2371** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning 2372** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after 2373** all calls to the interfaces listed here are completed. 2374** 2375** If an interface fails with SQLITE_MISUSE, that means the interface 2376** was invoked incorrectly by the application. In that case, the 2377** error code and message may or may not be set. 2378*/ 2379int sqlite3_errcode(sqlite3 *db); 2380int sqlite3_extended_errcode(sqlite3 *db); 2381const char *sqlite3_errmsg(sqlite3*); 2382const void *sqlite3_errmsg16(sqlite3*); 2383 2384/* 2385** CAPI3REF: SQL Statement Object 2386** KEYWORDS: {prepared statement} {prepared statements} 2387** 2388** An instance of this object represents a single SQL statement. 2389** This object is variously known as a "prepared statement" or a 2390** "compiled SQL statement" or simply as a "statement". 2391** 2392** The life of a statement object goes something like this: 2393** 2394** <ol> 2395** <li> Create the object using [sqlite3_prepare_v2()] or a related 2396** function. 2397** <li> Bind values to [host parameters] using the sqlite3_bind_*() 2398** interfaces. 2399** <li> Run the SQL by calling [sqlite3_step()] one or more times. 2400** <li> Reset the statement using [sqlite3_reset()] then go back 2401** to step 2. Do this zero or more times. 2402** <li> Destroy the object using [sqlite3_finalize()]. 2403** </ol> 2404** 2405** Refer to documentation on individual methods above for additional 2406** information. 2407*/ 2408typedef struct sqlite3_stmt sqlite3_stmt; 2409 2410/* 2411** CAPI3REF: Run-time Limits 2412** 2413** ^(This interface allows the size of various constructs to be limited 2414** on a connection by connection basis. The first parameter is the 2415** [database connection] whose limit is to be set or queried. The 2416** second parameter is one of the [limit categories] that define a 2417** class of constructs to be size limited. The third parameter is the 2418** new limit for that construct.)^ 2419** 2420** ^If the new limit is a negative number, the limit is unchanged. 2421** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a 2422** [limits | hard upper bound] 2423** set at compile-time by a C preprocessor macro called 2424** [limits | SQLITE_MAX_<i>NAME</i>]. 2425** (The "_LIMIT_" in the name is changed to "_MAX_".))^ 2426** ^Attempts to increase a limit above its hard upper bound are 2427** silently truncated to the hard upper bound. 2428** 2429** ^Regardless of whether or not the limit was changed, the 2430** [sqlite3_limit()] interface returns the prior value of the limit. 2431** ^Hence, to find the current value of a limit without changing it, 2432** simply invoke this interface with the third parameter set to -1. 2433** 2434** Run-time limits are intended for use in applications that manage 2435** both their own internal database and also databases that are controlled 2436** by untrusted external sources. An example application might be a 2437** web browser that has its own databases for storing history and 2438** separate databases controlled by JavaScript applications downloaded 2439** off the Internet. The internal databases can be given the 2440** large, default limits. Databases managed by external sources can 2441** be given much smaller limits designed to prevent a denial of service 2442** attack. Developers might also want to use the [sqlite3_set_authorizer()] 2443** interface to further control untrusted SQL. The size of the database 2444** created by an untrusted script can be contained using the 2445** [max_page_count] [PRAGMA]. 2446** 2447** New run-time limit categories may be added in future releases. 2448*/ 2449int sqlite3_limit(sqlite3*, int id, int newVal); 2450 2451/* 2452** CAPI3REF: Run-Time Limit Categories 2453** KEYWORDS: {limit category} {*limit categories} 2454** 2455** These constants define various performance limits 2456** that can be lowered at run-time using [sqlite3_limit()]. 2457** The synopsis of the meanings of the various limits is shown below. 2458** Additional information is available at [limits | Limits in SQLite]. 2459** 2460** <dl> 2461** ^(<dt>SQLITE_LIMIT_LENGTH</dt> 2462** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^ 2463** 2464** ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt> 2465** <dd>The maximum length of an SQL statement, in bytes.</dd>)^ 2466** 2467** ^(<dt>SQLITE_LIMIT_COLUMN</dt> 2468** <dd>The maximum number of columns in a table definition or in the 2469** result set of a [SELECT] or the maximum number of columns in an index 2470** or in an ORDER BY or GROUP BY clause.</dd>)^ 2471** 2472** ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt> 2473** <dd>The maximum depth of the parse tree on any expression.</dd>)^ 2474** 2475** ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt> 2476** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^ 2477** 2478** ^(<dt>SQLITE_LIMIT_VDBE_OP</dt> 2479** <dd>The maximum number of instructions in a virtual machine program 2480** used to implement an SQL statement. This limit is not currently 2481** enforced, though that might be added in some future release of 2482** SQLite.</dd>)^ 2483** 2484** ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt> 2485** <dd>The maximum number of arguments on a function.</dd>)^ 2486** 2487** ^(<dt>SQLITE_LIMIT_ATTACHED</dt> 2488** <dd>The maximum number of [ATTACH | attached databases].)^</dd> 2489** 2490** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt> 2491** <dd>The maximum length of the pattern argument to the [LIKE] or 2492** [GLOB] operators.</dd>)^ 2493** 2494** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt> 2495** <dd>The maximum index number of any [parameter] in an SQL statement.)^ 2496** 2497** ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt> 2498** <dd>The maximum depth of recursion for triggers.</dd>)^ 2499** </dl> 2500*/ 2501#define SQLITE_LIMIT_LENGTH 0 2502#define SQLITE_LIMIT_SQL_LENGTH 1 2503#define SQLITE_LIMIT_COLUMN 2 2504#define SQLITE_LIMIT_EXPR_DEPTH 3 2505#define SQLITE_LIMIT_COMPOUND_SELECT 4 2506#define SQLITE_LIMIT_VDBE_OP 5 2507#define SQLITE_LIMIT_FUNCTION_ARG 6 2508#define SQLITE_LIMIT_ATTACHED 7 2509#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8 2510#define SQLITE_LIMIT_VARIABLE_NUMBER 9 2511#define SQLITE_LIMIT_TRIGGER_DEPTH 10 2512 2513/* 2514** CAPI3REF: Compiling An SQL Statement 2515** KEYWORDS: {SQL statement compiler} 2516** 2517** To execute an SQL query, it must first be compiled into a byte-code 2518** program using one of these routines. 2519** 2520** The first argument, "db", is a [database connection] obtained from a 2521** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or 2522** [sqlite3_open16()]. The database connection must not have been closed. 2523** 2524** The second argument, "zSql", is the statement to be compiled, encoded 2525** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() 2526** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2() 2527** use UTF-16. 2528** 2529** ^If the nByte argument is less than zero, then zSql is read up to the 2530** first zero terminator. ^If nByte is non-negative, then it is the maximum 2531** number of bytes read from zSql. ^When nByte is non-negative, the 2532** zSql string ends at either the first '\000' or '\u0000' character or 2533** the nByte-th byte, whichever comes first. If the caller knows 2534** that the supplied string is nul-terminated, then there is a small 2535** performance advantage to be gained by passing an nByte parameter that 2536** is equal to the number of bytes in the input string <i>including</i> 2537** the nul-terminator bytes. 2538** 2539** ^If pzTail is not NULL then *pzTail is made to point to the first byte 2540** past the end of the first SQL statement in zSql. These routines only 2541** compile the first statement in zSql, so *pzTail is left pointing to 2542** what remains uncompiled. 2543** 2544** ^*ppStmt is left pointing to a compiled [prepared statement] that can be 2545** executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set 2546** to NULL. ^If the input text contains no SQL (if the input is an empty 2547** string or a comment) then *ppStmt is set to NULL. 2548** The calling procedure is responsible for deleting the compiled 2549** SQL statement using [sqlite3_finalize()] after it has finished with it. 2550** ppStmt may not be NULL. 2551** 2552** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK]; 2553** otherwise an [error code] is returned. 2554** 2555** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are 2556** recommended for all new programs. The two older interfaces are retained 2557** for backwards compatibility, but their use is discouraged. 2558** ^In the "v2" interfaces, the prepared statement 2559** that is returned (the [sqlite3_stmt] object) contains a copy of the 2560** original SQL text. This causes the [sqlite3_step()] interface to 2561** behave differently in three ways: 2562** 2563** <ol> 2564** <li> 2565** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it 2566** always used to do, [sqlite3_step()] will automatically recompile the SQL 2567** statement and try to run it again. 2568** </li> 2569** 2570** <li> 2571** ^When an error occurs, [sqlite3_step()] will return one of the detailed 2572** [error codes] or [extended error codes]. ^The legacy behavior was that 2573** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code 2574** and the application would have to make a second call to [sqlite3_reset()] 2575** in order to find the underlying cause of the problem. With the "v2" prepare 2576** interfaces, the underlying reason for the error is returned immediately. 2577** </li> 2578** 2579** <li> 2580** ^If the specific value bound to [parameter | host parameter] in the 2581** WHERE clause might influence the choice of query plan for a statement, 2582** then the statement will be automatically recompiled, as if there had been 2583** a schema change, on the first [sqlite3_step()] call following any change 2584** to the [sqlite3_bind_text | bindings] of that [parameter]. 2585** ^The specific value of WHERE-clause [parameter] might influence the 2586** choice of query plan if the parameter is the left-hand side of a [LIKE] 2587** or [GLOB] operator or if the parameter is compared to an indexed column 2588** and the [SQLITE_ENABLE_STAT2] compile-time option is enabled. 2589** the 2590** </li> 2591** </ol> 2592*/ 2593int sqlite3_prepare( 2594 sqlite3 *db, /* Database handle */ 2595 const char *zSql, /* SQL statement, UTF-8 encoded */ 2596 int nByte, /* Maximum length of zSql in bytes. */ 2597 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 2598 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 2599); 2600int sqlite3_prepare_v2( 2601 sqlite3 *db, /* Database handle */ 2602 const char *zSql, /* SQL statement, UTF-8 encoded */ 2603 int nByte, /* Maximum length of zSql in bytes. */ 2604 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 2605 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 2606); 2607int sqlite3_prepare16( 2608 sqlite3 *db, /* Database handle */ 2609 const void *zSql, /* SQL statement, UTF-16 encoded */ 2610 int nByte, /* Maximum length of zSql in bytes. */ 2611 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 2612 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 2613); 2614int sqlite3_prepare16_v2( 2615 sqlite3 *db, /* Database handle */ 2616 const void *zSql, /* SQL statement, UTF-16 encoded */ 2617 int nByte, /* Maximum length of zSql in bytes. */ 2618 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 2619 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 2620); 2621 2622/* 2623** CAPI3REF: Retrieving Statement SQL 2624** 2625** ^This interface can be used to retrieve a saved copy of the original 2626** SQL text used to create a [prepared statement] if that statement was 2627** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. 2628*/ 2629const char *sqlite3_sql(sqlite3_stmt *pStmt); 2630 2631/* 2632** CAPI3REF: Dynamically Typed Value Object 2633** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} 2634** 2635** SQLite uses the sqlite3_value object to represent all values 2636** that can be stored in a database table. SQLite uses dynamic typing 2637** for the values it stores. ^Values stored in sqlite3_value objects 2638** can be integers, floating point values, strings, BLOBs, or NULL. 2639** 2640** An sqlite3_value object may be either "protected" or "unprotected". 2641** Some interfaces require a protected sqlite3_value. Other interfaces 2642** will accept either a protected or an unprotected sqlite3_value. 2643** Every interface that accepts sqlite3_value arguments specifies 2644** whether or not it requires a protected sqlite3_value. 2645** 2646** The terms "protected" and "unprotected" refer to whether or not 2647** a mutex is held. A internal mutex is held for a protected 2648** sqlite3_value object but no mutex is held for an unprotected 2649** sqlite3_value object. If SQLite is compiled to be single-threaded 2650** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0) 2651** or if SQLite is run in one of reduced mutex modes 2652** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD] 2653** then there is no distinction between protected and unprotected 2654** sqlite3_value objects and they can be used interchangeably. However, 2655** for maximum code portability it is recommended that applications 2656** still make the distinction between protected and unprotected 2657** sqlite3_value objects even when not strictly required. 2658** 2659** ^The sqlite3_value objects that are passed as parameters into the 2660** implementation of [application-defined SQL functions] are protected. 2661** ^The sqlite3_value object returned by 2662** [sqlite3_column_value()] is unprotected. 2663** Unprotected sqlite3_value objects may only be used with 2664** [sqlite3_result_value()] and [sqlite3_bind_value()]. 2665** The [sqlite3_value_blob | sqlite3_value_type()] family of 2666** interfaces require protected sqlite3_value objects. 2667*/ 2668typedef struct Mem sqlite3_value; 2669 2670/* 2671** CAPI3REF: SQL Function Context Object 2672** 2673** The context in which an SQL function executes is stored in an 2674** sqlite3_context object. ^A pointer to an sqlite3_context object 2675** is always first parameter to [application-defined SQL functions]. 2676** The application-defined SQL function implementation will pass this 2677** pointer through into calls to [sqlite3_result_int | sqlite3_result()], 2678** [sqlite3_aggregate_context()], [sqlite3_user_data()], 2679** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()], 2680** and/or [sqlite3_set_auxdata()]. 2681*/ 2682typedef struct sqlite3_context sqlite3_context; 2683 2684/* 2685** CAPI3REF: Binding Values To Prepared Statements 2686** KEYWORDS: {host parameter} {host parameters} {host parameter name} 2687** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding} 2688** 2689** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants, 2690** literals may be replaced by a [parameter] that matches one of following 2691** templates: 2692** 2693** <ul> 2694** <li> ? 2695** <li> ?NNN 2696** <li> :VVV 2697** <li> @VVV 2698** <li> $VVV 2699** </ul> 2700** 2701** In the templates above, NNN represents an integer literal, 2702** and VVV represents an alphanumeric identifier.)^ ^The values of these 2703** parameters (also called "host parameter names" or "SQL parameters") 2704** can be set using the sqlite3_bind_*() routines defined here. 2705** 2706** ^The first argument to the sqlite3_bind_*() routines is always 2707** a pointer to the [sqlite3_stmt] object returned from 2708** [sqlite3_prepare_v2()] or its variants. 2709** 2710** ^The second argument is the index of the SQL parameter to be set. 2711** ^The leftmost SQL parameter has an index of 1. ^When the same named 2712** SQL parameter is used more than once, second and subsequent 2713** occurrences have the same index as the first occurrence. 2714** ^The index for named parameters can be looked up using the 2715** [sqlite3_bind_parameter_index()] API if desired. ^The index 2716** for "?NNN" parameters is the value of NNN. 2717** ^The NNN value must be between 1 and the [sqlite3_limit()] 2718** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999). 2719** 2720** ^The third argument is the value to bind to the parameter. 2721** 2722** ^(In those routines that have a fourth argument, its value is the 2723** number of bytes in the parameter. To be clear: the value is the 2724** number of <u>bytes</u> in the value, not the number of characters.)^ 2725** ^If the fourth parameter is negative, the length of the string is 2726** the number of bytes up to the first zero terminator. 2727** 2728** ^The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and 2729** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or 2730** string after SQLite has finished with it. ^The destructor is called 2731** to dispose of the BLOB or string even if the call to sqlite3_bind_blob(), 2732** sqlite3_bind_text(), or sqlite3_bind_text16() fails. 2733** ^If the fifth argument is 2734** the special value [SQLITE_STATIC], then SQLite assumes that the 2735** information is in static, unmanaged space and does not need to be freed. 2736** ^If the fifth argument has the value [SQLITE_TRANSIENT], then 2737** SQLite makes its own private copy of the data immediately, before 2738** the sqlite3_bind_*() routine returns. 2739** 2740** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that 2741** is filled with zeroes. ^A zeroblob uses a fixed amount of memory 2742** (just an integer to hold its size) while it is being processed. 2743** Zeroblobs are intended to serve as placeholders for BLOBs whose 2744** content is later written using 2745** [sqlite3_blob_open | incremental BLOB I/O] routines. 2746** ^A negative value for the zeroblob results in a zero-length BLOB. 2747** 2748** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer 2749** for the [prepared statement] or with a prepared statement for which 2750** [sqlite3_step()] has been called more recently than [sqlite3_reset()], 2751** then the call will return [SQLITE_MISUSE]. If any sqlite3_bind_() 2752** routine is passed a [prepared statement] that has been finalized, the 2753** result is undefined and probably harmful. 2754** 2755** ^Bindings are not cleared by the [sqlite3_reset()] routine. 2756** ^Unbound parameters are interpreted as NULL. 2757** 2758** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an 2759** [error code] if anything goes wrong. 2760** ^[SQLITE_RANGE] is returned if the parameter 2761** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails. 2762** 2763** See also: [sqlite3_bind_parameter_count()], 2764** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. 2765*/ 2766int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); 2767int sqlite3_bind_double(sqlite3_stmt*, int, double); 2768int sqlite3_bind_int(sqlite3_stmt*, int, int); 2769int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); 2770int sqlite3_bind_null(sqlite3_stmt*, int); 2771int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); 2772int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); 2773int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); 2774int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); 2775 2776/* 2777** CAPI3REF: Number Of SQL Parameters 2778** 2779** ^This routine can be used to find the number of [SQL parameters] 2780** in a [prepared statement]. SQL parameters are tokens of the 2781** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as 2782** placeholders for values that are [sqlite3_bind_blob | bound] 2783** to the parameters at a later time. 2784** 2785** ^(This routine actually returns the index of the largest (rightmost) 2786** parameter. For all forms except ?NNN, this will correspond to the 2787** number of unique parameters. If parameters of the ?NNN form are used, 2788** there may be gaps in the list.)^ 2789** 2790** See also: [sqlite3_bind_blob|sqlite3_bind()], 2791** [sqlite3_bind_parameter_name()], and 2792** [sqlite3_bind_parameter_index()]. 2793*/ 2794int sqlite3_bind_parameter_count(sqlite3_stmt*); 2795 2796/* 2797** CAPI3REF: Name Of A Host Parameter 2798** 2799** ^The sqlite3_bind_parameter_name(P,N) interface returns 2800** the name of the N-th [SQL parameter] in the [prepared statement] P. 2801** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" 2802** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" 2803** respectively. 2804** In other words, the initial ":" or "$" or "@" or "?" 2805** is included as part of the name.)^ 2806** ^Parameters of the form "?" without a following integer have no name 2807** and are referred to as "nameless" or "anonymous parameters". 2808** 2809** ^The first host parameter has an index of 1, not 0. 2810** 2811** ^If the value N is out of range or if the N-th parameter is 2812** nameless, then NULL is returned. ^The returned string is 2813** always in UTF-8 encoding even if the named parameter was 2814** originally specified as UTF-16 in [sqlite3_prepare16()] or 2815** [sqlite3_prepare16_v2()]. 2816** 2817** See also: [sqlite3_bind_blob|sqlite3_bind()], 2818** [sqlite3_bind_parameter_count()], and 2819** [sqlite3_bind_parameter_index()]. 2820*/ 2821const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); 2822 2823/* 2824** CAPI3REF: Index Of A Parameter With A Given Name 2825** 2826** ^Return the index of an SQL parameter given its name. ^The 2827** index value returned is suitable for use as the second 2828** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero 2829** is returned if no matching parameter is found. ^The parameter 2830** name must be given in UTF-8 even if the original statement 2831** was prepared from UTF-16 text using [sqlite3_prepare16_v2()]. 2832** 2833** See also: [sqlite3_bind_blob|sqlite3_bind()], 2834** [sqlite3_bind_parameter_count()], and 2835** [sqlite3_bind_parameter_index()]. 2836*/ 2837int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); 2838 2839/* 2840** CAPI3REF: Reset All Bindings On A Prepared Statement 2841** 2842** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset 2843** the [sqlite3_bind_blob | bindings] on a [prepared statement]. 2844** ^Use this routine to reset all host parameters to NULL. 2845*/ 2846int sqlite3_clear_bindings(sqlite3_stmt*); 2847 2848/* 2849** CAPI3REF: Number Of Columns In A Result Set 2850** 2851** ^Return the number of columns in the result set returned by the 2852** [prepared statement]. ^This routine returns 0 if pStmt is an SQL 2853** statement that does not return data (for example an [UPDATE]). 2854** 2855** See also: [sqlite3_data_count()] 2856*/ 2857int sqlite3_column_count(sqlite3_stmt *pStmt); 2858 2859/* 2860** CAPI3REF: Column Names In A Result Set 2861** 2862** ^These routines return the name assigned to a particular column 2863** in the result set of a [SELECT] statement. ^The sqlite3_column_name() 2864** interface returns a pointer to a zero-terminated UTF-8 string 2865** and sqlite3_column_name16() returns a pointer to a zero-terminated 2866** UTF-16 string. ^The first parameter is the [prepared statement] 2867** that implements the [SELECT] statement. ^The second parameter is the 2868** column number. ^The leftmost column is number 0. 2869** 2870** ^The returned string pointer is valid until either the [prepared statement] 2871** is destroyed by [sqlite3_finalize()] or until the next call to 2872** sqlite3_column_name() or sqlite3_column_name16() on the same column. 2873** 2874** ^If sqlite3_malloc() fails during the processing of either routine 2875** (for example during a conversion from UTF-8 to UTF-16) then a 2876** NULL pointer is returned. 2877** 2878** ^The name of a result column is the value of the "AS" clause for 2879** that column, if there is an AS clause. If there is no AS clause 2880** then the name of the column is unspecified and may change from 2881** one release of SQLite to the next. 2882*/ 2883const char *sqlite3_column_name(sqlite3_stmt*, int N); 2884const void *sqlite3_column_name16(sqlite3_stmt*, int N); 2885 2886/* 2887** CAPI3REF: Source Of Data In A Query Result 2888** 2889** ^These routines provide a means to determine the database, table, and 2890** table column that is the origin of a particular result column in 2891** [SELECT] statement. 2892** ^The name of the database or table or column can be returned as 2893** either a UTF-8 or UTF-16 string. ^The _database_ routines return 2894** the database name, the _table_ routines return the table name, and 2895** the origin_ routines return the column name. 2896** ^The returned string is valid until the [prepared statement] is destroyed 2897** using [sqlite3_finalize()] or until the same information is requested 2898** again in a different encoding. 2899** 2900** ^The names returned are the original un-aliased names of the 2901** database, table, and column. 2902** 2903** ^The first argument to these interfaces is a [prepared statement]. 2904** ^These functions return information about the Nth result column returned by 2905** the statement, where N is the second function argument. 2906** ^The left-most column is column 0 for these routines. 2907** 2908** ^If the Nth column returned by the statement is an expression or 2909** subquery and is not a column value, then all of these functions return 2910** NULL. ^These routine might also return NULL if a memory allocation error 2911** occurs. ^Otherwise, they return the name of the attached database, table, 2912** or column that query result column was extracted from. 2913** 2914** ^As with all other SQLite APIs, those whose names end with "16" return 2915** UTF-16 encoded strings and the other functions return UTF-8. 2916** 2917** ^These APIs are only available if the library was compiled with the 2918** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol. 2919** 2920** If two or more threads call one or more of these routines against the same 2921** prepared statement and column at the same time then the results are 2922** undefined. 2923** 2924** If two or more threads call one or more 2925** [sqlite3_column_database_name | column metadata interfaces] 2926** for the same [prepared statement] and result column 2927** at the same time then the results are undefined. 2928*/ 2929const char *sqlite3_column_database_name(sqlite3_stmt*,int); 2930const void *sqlite3_column_database_name16(sqlite3_stmt*,int); 2931const char *sqlite3_column_table_name(sqlite3_stmt*,int); 2932const void *sqlite3_column_table_name16(sqlite3_stmt*,int); 2933const char *sqlite3_column_origin_name(sqlite3_stmt*,int); 2934const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); 2935 2936/* 2937** CAPI3REF: Declared Datatype Of A Query Result 2938** 2939** ^(The first parameter is a [prepared statement]. 2940** If this statement is a [SELECT] statement and the Nth column of the 2941** returned result set of that [SELECT] is a table column (not an 2942** expression or subquery) then the declared type of the table 2943** column is returned.)^ ^If the Nth column of the result set is an 2944** expression or subquery, then a NULL pointer is returned. 2945** ^The returned string is always UTF-8 encoded. 2946** 2947** ^(For example, given the database schema: 2948** 2949** CREATE TABLE t1(c1 VARIANT); 2950** 2951** and the following statement to be compiled: 2952** 2953** SELECT c1 + 1, c1 FROM t1; 2954** 2955** this routine would return the string "VARIANT" for the second result 2956** column (i==1), and a NULL pointer for the first result column (i==0).)^ 2957** 2958** ^SQLite uses dynamic run-time typing. ^So just because a column 2959** is declared to contain a particular type does not mean that the 2960** data stored in that column is of the declared type. SQLite is 2961** strongly typed, but the typing is dynamic not static. ^Type 2962** is associated with individual values, not with the containers 2963** used to hold those values. 2964*/ 2965const char *sqlite3_column_decltype(sqlite3_stmt*,int); 2966const void *sqlite3_column_decltype16(sqlite3_stmt*,int); 2967 2968/* 2969** CAPI3REF: Evaluate An SQL Statement 2970** 2971** After a [prepared statement] has been prepared using either 2972** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy 2973** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function 2974** must be called one or more times to evaluate the statement. 2975** 2976** The details of the behavior of the sqlite3_step() interface depend 2977** on whether the statement was prepared using the newer "v2" interface 2978** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy 2979** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the 2980** new "v2" interface is recommended for new applications but the legacy 2981** interface will continue to be supported. 2982** 2983** ^In the legacy interface, the return value will be either [SQLITE_BUSY], 2984** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. 2985** ^With the "v2" interface, any of the other [result codes] or 2986** [extended result codes] might be returned as well. 2987** 2988** ^[SQLITE_BUSY] means that the database engine was unable to acquire the 2989** database locks it needs to do its job. ^If the statement is a [COMMIT] 2990** or occurs outside of an explicit transaction, then you can retry the 2991** statement. If the statement is not a [COMMIT] and occurs within a 2992** explicit transaction then you should rollback the transaction before 2993** continuing. 2994** 2995** ^[SQLITE_DONE] means that the statement has finished executing 2996** successfully. sqlite3_step() should not be called again on this virtual 2997** machine without first calling [sqlite3_reset()] to reset the virtual 2998** machine back to its initial state. 2999** 3000** ^If the SQL statement being executed returns any data, then [SQLITE_ROW] 3001** is returned each time a new row of data is ready for processing by the 3002** caller. The values may be accessed using the [column access functions]. 3003** sqlite3_step() is called again to retrieve the next row of data. 3004** 3005** ^[SQLITE_ERROR] means that a run-time error (such as a constraint 3006** violation) has occurred. sqlite3_step() should not be called again on 3007** the VM. More information may be found by calling [sqlite3_errmsg()]. 3008** ^With the legacy interface, a more specific error code (for example, 3009** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth) 3010** can be obtained by calling [sqlite3_reset()] on the 3011** [prepared statement]. ^In the "v2" interface, 3012** the more specific error code is returned directly by sqlite3_step(). 3013** 3014** [SQLITE_MISUSE] means that the this routine was called inappropriately. 3015** Perhaps it was called on a [prepared statement] that has 3016** already been [sqlite3_finalize | finalized] or on one that had 3017** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could 3018** be the case that the same database connection is being used by two or 3019** more threads at the same moment in time. 3020** 3021** For all versions of SQLite up to and including 3.6.23.1, it was required 3022** after sqlite3_step() returned anything other than [SQLITE_ROW] that 3023** [sqlite3_reset()] be called before any subsequent invocation of 3024** sqlite3_step(). Failure to invoke [sqlite3_reset()] in this way would 3025** result in an [SQLITE_MISUSE] return from sqlite3_step(). But after 3026** version 3.6.23.1, sqlite3_step() began calling [sqlite3_reset()] 3027** automatically in this circumstance rather than returning [SQLITE_MISUSE]. 3028** 3029** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step() 3030** API always returns a generic error code, [SQLITE_ERROR], following any 3031** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call 3032** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the 3033** specific [error codes] that better describes the error. 3034** We admit that this is a goofy design. The problem has been fixed 3035** with the "v2" interface. If you prepare all of your SQL statements 3036** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead 3037** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces, 3038** then the more specific [error codes] are returned directly 3039** by sqlite3_step(). The use of the "v2" interface is recommended. 3040*/ 3041int sqlite3_step(sqlite3_stmt*); 3042 3043/* 3044** CAPI3REF: Number of columns in a result set 3045** 3046** ^The sqlite3_data_count(P) interface returns the number of columns in the 3047** current row of the result set of [prepared statement] P. 3048** ^If prepared statement P does not have results ready to return 3049** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of 3050** interfaces) then sqlite3_data_count(P) returns 0. 3051** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer. 3052** 3053** See also: [sqlite3_column_count()] 3054*/ 3055int sqlite3_data_count(sqlite3_stmt *pStmt); 3056 3057/* 3058** CAPI3REF: Fundamental Datatypes 3059** KEYWORDS: SQLITE_TEXT 3060** 3061** ^(Every value in SQLite has one of five fundamental datatypes: 3062** 3063** <ul> 3064** <li> 64-bit signed integer 3065** <li> 64-bit IEEE floating point number 3066** <li> string 3067** <li> BLOB 3068** <li> NULL 3069** </ul>)^ 3070** 3071** These constants are codes for each of those types. 3072** 3073** Note that the SQLITE_TEXT constant was also used in SQLite version 2 3074** for a completely different meaning. Software that links against both 3075** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not 3076** SQLITE_TEXT. 3077*/ 3078#define SQLITE_INTEGER 1 3079#define SQLITE_FLOAT 2 3080#define SQLITE_BLOB 4 3081#define SQLITE_NULL 5 3082#ifdef SQLITE_TEXT 3083# undef SQLITE_TEXT 3084#else 3085# define SQLITE_TEXT 3 3086#endif 3087#define SQLITE3_TEXT 3 3088 3089/* 3090** CAPI3REF: Result Values From A Query 3091** KEYWORDS: {column access functions} 3092** 3093** These routines form the "result set" interface. 3094** 3095** ^These routines return information about a single column of the current 3096** result row of a query. ^In every case the first argument is a pointer 3097** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*] 3098** that was returned from [sqlite3_prepare_v2()] or one of its variants) 3099** and the second argument is the index of the column for which information 3100** should be returned. ^The leftmost column of the result set has the index 0. 3101** ^The number of columns in the result can be determined using 3102** [sqlite3_column_count()]. 3103** 3104** If the SQL statement does not currently point to a valid row, or if the 3105** column index is out of range, the result is undefined. 3106** These routines may only be called when the most recent call to 3107** [sqlite3_step()] has returned [SQLITE_ROW] and neither 3108** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently. 3109** If any of these routines are called after [sqlite3_reset()] or 3110** [sqlite3_finalize()] or after [sqlite3_step()] has returned 3111** something other than [SQLITE_ROW], the results are undefined. 3112** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()] 3113** are called from a different thread while any of these routines 3114** are pending, then the results are undefined. 3115** 3116** ^The sqlite3_column_type() routine returns the 3117** [SQLITE_INTEGER | datatype code] for the initial data type 3118** of the result column. ^The returned value is one of [SQLITE_INTEGER], 3119** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value 3120** returned by sqlite3_column_type() is only meaningful if no type 3121** conversions have occurred as described below. After a type conversion, 3122** the value returned by sqlite3_column_type() is undefined. Future 3123** versions of SQLite may change the behavior of sqlite3_column_type() 3124** following a type conversion. 3125** 3126** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 3127** routine returns the number of bytes in that BLOB or string. 3128** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts 3129** the string to UTF-8 and then returns the number of bytes. 3130** ^If the result is a numeric value then sqlite3_column_bytes() uses 3131** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns 3132** the number of bytes in that string. 3133** ^If the result is NULL, then sqlite3_column_bytes() returns zero. 3134** 3135** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16() 3136** routine returns the number of bytes in that BLOB or string. 3137** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts 3138** the string to UTF-16 and then returns the number of bytes. 3139** ^If the result is a numeric value then sqlite3_column_bytes16() uses 3140** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns 3141** the number of bytes in that string. 3142** ^If the result is NULL, then sqlite3_column_bytes16() returns zero. 3143** 3144** ^The values returned by [sqlite3_column_bytes()] and 3145** [sqlite3_column_bytes16()] do not include the zero terminators at the end 3146** of the string. ^For clarity: the values returned by 3147** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of 3148** bytes in the string, not the number of characters. 3149** 3150** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(), 3151** even empty strings, are always zero terminated. ^The return 3152** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer. 3153** 3154** ^The object returned by [sqlite3_column_value()] is an 3155** [unprotected sqlite3_value] object. An unprotected sqlite3_value object 3156** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()]. 3157** If the [unprotected sqlite3_value] object returned by 3158** [sqlite3_column_value()] is used in any other way, including calls 3159** to routines like [sqlite3_value_int()], [sqlite3_value_text()], 3160** or [sqlite3_value_bytes()], then the behavior is undefined. 3161** 3162** These routines attempt to convert the value where appropriate. ^For 3163** example, if the internal representation is FLOAT and a text result 3164** is requested, [sqlite3_snprintf()] is used internally to perform the 3165** conversion automatically. ^(The following table details the conversions 3166** that are applied: 3167** 3168** <blockquote> 3169** <table border="1"> 3170** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion 3171** 3172** <tr><td> NULL <td> INTEGER <td> Result is 0 3173** <tr><td> NULL <td> FLOAT <td> Result is 0.0 3174** <tr><td> NULL <td> TEXT <td> Result is NULL pointer 3175** <tr><td> NULL <td> BLOB <td> Result is NULL pointer 3176** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float 3177** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer 3178** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT 3179** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer 3180** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float 3181** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT 3182** <tr><td> TEXT <td> INTEGER <td> Use atoi() 3183** <tr><td> TEXT <td> FLOAT <td> Use atof() 3184** <tr><td> TEXT <td> BLOB <td> No change 3185** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi() 3186** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof() 3187** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed 3188** </table> 3189** </blockquote>)^ 3190** 3191** The table above makes reference to standard C library functions atoi() 3192** and atof(). SQLite does not really use these functions. It has its 3193** own equivalent internal routines. The atoi() and atof() names are 3194** used in the table for brevity and because they are familiar to most 3195** C programmers. 3196** 3197** Note that when type conversions occur, pointers returned by prior 3198** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or 3199** sqlite3_column_text16() may be invalidated. 3200** Type conversions and pointer invalidations might occur 3201** in the following cases: 3202** 3203** <ul> 3204** <li> The initial content is a BLOB and sqlite3_column_text() or 3205** sqlite3_column_text16() is called. A zero-terminator might 3206** need to be added to the string.</li> 3207** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or 3208** sqlite3_column_text16() is called. The content must be converted 3209** to UTF-16.</li> 3210** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or 3211** sqlite3_column_text() is called. The content must be converted 3212** to UTF-8.</li> 3213** </ul> 3214** 3215** ^Conversions between UTF-16be and UTF-16le are always done in place and do 3216** not invalidate a prior pointer, though of course the content of the buffer 3217** that the prior pointer references will have been modified. Other kinds 3218** of conversion are done in place when it is possible, but sometimes they 3219** are not possible and in those cases prior pointers are invalidated. 3220** 3221** The safest and easiest to remember policy is to invoke these routines 3222** in one of the following ways: 3223** 3224** <ul> 3225** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li> 3226** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li> 3227** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li> 3228** </ul> 3229** 3230** In other words, you should call sqlite3_column_text(), 3231** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result 3232** into the desired format, then invoke sqlite3_column_bytes() or 3233** sqlite3_column_bytes16() to find the size of the result. Do not mix calls 3234** to sqlite3_column_text() or sqlite3_column_blob() with calls to 3235** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() 3236** with calls to sqlite3_column_bytes(). 3237** 3238** ^The pointers returned are valid until a type conversion occurs as 3239** described above, or until [sqlite3_step()] or [sqlite3_reset()] or 3240** [sqlite3_finalize()] is called. ^The memory space used to hold strings 3241** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned 3242** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into 3243** [sqlite3_free()]. 3244** 3245** ^(If a memory allocation error occurs during the evaluation of any 3246** of these routines, a default value is returned. The default value 3247** is either the integer 0, the floating point number 0.0, or a NULL 3248** pointer. Subsequent calls to [sqlite3_errcode()] will return 3249** [SQLITE_NOMEM].)^ 3250*/ 3251const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); 3252int sqlite3_column_bytes(sqlite3_stmt*, int iCol); 3253int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); 3254double sqlite3_column_double(sqlite3_stmt*, int iCol); 3255int sqlite3_column_int(sqlite3_stmt*, int iCol); 3256sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); 3257const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); 3258const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); 3259int sqlite3_column_type(sqlite3_stmt*, int iCol); 3260sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); 3261 3262/* 3263** CAPI3REF: Destroy A Prepared Statement Object 3264** 3265** ^The sqlite3_finalize() function is called to delete a [prepared statement]. 3266** ^If the most recent evaluation of the statement encountered no errors or 3267** or if the statement is never been evaluated, then sqlite3_finalize() returns 3268** SQLITE_OK. ^If the most recent evaluation of statement S failed, then 3269** sqlite3_finalize(S) returns the appropriate [error code] or 3270** [extended error code]. 3271** 3272** ^The sqlite3_finalize(S) routine can be called at any point during 3273** the life cycle of [prepared statement] S: 3274** before statement S is ever evaluated, after 3275** one or more calls to [sqlite3_reset()], or after any call 3276** to [sqlite3_step()] regardless of whether or not the statement has 3277** completed execution. 3278** 3279** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op. 3280** 3281** The application must finalize every [prepared statement] in order to avoid 3282** resource leaks. It is a grievous error for the application to try to use 3283** a prepared statement after it has been finalized. Any use of a prepared 3284** statement after it has been finalized can result in undefined and 3285** undesirable behavior such as segfaults and heap corruption. 3286*/ 3287int sqlite3_finalize(sqlite3_stmt *pStmt); 3288 3289/* 3290** CAPI3REF: Reset A Prepared Statement Object 3291** 3292** The sqlite3_reset() function is called to reset a [prepared statement] 3293** object back to its initial state, ready to be re-executed. 3294** ^Any SQL statement variables that had values bound to them using 3295** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. 3296** Use [sqlite3_clear_bindings()] to reset the bindings. 3297** 3298** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S 3299** back to the beginning of its program. 3300** 3301** ^If the most recent call to [sqlite3_step(S)] for the 3302** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE], 3303** or if [sqlite3_step(S)] has never before been called on S, 3304** then [sqlite3_reset(S)] returns [SQLITE_OK]. 3305** 3306** ^If the most recent call to [sqlite3_step(S)] for the 3307** [prepared statement] S indicated an error, then 3308** [sqlite3_reset(S)] returns an appropriate [error code]. 3309** 3310** ^The [sqlite3_reset(S)] interface does not change the values 3311** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S. 3312*/ 3313int sqlite3_reset(sqlite3_stmt *pStmt); 3314 3315/* 3316** CAPI3REF: Create Or Redefine SQL Functions 3317** KEYWORDS: {function creation routines} 3318** KEYWORDS: {application-defined SQL function} 3319** KEYWORDS: {application-defined SQL functions} 3320** 3321** ^These functions (collectively known as "function creation routines") 3322** are used to add SQL functions or aggregates or to redefine the behavior 3323** of existing SQL functions or aggregates. The only differences between 3324** these routines are the text encoding expected for 3325** the the second parameter (the name of the function being created) 3326** and the presence or absence of a destructor callback for 3327** the application data pointer. 3328** 3329** ^The first parameter is the [database connection] to which the SQL 3330** function is to be added. ^If an application uses more than one database 3331** connection then application-defined SQL functions must be added 3332** to each database connection separately. 3333** 3334** ^The second parameter is the name of the SQL function to be created or 3335** redefined. ^The length of the name is limited to 255 bytes in a UTF-8 3336** representation, exclusive of the zero-terminator. ^Note that the name 3337** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes. 3338** ^Any attempt to create a function with a longer name 3339** will result in [SQLITE_MISUSE] being returned. 3340** 3341** ^The third parameter (nArg) 3342** is the number of arguments that the SQL function or 3343** aggregate takes. ^If this parameter is -1, then the SQL function or 3344** aggregate may take any number of arguments between 0 and the limit 3345** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third 3346** parameter is less than -1 or greater than 127 then the behavior is 3347** undefined. 3348** 3349** ^The fourth parameter, eTextRep, specifies what 3350** [SQLITE_UTF8 | text encoding] this SQL function prefers for 3351** its parameters. Every SQL function implementation must be able to work 3352** with UTF-8, UTF-16le, or UTF-16be. But some implementations may be 3353** more efficient with one encoding than another. ^An application may 3354** invoke sqlite3_create_function() or sqlite3_create_function16() multiple 3355** times with the same function but with different values of eTextRep. 3356** ^When multiple implementations of the same function are available, SQLite 3357** will pick the one that involves the least amount of data conversion. 3358** If there is only a single implementation which does not care what text 3359** encoding is used, then the fourth argument should be [SQLITE_ANY]. 3360** 3361** ^(The fifth parameter is an arbitrary pointer. The implementation of the 3362** function can gain access to this pointer using [sqlite3_user_data()].)^ 3363** 3364** ^The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are 3365** pointers to C-language functions that implement the SQL function or 3366** aggregate. ^A scalar SQL function requires an implementation of the xFunc 3367** callback only; NULL pointers must be passed as the xStep and xFinal 3368** parameters. ^An aggregate SQL function requires an implementation of xStep 3369** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing 3370** SQL function or aggregate, pass NULL poiners for all three function 3371** callbacks. 3372** 3373** ^(If the tenth parameter to sqlite3_create_function_v2() is not NULL, 3374** then it is destructor for the application data pointer. 3375** The destructor is invoked when the function is deleted, either by being 3376** overloaded or when the database connection closes.)^ 3377** ^The destructor is also invoked if the call to 3378** sqlite3_create_function_v2() fails. 3379** ^When the destructor callback of the tenth parameter is invoked, it 3380** is passed a single argument which is a copy of the application data 3381** pointer which was the fifth parameter to sqlite3_create_function_v2(). 3382** 3383** ^It is permitted to register multiple implementations of the same 3384** functions with the same name but with either differing numbers of 3385** arguments or differing preferred text encodings. ^SQLite will use 3386** the implementation that most closely matches the way in which the 3387** SQL function is used. ^A function implementation with a non-negative 3388** nArg parameter is a better match than a function implementation with 3389** a negative nArg. ^A function where the preferred text encoding 3390** matches the database encoding is a better 3391** match than a function where the encoding is different. 3392** ^A function where the encoding difference is between UTF16le and UTF16be 3393** is a closer match than a function where the encoding difference is 3394** between UTF8 and UTF16. 3395** 3396** ^Built-in functions may be overloaded by new application-defined functions. 3397** 3398** ^An application-defined function is permitted to call other 3399** SQLite interfaces. However, such calls must not 3400** close the database connection nor finalize or reset the prepared 3401** statement in which the function is running. 3402*/ 3403int sqlite3_create_function( 3404 sqlite3 *db, 3405 const char *zFunctionName, 3406 int nArg, 3407 int eTextRep, 3408 void *pApp, 3409 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 3410 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 3411 void (*xFinal)(sqlite3_context*) 3412); 3413int sqlite3_create_function16( 3414 sqlite3 *db, 3415 const void *zFunctionName, 3416 int nArg, 3417 int eTextRep, 3418 void *pApp, 3419 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 3420 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 3421 void (*xFinal)(sqlite3_context*) 3422); 3423int sqlite3_create_function_v2( 3424 sqlite3 *db, 3425 const char *zFunctionName, 3426 int nArg, 3427 int eTextRep, 3428 void *pApp, 3429 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 3430 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 3431 void (*xFinal)(sqlite3_context*), 3432 void(*xDestroy)(void*) 3433); 3434 3435/* 3436** CAPI3REF: Text Encodings 3437** 3438** These constant define integer codes that represent the various 3439** text encodings supported by SQLite. 3440*/ 3441#define SQLITE_UTF8 1 3442#define SQLITE_UTF16LE 2 3443#define SQLITE_UTF16BE 3 3444#define SQLITE_UTF16 4 /* Use native byte order */ 3445#define SQLITE_ANY 5 /* sqlite3_create_function only */ 3446#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ 3447 3448/* 3449** CAPI3REF: Deprecated Functions 3450** DEPRECATED 3451** 3452** These functions are [deprecated]. In order to maintain 3453** backwards compatibility with older code, these functions continue 3454** to be supported. However, new applications should avoid 3455** the use of these functions. To help encourage people to avoid 3456** using these functions, we are not going to tell you what they do. 3457*/ 3458#ifndef SQLITE_OMIT_DEPRECATED 3459SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*); 3460SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*); 3461SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); 3462SQLITE_DEPRECATED int sqlite3_global_recover(void); 3463SQLITE_DEPRECATED void sqlite3_thread_cleanup(void); 3464SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); 3465#endif 3466 3467/* 3468** CAPI3REF: Obtaining SQL Function Parameter Values 3469** 3470** The C-language implementation of SQL functions and aggregates uses 3471** this set of interface routines to access the parameter values on 3472** the function or aggregate. 3473** 3474** The xFunc (for scalar functions) or xStep (for aggregates) parameters 3475** to [sqlite3_create_function()] and [sqlite3_create_function16()] 3476** define callbacks that implement the SQL functions and aggregates. 3477** The 4th parameter to these callbacks is an array of pointers to 3478** [protected sqlite3_value] objects. There is one [sqlite3_value] object for 3479** each parameter to the SQL function. These routines are used to 3480** extract values from the [sqlite3_value] objects. 3481** 3482** These routines work only with [protected sqlite3_value] objects. 3483** Any attempt to use these routines on an [unprotected sqlite3_value] 3484** object results in undefined behavior. 3485** 3486** ^These routines work just like the corresponding [column access functions] 3487** except that these routines take a single [protected sqlite3_value] object 3488** pointer instead of a [sqlite3_stmt*] pointer and an integer column number. 3489** 3490** ^The sqlite3_value_text16() interface extracts a UTF-16 string 3491** in the native byte-order of the host machine. ^The 3492** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces 3493** extract UTF-16 strings as big-endian and little-endian respectively. 3494** 3495** ^(The sqlite3_value_numeric_type() interface attempts to apply 3496** numeric affinity to the value. This means that an attempt is 3497** made to convert the value to an integer or floating point. If 3498** such a conversion is possible without loss of information (in other 3499** words, if the value is a string that looks like a number) 3500** then the conversion is performed. Otherwise no conversion occurs. 3501** The [SQLITE_INTEGER | datatype] after conversion is returned.)^ 3502** 3503** Please pay particular attention to the fact that the pointer returned 3504** from [sqlite3_value_blob()], [sqlite3_value_text()], or 3505** [sqlite3_value_text16()] can be invalidated by a subsequent call to 3506** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], 3507** or [sqlite3_value_text16()]. 3508** 3509** These routines must be called from the same thread as 3510** the SQL function that supplied the [sqlite3_value*] parameters. 3511*/ 3512const void *sqlite3_value_blob(sqlite3_value*); 3513int sqlite3_value_bytes(sqlite3_value*); 3514int sqlite3_value_bytes16(sqlite3_value*); 3515double sqlite3_value_double(sqlite3_value*); 3516int sqlite3_value_int(sqlite3_value*); 3517sqlite3_int64 sqlite3_value_int64(sqlite3_value*); 3518const unsigned char *sqlite3_value_text(sqlite3_value*); 3519const void *sqlite3_value_text16(sqlite3_value*); 3520const void *sqlite3_value_text16le(sqlite3_value*); 3521const void *sqlite3_value_text16be(sqlite3_value*); 3522int sqlite3_value_type(sqlite3_value*); 3523int sqlite3_value_numeric_type(sqlite3_value*); 3524 3525/* 3526** CAPI3REF: Obtain Aggregate Function Context 3527** 3528** Implementations of aggregate SQL functions use this 3529** routine to allocate memory for storing their state. 3530** 3531** ^The first time the sqlite3_aggregate_context(C,N) routine is called 3532** for a particular aggregate function, SQLite 3533** allocates N of memory, zeroes out that memory, and returns a pointer 3534** to the new memory. ^On second and subsequent calls to 3535** sqlite3_aggregate_context() for the same aggregate function instance, 3536** the same buffer is returned. Sqlite3_aggregate_context() is normally 3537** called once for each invocation of the xStep callback and then one 3538** last time when the xFinal callback is invoked. ^(When no rows match 3539** an aggregate query, the xStep() callback of the aggregate function 3540** implementation is never called and xFinal() is called exactly once. 3541** In those cases, sqlite3_aggregate_context() might be called for the 3542** first time from within xFinal().)^ 3543** 3544** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer if N is 3545** less than or equal to zero or if a memory allocate error occurs. 3546** 3547** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is 3548** determined by the N parameter on first successful call. Changing the 3549** value of N in subsequent call to sqlite3_aggregate_context() within 3550** the same aggregate function instance will not resize the memory 3551** allocation.)^ 3552** 3553** ^SQLite automatically frees the memory allocated by 3554** sqlite3_aggregate_context() when the aggregate query concludes. 3555** 3556** The first parameter must be a copy of the 3557** [sqlite3_context | SQL function context] that is the first parameter 3558** to the xStep or xFinal callback routine that implements the aggregate 3559** function. 3560** 3561** This routine must be called from the same thread in which 3562** the aggregate SQL function is running. 3563*/ 3564void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); 3565 3566/* 3567** CAPI3REF: User Data For Functions 3568** 3569** ^The sqlite3_user_data() interface returns a copy of 3570** the pointer that was the pUserData parameter (the 5th parameter) 3571** of the [sqlite3_create_function()] 3572** and [sqlite3_create_function16()] routines that originally 3573** registered the application defined function. 3574** 3575** This routine must be called from the same thread in which 3576** the application-defined function is running. 3577*/ 3578void *sqlite3_user_data(sqlite3_context*); 3579 3580/* 3581** CAPI3REF: Database Connection For Functions 3582** 3583** ^The sqlite3_context_db_handle() interface returns a copy of 3584** the pointer to the [database connection] (the 1st parameter) 3585** of the [sqlite3_create_function()] 3586** and [sqlite3_create_function16()] routines that originally 3587** registered the application defined function. 3588*/ 3589sqlite3 *sqlite3_context_db_handle(sqlite3_context*); 3590 3591/* 3592** CAPI3REF: Function Auxiliary Data 3593** 3594** The following two functions may be used by scalar SQL functions to 3595** associate metadata with argument values. If the same value is passed to 3596** multiple invocations of the same SQL function during query execution, under 3597** some circumstances the associated metadata may be preserved. This may 3598** be used, for example, to add a regular-expression matching scalar 3599** function. The compiled version of the regular expression is stored as 3600** metadata associated with the SQL value passed as the regular expression 3601** pattern. The compiled regular expression can be reused on multiple 3602** invocations of the same function so that the original pattern string 3603** does not need to be recompiled on each invocation. 3604** 3605** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata 3606** associated by the sqlite3_set_auxdata() function with the Nth argument 3607** value to the application-defined function. ^If no metadata has been ever 3608** been set for the Nth argument of the function, or if the corresponding 3609** function parameter has changed since the meta-data was set, 3610** then sqlite3_get_auxdata() returns a NULL pointer. 3611** 3612** ^The sqlite3_set_auxdata() interface saves the metadata 3613** pointed to by its 3rd parameter as the metadata for the N-th 3614** argument of the application-defined function. Subsequent 3615** calls to sqlite3_get_auxdata() might return this data, if it has 3616** not been destroyed. 3617** ^If it is not NULL, SQLite will invoke the destructor 3618** function given by the 4th parameter to sqlite3_set_auxdata() on 3619** the metadata when the corresponding function parameter changes 3620** or when the SQL statement completes, whichever comes first. 3621** 3622** SQLite is free to call the destructor and drop metadata on any 3623** parameter of any function at any time. ^The only guarantee is that 3624** the destructor will be called before the metadata is dropped. 3625** 3626** ^(In practice, metadata is preserved between function calls for 3627** expressions that are constant at compile time. This includes literal 3628** values and [parameters].)^ 3629** 3630** These routines must be called from the same thread in which 3631** the SQL function is running. 3632*/ 3633void *sqlite3_get_auxdata(sqlite3_context*, int N); 3634void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*)); 3635 3636 3637/* 3638** CAPI3REF: Constants Defining Special Destructor Behavior 3639** 3640** These are special values for the destructor that is passed in as the 3641** final argument to routines like [sqlite3_result_blob()]. ^If the destructor 3642** argument is SQLITE_STATIC, it means that the content pointer is constant 3643** and will never change. It does not need to be destroyed. ^The 3644** SQLITE_TRANSIENT value means that the content will likely change in 3645** the near future and that SQLite should make its own private copy of 3646** the content before returning. 3647** 3648** The typedef is necessary to work around problems in certain 3649** C++ compilers. See ticket #2191. 3650*/ 3651typedef void (*sqlite3_destructor_type)(void*); 3652#define SQLITE_STATIC ((sqlite3_destructor_type)0) 3653#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) 3654 3655/* 3656** CAPI3REF: Setting The Result Of An SQL Function 3657** 3658** These routines are used by the xFunc or xFinal callbacks that 3659** implement SQL functions and aggregates. See 3660** [sqlite3_create_function()] and [sqlite3_create_function16()] 3661** for additional information. 3662** 3663** These functions work very much like the [parameter binding] family of 3664** functions used to bind values to host parameters in prepared statements. 3665** Refer to the [SQL parameter] documentation for additional information. 3666** 3667** ^The sqlite3_result_blob() interface sets the result from 3668** an application-defined function to be the BLOB whose content is pointed 3669** to by the second parameter and which is N bytes long where N is the 3670** third parameter. 3671** 3672** ^The sqlite3_result_zeroblob() interfaces set the result of 3673** the application-defined function to be a BLOB containing all zero 3674** bytes and N bytes in size, where N is the value of the 2nd parameter. 3675** 3676** ^The sqlite3_result_double() interface sets the result from 3677** an application-defined function to be a floating point value specified 3678** by its 2nd argument. 3679** 3680** ^The sqlite3_result_error() and sqlite3_result_error16() functions 3681** cause the implemented SQL function to throw an exception. 3682** ^SQLite uses the string pointed to by the 3683** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16() 3684** as the text of an error message. ^SQLite interprets the error 3685** message string from sqlite3_result_error() as UTF-8. ^SQLite 3686** interprets the string from sqlite3_result_error16() as UTF-16 in native 3687** byte order. ^If the third parameter to sqlite3_result_error() 3688** or sqlite3_result_error16() is negative then SQLite takes as the error 3689** message all text up through the first zero character. 3690** ^If the third parameter to sqlite3_result_error() or 3691** sqlite3_result_error16() is non-negative then SQLite takes that many 3692** bytes (not characters) from the 2nd parameter as the error message. 3693** ^The sqlite3_result_error() and sqlite3_result_error16() 3694** routines make a private copy of the error message text before 3695** they return. Hence, the calling function can deallocate or 3696** modify the text after they return without harm. 3697** ^The sqlite3_result_error_code() function changes the error code 3698** returned by SQLite as a result of an error in a function. ^By default, 3699** the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error() 3700** or sqlite3_result_error16() resets the error code to SQLITE_ERROR. 3701** 3702** ^The sqlite3_result_toobig() interface causes SQLite to throw an error 3703** indicating that a string or BLOB is too long to represent. 3704** 3705** ^The sqlite3_result_nomem() interface causes SQLite to throw an error 3706** indicating that a memory allocation failed. 3707** 3708** ^The sqlite3_result_int() interface sets the return value 3709** of the application-defined function to be the 32-bit signed integer 3710** value given in the 2nd argument. 3711** ^The sqlite3_result_int64() interface sets the return value 3712** of the application-defined function to be the 64-bit signed integer 3713** value given in the 2nd argument. 3714** 3715** ^The sqlite3_result_null() interface sets the return value 3716** of the application-defined function to be NULL. 3717** 3718** ^The sqlite3_result_text(), sqlite3_result_text16(), 3719** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces 3720** set the return value of the application-defined function to be 3721** a text string which is represented as UTF-8, UTF-16 native byte order, 3722** UTF-16 little endian, or UTF-16 big endian, respectively. 3723** ^SQLite takes the text result from the application from 3724** the 2nd parameter of the sqlite3_result_text* interfaces. 3725** ^If the 3rd parameter to the sqlite3_result_text* interfaces 3726** is negative, then SQLite takes result text from the 2nd parameter 3727** through the first zero character. 3728** ^If the 3rd parameter to the sqlite3_result_text* interfaces 3729** is non-negative, then as many bytes (not characters) of the text 3730** pointed to by the 2nd parameter are taken as the application-defined 3731** function result. 3732** ^If the 4th parameter to the sqlite3_result_text* interfaces 3733** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that 3734** function as the destructor on the text or BLOB result when it has 3735** finished using that result. 3736** ^If the 4th parameter to the sqlite3_result_text* interfaces or to 3737** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite 3738** assumes that the text or BLOB result is in constant space and does not 3739** copy the content of the parameter nor call a destructor on the content 3740** when it has finished using that result. 3741** ^If the 4th parameter to the sqlite3_result_text* interfaces 3742** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT 3743** then SQLite makes a copy of the result into space obtained from 3744** from [sqlite3_malloc()] before it returns. 3745** 3746** ^The sqlite3_result_value() interface sets the result of 3747** the application-defined function to be a copy the 3748** [unprotected sqlite3_value] object specified by the 2nd parameter. ^The 3749** sqlite3_result_value() interface makes a copy of the [sqlite3_value] 3750** so that the [sqlite3_value] specified in the parameter may change or 3751** be deallocated after sqlite3_result_value() returns without harm. 3752** ^A [protected sqlite3_value] object may always be used where an 3753** [unprotected sqlite3_value] object is required, so either 3754** kind of [sqlite3_value] object can be used with this interface. 3755** 3756** If these routines are called from within the different thread 3757** than the one containing the application-defined function that received 3758** the [sqlite3_context] pointer, the results are undefined. 3759*/ 3760void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); 3761void sqlite3_result_double(sqlite3_context*, double); 3762void sqlite3_result_error(sqlite3_context*, const char*, int); 3763void sqlite3_result_error16(sqlite3_context*, const void*, int); 3764void sqlite3_result_error_toobig(sqlite3_context*); 3765void sqlite3_result_error_nomem(sqlite3_context*); 3766void sqlite3_result_error_code(sqlite3_context*, int); 3767void sqlite3_result_int(sqlite3_context*, int); 3768void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); 3769void sqlite3_result_null(sqlite3_context*); 3770void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); 3771void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); 3772void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); 3773void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); 3774void sqlite3_result_value(sqlite3_context*, sqlite3_value*); 3775void sqlite3_result_zeroblob(sqlite3_context*, int n); 3776 3777/* 3778** CAPI3REF: Define New Collating Sequences 3779** 3780** ^These functions add, remove, or modify a [collation] associated 3781** with the [database connection] specified as the first argument. 3782** 3783** ^The name of the collation is a UTF-8 string 3784** for sqlite3_create_collation() and sqlite3_create_collation_v2() 3785** and a UTF-16 string in native byte order for sqlite3_create_collation16(). 3786** ^Collation names that compare equal according to [sqlite3_strnicmp()] are 3787** considered to be the same name. 3788** 3789** ^(The third argument (eTextRep) must be one of the constants: 3790** <ul> 3791** <li> [SQLITE_UTF8], 3792** <li> [SQLITE_UTF16LE], 3793** <li> [SQLITE_UTF16BE], 3794** <li> [SQLITE_UTF16], or 3795** <li> [SQLITE_UTF16_ALIGNED]. 3796** </ul>)^ 3797** ^The eTextRep argument determines the encoding of strings passed 3798** to the collating function callback, xCallback. 3799** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep 3800** force strings to be UTF16 with native byte order. 3801** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin 3802** on an even byte address. 3803** 3804** ^The fourth argument, pArg, is a application data pointer that is passed 3805** through as the first argument to the collating function callback. 3806** 3807** ^The fifth argument, xCallback, is a pointer to the collating function. 3808** ^Multiple collating functions can be registered using the same name but 3809** with different eTextRep parameters and SQLite will use whichever 3810** function requires the least amount of data transformation. 3811** ^If the xCallback argument is NULL then the collating function is 3812** deleted. ^When all collating functions having the same name are deleted, 3813** that collation is no longer usable. 3814** 3815** ^The collating function callback is invoked with a copy of the pArg 3816** application data pointer and with two strings in the encoding specified 3817** by the eTextRep argument. The collating function must return an 3818** integer that is negative, zero, or positive 3819** if the first string is less than, equal to, or greater than the second, 3820** respectively. A collating function must alway return the same answer 3821** given the same inputs. If two or more collating functions are registered 3822** to the same collation name (using different eTextRep values) then all 3823** must give an equivalent answer when invoked with equivalent strings. 3824** The collating function must obey the following properties for all 3825** strings A, B, and C: 3826** 3827** <ol> 3828** <li> If A==B then B==A. 3829** <li> If A==B and B==C then A==C. 3830** <li> If A<B THEN B>A. 3831** <li> If A<B and B<C then A<C. 3832** </ol> 3833** 3834** If a collating function fails any of the above constraints and that 3835** collating function is registered and used, then the behavior of SQLite 3836** is undefined. 3837** 3838** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation() 3839** with the addition that the xDestroy callback is invoked on pArg when 3840** the collating function is deleted. 3841** ^Collating functions are deleted when they are overridden by later 3842** calls to the collation creation functions or when the 3843** [database connection] is closed using [sqlite3_close()]. 3844** 3845** ^The xDestroy callback is <u>not</u> called if the 3846** sqlite3_create_collation_v2() function fails. Applications that invoke 3847** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should 3848** check the return code and dispose of the application data pointer 3849** themselves rather than expecting SQLite to deal with it for them. 3850** This is different from every other SQLite interface. The inconsistency 3851** is unfortunate but cannot be changed without breaking backwards 3852** compatibility. 3853** 3854** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()]. 3855*/ 3856int sqlite3_create_collation( 3857 sqlite3*, 3858 const char *zName, 3859 int eTextRep, 3860 void *pArg, 3861 int(*xCompare)(void*,int,const void*,int,const void*) 3862); 3863int sqlite3_create_collation_v2( 3864 sqlite3*, 3865 const char *zName, 3866 int eTextRep, 3867 void *pArg, 3868 int(*xCompare)(void*,int,const void*,int,const void*), 3869 void(*xDestroy)(void*) 3870); 3871int sqlite3_create_collation16( 3872 sqlite3*, 3873 const void *zName, 3874 int eTextRep, 3875 void *pArg, 3876 int(*xCompare)(void*,int,const void*,int,const void*) 3877); 3878 3879/* 3880** CAPI3REF: Collation Needed Callbacks 3881** 3882** ^To avoid having to register all collation sequences before a database 3883** can be used, a single callback function may be registered with the 3884** [database connection] to be invoked whenever an undefined collation 3885** sequence is required. 3886** 3887** ^If the function is registered using the sqlite3_collation_needed() API, 3888** then it is passed the names of undefined collation sequences as strings 3889** encoded in UTF-8. ^If sqlite3_collation_needed16() is used, 3890** the names are passed as UTF-16 in machine native byte order. 3891** ^A call to either function replaces the existing collation-needed callback. 3892** 3893** ^(When the callback is invoked, the first argument passed is a copy 3894** of the second argument to sqlite3_collation_needed() or 3895** sqlite3_collation_needed16(). The second argument is the database 3896** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], 3897** or [SQLITE_UTF16LE], indicating the most desirable form of the collation 3898** sequence function required. The fourth parameter is the name of the 3899** required collation sequence.)^ 3900** 3901** The callback function should register the desired collation using 3902** [sqlite3_create_collation()], [sqlite3_create_collation16()], or 3903** [sqlite3_create_collation_v2()]. 3904*/ 3905int sqlite3_collation_needed( 3906 sqlite3*, 3907 void*, 3908 void(*)(void*,sqlite3*,int eTextRep,const char*) 3909); 3910int sqlite3_collation_needed16( 3911 sqlite3*, 3912 void*, 3913 void(*)(void*,sqlite3*,int eTextRep,const void*) 3914); 3915 3916#ifdef SQLITE_HAS_CODEC 3917/* 3918** Specify the key for an encrypted database. This routine should be 3919** called right after sqlite3_open(). 3920** 3921** The code to implement this API is not available in the public release 3922** of SQLite. 3923*/ 3924int sqlite3_key( 3925 sqlite3 *db, /* Database to be rekeyed */ 3926 const void *pKey, int nKey /* The key */ 3927); 3928 3929/* 3930** Change the key on an open database. If the current database is not 3931** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the 3932** database is decrypted. 3933** 3934** The code to implement this API is not available in the public release 3935** of SQLite. 3936*/ 3937int sqlite3_rekey( 3938 sqlite3 *db, /* Database to be rekeyed */ 3939 const void *pKey, int nKey /* The new key */ 3940); 3941 3942/* 3943** Specify the activation key for a SEE database. Unless 3944** activated, none of the SEE routines will work. 3945*/ 3946void sqlite3_activate_see( 3947 const char *zPassPhrase /* Activation phrase */ 3948); 3949#endif 3950 3951#ifdef SQLITE_ENABLE_CEROD 3952/* 3953** Specify the activation key for a CEROD database. Unless 3954** activated, none of the CEROD routines will work. 3955*/ 3956void sqlite3_activate_cerod( 3957 const char *zPassPhrase /* Activation phrase */ 3958); 3959#endif 3960 3961/* 3962** CAPI3REF: Suspend Execution For A Short Time 3963** 3964** The sqlite3_sleep() function causes the current thread to suspend execution 3965** for at least a number of milliseconds specified in its parameter. 3966** 3967** If the operating system does not support sleep requests with 3968** millisecond time resolution, then the time will be rounded up to 3969** the nearest second. The number of milliseconds of sleep actually 3970** requested from the operating system is returned. 3971** 3972** ^SQLite implements this interface by calling the xSleep() 3973** method of the default [sqlite3_vfs] object. If the xSleep() method 3974** of the default VFS is not implemented correctly, or not implemented at 3975** all, then the behavior of sqlite3_sleep() may deviate from the description 3976** in the previous paragraphs. 3977*/ 3978int sqlite3_sleep(int); 3979 3980/* 3981** CAPI3REF: Name Of The Folder Holding Temporary Files 3982** 3983** ^(If this global variable is made to point to a string which is 3984** the name of a folder (a.k.a. directory), then all temporary files 3985** created by SQLite when using a built-in [sqlite3_vfs | VFS] 3986** will be placed in that directory.)^ ^If this variable 3987** is a NULL pointer, then SQLite performs a search for an appropriate 3988** temporary file directory. 3989** 3990** It is not safe to read or modify this variable in more than one 3991** thread at a time. It is not safe to read or modify this variable 3992** if a [database connection] is being used at the same time in a separate 3993** thread. 3994** It is intended that this variable be set once 3995** as part of process initialization and before any SQLite interface 3996** routines have been called and that this variable remain unchanged 3997** thereafter. 3998** 3999** ^The [temp_store_directory pragma] may modify this variable and cause 4000** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore, 4001** the [temp_store_directory pragma] always assumes that any string 4002** that this variable points to is held in memory obtained from 4003** [sqlite3_malloc] and the pragma may attempt to free that memory 4004** using [sqlite3_free]. 4005** Hence, if this variable is modified directly, either it should be 4006** made NULL or made to point to memory obtained from [sqlite3_malloc] 4007** or else the use of the [temp_store_directory pragma] should be avoided. 4008*/ 4009SQLITE_EXTERN char *sqlite3_temp_directory; 4010 4011/* 4012** CAPI3REF: Test For Auto-Commit Mode 4013** KEYWORDS: {autocommit mode} 4014** 4015** ^The sqlite3_get_autocommit() interface returns non-zero or 4016** zero if the given database connection is or is not in autocommit mode, 4017** respectively. ^Autocommit mode is on by default. 4018** ^Autocommit mode is disabled by a [BEGIN] statement. 4019** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK]. 4020** 4021** If certain kinds of errors occur on a statement within a multi-statement 4022** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR], 4023** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the 4024** transaction might be rolled back automatically. The only way to 4025** find out whether SQLite automatically rolled back the transaction after 4026** an error is to use this function. 4027** 4028** If another thread changes the autocommit status of the database 4029** connection while this routine is running, then the return value 4030** is undefined. 4031*/ 4032int sqlite3_get_autocommit(sqlite3*); 4033 4034/* 4035** CAPI3REF: Find The Database Handle Of A Prepared Statement 4036** 4037** ^The sqlite3_db_handle interface returns the [database connection] handle 4038** to which a [prepared statement] belongs. ^The [database connection] 4039** returned by sqlite3_db_handle is the same [database connection] 4040** that was the first argument 4041** to the [sqlite3_prepare_v2()] call (or its variants) that was used to 4042** create the statement in the first place. 4043*/ 4044sqlite3 *sqlite3_db_handle(sqlite3_stmt*); 4045 4046/* 4047** CAPI3REF: Find the next prepared statement 4048** 4049** ^This interface returns a pointer to the next [prepared statement] after 4050** pStmt associated with the [database connection] pDb. ^If pStmt is NULL 4051** then this interface returns a pointer to the first prepared statement 4052** associated with the database connection pDb. ^If no prepared statement 4053** satisfies the conditions of this routine, it returns NULL. 4054** 4055** The [database connection] pointer D in a call to 4056** [sqlite3_next_stmt(D,S)] must refer to an open database 4057** connection and in particular must not be a NULL pointer. 4058*/ 4059sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt); 4060 4061/* 4062** CAPI3REF: Commit And Rollback Notification Callbacks 4063** 4064** ^The sqlite3_commit_hook() interface registers a callback 4065** function to be invoked whenever a transaction is [COMMIT | committed]. 4066** ^Any callback set by a previous call to sqlite3_commit_hook() 4067** for the same database connection is overridden. 4068** ^The sqlite3_rollback_hook() interface registers a callback 4069** function to be invoked whenever a transaction is [ROLLBACK | rolled back]. 4070** ^Any callback set by a previous call to sqlite3_rollback_hook() 4071** for the same database connection is overridden. 4072** ^The pArg argument is passed through to the callback. 4073** ^If the callback on a commit hook function returns non-zero, 4074** then the commit is converted into a rollback. 4075** 4076** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions 4077** return the P argument from the previous call of the same function 4078** on the same [database connection] D, or NULL for 4079** the first call for each function on D. 4080** 4081** The callback implementation must not do anything that will modify 4082** the database connection that invoked the callback. Any actions 4083** to modify the database connection must be deferred until after the 4084** completion of the [sqlite3_step()] call that triggered the commit 4085** or rollback hook in the first place. 4086** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their 4087** database connections for the meaning of "modify" in this paragraph. 4088** 4089** ^Registering a NULL function disables the callback. 4090** 4091** ^When the commit hook callback routine returns zero, the [COMMIT] 4092** operation is allowed to continue normally. ^If the commit hook 4093** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK]. 4094** ^The rollback hook is invoked on a rollback that results from a commit 4095** hook returning non-zero, just as it would be with any other rollback. 4096** 4097** ^For the purposes of this API, a transaction is said to have been 4098** rolled back if an explicit "ROLLBACK" statement is executed, or 4099** an error or constraint causes an implicit rollback to occur. 4100** ^The rollback callback is not invoked if a transaction is 4101** automatically rolled back because the database connection is closed. 4102** 4103** See also the [sqlite3_update_hook()] interface. 4104*/ 4105void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); 4106void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); 4107 4108/* 4109** CAPI3REF: Data Change Notification Callbacks 4110** 4111** ^The sqlite3_update_hook() interface registers a callback function 4112** with the [database connection] identified by the first argument 4113** to be invoked whenever a row is updated, inserted or deleted. 4114** ^Any callback set by a previous call to this function 4115** for the same database connection is overridden. 4116** 4117** ^The second argument is a pointer to the function to invoke when a 4118** row is updated, inserted or deleted. 4119** ^The first argument to the callback is a copy of the third argument 4120** to sqlite3_update_hook(). 4121** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE], 4122** or [SQLITE_UPDATE], depending on the operation that caused the callback 4123** to be invoked. 4124** ^The third and fourth arguments to the callback contain pointers to the 4125** database and table name containing the affected row. 4126** ^The final callback parameter is the [rowid] of the row. 4127** ^In the case of an update, this is the [rowid] after the update takes place. 4128** 4129** ^(The update hook is not invoked when internal system tables are 4130** modified (i.e. sqlite_master and sqlite_sequence).)^ 4131** 4132** ^In the current implementation, the update hook 4133** is not invoked when duplication rows are deleted because of an 4134** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook 4135** invoked when rows are deleted using the [truncate optimization]. 4136** The exceptions defined in this paragraph might change in a future 4137** release of SQLite. 4138** 4139** The update hook implementation must not do anything that will modify 4140** the database connection that invoked the update hook. Any actions 4141** to modify the database connection must be deferred until after the 4142** completion of the [sqlite3_step()] call that triggered the update hook. 4143** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their 4144** database connections for the meaning of "modify" in this paragraph. 4145** 4146** ^The sqlite3_update_hook(D,C,P) function 4147** returns the P argument from the previous call 4148** on the same [database connection] D, or NULL for 4149** the first call on D. 4150** 4151** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()] 4152** interfaces. 4153*/ 4154void *sqlite3_update_hook( 4155 sqlite3*, 4156 void(*)(void *,int ,char const *,char const *,sqlite3_int64), 4157 void* 4158); 4159 4160/* 4161** CAPI3REF: Enable Or Disable Shared Pager Cache 4162** KEYWORDS: {shared cache} 4163** 4164** ^(This routine enables or disables the sharing of the database cache 4165** and schema data structures between [database connection | connections] 4166** to the same database. Sharing is enabled if the argument is true 4167** and disabled if the argument is false.)^ 4168** 4169** ^Cache sharing is enabled and disabled for an entire process. 4170** This is a change as of SQLite version 3.5.0. In prior versions of SQLite, 4171** sharing was enabled or disabled for each thread separately. 4172** 4173** ^(The cache sharing mode set by this interface effects all subsequent 4174** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. 4175** Existing database connections continue use the sharing mode 4176** that was in effect at the time they were opened.)^ 4177** 4178** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled 4179** successfully. An [error code] is returned otherwise.)^ 4180** 4181** ^Shared cache is disabled by default. But this might change in 4182** future releases of SQLite. Applications that care about shared 4183** cache setting should set it explicitly. 4184** 4185** See Also: [SQLite Shared-Cache Mode] 4186*/ 4187int sqlite3_enable_shared_cache(int); 4188 4189/* 4190** CAPI3REF: Attempt To Free Heap Memory 4191** 4192** ^The sqlite3_release_memory() interface attempts to free N bytes 4193** of heap memory by deallocating non-essential memory allocations 4194** held by the database library. Memory used to cache database 4195** pages to improve performance is an example of non-essential memory. 4196** ^sqlite3_release_memory() returns the number of bytes actually freed, 4197** which might be more or less than the amount requested. 4198** ^The sqlite3_release_memory() routine is a no-op returning zero 4199** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT]. 4200*/ 4201int sqlite3_release_memory(int); 4202 4203/* 4204** CAPI3REF: Impose A Limit On Heap Size 4205** 4206** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the 4207** soft limit on the amount of heap memory that may be allocated by SQLite. 4208** ^SQLite strives to keep heap memory utilization below the soft heap 4209** limit by reducing the number of pages held in the page cache 4210** as heap memory usages approaches the limit. 4211** ^The soft heap limit is "soft" because even though SQLite strives to stay 4212** below the limit, it will exceed the limit rather than generate 4213** an [SQLITE_NOMEM] error. In other words, the soft heap limit 4214** is advisory only. 4215** 4216** ^The return value from sqlite3_soft_heap_limit64() is the size of 4217** the soft heap limit prior to the call. ^If the argument N is negative 4218** then no change is made to the soft heap limit. Hence, the current 4219** size of the soft heap limit can be determined by invoking 4220** sqlite3_soft_heap_limit64() with a negative argument. 4221** 4222** ^If the argument N is zero then the soft heap limit is disabled. 4223** 4224** ^(The soft heap limit is not enforced in the current implementation 4225** if one or more of following conditions are true: 4226** 4227** <ul> 4228** <li> The soft heap limit is set to zero. 4229** <li> Memory accounting is disabled using a combination of the 4230** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and 4231** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option. 4232** <li> An alternative page cache implementation is specifed using 4233** [sqlite3_config]([SQLITE_CONFIG_PCACHE],...). 4234** <li> The page cache allocates from its own memory pool supplied 4235** by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than 4236** from the heap. 4237** </ul>)^ 4238** 4239** Beginning with SQLite version 3.7.3, the soft heap limit is enforced 4240** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT] 4241** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT], 4242** the soft heap limit is enforced on every memory allocation. Without 4243** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced 4244** when memory is allocated by the page cache. Testing suggests that because 4245** the page cache is the predominate memory user in SQLite, most 4246** applications will achieve adequate soft heap limit enforcement without 4247** the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT]. 4248** 4249** The circumstances under which SQLite will enforce the soft heap limit may 4250** changes in future releases of SQLite. 4251*/ 4252sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N); 4253 4254/* 4255** CAPI3REF: Deprecated Soft Heap Limit Interface 4256** DEPRECATED 4257** 4258** This is a deprecated version of the [sqlite3_soft_heap_limit64()] 4259** interface. This routine is provided for historical compatibility 4260** only. All new applications should use the 4261** [sqlite3_soft_heap_limit64()] interface rather than this one. 4262*/ 4263SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N); 4264 4265 4266/* 4267** CAPI3REF: Extract Metadata About A Column Of A Table 4268** 4269** ^This routine returns metadata about a specific column of a specific 4270** database table accessible using the [database connection] handle 4271** passed as the first function argument. 4272** 4273** ^The column is identified by the second, third and fourth parameters to 4274** this function. ^The second parameter is either the name of the database 4275** (i.e. "main", "temp", or an attached database) containing the specified 4276** table or NULL. ^If it is NULL, then all attached databases are searched 4277** for the table using the same algorithm used by the database engine to 4278** resolve unqualified table references. 4279** 4280** ^The third and fourth parameters to this function are the table and column 4281** name of the desired column, respectively. Neither of these parameters 4282** may be NULL. 4283** 4284** ^Metadata is returned by writing to the memory locations passed as the 5th 4285** and subsequent parameters to this function. ^Any of these arguments may be 4286** NULL, in which case the corresponding element of metadata is omitted. 4287** 4288** ^(<blockquote> 4289** <table border="1"> 4290** <tr><th> Parameter <th> Output<br>Type <th> Description 4291** 4292** <tr><td> 5th <td> const char* <td> Data type 4293** <tr><td> 6th <td> const char* <td> Name of default collation sequence 4294** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint 4295** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY 4296** <tr><td> 9th <td> int <td> True if column is [AUTOINCREMENT] 4297** </table> 4298** </blockquote>)^ 4299** 4300** ^The memory pointed to by the character pointers returned for the 4301** declaration type and collation sequence is valid only until the next 4302** call to any SQLite API function. 4303** 4304** ^If the specified table is actually a view, an [error code] is returned. 4305** 4306** ^If the specified column is "rowid", "oid" or "_rowid_" and an 4307** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output 4308** parameters are set for the explicitly declared column. ^(If there is no 4309** explicitly declared [INTEGER PRIMARY KEY] column, then the output 4310** parameters are set as follows: 4311** 4312** <pre> 4313** data type: "INTEGER" 4314** collation sequence: "BINARY" 4315** not null: 0 4316** primary key: 1 4317** auto increment: 0 4318** </pre>)^ 4319** 4320** ^(This function may load one or more schemas from database files. If an 4321** error occurs during this process, or if the requested table or column 4322** cannot be found, an [error code] is returned and an error message left 4323** in the [database connection] (to be retrieved using sqlite3_errmsg()).)^ 4324** 4325** ^This API is only available if the library was compiled with the 4326** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined. 4327*/ 4328int sqlite3_table_column_metadata( 4329 sqlite3 *db, /* Connection handle */ 4330 const char *zDbName, /* Database name or NULL */ 4331 const char *zTableName, /* Table name */ 4332 const char *zColumnName, /* Column name */ 4333 char const **pzDataType, /* OUTPUT: Declared data type */ 4334 char const **pzCollSeq, /* OUTPUT: Collation sequence name */ 4335 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ 4336 int *pPrimaryKey, /* OUTPUT: True if column part of PK */ 4337 int *pAutoinc /* OUTPUT: True if column is auto-increment */ 4338); 4339 4340/* 4341** CAPI3REF: Load An Extension 4342** 4343** ^This interface loads an SQLite extension library from the named file. 4344** 4345** ^The sqlite3_load_extension() interface attempts to load an 4346** SQLite extension library contained in the file zFile. 4347** 4348** ^The entry point is zProc. 4349** ^zProc may be 0, in which case the name of the entry point 4350** defaults to "sqlite3_extension_init". 4351** ^The sqlite3_load_extension() interface returns 4352** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. 4353** ^If an error occurs and pzErrMsg is not 0, then the 4354** [sqlite3_load_extension()] interface shall attempt to 4355** fill *pzErrMsg with error message text stored in memory 4356** obtained from [sqlite3_malloc()]. The calling function 4357** should free this memory by calling [sqlite3_free()]. 4358** 4359** ^Extension loading must be enabled using 4360** [sqlite3_enable_load_extension()] prior to calling this API, 4361** otherwise an error will be returned. 4362** 4363** See also the [load_extension() SQL function]. 4364*/ 4365int sqlite3_load_extension( 4366 sqlite3 *db, /* Load the extension into this database connection */ 4367 const char *zFile, /* Name of the shared library containing extension */ 4368 const char *zProc, /* Entry point. Derived from zFile if 0 */ 4369 char **pzErrMsg /* Put error message here if not 0 */ 4370); 4371 4372/* 4373** CAPI3REF: Enable Or Disable Extension Loading 4374** 4375** ^So as not to open security holes in older applications that are 4376** unprepared to deal with extension loading, and as a means of disabling 4377** extension loading while evaluating user-entered SQL, the following API 4378** is provided to turn the [sqlite3_load_extension()] mechanism on and off. 4379** 4380** ^Extension loading is off by default. See ticket #1863. 4381** ^Call the sqlite3_enable_load_extension() routine with onoff==1 4382** to turn extension loading on and call it with onoff==0 to turn 4383** it back off again. 4384*/ 4385int sqlite3_enable_load_extension(sqlite3 *db, int onoff); 4386 4387/* 4388** CAPI3REF: Automatically Load Statically Linked Extensions 4389** 4390** ^This interface causes the xEntryPoint() function to be invoked for 4391** each new [database connection] that is created. The idea here is that 4392** xEntryPoint() is the entry point for a statically linked SQLite extension 4393** that is to be automatically loaded into all new database connections. 4394** 4395** ^(Even though the function prototype shows that xEntryPoint() takes 4396** no arguments and returns void, SQLite invokes xEntryPoint() with three 4397** arguments and expects and integer result as if the signature of the 4398** entry point where as follows: 4399** 4400** <blockquote><pre> 4401** int xEntryPoint( 4402** sqlite3 *db, 4403** const char **pzErrMsg, 4404** const struct sqlite3_api_routines *pThunk 4405** ); 4406** </pre></blockquote>)^ 4407** 4408** If the xEntryPoint routine encounters an error, it should make *pzErrMsg 4409** point to an appropriate error message (obtained from [sqlite3_mprintf()]) 4410** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg 4411** is NULL before calling the xEntryPoint(). ^SQLite will invoke 4412** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns. ^If any 4413** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()], 4414** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail. 4415** 4416** ^Calling sqlite3_auto_extension(X) with an entry point X that is already 4417** on the list of automatic extensions is a harmless no-op. ^No entry point 4418** will be called more than once for each database connection that is opened. 4419** 4420** See also: [sqlite3_reset_auto_extension()]. 4421*/ 4422int sqlite3_auto_extension(void (*xEntryPoint)(void)); 4423 4424/* 4425** CAPI3REF: Reset Automatic Extension Loading 4426** 4427** ^This interface disables all automatic extensions previously 4428** registered using [sqlite3_auto_extension()]. 4429*/ 4430void sqlite3_reset_auto_extension(void); 4431 4432/* 4433** The interface to the virtual-table mechanism is currently considered 4434** to be experimental. The interface might change in incompatible ways. 4435** If this is a problem for you, do not use the interface at this time. 4436** 4437** When the virtual-table mechanism stabilizes, we will declare the 4438** interface fixed, support it indefinitely, and remove this comment. 4439*/ 4440 4441/* 4442** Structures used by the virtual table interface 4443*/ 4444typedef struct sqlite3_vtab sqlite3_vtab; 4445typedef struct sqlite3_index_info sqlite3_index_info; 4446typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; 4447typedef struct sqlite3_module sqlite3_module; 4448 4449/* 4450** CAPI3REF: Virtual Table Object 4451** KEYWORDS: sqlite3_module {virtual table module} 4452** 4453** This structure, sometimes called a a "virtual table module", 4454** defines the implementation of a [virtual tables]. 4455** This structure consists mostly of methods for the module. 4456** 4457** ^A virtual table module is created by filling in a persistent 4458** instance of this structure and passing a pointer to that instance 4459** to [sqlite3_create_module()] or [sqlite3_create_module_v2()]. 4460** ^The registration remains valid until it is replaced by a different 4461** module or until the [database connection] closes. The content 4462** of this structure must not change while it is registered with 4463** any database connection. 4464*/ 4465struct sqlite3_module { 4466 int iVersion; 4467 int (*xCreate)(sqlite3*, void *pAux, 4468 int argc, const char *const*argv, 4469 sqlite3_vtab **ppVTab, char**); 4470 int (*xConnect)(sqlite3*, void *pAux, 4471 int argc, const char *const*argv, 4472 sqlite3_vtab **ppVTab, char**); 4473 int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); 4474 int (*xDisconnect)(sqlite3_vtab *pVTab); 4475 int (*xDestroy)(sqlite3_vtab *pVTab); 4476 int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor); 4477 int (*xClose)(sqlite3_vtab_cursor*); 4478 int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr, 4479 int argc, sqlite3_value **argv); 4480 int (*xNext)(sqlite3_vtab_cursor*); 4481 int (*xEof)(sqlite3_vtab_cursor*); 4482 int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int); 4483 int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid); 4484 int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *); 4485 int (*xBegin)(sqlite3_vtab *pVTab); 4486 int (*xSync)(sqlite3_vtab *pVTab); 4487 int (*xCommit)(sqlite3_vtab *pVTab); 4488 int (*xRollback)(sqlite3_vtab *pVTab); 4489 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, 4490 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), 4491 void **ppArg); 4492 int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); 4493}; 4494 4495/* 4496** CAPI3REF: Virtual Table Indexing Information 4497** KEYWORDS: sqlite3_index_info 4498** 4499** The sqlite3_index_info structure and its substructures is used as part 4500** of the [virtual table] interface to 4501** pass information into and receive the reply from the [xBestIndex] 4502** method of a [virtual table module]. The fields under **Inputs** are the 4503** inputs to xBestIndex and are read-only. xBestIndex inserts its 4504** results into the **Outputs** fields. 4505** 4506** ^(The aConstraint[] array records WHERE clause constraints of the form: 4507** 4508** <blockquote>column OP expr</blockquote> 4509** 4510** where OP is =, <, <=, >, or >=.)^ ^(The particular operator is 4511** stored in aConstraint[].op using one of the 4512** [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^ 4513** ^(The index of the column is stored in 4514** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the 4515** expr on the right-hand side can be evaluated (and thus the constraint 4516** is usable) and false if it cannot.)^ 4517** 4518** ^The optimizer automatically inverts terms of the form "expr OP column" 4519** and makes other simplifications to the WHERE clause in an attempt to 4520** get as many WHERE clause terms into the form shown above as possible. 4521** ^The aConstraint[] array only reports WHERE clause terms that are 4522** relevant to the particular virtual table being queried. 4523** 4524** ^Information about the ORDER BY clause is stored in aOrderBy[]. 4525** ^Each term of aOrderBy records a column of the ORDER BY clause. 4526** 4527** The [xBestIndex] method must fill aConstraintUsage[] with information 4528** about what parameters to pass to xFilter. ^If argvIndex>0 then 4529** the right-hand side of the corresponding aConstraint[] is evaluated 4530** and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit 4531** is true, then the constraint is assumed to be fully handled by the 4532** virtual table and is not checked again by SQLite.)^ 4533** 4534** ^The idxNum and idxPtr values are recorded and passed into the 4535** [xFilter] method. 4536** ^[sqlite3_free()] is used to free idxPtr if and only if 4537** needToFreeIdxPtr is true. 4538** 4539** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in 4540** the correct order to satisfy the ORDER BY clause so that no separate 4541** sorting step is required. 4542** 4543** ^The estimatedCost value is an estimate of the cost of doing the 4544** particular lookup. A full scan of a table with N entries should have 4545** a cost of N. A binary search of a table of N entries should have a 4546** cost of approximately log(N). 4547*/ 4548struct sqlite3_index_info { 4549 /* Inputs */ 4550 int nConstraint; /* Number of entries in aConstraint */ 4551 struct sqlite3_index_constraint { 4552 int iColumn; /* Column on left-hand side of constraint */ 4553 unsigned char op; /* Constraint operator */ 4554 unsigned char usable; /* True if this constraint is usable */ 4555 int iTermOffset; /* Used internally - xBestIndex should ignore */ 4556 } *aConstraint; /* Table of WHERE clause constraints */ 4557 int nOrderBy; /* Number of terms in the ORDER BY clause */ 4558 struct sqlite3_index_orderby { 4559 int iColumn; /* Column number */ 4560 unsigned char desc; /* True for DESC. False for ASC. */ 4561 } *aOrderBy; /* The ORDER BY clause */ 4562 /* Outputs */ 4563 struct sqlite3_index_constraint_usage { 4564 int argvIndex; /* if >0, constraint is part of argv to xFilter */ 4565 unsigned char omit; /* Do not code a test for this constraint */ 4566 } *aConstraintUsage; 4567 int idxNum; /* Number used to identify the index */ 4568 char *idxStr; /* String, possibly obtained from sqlite3_malloc */ 4569 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ 4570 int orderByConsumed; /* True if output is already ordered */ 4571 double estimatedCost; /* Estimated cost of using this index */ 4572}; 4573 4574/* 4575** CAPI3REF: Virtual Table Constraint Operator Codes 4576** 4577** These macros defined the allowed values for the 4578** [sqlite3_index_info].aConstraint[].op field. Each value represents 4579** an operator that is part of a constraint term in the wHERE clause of 4580** a query that uses a [virtual table]. 4581*/ 4582#define SQLITE_INDEX_CONSTRAINT_EQ 2 4583#define SQLITE_INDEX_CONSTRAINT_GT 4 4584#define SQLITE_INDEX_CONSTRAINT_LE 8 4585#define SQLITE_INDEX_CONSTRAINT_LT 16 4586#define SQLITE_INDEX_CONSTRAINT_GE 32 4587#define SQLITE_INDEX_CONSTRAINT_MATCH 64 4588 4589/* 4590** CAPI3REF: Register A Virtual Table Implementation 4591** 4592** ^These routines are used to register a new [virtual table module] name. 4593** ^Module names must be registered before 4594** creating a new [virtual table] using the module and before using a 4595** preexisting [virtual table] for the module. 4596** 4597** ^The module name is registered on the [database connection] specified 4598** by the first parameter. ^The name of the module is given by the 4599** second parameter. ^The third parameter is a pointer to 4600** the implementation of the [virtual table module]. ^The fourth 4601** parameter is an arbitrary client data pointer that is passed through 4602** into the [xCreate] and [xConnect] methods of the virtual table module 4603** when a new virtual table is be being created or reinitialized. 4604** 4605** ^The sqlite3_create_module_v2() interface has a fifth parameter which 4606** is a pointer to a destructor for the pClientData. ^SQLite will 4607** invoke the destructor function (if it is not NULL) when SQLite 4608** no longer needs the pClientData pointer. ^The destructor will also 4609** be invoked if the call to sqlite3_create_module_v2() fails. 4610** ^The sqlite3_create_module() 4611** interface is equivalent to sqlite3_create_module_v2() with a NULL 4612** destructor. 4613*/ 4614int sqlite3_create_module( 4615 sqlite3 *db, /* SQLite connection to register module with */ 4616 const char *zName, /* Name of the module */ 4617 const sqlite3_module *p, /* Methods for the module */ 4618 void *pClientData /* Client data for xCreate/xConnect */ 4619); 4620int sqlite3_create_module_v2( 4621 sqlite3 *db, /* SQLite connection to register module with */ 4622 const char *zName, /* Name of the module */ 4623 const sqlite3_module *p, /* Methods for the module */ 4624 void *pClientData, /* Client data for xCreate/xConnect */ 4625 void(*xDestroy)(void*) /* Module destructor function */ 4626); 4627 4628/* 4629** CAPI3REF: Virtual Table Instance Object 4630** KEYWORDS: sqlite3_vtab 4631** 4632** Every [virtual table module] implementation uses a subclass 4633** of this object to describe a particular instance 4634** of the [virtual table]. Each subclass will 4635** be tailored to the specific needs of the module implementation. 4636** The purpose of this superclass is to define certain fields that are 4637** common to all module implementations. 4638** 4639** ^Virtual tables methods can set an error message by assigning a 4640** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should 4641** take care that any prior string is freed by a call to [sqlite3_free()] 4642** prior to assigning a new string to zErrMsg. ^After the error message 4643** is delivered up to the client application, the string will be automatically 4644** freed by sqlite3_free() and the zErrMsg field will be zeroed. 4645*/ 4646struct sqlite3_vtab { 4647 const sqlite3_module *pModule; /* The module for this virtual table */ 4648 int nRef; /* NO LONGER USED */ 4649 char *zErrMsg; /* Error message from sqlite3_mprintf() */ 4650 /* Virtual table implementations will typically add additional fields */ 4651}; 4652 4653/* 4654** CAPI3REF: Virtual Table Cursor Object 4655** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor} 4656** 4657** Every [virtual table module] implementation uses a subclass of the 4658** following structure to describe cursors that point into the 4659** [virtual table] and are used 4660** to loop through the virtual table. Cursors are created using the 4661** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed 4662** by the [sqlite3_module.xClose | xClose] method. Cursors are used 4663** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods 4664** of the module. Each module implementation will define 4665** the content of a cursor structure to suit its own needs. 4666** 4667** This superclass exists in order to define fields of the cursor that 4668** are common to all implementations. 4669*/ 4670struct sqlite3_vtab_cursor { 4671 sqlite3_vtab *pVtab; /* Virtual table of this cursor */ 4672 /* Virtual table implementations will typically add additional fields */ 4673}; 4674 4675/* 4676** CAPI3REF: Declare The Schema Of A Virtual Table 4677** 4678** ^The [xCreate] and [xConnect] methods of a 4679** [virtual table module] call this interface 4680** to declare the format (the names and datatypes of the columns) of 4681** the virtual tables they implement. 4682*/ 4683int sqlite3_declare_vtab(sqlite3*, const char *zSQL); 4684 4685/* 4686** CAPI3REF: Overload A Function For A Virtual Table 4687** 4688** ^(Virtual tables can provide alternative implementations of functions 4689** using the [xFindFunction] method of the [virtual table module]. 4690** But global versions of those functions 4691** must exist in order to be overloaded.)^ 4692** 4693** ^(This API makes sure a global version of a function with a particular 4694** name and number of parameters exists. If no such function exists 4695** before this API is called, a new function is created.)^ ^The implementation 4696** of the new function always causes an exception to be thrown. So 4697** the new function is not good for anything by itself. Its only 4698** purpose is to be a placeholder function that can be overloaded 4699** by a [virtual table]. 4700*/ 4701int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); 4702 4703/* 4704** The interface to the virtual-table mechanism defined above (back up 4705** to a comment remarkably similar to this one) is currently considered 4706** to be experimental. The interface might change in incompatible ways. 4707** If this is a problem for you, do not use the interface at this time. 4708** 4709** When the virtual-table mechanism stabilizes, we will declare the 4710** interface fixed, support it indefinitely, and remove this comment. 4711*/ 4712 4713/* 4714** CAPI3REF: A Handle To An Open BLOB 4715** KEYWORDS: {BLOB handle} {BLOB handles} 4716** 4717** An instance of this object represents an open BLOB on which 4718** [sqlite3_blob_open | incremental BLOB I/O] can be performed. 4719** ^Objects of this type are created by [sqlite3_blob_open()] 4720** and destroyed by [sqlite3_blob_close()]. 4721** ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces 4722** can be used to read or write small subsections of the BLOB. 4723** ^The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes. 4724*/ 4725typedef struct sqlite3_blob sqlite3_blob; 4726 4727/* 4728** CAPI3REF: Open A BLOB For Incremental I/O 4729** 4730** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located 4731** in row iRow, column zColumn, table zTable in database zDb; 4732** in other words, the same BLOB that would be selected by: 4733** 4734** <pre> 4735** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow; 4736** </pre>)^ 4737** 4738** ^If the flags parameter is non-zero, then the BLOB is opened for read 4739** and write access. ^If it is zero, the BLOB is opened for read access. 4740** ^It is not possible to open a column that is part of an index or primary 4741** key for writing. ^If [foreign key constraints] are enabled, it is 4742** not possible to open a column that is part of a [child key] for writing. 4743** 4744** ^Note that the database name is not the filename that contains 4745** the database but rather the symbolic name of the database that 4746** appears after the AS keyword when the database is connected using [ATTACH]. 4747** ^For the main database file, the database name is "main". 4748** ^For TEMP tables, the database name is "temp". 4749** 4750** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is written 4751** to *ppBlob. Otherwise an [error code] is returned and *ppBlob is set 4752** to be a null pointer.)^ 4753** ^This function sets the [database connection] error code and message 4754** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()] and related 4755** functions. ^Note that the *ppBlob variable is always initialized in a 4756** way that makes it safe to invoke [sqlite3_blob_close()] on *ppBlob 4757** regardless of the success or failure of this routine. 4758** 4759** ^(If the row that a BLOB handle points to is modified by an 4760** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects 4761** then the BLOB handle is marked as "expired". 4762** This is true if any column of the row is changed, even a column 4763** other than the one the BLOB handle is open on.)^ 4764** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for 4765** a expired BLOB handle fail with an return code of [SQLITE_ABORT]. 4766** ^(Changes written into a BLOB prior to the BLOB expiring are not 4767** rolled back by the expiration of the BLOB. Such changes will eventually 4768** commit if the transaction continues to completion.)^ 4769** 4770** ^Use the [sqlite3_blob_bytes()] interface to determine the size of 4771** the opened blob. ^The size of a blob may not be changed by this 4772** interface. Use the [UPDATE] SQL command to change the size of a 4773** blob. 4774** 4775** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces 4776** and the built-in [zeroblob] SQL function can be used, if desired, 4777** to create an empty, zero-filled blob in which to read or write using 4778** this interface. 4779** 4780** To avoid a resource leak, every open [BLOB handle] should eventually 4781** be released by a call to [sqlite3_blob_close()]. 4782*/ 4783int sqlite3_blob_open( 4784 sqlite3*, 4785 const char *zDb, 4786 const char *zTable, 4787 const char *zColumn, 4788 sqlite3_int64 iRow, 4789 int flags, 4790 sqlite3_blob **ppBlob 4791); 4792 4793/* 4794** CAPI3REF: Move a BLOB Handle to a New Row 4795** 4796** ^This function is used to move an existing blob handle so that it points 4797** to a different row of the same database table. ^The new row is identified 4798** by the rowid value passed as the second argument. Only the row can be 4799** changed. ^The database, table and column on which the blob handle is open 4800** remain the same. Moving an existing blob handle to a new row can be 4801** faster than closing the existing handle and opening a new one. 4802** 4803** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] - 4804** it must exist and there must be either a blob or text value stored in 4805** the nominated column.)^ ^If the new row is not present in the table, or if 4806** it does not contain a blob or text value, or if another error occurs, an 4807** SQLite error code is returned and the blob handle is considered aborted. 4808** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or 4809** [sqlite3_blob_reopen()] on an aborted blob handle immediately return 4810** SQLITE_ABORT. 4811** 4812** ^This function sets the database handle error code and message. 4813*/ 4814SQLITE_EXPERIMENTAL int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64); 4815 4816/* 4817** CAPI3REF: Close A BLOB Handle 4818** 4819** ^Closes an open [BLOB handle]. 4820** 4821** ^Closing a BLOB shall cause the current transaction to commit 4822** if there are no other BLOBs, no pending prepared statements, and the 4823** database connection is in [autocommit mode]. 4824** ^If any writes were made to the BLOB, they might be held in cache 4825** until the close operation if they will fit. 4826** 4827** ^(Closing the BLOB often forces the changes 4828** out to disk and so if any I/O errors occur, they will likely occur 4829** at the time when the BLOB is closed. Any errors that occur during 4830** closing are reported as a non-zero return value.)^ 4831** 4832** ^(The BLOB is closed unconditionally. Even if this routine returns 4833** an error code, the BLOB is still closed.)^ 4834** 4835** ^Calling this routine with a null pointer (such as would be returned 4836** by a failed call to [sqlite3_blob_open()]) is a harmless no-op. 4837*/ 4838int sqlite3_blob_close(sqlite3_blob *); 4839 4840/* 4841** CAPI3REF: Return The Size Of An Open BLOB 4842** 4843** ^Returns the size in bytes of the BLOB accessible via the 4844** successfully opened [BLOB handle] in its only argument. ^The 4845** incremental blob I/O routines can only read or overwriting existing 4846** blob content; they cannot change the size of a blob. 4847** 4848** This routine only works on a [BLOB handle] which has been created 4849** by a prior successful call to [sqlite3_blob_open()] and which has not 4850** been closed by [sqlite3_blob_close()]. Passing any other pointer in 4851** to this routine results in undefined and probably undesirable behavior. 4852*/ 4853int sqlite3_blob_bytes(sqlite3_blob *); 4854 4855/* 4856** CAPI3REF: Read Data From A BLOB Incrementally 4857** 4858** ^(This function is used to read data from an open [BLOB handle] into a 4859** caller-supplied buffer. N bytes of data are copied into buffer Z 4860** from the open BLOB, starting at offset iOffset.)^ 4861** 4862** ^If offset iOffset is less than N bytes from the end of the BLOB, 4863** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is 4864** less than zero, [SQLITE_ERROR] is returned and no data is read. 4865** ^The size of the blob (and hence the maximum value of N+iOffset) 4866** can be determined using the [sqlite3_blob_bytes()] interface. 4867** 4868** ^An attempt to read from an expired [BLOB handle] fails with an 4869** error code of [SQLITE_ABORT]. 4870** 4871** ^(On success, sqlite3_blob_read() returns SQLITE_OK. 4872** Otherwise, an [error code] or an [extended error code] is returned.)^ 4873** 4874** This routine only works on a [BLOB handle] which has been created 4875** by a prior successful call to [sqlite3_blob_open()] and which has not 4876** been closed by [sqlite3_blob_close()]. Passing any other pointer in 4877** to this routine results in undefined and probably undesirable behavior. 4878** 4879** See also: [sqlite3_blob_write()]. 4880*/ 4881int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); 4882 4883/* 4884** CAPI3REF: Write Data Into A BLOB Incrementally 4885** 4886** ^This function is used to write data into an open [BLOB handle] from a 4887** caller-supplied buffer. ^N bytes of data are copied from the buffer Z 4888** into the open BLOB, starting at offset iOffset. 4889** 4890** ^If the [BLOB handle] passed as the first argument was not opened for 4891** writing (the flags parameter to [sqlite3_blob_open()] was zero), 4892** this function returns [SQLITE_READONLY]. 4893** 4894** ^This function may only modify the contents of the BLOB; it is 4895** not possible to increase the size of a BLOB using this API. 4896** ^If offset iOffset is less than N bytes from the end of the BLOB, 4897** [SQLITE_ERROR] is returned and no data is written. ^If N is 4898** less than zero [SQLITE_ERROR] is returned and no data is written. 4899** The size of the BLOB (and hence the maximum value of N+iOffset) 4900** can be determined using the [sqlite3_blob_bytes()] interface. 4901** 4902** ^An attempt to write to an expired [BLOB handle] fails with an 4903** error code of [SQLITE_ABORT]. ^Writes to the BLOB that occurred 4904** before the [BLOB handle] expired are not rolled back by the 4905** expiration of the handle, though of course those changes might 4906** have been overwritten by the statement that expired the BLOB handle 4907** or by other independent statements. 4908** 4909** ^(On success, sqlite3_blob_write() returns SQLITE_OK. 4910** Otherwise, an [error code] or an [extended error code] is returned.)^ 4911** 4912** This routine only works on a [BLOB handle] which has been created 4913** by a prior successful call to [sqlite3_blob_open()] and which has not 4914** been closed by [sqlite3_blob_close()]. Passing any other pointer in 4915** to this routine results in undefined and probably undesirable behavior. 4916** 4917** See also: [sqlite3_blob_read()]. 4918*/ 4919int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); 4920 4921/* 4922** CAPI3REF: Virtual File System Objects 4923** 4924** A virtual filesystem (VFS) is an [sqlite3_vfs] object 4925** that SQLite uses to interact 4926** with the underlying operating system. Most SQLite builds come with a 4927** single default VFS that is appropriate for the host computer. 4928** New VFSes can be registered and existing VFSes can be unregistered. 4929** The following interfaces are provided. 4930** 4931** ^The sqlite3_vfs_find() interface returns a pointer to a VFS given its name. 4932** ^Names are case sensitive. 4933** ^Names are zero-terminated UTF-8 strings. 4934** ^If there is no match, a NULL pointer is returned. 4935** ^If zVfsName is NULL then the default VFS is returned. 4936** 4937** ^New VFSes are registered with sqlite3_vfs_register(). 4938** ^Each new VFS becomes the default VFS if the makeDflt flag is set. 4939** ^The same VFS can be registered multiple times without injury. 4940** ^To make an existing VFS into the default VFS, register it again 4941** with the makeDflt flag set. If two different VFSes with the 4942** same name are registered, the behavior is undefined. If a 4943** VFS is registered with a name that is NULL or an empty string, 4944** then the behavior is undefined. 4945** 4946** ^Unregister a VFS with the sqlite3_vfs_unregister() interface. 4947** ^(If the default VFS is unregistered, another VFS is chosen as 4948** the default. The choice for the new VFS is arbitrary.)^ 4949*/ 4950sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); 4951int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); 4952int sqlite3_vfs_unregister(sqlite3_vfs*); 4953 4954/* 4955** CAPI3REF: Mutexes 4956** 4957** The SQLite core uses these routines for thread 4958** synchronization. Though they are intended for internal 4959** use by SQLite, code that links against SQLite is 4960** permitted to use any of these routines. 4961** 4962** The SQLite source code contains multiple implementations 4963** of these mutex routines. An appropriate implementation 4964** is selected automatically at compile-time. ^(The following 4965** implementations are available in the SQLite core: 4966** 4967** <ul> 4968** <li> SQLITE_MUTEX_OS2 4969** <li> SQLITE_MUTEX_PTHREAD 4970** <li> SQLITE_MUTEX_W32 4971** <li> SQLITE_MUTEX_NOOP 4972** </ul>)^ 4973** 4974** ^The SQLITE_MUTEX_NOOP implementation is a set of routines 4975** that does no real locking and is appropriate for use in 4976** a single-threaded application. ^The SQLITE_MUTEX_OS2, 4977** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations 4978** are appropriate for use on OS/2, Unix, and Windows. 4979** 4980** ^(If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor 4981** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex 4982** implementation is included with the library. In this case the 4983** application must supply a custom mutex implementation using the 4984** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function 4985** before calling sqlite3_initialize() or any other public sqlite3_ 4986** function that calls sqlite3_initialize().)^ 4987** 4988** ^The sqlite3_mutex_alloc() routine allocates a new 4989** mutex and returns a pointer to it. ^If it returns NULL 4990** that means that a mutex could not be allocated. ^SQLite 4991** will unwind its stack and return an error. ^(The argument 4992** to sqlite3_mutex_alloc() is one of these integer constants: 4993** 4994** <ul> 4995** <li> SQLITE_MUTEX_FAST 4996** <li> SQLITE_MUTEX_RECURSIVE 4997** <li> SQLITE_MUTEX_STATIC_MASTER 4998** <li> SQLITE_MUTEX_STATIC_MEM 4999** <li> SQLITE_MUTEX_STATIC_MEM2 5000** <li> SQLITE_MUTEX_STATIC_PRNG 5001** <li> SQLITE_MUTEX_STATIC_LRU 5002** <li> SQLITE_MUTEX_STATIC_LRU2 5003** </ul>)^ 5004** 5005** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) 5006** cause sqlite3_mutex_alloc() to create 5007** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE 5008** is used but not necessarily so when SQLITE_MUTEX_FAST is used. 5009** The mutex implementation does not need to make a distinction 5010** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does 5011** not want to. ^SQLite will only request a recursive mutex in 5012** cases where it really needs one. ^If a faster non-recursive mutex 5013** implementation is available on the host platform, the mutex subsystem 5014** might return such a mutex in response to SQLITE_MUTEX_FAST. 5015** 5016** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other 5017** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return 5018** a pointer to a static preexisting mutex. ^Six static mutexes are 5019** used by the current version of SQLite. Future versions of SQLite 5020** may add additional static mutexes. Static mutexes are for internal 5021** use by SQLite only. Applications that use SQLite mutexes should 5022** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or 5023** SQLITE_MUTEX_RECURSIVE. 5024** 5025** ^Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST 5026** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() 5027** returns a different mutex on every call. ^But for the static 5028** mutex types, the same mutex is returned on every call that has 5029** the same type number. 5030** 5031** ^The sqlite3_mutex_free() routine deallocates a previously 5032** allocated dynamic mutex. ^SQLite is careful to deallocate every 5033** dynamic mutex that it allocates. The dynamic mutexes must not be in 5034** use when they are deallocated. Attempting to deallocate a static 5035** mutex results in undefined behavior. ^SQLite never deallocates 5036** a static mutex. 5037** 5038** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt 5039** to enter a mutex. ^If another thread is already within the mutex, 5040** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return 5041** SQLITE_BUSY. ^The sqlite3_mutex_try() interface returns [SQLITE_OK] 5042** upon successful entry. ^(Mutexes created using 5043** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. 5044** In such cases the, 5045** mutex must be exited an equal number of times before another thread 5046** can enter.)^ ^(If the same thread tries to enter any other 5047** kind of mutex more than once, the behavior is undefined. 5048** SQLite will never exhibit 5049** such behavior in its own use of mutexes.)^ 5050** 5051** ^(Some systems (for example, Windows 95) do not support the operation 5052** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() 5053** will always return SQLITE_BUSY. The SQLite core only ever uses 5054** sqlite3_mutex_try() as an optimization so this is acceptable behavior.)^ 5055** 5056** ^The sqlite3_mutex_leave() routine exits a mutex that was 5057** previously entered by the same thread. ^(The behavior 5058** is undefined if the mutex is not currently entered by the 5059** calling thread or is not currently allocated. SQLite will 5060** never do either.)^ 5061** 5062** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or 5063** sqlite3_mutex_leave() is a NULL pointer, then all three routines 5064** behave as no-ops. 5065** 5066** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. 5067*/ 5068sqlite3_mutex *sqlite3_mutex_alloc(int); 5069void sqlite3_mutex_free(sqlite3_mutex*); 5070void sqlite3_mutex_enter(sqlite3_mutex*); 5071int sqlite3_mutex_try(sqlite3_mutex*); 5072void sqlite3_mutex_leave(sqlite3_mutex*); 5073 5074/* 5075** CAPI3REF: Mutex Methods Object 5076** 5077** An instance of this structure defines the low-level routines 5078** used to allocate and use mutexes. 5079** 5080** Usually, the default mutex implementations provided by SQLite are 5081** sufficient, however the user has the option of substituting a custom 5082** implementation for specialized deployments or systems for which SQLite 5083** does not provide a suitable implementation. In this case, the user 5084** creates and populates an instance of this structure to pass 5085** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option. 5086** Additionally, an instance of this structure can be used as an 5087** output variable when querying the system for the current mutex 5088** implementation, using the [SQLITE_CONFIG_GETMUTEX] option. 5089** 5090** ^The xMutexInit method defined by this structure is invoked as 5091** part of system initialization by the sqlite3_initialize() function. 5092** ^The xMutexInit routine is called by SQLite exactly once for each 5093** effective call to [sqlite3_initialize()]. 5094** 5095** ^The xMutexEnd method defined by this structure is invoked as 5096** part of system shutdown by the sqlite3_shutdown() function. The 5097** implementation of this method is expected to release all outstanding 5098** resources obtained by the mutex methods implementation, especially 5099** those obtained by the xMutexInit method. ^The xMutexEnd() 5100** interface is invoked exactly once for each call to [sqlite3_shutdown()]. 5101** 5102** ^(The remaining seven methods defined by this structure (xMutexAlloc, 5103** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and 5104** xMutexNotheld) implement the following interfaces (respectively): 5105** 5106** <ul> 5107** <li> [sqlite3_mutex_alloc()] </li> 5108** <li> [sqlite3_mutex_free()] </li> 5109** <li> [sqlite3_mutex_enter()] </li> 5110** <li> [sqlite3_mutex_try()] </li> 5111** <li> [sqlite3_mutex_leave()] </li> 5112** <li> [sqlite3_mutex_held()] </li> 5113** <li> [sqlite3_mutex_notheld()] </li> 5114** </ul>)^ 5115** 5116** The only difference is that the public sqlite3_XXX functions enumerated 5117** above silently ignore any invocations that pass a NULL pointer instead 5118** of a valid mutex handle. The implementations of the methods defined 5119** by this structure are not required to handle this case, the results 5120** of passing a NULL pointer instead of a valid mutex handle are undefined 5121** (i.e. it is acceptable to provide an implementation that segfaults if 5122** it is passed a NULL pointer). 5123** 5124** The xMutexInit() method must be threadsafe. ^It must be harmless to 5125** invoke xMutexInit() multiple times within the same process and without 5126** intervening calls to xMutexEnd(). Second and subsequent calls to 5127** xMutexInit() must be no-ops. 5128** 5129** ^xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()] 5130** and its associates). ^Similarly, xMutexAlloc() must not use SQLite memory 5131** allocation for a static mutex. ^However xMutexAlloc() may use SQLite 5132** memory allocation for a fast or recursive mutex. 5133** 5134** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is 5135** called, but only if the prior call to xMutexInit returned SQLITE_OK. 5136** If xMutexInit fails in any way, it is expected to clean up after itself 5137** prior to returning. 5138*/ 5139typedef struct sqlite3_mutex_methods sqlite3_mutex_methods; 5140struct sqlite3_mutex_methods { 5141 int (*xMutexInit)(void); 5142 int (*xMutexEnd)(void); 5143 sqlite3_mutex *(*xMutexAlloc)(int); 5144 void (*xMutexFree)(sqlite3_mutex *); 5145 void (*xMutexEnter)(sqlite3_mutex *); 5146 int (*xMutexTry)(sqlite3_mutex *); 5147 void (*xMutexLeave)(sqlite3_mutex *); 5148 int (*xMutexHeld)(sqlite3_mutex *); 5149 int (*xMutexNotheld)(sqlite3_mutex *); 5150}; 5151 5152/* 5153** CAPI3REF: Mutex Verification Routines 5154** 5155** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines 5156** are intended for use inside assert() statements. ^The SQLite core 5157** never uses these routines except inside an assert() and applications 5158** are advised to follow the lead of the core. ^The SQLite core only 5159** provides implementations for these routines when it is compiled 5160** with the SQLITE_DEBUG flag. ^External mutex implementations 5161** are only required to provide these routines if SQLITE_DEBUG is 5162** defined and if NDEBUG is not defined. 5163** 5164** ^These routines should return true if the mutex in their argument 5165** is held or not held, respectively, by the calling thread. 5166** 5167** ^The implementation is not required to provided versions of these 5168** routines that actually work. If the implementation does not provide working 5169** versions of these routines, it should at least provide stubs that always 5170** return true so that one does not get spurious assertion failures. 5171** 5172** ^If the argument to sqlite3_mutex_held() is a NULL pointer then 5173** the routine should return 1. This seems counter-intuitive since 5174** clearly the mutex cannot be held if it does not exist. But the 5175** the reason the mutex does not exist is because the build is not 5176** using mutexes. And we do not want the assert() containing the 5177** call to sqlite3_mutex_held() to fail, so a non-zero return is 5178** the appropriate thing to do. ^The sqlite3_mutex_notheld() 5179** interface should also return 1 when given a NULL pointer. 5180*/ 5181#ifndef NDEBUG 5182int sqlite3_mutex_held(sqlite3_mutex*); 5183int sqlite3_mutex_notheld(sqlite3_mutex*); 5184#endif 5185 5186/* 5187** CAPI3REF: Mutex Types 5188** 5189** The [sqlite3_mutex_alloc()] interface takes a single argument 5190** which is one of these integer constants. 5191** 5192** The set of static mutexes may change from one SQLite release to the 5193** next. Applications that override the built-in mutex logic must be 5194** prepared to accommodate additional static mutexes. 5195*/ 5196#define SQLITE_MUTEX_FAST 0 5197#define SQLITE_MUTEX_RECURSIVE 1 5198#define SQLITE_MUTEX_STATIC_MASTER 2 5199#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ 5200#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */ 5201#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ 5202#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ 5203#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ 5204#define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */ 5205 5206/* 5207** CAPI3REF: Retrieve the mutex for a database connection 5208** 5209** ^This interface returns a pointer the [sqlite3_mutex] object that 5210** serializes access to the [database connection] given in the argument 5211** when the [threading mode] is Serialized. 5212** ^If the [threading mode] is Single-thread or Multi-thread then this 5213** routine returns a NULL pointer. 5214*/ 5215sqlite3_mutex *sqlite3_db_mutex(sqlite3*); 5216 5217/* 5218** CAPI3REF: Low-Level Control Of Database Files 5219** 5220** ^The [sqlite3_file_control()] interface makes a direct call to the 5221** xFileControl method for the [sqlite3_io_methods] object associated 5222** with a particular database identified by the second argument. ^The 5223** name of the database "main" for the main database or "temp" for the 5224** TEMP database, or the name that appears after the AS keyword for 5225** databases that are added using the [ATTACH] SQL command. 5226** ^A NULL pointer can be used in place of "main" to refer to the 5227** main database file. 5228** ^The third and fourth parameters to this routine 5229** are passed directly through to the second and third parameters of 5230** the xFileControl method. ^The return value of the xFileControl 5231** method becomes the return value of this routine. 5232** 5233** ^If the second parameter (zDbName) does not match the name of any 5234** open database file, then SQLITE_ERROR is returned. ^This error 5235** code is not remembered and will not be recalled by [sqlite3_errcode()] 5236** or [sqlite3_errmsg()]. The underlying xFileControl method might 5237** also return SQLITE_ERROR. There is no way to distinguish between 5238** an incorrect zDbName and an SQLITE_ERROR return from the underlying 5239** xFileControl method. 5240** 5241** See also: [SQLITE_FCNTL_LOCKSTATE] 5242*/ 5243int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); 5244 5245/* 5246** CAPI3REF: Testing Interface 5247** 5248** ^The sqlite3_test_control() interface is used to read out internal 5249** state of SQLite and to inject faults into SQLite for testing 5250** purposes. ^The first parameter is an operation code that determines 5251** the number, meaning, and operation of all subsequent parameters. 5252** 5253** This interface is not for use by applications. It exists solely 5254** for verifying the correct operation of the SQLite library. Depending 5255** on how the SQLite library is compiled, this interface might not exist. 5256** 5257** The details of the operation codes, their meanings, the parameters 5258** they take, and what they do are all subject to change without notice. 5259** Unlike most of the SQLite API, this function is not guaranteed to 5260** operate consistently from one release to the next. 5261*/ 5262int sqlite3_test_control(int op, ...); 5263 5264/* 5265** CAPI3REF: Testing Interface Operation Codes 5266** 5267** These constants are the valid operation code parameters used 5268** as the first argument to [sqlite3_test_control()]. 5269** 5270** These parameters and their meanings are subject to change 5271** without notice. These values are for testing purposes only. 5272** Applications should not use any of these parameters or the 5273** [sqlite3_test_control()] interface. 5274*/ 5275#define SQLITE_TESTCTRL_FIRST 5 5276#define SQLITE_TESTCTRL_PRNG_SAVE 5 5277#define SQLITE_TESTCTRL_PRNG_RESTORE 6 5278#define SQLITE_TESTCTRL_PRNG_RESET 7 5279#define SQLITE_TESTCTRL_BITVEC_TEST 8 5280#define SQLITE_TESTCTRL_FAULT_INSTALL 9 5281#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 5282#define SQLITE_TESTCTRL_PENDING_BYTE 11 5283#define SQLITE_TESTCTRL_ASSERT 12 5284#define SQLITE_TESTCTRL_ALWAYS 13 5285#define SQLITE_TESTCTRL_RESERVE 14 5286#define SQLITE_TESTCTRL_OPTIMIZATIONS 15 5287#define SQLITE_TESTCTRL_ISKEYWORD 16 5288#define SQLITE_TESTCTRL_PGHDRSZ 17 5289#define SQLITE_TESTCTRL_SCRATCHMALLOC 18 5290#define SQLITE_TESTCTRL_LAST 18 5291 5292/* 5293** CAPI3REF: SQLite Runtime Status 5294** 5295** ^This interface is used to retrieve runtime status information 5296** about the performance of SQLite, and optionally to reset various 5297** highwater marks. ^The first argument is an integer code for 5298** the specific parameter to measure. ^(Recognized integer codes 5299** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...].)^ 5300** ^The current value of the parameter is returned into *pCurrent. 5301** ^The highest recorded value is returned in *pHighwater. ^If the 5302** resetFlag is true, then the highest record value is reset after 5303** *pHighwater is written. ^(Some parameters do not record the highest 5304** value. For those parameters 5305** nothing is written into *pHighwater and the resetFlag is ignored.)^ 5306** ^(Other parameters record only the highwater mark and not the current 5307** value. For these latter parameters nothing is written into *pCurrent.)^ 5308** 5309** ^The sqlite3_status() routine returns SQLITE_OK on success and a 5310** non-zero [error code] on failure. 5311** 5312** This routine is threadsafe but is not atomic. This routine can be 5313** called while other threads are running the same or different SQLite 5314** interfaces. However the values returned in *pCurrent and 5315** *pHighwater reflect the status of SQLite at different points in time 5316** and it is possible that another thread might change the parameter 5317** in between the times when *pCurrent and *pHighwater are written. 5318** 5319** See also: [sqlite3_db_status()] 5320*/ 5321int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); 5322 5323 5324/* 5325** CAPI3REF: Status Parameters 5326** 5327** These integer constants designate various run-time status parameters 5328** that can be returned by [sqlite3_status()]. 5329** 5330** <dl> 5331** ^(<dt>SQLITE_STATUS_MEMORY_USED</dt> 5332** <dd>This parameter is the current amount of memory checked out 5333** using [sqlite3_malloc()], either directly or indirectly. The 5334** figure includes calls made to [sqlite3_malloc()] by the application 5335** and internal memory usage by the SQLite library. Scratch memory 5336** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache 5337** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in 5338** this parameter. The amount returned is the sum of the allocation 5339** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^ 5340** 5341** ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt> 5342** <dd>This parameter records the largest memory allocation request 5343** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their 5344** internal equivalents). Only the value returned in the 5345** *pHighwater parameter to [sqlite3_status()] is of interest. 5346** The value written into the *pCurrent parameter is undefined.</dd>)^ 5347** 5348** ^(<dt>SQLITE_STATUS_MALLOC_COUNT</dt> 5349** <dd>This parameter records the number of separate memory allocations.</dd>)^ 5350** 5351** ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt> 5352** <dd>This parameter returns the number of pages used out of the 5353** [pagecache memory allocator] that was configured using 5354** [SQLITE_CONFIG_PAGECACHE]. The 5355** value returned is in pages, not in bytes.</dd>)^ 5356** 5357** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt> 5358** <dd>This parameter returns the number of bytes of page cache 5359** allocation which could not be satisfied by the [SQLITE_CONFIG_PAGECACHE] 5360** buffer and where forced to overflow to [sqlite3_malloc()]. The 5361** returned value includes allocations that overflowed because they 5362** where too large (they were larger than the "sz" parameter to 5363** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because 5364** no space was left in the page cache.</dd>)^ 5365** 5366** ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt> 5367** <dd>This parameter records the largest memory allocation request 5368** handed to [pagecache memory allocator]. Only the value returned in the 5369** *pHighwater parameter to [sqlite3_status()] is of interest. 5370** The value written into the *pCurrent parameter is undefined.</dd>)^ 5371** 5372** ^(<dt>SQLITE_STATUS_SCRATCH_USED</dt> 5373** <dd>This parameter returns the number of allocations used out of the 5374** [scratch memory allocator] configured using 5375** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not 5376** in bytes. Since a single thread may only have one scratch allocation 5377** outstanding at time, this parameter also reports the number of threads 5378** using scratch memory at the same time.</dd>)^ 5379** 5380** ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt> 5381** <dd>This parameter returns the number of bytes of scratch memory 5382** allocation which could not be satisfied by the [SQLITE_CONFIG_SCRATCH] 5383** buffer and where forced to overflow to [sqlite3_malloc()]. The values 5384** returned include overflows because the requested allocation was too 5385** larger (that is, because the requested allocation was larger than the 5386** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer 5387** slots were available. 5388** </dd>)^ 5389** 5390** ^(<dt>SQLITE_STATUS_SCRATCH_SIZE</dt> 5391** <dd>This parameter records the largest memory allocation request 5392** handed to [scratch memory allocator]. Only the value returned in the 5393** *pHighwater parameter to [sqlite3_status()] is of interest. 5394** The value written into the *pCurrent parameter is undefined.</dd>)^ 5395** 5396** ^(<dt>SQLITE_STATUS_PARSER_STACK</dt> 5397** <dd>This parameter records the deepest parser stack. It is only 5398** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^ 5399** </dl> 5400** 5401** New status parameters may be added from time to time. 5402*/ 5403#define SQLITE_STATUS_MEMORY_USED 0 5404#define SQLITE_STATUS_PAGECACHE_USED 1 5405#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2 5406#define SQLITE_STATUS_SCRATCH_USED 3 5407#define SQLITE_STATUS_SCRATCH_OVERFLOW 4 5408#define SQLITE_STATUS_MALLOC_SIZE 5 5409#define SQLITE_STATUS_PARSER_STACK 6 5410#define SQLITE_STATUS_PAGECACHE_SIZE 7 5411#define SQLITE_STATUS_SCRATCH_SIZE 8 5412#define SQLITE_STATUS_MALLOC_COUNT 9 5413 5414/* 5415** CAPI3REF: Database Connection Status 5416** 5417** ^This interface is used to retrieve runtime status information 5418** about a single [database connection]. ^The first argument is the 5419** database connection object to be interrogated. ^The second argument 5420** is an integer constant, taken from the set of 5421** [SQLITE_DBSTATUS_LOOKASIDE_USED | SQLITE_DBSTATUS_*] macros, that 5422** determines the parameter to interrogate. The set of 5423** [SQLITE_DBSTATUS_LOOKASIDE_USED | SQLITE_DBSTATUS_*] macros is likely 5424** to grow in future releases of SQLite. 5425** 5426** ^The current value of the requested parameter is written into *pCur 5427** and the highest instantaneous value is written into *pHiwtr. ^If 5428** the resetFlg is true, then the highest instantaneous value is 5429** reset back down to the current value. 5430** 5431** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a 5432** non-zero [error code] on failure. 5433** 5434** See also: [sqlite3_status()] and [sqlite3_stmt_status()]. 5435*/ 5436int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg); 5437 5438/* 5439** CAPI3REF: Status Parameters for database connections 5440** 5441** These constants are the available integer "verbs" that can be passed as 5442** the second argument to the [sqlite3_db_status()] interface. 5443** 5444** New verbs may be added in future releases of SQLite. Existing verbs 5445** might be discontinued. Applications should check the return code from 5446** [sqlite3_db_status()] to make sure that the call worked. 5447** The [sqlite3_db_status()] interface will return a non-zero error code 5448** if a discontinued or unsupported verb is invoked. 5449** 5450** <dl> 5451** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt> 5452** <dd>This parameter returns the number of lookaside memory slots currently 5453** checked out.</dd>)^ 5454** 5455** ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt> 5456** <dd>This parameter returns the approximate number of of bytes of heap 5457** memory used by all pager caches associated with the database connection.)^ 5458** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0. 5459** 5460** ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt> 5461** <dd>This parameter returns the approximate number of of bytes of heap 5462** memory used to store the schema for all databases associated 5463** with the connection - main, temp, and any [ATTACH]-ed databases.)^ 5464** ^The full amount of memory used by the schemas is reported, even if the 5465** schema memory is shared with other database connections due to 5466** [shared cache mode] being enabled. 5467** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0. 5468** 5469** ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt> 5470** <dd>This parameter returns the approximate number of of bytes of heap 5471** and lookaside memory used by all prepared statements associated with 5472** the database connection.)^ 5473** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0. 5474** </dd> 5475** </dl> 5476*/ 5477#define SQLITE_DBSTATUS_LOOKASIDE_USED 0 5478#define SQLITE_DBSTATUS_CACHE_USED 1 5479#define SQLITE_DBSTATUS_SCHEMA_USED 2 5480#define SQLITE_DBSTATUS_STMT_USED 3 5481#define SQLITE_DBSTATUS_MAX 3 /* Largest defined DBSTATUS */ 5482 5483 5484/* 5485** CAPI3REF: Prepared Statement Status 5486** 5487** ^(Each prepared statement maintains various 5488** [SQLITE_STMTSTATUS_SORT | counters] that measure the number 5489** of times it has performed specific operations.)^ These counters can 5490** be used to monitor the performance characteristics of the prepared 5491** statements. For example, if the number of table steps greatly exceeds 5492** the number of table searches or result rows, that would tend to indicate 5493** that the prepared statement is using a full table scan rather than 5494** an index. 5495** 5496** ^(This interface is used to retrieve and reset counter values from 5497** a [prepared statement]. The first argument is the prepared statement 5498** object to be interrogated. The second argument 5499** is an integer code for a specific [SQLITE_STMTSTATUS_SORT | counter] 5500** to be interrogated.)^ 5501** ^The current value of the requested counter is returned. 5502** ^If the resetFlg is true, then the counter is reset to zero after this 5503** interface call returns. 5504** 5505** See also: [sqlite3_status()] and [sqlite3_db_status()]. 5506*/ 5507int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg); 5508 5509/* 5510** CAPI3REF: Status Parameters for prepared statements 5511** 5512** These preprocessor macros define integer codes that name counter 5513** values associated with the [sqlite3_stmt_status()] interface. 5514** The meanings of the various counters are as follows: 5515** 5516** <dl> 5517** <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt> 5518** <dd>^This is the number of times that SQLite has stepped forward in 5519** a table as part of a full table scan. Large numbers for this counter 5520** may indicate opportunities for performance improvement through 5521** careful use of indices.</dd> 5522** 5523** <dt>SQLITE_STMTSTATUS_SORT</dt> 5524** <dd>^This is the number of sort operations that have occurred. 5525** A non-zero value in this counter may indicate an opportunity to 5526** improvement performance through careful use of indices.</dd> 5527** 5528** <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt> 5529** <dd>^This is the number of rows inserted into transient indices that 5530** were created automatically in order to help joins run faster. 5531** A non-zero value in this counter may indicate an opportunity to 5532** improvement performance by adding permanent indices that do not 5533** need to be reinitialized each time the statement is run.</dd> 5534** 5535** </dl> 5536*/ 5537#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1 5538#define SQLITE_STMTSTATUS_SORT 2 5539#define SQLITE_STMTSTATUS_AUTOINDEX 3 5540 5541/* 5542** CAPI3REF: Custom Page Cache Object 5543** 5544** The sqlite3_pcache type is opaque. It is implemented by 5545** the pluggable module. The SQLite core has no knowledge of 5546** its size or internal structure and never deals with the 5547** sqlite3_pcache object except by holding and passing pointers 5548** to the object. 5549** 5550** See [sqlite3_pcache_methods] for additional information. 5551*/ 5552typedef struct sqlite3_pcache sqlite3_pcache; 5553 5554/* 5555** CAPI3REF: Application Defined Page Cache. 5556** KEYWORDS: {page cache} 5557** 5558** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can 5559** register an alternative page cache implementation by passing in an 5560** instance of the sqlite3_pcache_methods structure.)^ 5561** In many applications, most of the heap memory allocated by 5562** SQLite is used for the page cache. 5563** By implementing a 5564** custom page cache using this API, an application can better control 5565** the amount of memory consumed by SQLite, the way in which 5566** that memory is allocated and released, and the policies used to 5567** determine exactly which parts of a database file are cached and for 5568** how long. 5569** 5570** The alternative page cache mechanism is an 5571** extreme measure that is only needed by the most demanding applications. 5572** The built-in page cache is recommended for most uses. 5573** 5574** ^(The contents of the sqlite3_pcache_methods structure are copied to an 5575** internal buffer by SQLite within the call to [sqlite3_config]. Hence 5576** the application may discard the parameter after the call to 5577** [sqlite3_config()] returns.)^ 5578** 5579** ^(The xInit() method is called once for each effective 5580** call to [sqlite3_initialize()])^ 5581** (usually only once during the lifetime of the process). ^(The xInit() 5582** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^ 5583** The intent of the xInit() method is to set up global data structures 5584** required by the custom page cache implementation. 5585** ^(If the xInit() method is NULL, then the 5586** built-in default page cache is used instead of the application defined 5587** page cache.)^ 5588** 5589** ^The xShutdown() method is called by [sqlite3_shutdown()]. 5590** It can be used to clean up 5591** any outstanding resources before process shutdown, if required. 5592** ^The xShutdown() method may be NULL. 5593** 5594** ^SQLite automatically serializes calls to the xInit method, 5595** so the xInit method need not be threadsafe. ^The 5596** xShutdown method is only called from [sqlite3_shutdown()] so it does 5597** not need to be threadsafe either. All other methods must be threadsafe 5598** in multithreaded applications. 5599** 5600** ^SQLite will never invoke xInit() more than once without an intervening 5601** call to xShutdown(). 5602** 5603** ^SQLite invokes the xCreate() method to construct a new cache instance. 5604** SQLite will typically create one cache instance for each open database file, 5605** though this is not guaranteed. ^The 5606** first parameter, szPage, is the size in bytes of the pages that must 5607** be allocated by the cache. ^szPage will not be a power of two. ^szPage 5608** will the page size of the database file that is to be cached plus an 5609** increment (here called "R") of about 100 or 200. SQLite will use the 5610** extra R bytes on each page to store metadata about the underlying 5611** database page on disk. The value of R depends 5612** on the SQLite version, the target platform, and how SQLite was compiled. 5613** ^R is constant for a particular build of SQLite. ^The second argument to 5614** xCreate(), bPurgeable, is true if the cache being created will 5615** be used to cache database pages of a file stored on disk, or 5616** false if it is used for an in-memory database. The cache implementation 5617** does not have to do anything special based with the value of bPurgeable; 5618** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will 5619** never invoke xUnpin() except to deliberately delete a page. 5620** ^In other words, calls to xUnpin() on a cache with bPurgeable set to 5621** false will always have the "discard" flag set to true. 5622** ^Hence, a cache created with bPurgeable false will 5623** never contain any unpinned pages. 5624** 5625** ^(The xCachesize() method may be called at any time by SQLite to set the 5626** suggested maximum cache-size (number of pages stored by) the cache 5627** instance passed as the first argument. This is the value configured using 5628** the SQLite "[PRAGMA cache_size]" command.)^ As with the bPurgeable 5629** parameter, the implementation is not required to do anything with this 5630** value; it is advisory only. 5631** 5632** The xPagecount() method must return the number of pages currently 5633** stored in the cache, both pinned and unpinned. 5634** 5635** The xFetch() method locates a page in the cache and returns a pointer to 5636** the page, or a NULL pointer. 5637** A "page", in this context, means a buffer of szPage bytes aligned at an 5638** 8-byte boundary. The page to be fetched is determined by the key. ^The 5639** mimimum key value is 1. After it has been retrieved using xFetch, the page 5640** is considered to be "pinned". 5641** 5642** If the requested page is already in the page cache, then the page cache 5643** implementation must return a pointer to the page buffer with its content 5644** intact. If the requested page is not already in the cache, then the 5645** behavior of the cache implementation should use the value of the createFlag 5646** parameter to help it determined what action to take: 5647** 5648** <table border=1 width=85% align=center> 5649** <tr><th> createFlag <th> Behaviour when page is not already in cache 5650** <tr><td> 0 <td> Do not allocate a new page. Return NULL. 5651** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so. 5652** Otherwise return NULL. 5653** <tr><td> 2 <td> Make every effort to allocate a new page. Only return 5654** NULL if allocating a new page is effectively impossible. 5655** </table> 5656** 5657** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite 5658** will only use a createFlag of 2 after a prior call with a createFlag of 1 5659** failed.)^ In between the to xFetch() calls, SQLite may 5660** attempt to unpin one or more cache pages by spilling the content of 5661** pinned pages to disk and synching the operating system disk cache. 5662** 5663** ^xUnpin() is called by SQLite with a pointer to a currently pinned page 5664** as its second argument. If the third parameter, discard, is non-zero, 5665** then the page must be evicted from the cache. 5666** ^If the discard parameter is 5667** zero, then the page may be discarded or retained at the discretion of 5668** page cache implementation. ^The page cache implementation 5669** may choose to evict unpinned pages at any time. 5670** 5671** The cache must not perform any reference counting. A single 5672** call to xUnpin() unpins the page regardless of the number of prior calls 5673** to xFetch(). 5674** 5675** The xRekey() method is used to change the key value associated with the 5676** page passed as the second argument. If the cache 5677** previously contains an entry associated with newKey, it must be 5678** discarded. ^Any prior cache entry associated with newKey is guaranteed not 5679** to be pinned. 5680** 5681** When SQLite calls the xTruncate() method, the cache must discard all 5682** existing cache entries with page numbers (keys) greater than or equal 5683** to the value of the iLimit parameter passed to xTruncate(). If any 5684** of these pages are pinned, they are implicitly unpinned, meaning that 5685** they can be safely discarded. 5686** 5687** ^The xDestroy() method is used to delete a cache allocated by xCreate(). 5688** All resources associated with the specified cache should be freed. ^After 5689** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*] 5690** handle invalid, and will not use it with any other sqlite3_pcache_methods 5691** functions. 5692*/ 5693typedef struct sqlite3_pcache_methods sqlite3_pcache_methods; 5694struct sqlite3_pcache_methods { 5695 void *pArg; 5696 int (*xInit)(void*); 5697 void (*xShutdown)(void*); 5698 sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable); 5699 void (*xCachesize)(sqlite3_pcache*, int nCachesize); 5700 int (*xPagecount)(sqlite3_pcache*); 5701 void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag); 5702 void (*xUnpin)(sqlite3_pcache*, void*, int discard); 5703 void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey); 5704 void (*xTruncate)(sqlite3_pcache*, unsigned iLimit); 5705 void (*xDestroy)(sqlite3_pcache*); 5706}; 5707 5708/* 5709** CAPI3REF: Online Backup Object 5710** 5711** The sqlite3_backup object records state information about an ongoing 5712** online backup operation. ^The sqlite3_backup object is created by 5713** a call to [sqlite3_backup_init()] and is destroyed by a call to 5714** [sqlite3_backup_finish()]. 5715** 5716** See Also: [Using the SQLite Online Backup API] 5717*/ 5718typedef struct sqlite3_backup sqlite3_backup; 5719 5720/* 5721** CAPI3REF: Online Backup API. 5722** 5723** The backup API copies the content of one database into another. 5724** It is useful either for creating backups of databases or 5725** for copying in-memory databases to or from persistent files. 5726** 5727** See Also: [Using the SQLite Online Backup API] 5728** 5729** ^Exclusive access is required to the destination database for the 5730** duration of the operation. ^However the source database is only 5731** read-locked while it is actually being read; it is not locked 5732** continuously for the entire backup operation. ^Thus, the backup may be 5733** performed on a live source database without preventing other users from 5734** reading or writing to the source database while the backup is underway. 5735** 5736** ^(To perform a backup operation: 5737** <ol> 5738** <li><b>sqlite3_backup_init()</b> is called once to initialize the 5739** backup, 5740** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer 5741** the data between the two databases, and finally 5742** <li><b>sqlite3_backup_finish()</b> is called to release all resources 5743** associated with the backup operation. 5744** </ol>)^ 5745** There should be exactly one call to sqlite3_backup_finish() for each 5746** successful call to sqlite3_backup_init(). 5747** 5748** <b>sqlite3_backup_init()</b> 5749** 5750** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the 5751** [database connection] associated with the destination database 5752** and the database name, respectively. 5753** ^The database name is "main" for the main database, "temp" for the 5754** temporary database, or the name specified after the AS keyword in 5755** an [ATTACH] statement for an attached database. 5756** ^The S and M arguments passed to 5757** sqlite3_backup_init(D,N,S,M) identify the [database connection] 5758** and database name of the source database, respectively. 5759** ^The source and destination [database connections] (parameters S and D) 5760** must be different or else sqlite3_backup_init(D,N,S,M) will file with 5761** an error. 5762** 5763** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is 5764** returned and an error code and error message are store3d in the 5765** destination [database connection] D. 5766** ^The error code and message for the failed call to sqlite3_backup_init() 5767** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or 5768** [sqlite3_errmsg16()] functions. 5769** ^A successful call to sqlite3_backup_init() returns a pointer to an 5770** [sqlite3_backup] object. 5771** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and 5772** sqlite3_backup_finish() functions to perform the specified backup 5773** operation. 5774** 5775** <b>sqlite3_backup_step()</b> 5776** 5777** ^Function sqlite3_backup_step(B,N) will copy up to N pages between 5778** the source and destination databases specified by [sqlite3_backup] object B. 5779** ^If N is negative, all remaining source pages are copied. 5780** ^If sqlite3_backup_step(B,N) successfully copies N pages and there 5781** are still more pages to be copied, then the function resturns [SQLITE_OK]. 5782** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages 5783** from source to destination, then it returns [SQLITE_DONE]. 5784** ^If an error occurs while running sqlite3_backup_step(B,N), 5785** then an [error code] is returned. ^As well as [SQLITE_OK] and 5786** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY], 5787** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an 5788** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code. 5789** 5790** ^(The sqlite3_backup_step() might return [SQLITE_READONLY] if 5791** <ol> 5792** <li> the destination database was opened read-only, or 5793** <li> the destination database is using write-ahead-log journaling 5794** and the destination and source page sizes differ, or 5795** <li> The destination database is an in-memory database and the 5796** destination and source page sizes differ. 5797** </ol>)^ 5798** 5799** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then 5800** the [sqlite3_busy_handler | busy-handler function] 5801** is invoked (if one is specified). ^If the 5802** busy-handler returns non-zero before the lock is available, then 5803** [SQLITE_BUSY] is returned to the caller. ^In this case the call to 5804** sqlite3_backup_step() can be retried later. ^If the source 5805** [database connection] 5806** is being used to write to the source database when sqlite3_backup_step() 5807** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this 5808** case the call to sqlite3_backup_step() can be retried later on. ^(If 5809** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or 5810** [SQLITE_READONLY] is returned, then 5811** there is no point in retrying the call to sqlite3_backup_step(). These 5812** errors are considered fatal.)^ The application must accept 5813** that the backup operation has failed and pass the backup operation handle 5814** to the sqlite3_backup_finish() to release associated resources. 5815** 5816** ^The first call to sqlite3_backup_step() obtains an exclusive lock 5817** on the destination file. ^The exclusive lock is not released until either 5818** sqlite3_backup_finish() is called or the backup operation is complete 5819** and sqlite3_backup_step() returns [SQLITE_DONE]. ^Every call to 5820** sqlite3_backup_step() obtains a [shared lock] on the source database that 5821** lasts for the duration of the sqlite3_backup_step() call. 5822** ^Because the source database is not locked between calls to 5823** sqlite3_backup_step(), the source database may be modified mid-way 5824** through the backup process. ^If the source database is modified by an 5825** external process or via a database connection other than the one being 5826** used by the backup operation, then the backup will be automatically 5827** restarted by the next call to sqlite3_backup_step(). ^If the source 5828** database is modified by the using the same database connection as is used 5829** by the backup operation, then the backup database is automatically 5830** updated at the same time. 5831** 5832** <b>sqlite3_backup_finish()</b> 5833** 5834** When sqlite3_backup_step() has returned [SQLITE_DONE], or when the 5835** application wishes to abandon the backup operation, the application 5836** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish(). 5837** ^The sqlite3_backup_finish() interfaces releases all 5838** resources associated with the [sqlite3_backup] object. 5839** ^If sqlite3_backup_step() has not yet returned [SQLITE_DONE], then any 5840** active write-transaction on the destination database is rolled back. 5841** The [sqlite3_backup] object is invalid 5842** and may not be used following a call to sqlite3_backup_finish(). 5843** 5844** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no 5845** sqlite3_backup_step() errors occurred, regardless or whether or not 5846** sqlite3_backup_step() completed. 5847** ^If an out-of-memory condition or IO error occurred during any prior 5848** sqlite3_backup_step() call on the same [sqlite3_backup] object, then 5849** sqlite3_backup_finish() returns the corresponding [error code]. 5850** 5851** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step() 5852** is not a permanent error and does not affect the return value of 5853** sqlite3_backup_finish(). 5854** 5855** <b>sqlite3_backup_remaining(), sqlite3_backup_pagecount()</b> 5856** 5857** ^Each call to sqlite3_backup_step() sets two values inside 5858** the [sqlite3_backup] object: the number of pages still to be backed 5859** up and the total number of pages in the source database file. 5860** The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces 5861** retrieve these two values, respectively. 5862** 5863** ^The values returned by these functions are only updated by 5864** sqlite3_backup_step(). ^If the source database is modified during a backup 5865** operation, then the values are not updated to account for any extra 5866** pages that need to be updated or the size of the source database file 5867** changing. 5868** 5869** <b>Concurrent Usage of Database Handles</b> 5870** 5871** ^The source [database connection] may be used by the application for other 5872** purposes while a backup operation is underway or being initialized. 5873** ^If SQLite is compiled and configured to support threadsafe database 5874** connections, then the source database connection may be used concurrently 5875** from within other threads. 5876** 5877** However, the application must guarantee that the destination 5878** [database connection] is not passed to any other API (by any thread) after 5879** sqlite3_backup_init() is called and before the corresponding call to 5880** sqlite3_backup_finish(). SQLite does not currently check to see 5881** if the application incorrectly accesses the destination [database connection] 5882** and so no error code is reported, but the operations may malfunction 5883** nevertheless. Use of the destination database connection while a 5884** backup is in progress might also also cause a mutex deadlock. 5885** 5886** If running in [shared cache mode], the application must 5887** guarantee that the shared cache used by the destination database 5888** is not accessed while the backup is running. In practice this means 5889** that the application must guarantee that the disk file being 5890** backed up to is not accessed by any connection within the process, 5891** not just the specific connection that was passed to sqlite3_backup_init(). 5892** 5893** The [sqlite3_backup] object itself is partially threadsafe. Multiple 5894** threads may safely make multiple concurrent calls to sqlite3_backup_step(). 5895** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() 5896** APIs are not strictly speaking threadsafe. If they are invoked at the 5897** same time as another thread is invoking sqlite3_backup_step() it is 5898** possible that they return invalid values. 5899*/ 5900sqlite3_backup *sqlite3_backup_init( 5901 sqlite3 *pDest, /* Destination database handle */ 5902 const char *zDestName, /* Destination database name */ 5903 sqlite3 *pSource, /* Source database handle */ 5904 const char *zSourceName /* Source database name */ 5905); 5906int sqlite3_backup_step(sqlite3_backup *p, int nPage); 5907int sqlite3_backup_finish(sqlite3_backup *p); 5908int sqlite3_backup_remaining(sqlite3_backup *p); 5909int sqlite3_backup_pagecount(sqlite3_backup *p); 5910 5911/* 5912** CAPI3REF: Unlock Notification 5913** 5914** ^When running in shared-cache mode, a database operation may fail with 5915** an [SQLITE_LOCKED] error if the required locks on the shared-cache or 5916** individual tables within the shared-cache cannot be obtained. See 5917** [SQLite Shared-Cache Mode] for a description of shared-cache locking. 5918** ^This API may be used to register a callback that SQLite will invoke 5919** when the connection currently holding the required lock relinquishes it. 5920** ^This API is only available if the library was compiled with the 5921** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined. 5922** 5923** See Also: [Using the SQLite Unlock Notification Feature]. 5924** 5925** ^Shared-cache locks are released when a database connection concludes 5926** its current transaction, either by committing it or rolling it back. 5927** 5928** ^When a connection (known as the blocked connection) fails to obtain a 5929** shared-cache lock and SQLITE_LOCKED is returned to the caller, the 5930** identity of the database connection (the blocking connection) that 5931** has locked the required resource is stored internally. ^After an 5932** application receives an SQLITE_LOCKED error, it may call the 5933** sqlite3_unlock_notify() method with the blocked connection handle as 5934** the first argument to register for a callback that will be invoked 5935** when the blocking connections current transaction is concluded. ^The 5936** callback is invoked from within the [sqlite3_step] or [sqlite3_close] 5937** call that concludes the blocking connections transaction. 5938** 5939** ^(If sqlite3_unlock_notify() is called in a multi-threaded application, 5940** there is a chance that the blocking connection will have already 5941** concluded its transaction by the time sqlite3_unlock_notify() is invoked. 5942** If this happens, then the specified callback is invoked immediately, 5943** from within the call to sqlite3_unlock_notify().)^ 5944** 5945** ^If the blocked connection is attempting to obtain a write-lock on a 5946** shared-cache table, and more than one other connection currently holds 5947** a read-lock on the same table, then SQLite arbitrarily selects one of 5948** the other connections to use as the blocking connection. 5949** 5950** ^(There may be at most one unlock-notify callback registered by a 5951** blocked connection. If sqlite3_unlock_notify() is called when the 5952** blocked connection already has a registered unlock-notify callback, 5953** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is 5954** called with a NULL pointer as its second argument, then any existing 5955** unlock-notify callback is canceled. ^The blocked connections 5956** unlock-notify callback may also be canceled by closing the blocked 5957** connection using [sqlite3_close()]. 5958** 5959** The unlock-notify callback is not reentrant. If an application invokes 5960** any sqlite3_xxx API functions from within an unlock-notify callback, a 5961** crash or deadlock may be the result. 5962** 5963** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always 5964** returns SQLITE_OK. 5965** 5966** <b>Callback Invocation Details</b> 5967** 5968** When an unlock-notify callback is registered, the application provides a 5969** single void* pointer that is passed to the callback when it is invoked. 5970** However, the signature of the callback function allows SQLite to pass 5971** it an array of void* context pointers. The first argument passed to 5972** an unlock-notify callback is a pointer to an array of void* pointers, 5973** and the second is the number of entries in the array. 5974** 5975** When a blocking connections transaction is concluded, there may be 5976** more than one blocked connection that has registered for an unlock-notify 5977** callback. ^If two or more such blocked connections have specified the 5978** same callback function, then instead of invoking the callback function 5979** multiple times, it is invoked once with the set of void* context pointers 5980** specified by the blocked connections bundled together into an array. 5981** This gives the application an opportunity to prioritize any actions 5982** related to the set of unblocked database connections. 5983** 5984** <b>Deadlock Detection</b> 5985** 5986** Assuming that after registering for an unlock-notify callback a 5987** database waits for the callback to be issued before taking any further 5988** action (a reasonable assumption), then using this API may cause the 5989** application to deadlock. For example, if connection X is waiting for 5990** connection Y's transaction to be concluded, and similarly connection 5991** Y is waiting on connection X's transaction, then neither connection 5992** will proceed and the system may remain deadlocked indefinitely. 5993** 5994** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock 5995** detection. ^If a given call to sqlite3_unlock_notify() would put the 5996** system in a deadlocked state, then SQLITE_LOCKED is returned and no 5997** unlock-notify callback is registered. The system is said to be in 5998** a deadlocked state if connection A has registered for an unlock-notify 5999** callback on the conclusion of connection B's transaction, and connection 6000** B has itself registered for an unlock-notify callback when connection 6001** A's transaction is concluded. ^Indirect deadlock is also detected, so 6002** the system is also considered to be deadlocked if connection B has 6003** registered for an unlock-notify callback on the conclusion of connection 6004** C's transaction, where connection C is waiting on connection A. ^Any 6005** number of levels of indirection are allowed. 6006** 6007** <b>The "DROP TABLE" Exception</b> 6008** 6009** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost 6010** always appropriate to call sqlite3_unlock_notify(). There is however, 6011** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement, 6012** SQLite checks if there are any currently executing SELECT statements 6013** that belong to the same connection. If there are, SQLITE_LOCKED is 6014** returned. In this case there is no "blocking connection", so invoking 6015** sqlite3_unlock_notify() results in the unlock-notify callback being 6016** invoked immediately. If the application then re-attempts the "DROP TABLE" 6017** or "DROP INDEX" query, an infinite loop might be the result. 6018** 6019** One way around this problem is to check the extended error code returned 6020** by an sqlite3_step() call. ^(If there is a blocking connection, then the 6021** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in 6022** the special "DROP TABLE/INDEX" case, the extended error code is just 6023** SQLITE_LOCKED.)^ 6024*/ 6025int sqlite3_unlock_notify( 6026 sqlite3 *pBlocked, /* Waiting connection */ 6027 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */ 6028 void *pNotifyArg /* Argument to pass to xNotify */ 6029); 6030 6031 6032/* 6033** CAPI3REF: String Comparison 6034** 6035** ^The [sqlite3_strnicmp()] API allows applications and extensions to 6036** compare the contents of two buffers containing UTF-8 strings in a 6037** case-independent fashion, using the same definition of case independence 6038** that SQLite uses internally when comparing identifiers. 6039*/ 6040int sqlite3_strnicmp(const char *, const char *, int); 6041 6042/* 6043** CAPI3REF: Error Logging Interface 6044** 6045** ^The [sqlite3_log()] interface writes a message into the error log 6046** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()]. 6047** ^If logging is enabled, the zFormat string and subsequent arguments are 6048** used with [sqlite3_snprintf()] to generate the final output string. 6049** 6050** The sqlite3_log() interface is intended for use by extensions such as 6051** virtual tables, collating functions, and SQL functions. While there is 6052** nothing to prevent an application from calling sqlite3_log(), doing so 6053** is considered bad form. 6054** 6055** The zFormat string must not be NULL. 6056** 6057** To avoid deadlocks and other threading problems, the sqlite3_log() routine 6058** will not use dynamically allocated memory. The log message is stored in 6059** a fixed-length buffer on the stack. If the log message is longer than 6060** a few hundred characters, it will be truncated to the length of the 6061** buffer. 6062*/ 6063void sqlite3_log(int iErrCode, const char *zFormat, ...); 6064 6065/* 6066** CAPI3REF: Write-Ahead Log Commit Hook 6067** 6068** ^The [sqlite3_wal_hook()] function is used to register a callback that 6069** will be invoked each time a database connection commits data to a 6070** [write-ahead log] (i.e. whenever a transaction is committed in 6071** [journal_mode | journal_mode=WAL mode]). 6072** 6073** ^The callback is invoked by SQLite after the commit has taken place and 6074** the associated write-lock on the database released, so the implementation 6075** may read, write or [checkpoint] the database as required. 6076** 6077** ^The first parameter passed to the callback function when it is invoked 6078** is a copy of the third parameter passed to sqlite3_wal_hook() when 6079** registering the callback. ^The second is a copy of the database handle. 6080** ^The third parameter is the name of the database that was written to - 6081** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter 6082** is the number of pages currently in the write-ahead log file, 6083** including those that were just committed. 6084** 6085** The callback function should normally return [SQLITE_OK]. ^If an error 6086** code is returned, that error will propagate back up through the 6087** SQLite code base to cause the statement that provoked the callback 6088** to report an error, though the commit will have still occurred. If the 6089** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value 6090** that does not correspond to any valid SQLite error code, the results 6091** are undefined. 6092** 6093** A single database handle may have at most a single write-ahead log callback 6094** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any 6095** previously registered write-ahead log callback. ^Note that the 6096** [sqlite3_wal_autocheckpoint()] interface and the 6097** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will 6098** those overwrite any prior [sqlite3_wal_hook()] settings. 6099*/ 6100void *sqlite3_wal_hook( 6101 sqlite3*, 6102 int(*)(void *,sqlite3*,const char*,int), 6103 void* 6104); 6105 6106/* 6107** CAPI3REF: Configure an auto-checkpoint 6108** 6109** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around 6110** [sqlite3_wal_hook()] that causes any database on [database connection] D 6111** to automatically [checkpoint] 6112** after committing a transaction if there are N or 6113** more frames in the [write-ahead log] file. ^Passing zero or 6114** a negative value as the nFrame parameter disables automatic 6115** checkpoints entirely. 6116** 6117** ^The callback registered by this function replaces any existing callback 6118** registered using [sqlite3_wal_hook()]. ^Likewise, registering a callback 6119** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism 6120** configured by this function. 6121** 6122** ^The [wal_autocheckpoint pragma] can be used to invoke this interface 6123** from SQL. 6124** 6125** ^Every new [database connection] defaults to having the auto-checkpoint 6126** enabled with a threshold of 1000 pages. The use of this interface 6127** is only necessary if the default setting is found to be suboptimal 6128** for a particular application. 6129*/ 6130int sqlite3_wal_autocheckpoint(sqlite3 *db, int N); 6131 6132/* 6133** CAPI3REF: Checkpoint a database 6134** 6135** ^The [sqlite3_wal_checkpoint(D,X)] interface causes database named X 6136** on [database connection] D to be [checkpointed]. ^If X is NULL or an 6137** empty string, then a checkpoint is run on all databases of 6138** connection D. ^If the database connection D is not in 6139** [WAL | write-ahead log mode] then this interface is a harmless no-op. 6140** 6141** ^The [wal_checkpoint pragma] can be used to invoke this interface 6142** from SQL. ^The [sqlite3_wal_autocheckpoint()] interface and the 6143** [wal_autocheckpoint pragma] can be used to cause this interface to be 6144** run whenever the WAL reaches a certain size threshold. 6145*/ 6146int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb); 6147 6148/* 6149** Undo the hack that converts floating point types to integer for 6150** builds on processors without floating point support. 6151*/ 6152#ifdef SQLITE_OMIT_FLOATING_POINT 6153# undef double 6154#endif 6155 6156#ifdef __cplusplus 6157} /* End of the 'extern "C"' block */ 6158#endif 6159#endif 6160