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