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.420 2008/12/16 13:46:30 drh 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 /* NULL 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_COPY 0 /* No longer used */ 2411 2412/* 2413** CAPI3REF: Tracing And Profiling Functions {H12280} <S60400> 2414** EXPERIMENTAL 2415** 2416** These routines register callback functions that can be used for 2417** tracing and profiling the execution of SQL statements. 2418** 2419** The callback function registered by sqlite3_trace() is invoked at 2420** various times when an SQL statement is being run by [sqlite3_step()]. 2421** The callback returns a UTF-8 rendering of the SQL statement text 2422** as the statement first begins executing. Additional callbacks occur 2423** as each triggered subprogram is entered. The callbacks for triggers 2424** contain a UTF-8 SQL comment that identifies the trigger. 2425** 2426** The callback function registered by sqlite3_profile() is invoked 2427** as each SQL statement finishes. The profile callback contains 2428** the original statement text and an estimate of wall-clock time 2429** of how long that statement took to run. 2430** 2431** INVARIANTS: 2432** 2433** {H12281} The callback function registered by [sqlite3_trace()] 2434** shall be invoked 2435** whenever an SQL statement first begins to execute and 2436** whenever a trigger subprogram first begins to run. 2437** 2438** {H12282} Each call to [sqlite3_trace()] shall override the previously 2439** registered trace callback. 2440** 2441** {H12283} A NULL trace callback shall disable tracing. 2442** 2443** {H12284} The first argument to the trace callback shall be a copy of 2444** the pointer which was the 3rd argument to [sqlite3_trace()]. 2445** 2446** {H12285} The second argument to the trace callback is a 2447** zero-terminated UTF-8 string containing the original text 2448** of the SQL statement as it was passed into [sqlite3_prepare_v2()] 2449** or the equivalent, or an SQL comment indicating the beginning 2450** of a trigger subprogram. 2451** 2452** {H12287} The callback function registered by [sqlite3_profile()] is invoked 2453** as each SQL statement finishes. 2454** 2455** {H12288} The first parameter to the profile callback is a copy of 2456** the 3rd parameter to [sqlite3_profile()]. 2457** 2458** {H12289} The second parameter to the profile callback is a 2459** zero-terminated UTF-8 string that contains the complete text of 2460** the SQL statement as it was processed by [sqlite3_prepare_v2()] 2461** or the equivalent. 2462** 2463** {H12290} The third parameter to the profile callback is an estimate 2464** of the number of nanoseconds of wall-clock time required to 2465** run the SQL statement from start to finish. 2466*/ 2467SQLITE_EXPERIMENTAL void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); 2468SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*, 2469 void(*xProfile)(void*,const char*,sqlite3_uint64), void*); 2470 2471/* 2472** CAPI3REF: Query Progress Callbacks {H12910} <S60400> 2473** 2474** This routine configures a callback function - the 2475** progress callback - that is invoked periodically during long 2476** running calls to [sqlite3_exec()], [sqlite3_step()] and 2477** [sqlite3_get_table()]. An example use for this 2478** interface is to keep a GUI updated during a large query. 2479** 2480** If the progress callback returns non-zero, the operation is 2481** interrupted. This feature can be used to implement a 2482** "Cancel" button on a GUI progress dialog box. 2483** 2484** The progress handler must not do anything that will modify 2485** the database connection that invoked the progress handler. 2486** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their 2487** database connections for the meaning of "modify" in this paragraph. 2488** 2489** INVARIANTS: 2490** 2491** {H12911} The callback function registered by sqlite3_progress_handler() 2492** is invoked periodically during long running calls to 2493** [sqlite3_step()]. 2494** 2495** {H12912} The progress callback is invoked once for every N virtual 2496** machine opcodes, where N is the second argument to 2497** the [sqlite3_progress_handler()] call that registered 2498** the callback. If N is less than 1, sqlite3_progress_handler() 2499** acts as if a NULL progress handler had been specified. 2500** 2501** {H12913} The progress callback itself is identified by the third 2502** argument to sqlite3_progress_handler(). 2503** 2504** {H12914} The fourth argument to sqlite3_progress_handler() is a 2505** void pointer passed to the progress callback 2506** function each time it is invoked. 2507** 2508** {H12915} If a call to [sqlite3_step()] results in fewer than N opcodes 2509** being executed, then the progress callback is never invoked. 2510** 2511** {H12916} Every call to [sqlite3_progress_handler()] 2512** overwrites any previously registered progress handler. 2513** 2514** {H12917} If the progress handler callback is NULL then no progress 2515** handler is invoked. 2516** 2517** {H12918} If the progress callback returns a result other than 0, then 2518** the behavior is a if [sqlite3_interrupt()] had been called. 2519** <S30500> 2520*/ 2521void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); 2522 2523/* 2524** CAPI3REF: Opening A New Database Connection {H12700} <S40200> 2525** 2526** These routines open an SQLite database file whose name is given by the 2527** filename argument. The filename argument is interpreted as UTF-8 for 2528** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte 2529** order for sqlite3_open16(). A [database connection] handle is usually 2530** returned in *ppDb, even if an error occurs. The only exception is that 2531** if SQLite is unable to allocate memory to hold the [sqlite3] object, 2532** a NULL will be written into *ppDb instead of a pointer to the [sqlite3] 2533** object. If the database is opened (and/or created) successfully, then 2534** [SQLITE_OK] is returned. Otherwise an [error code] is returned. The 2535** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain 2536** an English language description of the error. 2537** 2538** The default encoding for the database will be UTF-8 if 2539** sqlite3_open() or sqlite3_open_v2() is called and 2540** UTF-16 in the native byte order if sqlite3_open16() is used. 2541** 2542** Whether or not an error occurs when it is opened, resources 2543** associated with the [database connection] handle should be released by 2544** passing it to [sqlite3_close()] when it is no longer required. 2545** 2546** The sqlite3_open_v2() interface works like sqlite3_open() 2547** except that it accepts two additional parameters for additional control 2548** over the new database connection. The flags parameter can take one of 2549** the following three values, optionally combined with the 2550** [SQLITE_OPEN_NOMUTEX] or [SQLITE_OPEN_FULLMUTEX] flags: 2551** 2552** <dl> 2553** <dt>[SQLITE_OPEN_READONLY]</dt> 2554** <dd>The database is opened in read-only mode. If the database does not 2555** already exist, an error is returned.</dd> 2556** 2557** <dt>[SQLITE_OPEN_READWRITE]</dt> 2558** <dd>The database is opened for reading and writing if possible, or reading 2559** only if the file is write protected by the operating system. In either 2560** case the database must already exist, otherwise an error is returned.</dd> 2561** 2562** <dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt> 2563** <dd>The database is opened for reading and writing, and is creates it if 2564** it does not already exist. This is the behavior that is always used for 2565** sqlite3_open() and sqlite3_open16().</dd> 2566** </dl> 2567** 2568** If the 3rd parameter to sqlite3_open_v2() is not one of the 2569** combinations shown above or one of the combinations shown above combined 2570** with the [SQLITE_OPEN_NOMUTEX] or [SQLITE_OPEN_FULLMUTEX] flags, 2571** then the behavior is undefined. 2572** 2573** If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection 2574** opens in the multi-thread [threading mode] as long as the single-thread 2575** mode has not been set at compile-time or start-time. If the 2576** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens 2577** in the serialized [threading mode] unless single-thread was 2578** previously selected at compile-time or start-time. 2579** 2580** If the filename is ":memory:", then a private, temporary in-memory database 2581** is created for the connection. This in-memory database will vanish when 2582** the database connection is closed. Future versions of SQLite might 2583** make use of additional special filenames that begin with the ":" character. 2584** It is recommended that when a database filename actually does begin with 2585** a ":" character you should prefix the filename with a pathname such as 2586** "./" to avoid ambiguity. 2587** 2588** If the filename is an empty string, then a private, temporary 2589** on-disk database will be created. This private database will be 2590** automatically deleted as soon as the database connection is closed. 2591** 2592** The fourth parameter to sqlite3_open_v2() is the name of the 2593** [sqlite3_vfs] object that defines the operating system interface that 2594** the new database connection should use. If the fourth parameter is 2595** a NULL pointer then the default [sqlite3_vfs] object is used. 2596** 2597** <b>Note to Windows users:</b> The encoding used for the filename argument 2598** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever 2599** codepage is currently defined. Filenames containing international 2600** characters must be converted to UTF-8 prior to passing them into 2601** sqlite3_open() or sqlite3_open_v2(). 2602** 2603** INVARIANTS: 2604** 2605** {H12701} The [sqlite3_open()], [sqlite3_open16()], and 2606** [sqlite3_open_v2()] interfaces create a new 2607** [database connection] associated with 2608** the database file given in their first parameter. 2609** 2610** {H12702} The filename argument is interpreted as UTF-8 2611** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16 2612** in the native byte order for [sqlite3_open16()]. 2613** 2614** {H12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()], 2615** or [sqlite3_open_v2()] writes a pointer to a new 2616** [database connection] into *ppDb. 2617** 2618** {H12704} The [sqlite3_open()], [sqlite3_open16()], and 2619** [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success, 2620** or an appropriate [error code] on failure. 2621** 2622** {H12706} The default text encoding for a new database created using 2623** [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8. 2624** 2625** {H12707} The default text encoding for a new database created using 2626** [sqlite3_open16()] will be UTF-16. 2627** 2628** {H12709} The [sqlite3_open(F,D)] interface is equivalent to 2629** [sqlite3_open_v2(F,D,G,0)] where the G parameter is 2630** [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE]. 2631** 2632** {H12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the 2633** bit value [SQLITE_OPEN_READONLY] then the database is opened 2634** for reading only. 2635** 2636** {H12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the 2637** bit value [SQLITE_OPEN_READWRITE] then the database is opened 2638** reading and writing if possible, or for reading only if the 2639** file is write protected by the operating system. 2640** 2641** {H12713} If the G parameter to [sqlite3_open_v2(F,D,G,V)] omits the 2642** bit value [SQLITE_OPEN_CREATE] and the database does not 2643** previously exist, an error is returned. 2644** 2645** {H12714} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the 2646** bit value [SQLITE_OPEN_CREATE] and the database does not 2647** previously exist, then an attempt is made to create and 2648** initialize the database. 2649** 2650** {H12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()], 2651** or [sqlite3_open_v2()] is ":memory:", then an private, 2652** ephemeral, in-memory database is created for the connection. 2653** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required 2654** in sqlite3_open_v2()?</todo> 2655** 2656** {H12719} If the filename is NULL or an empty string, then a private, 2657** ephemeral on-disk database will be created. 2658** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required 2659** in sqlite3_open_v2()?</todo> 2660** 2661** {H12721} The [database connection] created by [sqlite3_open_v2(F,D,G,V)] 2662** will use the [sqlite3_vfs] object identified by the V parameter, 2663** or the default [sqlite3_vfs] object if V is a NULL pointer. 2664** 2665** {H12723} Two [database connections] will share a common cache if both were 2666** opened with the same VFS while [shared cache mode] was enabled and 2667** if both filenames compare equal using memcmp() after having been 2668** processed by the [sqlite3_vfs | xFullPathname] method of the VFS. 2669*/ 2670int sqlite3_open( 2671 const char *filename, /* Database filename (UTF-8) */ 2672 sqlite3 **ppDb /* OUT: SQLite db handle */ 2673); 2674int sqlite3_open16( 2675 const void *filename, /* Database filename (UTF-16) */ 2676 sqlite3 **ppDb /* OUT: SQLite db handle */ 2677); 2678int sqlite3_open_v2( 2679 const char *filename, /* Database filename (UTF-8) */ 2680 sqlite3 **ppDb, /* OUT: SQLite db handle */ 2681 int flags, /* Flags */ 2682 const char *zVfs /* Name of VFS module to use */ 2683); 2684 2685/* 2686** CAPI3REF: Error Codes And Messages {H12800} <S60200> 2687** 2688** The sqlite3_errcode() interface returns the numeric [result code] or 2689** [extended result code] for the most recent failed sqlite3_* API call 2690** associated with a [database connection]. If a prior API call failed 2691** but the most recent API call succeeded, the return value from 2692** sqlite3_errcode() is undefined. The sqlite3_extended_errcode() 2693** interface is the same except that it always returns the 2694** [extended result code] even when extended result codes are 2695** disabled. 2696** 2697** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language 2698** text that describes the error, as either UTF-8 or UTF-16 respectively. 2699** Memory to hold the error message string is managed internally. 2700** The application does not need to worry about freeing the result. 2701** However, the error string might be overwritten or deallocated by 2702** subsequent calls to other SQLite interface functions. 2703** 2704** When the serialized [threading mode] is in use, it might be the 2705** case that a second error occurs on a separate thread in between 2706** the time of the first error and the call to these interfaces. 2707** When that happens, the second error will be reported since these 2708** interfaces always report the most recent result. To avoid 2709** this, each thread can obtain exclusive use of the [database connection] D 2710** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning 2711** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after 2712** all calls to the interfaces listed here are completed. 2713** 2714** If an interface fails with SQLITE_MISUSE, that means the interface 2715** was invoked incorrectly by the application. In that case, the 2716** error code and message may or may not be set. 2717** 2718** INVARIANTS: 2719** 2720** {H12801} The [sqlite3_errcode(D)] interface returns the numeric 2721** [result code] or [extended result code] for the most recently 2722** failed interface call associated with the [database connection] D. 2723** 2724** {H12802} The [sqlite3_extended_errcode(D)] interface returns the numeric 2725** [extended result code] for the most recently 2726** failed interface call associated with the [database connection] D. 2727** 2728** {H12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)] 2729** interfaces return English-language text that describes 2730** the error in the mostly recently failed interface call, 2731** encoded as either UTF-8 or UTF-16 respectively. 2732** 2733** {H12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()] 2734** are valid until the next SQLite interface call. 2735** 2736** {H12808} Calls to API routines that do not return an error code 2737** (example: [sqlite3_data_count()]) do not 2738** change the error code or message returned by 2739** [sqlite3_errcode()], [sqlite3_extended_errcode()], 2740** [sqlite3_errmsg()], or [sqlite3_errmsg16()]. 2741** 2742** {H12809} Interfaces that are not associated with a specific 2743** [database connection] (examples: 2744** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()] 2745** do not change the values returned by 2746** [sqlite3_errcode()], [sqlite3_extended_errcode()], 2747** [sqlite3_errmsg()], or [sqlite3_errmsg16()]. 2748*/ 2749int sqlite3_errcode(sqlite3 *db); 2750int sqlite3_extended_errcode(sqlite3 *db); 2751const char *sqlite3_errmsg(sqlite3*); 2752const void *sqlite3_errmsg16(sqlite3*); 2753 2754/* 2755** CAPI3REF: SQL Statement Object {H13000} <H13010> 2756** KEYWORDS: {prepared statement} {prepared statements} 2757** 2758** An instance of this object represents a single SQL statement. 2759** This object is variously known as a "prepared statement" or a 2760** "compiled SQL statement" or simply as a "statement". 2761** 2762** The life of a statement object goes something like this: 2763** 2764** <ol> 2765** <li> Create the object using [sqlite3_prepare_v2()] or a related 2766** function. 2767** <li> Bind values to [host parameters] using the sqlite3_bind_*() 2768** interfaces. 2769** <li> Run the SQL by calling [sqlite3_step()] one or more times. 2770** <li> Reset the statement using [sqlite3_reset()] then go back 2771** to step 2. Do this zero or more times. 2772** <li> Destroy the object using [sqlite3_finalize()]. 2773** </ol> 2774** 2775** Refer to documentation on individual methods above for additional 2776** information. 2777*/ 2778typedef struct sqlite3_stmt sqlite3_stmt; 2779 2780/* 2781** CAPI3REF: Run-time Limits {H12760} <S20600> 2782** 2783** This interface allows the size of various constructs to be limited 2784** on a connection by connection basis. The first parameter is the 2785** [database connection] whose limit is to be set or queried. The 2786** second parameter is one of the [limit categories] that define a 2787** class of constructs to be size limited. The third parameter is the 2788** new limit for that construct. The function returns the old limit. 2789** 2790** If the new limit is a negative number, the limit is unchanged. 2791** For the limit category of SQLITE_LIMIT_XYZ there is a hard upper 2792** bound set by a compile-time C preprocessor macro named SQLITE_MAX_XYZ. 2793** (The "_LIMIT_" in the name is changed to "_MAX_".) 2794** Attempts to increase a limit above its hard upper bound are 2795** silently truncated to the hard upper limit. 2796** 2797** Run time limits are intended for use in applications that manage 2798** both their own internal database and also databases that are controlled 2799** by untrusted external sources. An example application might be a 2800** webbrowser that has its own databases for storing history and 2801** separate databases controlled by JavaScript applications downloaded 2802** off the Internet. The internal databases can be given the 2803** large, default limits. Databases managed by external sources can 2804** be given much smaller limits designed to prevent a denial of service 2805** attack. Developers might also want to use the [sqlite3_set_authorizer()] 2806** interface to further control untrusted SQL. The size of the database 2807** created by an untrusted script can be contained using the 2808** [max_page_count] [PRAGMA]. 2809** 2810** New run-time limit categories may be added in future releases. 2811** 2812** INVARIANTS: 2813** 2814** {H12762} A successful call to [sqlite3_limit(D,C,V)] where V is 2815** positive changes the limit on the size of construct C in the 2816** [database connection] D to the lesser of V and the hard upper 2817** bound on the size of C that is set at compile-time. 2818** 2819** {H12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative 2820** leaves the state of the [database connection] D unchanged. 2821** 2822** {H12769} A successful call to [sqlite3_limit(D,C,V)] returns the 2823** value of the limit on the size of construct C in the 2824** [database connection] D as it was prior to the call. 2825*/ 2826int sqlite3_limit(sqlite3*, int id, int newVal); 2827 2828/* 2829** CAPI3REF: Run-Time Limit Categories {H12790} <H12760> 2830** KEYWORDS: {limit category} {limit categories} 2831** 2832** These constants define various aspects of a [database connection] 2833** that can be limited in size by calls to [sqlite3_limit()]. 2834** The meanings of the various limits are as follows: 2835** 2836** <dl> 2837** <dt>SQLITE_LIMIT_LENGTH</dt> 2838** <dd>The maximum size of any string or BLOB or table row.<dd> 2839** 2840** <dt>SQLITE_LIMIT_SQL_LENGTH</dt> 2841** <dd>The maximum length of an SQL statement.</dd> 2842** 2843** <dt>SQLITE_LIMIT_COLUMN</dt> 2844** <dd>The maximum number of columns in a table definition or in the 2845** result set of a SELECT or the maximum number of columns in an index 2846** or in an ORDER BY or GROUP BY clause.</dd> 2847** 2848** <dt>SQLITE_LIMIT_EXPR_DEPTH</dt> 2849** <dd>The maximum depth of the parse tree on any expression.</dd> 2850** 2851** <dt>SQLITE_LIMIT_COMPOUND_SELECT</dt> 2852** <dd>The maximum number of terms in a compound SELECT statement.</dd> 2853** 2854** <dt>SQLITE_LIMIT_VDBE_OP</dt> 2855** <dd>The maximum number of instructions in a virtual machine program 2856** used to implement an SQL statement.</dd> 2857** 2858** <dt>SQLITE_LIMIT_FUNCTION_ARG</dt> 2859** <dd>The maximum number of arguments on a function.</dd> 2860** 2861** <dt>SQLITE_LIMIT_ATTACHED</dt> 2862** <dd>The maximum number of attached databases.</dd> 2863** 2864** <dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt> 2865** <dd>The maximum length of the pattern argument to the LIKE or 2866** GLOB operators.</dd> 2867** 2868** <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt> 2869** <dd>The maximum number of variables in an SQL statement that can 2870** be bound.</dd> 2871** </dl> 2872*/ 2873#define SQLITE_LIMIT_LENGTH 0 2874#define SQLITE_LIMIT_SQL_LENGTH 1 2875#define SQLITE_LIMIT_COLUMN 2 2876#define SQLITE_LIMIT_EXPR_DEPTH 3 2877#define SQLITE_LIMIT_COMPOUND_SELECT 4 2878#define SQLITE_LIMIT_VDBE_OP 5 2879#define SQLITE_LIMIT_FUNCTION_ARG 6 2880#define SQLITE_LIMIT_ATTACHED 7 2881#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8 2882#define SQLITE_LIMIT_VARIABLE_NUMBER 9 2883 2884/* 2885** CAPI3REF: Compiling An SQL Statement {H13010} <S10000> 2886** KEYWORDS: {SQL statement compiler} 2887** 2888** To execute an SQL query, it must first be compiled into a byte-code 2889** program using one of these routines. 2890** 2891** The first argument, "db", is a [database connection] obtained from a 2892** prior call to [sqlite3_open()], [sqlite3_open_v2()] or [sqlite3_open16()]. 2893** 2894** The second argument, "zSql", is the statement to be compiled, encoded 2895** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() 2896** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2() 2897** use UTF-16. 2898** 2899** If the nByte argument is less than zero, then zSql is read up to the 2900** first zero terminator. If nByte is non-negative, then it is the maximum 2901** number of bytes read from zSql. When nByte is non-negative, the 2902** zSql string ends at either the first '\000' or '\u0000' character or 2903** the nByte-th byte, whichever comes first. If the caller knows 2904** that the supplied string is nul-terminated, then there is a small 2905** performance advantage to be gained by passing an nByte parameter that 2906** is equal to the number of bytes in the input string <i>including</i> 2907** the nul-terminator bytes. 2908** 2909** *pzTail is made to point to the first byte past the end of the 2910** first SQL statement in zSql. These routines only compile the first 2911** statement in zSql, so *pzTail is left pointing to what remains 2912** uncompiled. 2913** 2914** *ppStmt is left pointing to a compiled [prepared statement] that can be 2915** executed using [sqlite3_step()]. If there is an error, *ppStmt is set 2916** to NULL. If the input text contains no SQL (if the input is an empty 2917** string or a comment) then *ppStmt is set to NULL. 2918** {A13018} The calling procedure is responsible for deleting the compiled 2919** SQL statement using [sqlite3_finalize()] after it has finished with it. 2920** 2921** On success, [SQLITE_OK] is returned, otherwise an [error code] is returned. 2922** 2923** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are 2924** recommended for all new programs. The two older interfaces are retained 2925** for backwards compatibility, but their use is discouraged. 2926** In the "v2" interfaces, the prepared statement 2927** that is returned (the [sqlite3_stmt] object) contains a copy of the 2928** original SQL text. This causes the [sqlite3_step()] interface to 2929** behave a differently in two ways: 2930** 2931** <ol> 2932** <li> 2933** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it 2934** always used to do, [sqlite3_step()] will automatically recompile the SQL 2935** statement and try to run it again. If the schema has changed in 2936** a way that makes the statement no longer valid, [sqlite3_step()] will still 2937** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is 2938** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the 2939** error go away. Note: use [sqlite3_errmsg()] to find the text 2940** of the parsing error that results in an [SQLITE_SCHEMA] return. 2941** </li> 2942** 2943** <li> 2944** When an error occurs, [sqlite3_step()] will return one of the detailed 2945** [error codes] or [extended error codes]. The legacy behavior was that 2946** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code 2947** and you would have to make a second call to [sqlite3_reset()] in order 2948** to find the underlying cause of the problem. With the "v2" prepare 2949** interfaces, the underlying reason for the error is returned immediately. 2950** </li> 2951** </ol> 2952** 2953** INVARIANTS: 2954** 2955** {H13011} The [sqlite3_prepare(db,zSql,...)] and 2956** [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the 2957** text in their zSql parameter as UTF-8. 2958** 2959** {H13012} The [sqlite3_prepare16(db,zSql,...)] and 2960** [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the 2961** text in their zSql parameter as UTF-16 in the native byte order. 2962** 2963** {H13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] 2964** and its variants is less than zero, the SQL text is 2965** read from zSql is read up to the first zero terminator. 2966** 2967** {H13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] 2968** and its variants is non-negative, then at most nBytes bytes of 2969** SQL text is read from zSql. 2970** 2971** {H13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants 2972** if the zSql input text contains more than one SQL statement 2973** and pzTail is not NULL, then *pzTail is made to point to the 2974** first byte past the end of the first SQL statement in zSql. 2975** <todo>What does *pzTail point to if there is one statement?</todo> 2976** 2977** {H13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)] 2978** or one of its variants writes into *ppStmt a pointer to a new 2979** [prepared statement] or a pointer to NULL if zSql contains 2980** nothing other than whitespace or comments. 2981** 2982** {H13019} The [sqlite3_prepare_v2()] interface and its variants return 2983** [SQLITE_OK] or an appropriate [error code] upon failure. 2984** 2985** {H13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its 2986** variants returns an error (any value other than [SQLITE_OK]), 2987** they first set *ppStmt to NULL. 2988*/ 2989int sqlite3_prepare( 2990 sqlite3 *db, /* Database handle */ 2991 const char *zSql, /* SQL statement, UTF-8 encoded */ 2992 int nByte, /* Maximum length of zSql in bytes. */ 2993 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 2994 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 2995); 2996int sqlite3_prepare_v2( 2997 sqlite3 *db, /* Database handle */ 2998 const char *zSql, /* SQL statement, UTF-8 encoded */ 2999 int nByte, /* Maximum length of zSql in bytes. */ 3000 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 3001 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 3002); 3003int sqlite3_prepare16( 3004 sqlite3 *db, /* Database handle */ 3005 const void *zSql, /* SQL statement, UTF-16 encoded */ 3006 int nByte, /* Maximum length of zSql in bytes. */ 3007 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 3008 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 3009); 3010int sqlite3_prepare16_v2( 3011 sqlite3 *db, /* Database handle */ 3012 const void *zSql, /* SQL statement, UTF-16 encoded */ 3013 int nByte, /* Maximum length of zSql in bytes. */ 3014 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 3015 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 3016); 3017 3018/* 3019** CAPI3REF: Retrieving Statement SQL {H13100} <H13000> 3020** 3021** This interface can be used to retrieve a saved copy of the original 3022** SQL text used to create a [prepared statement] if that statement was 3023** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. 3024** 3025** INVARIANTS: 3026** 3027** {H13101} If the [prepared statement] passed as the argument to 3028** [sqlite3_sql()] was compiled using either [sqlite3_prepare_v2()] or 3029** [sqlite3_prepare16_v2()], then [sqlite3_sql()] returns 3030** a pointer to a zero-terminated string containing a UTF-8 rendering 3031** of the original SQL statement. 3032** 3033** {H13102} If the [prepared statement] passed as the argument to 3034** [sqlite3_sql()] was compiled using either [sqlite3_prepare()] or 3035** [sqlite3_prepare16()], then [sqlite3_sql()] returns a NULL pointer. 3036** 3037** {H13103} The string returned by [sqlite3_sql(S)] is valid until the 3038** [prepared statement] S is deleted using [sqlite3_finalize(S)]. 3039*/ 3040const char *sqlite3_sql(sqlite3_stmt *pStmt); 3041 3042/* 3043** CAPI3REF: Dynamically Typed Value Object {H15000} <S20200> 3044** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} 3045** 3046** SQLite uses the sqlite3_value object to represent all values 3047** that can be stored in a database table. SQLite uses dynamic typing 3048** for the values it stores. Values stored in sqlite3_value objects 3049** can be integers, floating point values, strings, BLOBs, or NULL. 3050** 3051** An sqlite3_value object may be either "protected" or "unprotected". 3052** Some interfaces require a protected sqlite3_value. Other interfaces 3053** will accept either a protected or an unprotected sqlite3_value. 3054** Every interface that accepts sqlite3_value arguments specifies 3055** whether or not it requires a protected sqlite3_value. 3056** 3057** The terms "protected" and "unprotected" refer to whether or not 3058** a mutex is held. A internal mutex is held for a protected 3059** sqlite3_value object but no mutex is held for an unprotected 3060** sqlite3_value object. If SQLite is compiled to be single-threaded 3061** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0) 3062** or if SQLite is run in one of reduced mutex modes 3063** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD] 3064** then there is no distinction between protected and unprotected 3065** sqlite3_value objects and they can be used interchangeably. However, 3066** for maximum code portability it is recommended that applications 3067** still make the distinction between between protected and unprotected 3068** sqlite3_value objects even when not strictly required. 3069** 3070** The sqlite3_value objects that are passed as parameters into the 3071** implementation of [application-defined SQL functions] are protected. 3072** The sqlite3_value object returned by 3073** [sqlite3_column_value()] is unprotected. 3074** Unprotected sqlite3_value objects may only be used with 3075** [sqlite3_result_value()] and [sqlite3_bind_value()]. 3076** The [sqlite3_value_blob | sqlite3_value_type()] family of 3077** interfaces require protected sqlite3_value objects. 3078*/ 3079typedef struct Mem sqlite3_value; 3080 3081/* 3082** CAPI3REF: SQL Function Context Object {H16001} <S20200> 3083** 3084** The context in which an SQL function executes is stored in an 3085** sqlite3_context object. A pointer to an sqlite3_context object 3086** is always first parameter to [application-defined SQL functions]. 3087** The application-defined SQL function implementation will pass this 3088** pointer through into calls to [sqlite3_result_int | sqlite3_result()], 3089** [sqlite3_aggregate_context()], [sqlite3_user_data()], 3090** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()], 3091** and/or [sqlite3_set_auxdata()]. 3092*/ 3093typedef struct sqlite3_context sqlite3_context; 3094 3095/* 3096** CAPI3REF: Binding Values To Prepared Statements {H13500} <S70300> 3097** KEYWORDS: {host parameter} {host parameters} {host parameter name} 3098** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding} 3099** 3100** In the SQL strings input to [sqlite3_prepare_v2()] and its variants, 3101** literals may be replaced by a parameter in one of these forms: 3102** 3103** <ul> 3104** <li> ? 3105** <li> ?NNN 3106** <li> :VVV 3107** <li> @VVV 3108** <li> $VVV 3109** </ul> 3110** 3111** In the parameter forms shown above NNN is an integer literal, 3112** and VVV is an alpha-numeric parameter name. The values of these 3113** parameters (also called "host parameter names" or "SQL parameters") 3114** can be set using the sqlite3_bind_*() routines defined here. 3115** 3116** The first argument to the sqlite3_bind_*() routines is always 3117** a pointer to the [sqlite3_stmt] object returned from 3118** [sqlite3_prepare_v2()] or its variants. 3119** 3120** The second argument is the index of the SQL parameter to be set. 3121** The leftmost SQL parameter has an index of 1. When the same named 3122** SQL parameter is used more than once, second and subsequent 3123** occurrences have the same index as the first occurrence. 3124** The index for named parameters can be looked up using the 3125** [sqlite3_bind_parameter_index()] API if desired. The index 3126** for "?NNN" parameters is the value of NNN. 3127** The NNN value must be between 1 and the [sqlite3_limit()] 3128** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999). 3129** 3130** The third argument is the value to bind to the parameter. 3131** 3132** In those routines that have a fourth argument, its value is the 3133** number of bytes in the parameter. To be clear: the value is the 3134** number of <u>bytes</u> in the value, not the number of characters. 3135** If the fourth parameter is negative, the length of the string is 3136** the number of bytes up to the first zero terminator. 3137** 3138** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and 3139** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or 3140** string after SQLite has finished with it. If the fifth argument is 3141** the special value [SQLITE_STATIC], then SQLite assumes that the 3142** information is in static, unmanaged space and does not need to be freed. 3143** If the fifth argument has the value [SQLITE_TRANSIENT], then 3144** SQLite makes its own private copy of the data immediately, before 3145** the sqlite3_bind_*() routine returns. 3146** 3147** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that 3148** is filled with zeroes. A zeroblob uses a fixed amount of memory 3149** (just an integer to hold its size) while it is being processed. 3150** Zeroblobs are intended to serve as placeholders for BLOBs whose 3151** content is later written using 3152** [sqlite3_blob_open | incremental BLOB I/O] routines. 3153** A negative value for the zeroblob results in a zero-length BLOB. 3154** 3155** The sqlite3_bind_*() routines must be called after 3156** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and 3157** before [sqlite3_step()]. 3158** Bindings are not cleared by the [sqlite3_reset()] routine. 3159** Unbound parameters are interpreted as NULL. 3160** 3161** These routines return [SQLITE_OK] on success or an error code if 3162** anything goes wrong. [SQLITE_RANGE] is returned if the parameter 3163** index is out of range. [SQLITE_NOMEM] is returned if malloc() fails. 3164** [SQLITE_MISUSE] might be returned if these routines are called on a 3165** virtual machine that is the wrong state or which has already been finalized. 3166** Detection of misuse is unreliable. Applications should not depend 3167** on SQLITE_MISUSE returns. SQLITE_MISUSE is intended to indicate a 3168** a logic error in the application. Future versions of SQLite might 3169** panic rather than return SQLITE_MISUSE. 3170** 3171** See also: [sqlite3_bind_parameter_count()], 3172** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. 3173** 3174** INVARIANTS: 3175** 3176** {H13506} The [SQL statement compiler] recognizes tokens of the forms 3177** "?", "?NNN", "$VVV", ":VVV", and "@VVV" as SQL parameters, 3178** where NNN is any sequence of one or more digits 3179** and where VVV is any sequence of one or more alphanumeric 3180** characters or "::" optionally followed by a string containing 3181** no spaces and contained within parentheses. 3182** 3183** {H13509} The initial value of an SQL parameter is NULL. 3184** 3185** {H13512} The index of an "?" SQL parameter is one larger than the 3186** largest index of SQL parameter to the left, or 1 if 3187** the "?" is the leftmost SQL parameter. 3188** 3189** {H13515} The index of an "?NNN" SQL parameter is the integer NNN. 3190** 3191** {H13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is 3192** the same as the index of leftmost occurrences of the same 3193** parameter, or one more than the largest index over all 3194** parameters to the left if this is the first occurrence 3195** of this parameter, or 1 if this is the leftmost parameter. 3196** 3197** {H13521} The [SQL statement compiler] fails with an [SQLITE_RANGE] 3198** error if the index of an SQL parameter is less than 1 3199** or greater than the compile-time SQLITE_MAX_VARIABLE_NUMBER 3200** parameter. 3201** 3202** {H13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)] 3203** associate the value V with all SQL parameters having an 3204** index of N in the [prepared statement] S. 3205** 3206** {H13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)] 3207** override prior calls with the same values of S and N. 3208** 3209** {H13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)] 3210** persist across calls to [sqlite3_reset(S)]. 3211** 3212** {H13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)], 3213** [sqlite3_bind_text(S,N,V,L,D)], or 3214** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L 3215** bytes of the BLOB or string pointed to by V, when L 3216** is non-negative. 3217** 3218** {H13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or 3219** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters 3220** from V through the first zero character when L is negative. 3221** 3222** {H13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)], 3223** [sqlite3_bind_text(S,N,V,L,D)], or 3224** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special 3225** constant [SQLITE_STATIC], SQLite assumes that the value V 3226** is held in static unmanaged space that will not change 3227** during the lifetime of the binding. 3228** 3229** {H13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)], 3230** [sqlite3_bind_text(S,N,V,L,D)], or 3231** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special 3232** constant [SQLITE_TRANSIENT], the routine makes a 3233** private copy of the value V before it returns. 3234** 3235** {H13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)], 3236** [sqlite3_bind_text(S,N,V,L,D)], or 3237** [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to 3238** a function, SQLite invokes that function to destroy the 3239** value V after it has finished using the value V. 3240** 3241** {H13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound 3242** is a BLOB of L bytes, or a zero-length BLOB if L is negative. 3243** 3244** {H13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may 3245** be either a [protected sqlite3_value] object or an 3246** [unprotected sqlite3_value] object. 3247*/ 3248int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); 3249int sqlite3_bind_double(sqlite3_stmt*, int, double); 3250int sqlite3_bind_int(sqlite3_stmt*, int, int); 3251int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); 3252int sqlite3_bind_null(sqlite3_stmt*, int); 3253int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); 3254int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); 3255int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); 3256int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); 3257 3258/* 3259** CAPI3REF: Number Of SQL Parameters {H13600} <S70300> 3260** 3261** This routine can be used to find the number of [SQL parameters] 3262** in a [prepared statement]. SQL parameters are tokens of the 3263** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as 3264** placeholders for values that are [sqlite3_bind_blob | bound] 3265** to the parameters at a later time. 3266** 3267** This routine actually returns the index of the largest (rightmost) 3268** parameter. For all forms except ?NNN, this will correspond to the 3269** number of unique parameters. If parameters of the ?NNN are used, 3270** there may be gaps in the list. 3271** 3272** See also: [sqlite3_bind_blob|sqlite3_bind()], 3273** [sqlite3_bind_parameter_name()], and 3274** [sqlite3_bind_parameter_index()]. 3275** 3276** INVARIANTS: 3277** 3278** {H13601} The [sqlite3_bind_parameter_count(S)] interface returns 3279** the largest index of all SQL parameters in the 3280** [prepared statement] S, or 0 if S contains no SQL parameters. 3281*/ 3282int sqlite3_bind_parameter_count(sqlite3_stmt*); 3283 3284/* 3285** CAPI3REF: Name Of A Host Parameter {H13620} <S70300> 3286** 3287** This routine returns a pointer to the name of the n-th 3288** [SQL parameter] in a [prepared statement]. 3289** SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" 3290** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" 3291** respectively. 3292** In other words, the initial ":" or "$" or "@" or "?" 3293** is included as part of the name. 3294** Parameters of the form "?" without a following integer have no name 3295** and are also referred to as "anonymous parameters". 3296** 3297** The first host parameter has an index of 1, not 0. 3298** 3299** If the value n is out of range or if the n-th parameter is 3300** nameless, then NULL is returned. The returned string is 3301** always in UTF-8 encoding even if the named parameter was 3302** originally specified as UTF-16 in [sqlite3_prepare16()] or 3303** [sqlite3_prepare16_v2()]. 3304** 3305** See also: [sqlite3_bind_blob|sqlite3_bind()], 3306** [sqlite3_bind_parameter_count()], and 3307** [sqlite3_bind_parameter_index()]. 3308** 3309** INVARIANTS: 3310** 3311** {H13621} The [sqlite3_bind_parameter_name(S,N)] interface returns 3312** a UTF-8 rendering of the name of the SQL parameter in 3313** the [prepared statement] S having index N, or 3314** NULL if there is no SQL parameter with index N or if the 3315** parameter with index N is an anonymous parameter "?". 3316*/ 3317const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); 3318 3319/* 3320** CAPI3REF: Index Of A Parameter With A Given Name {H13640} <S70300> 3321** 3322** Return the index of an SQL parameter given its name. The 3323** index value returned is suitable for use as the second 3324** parameter to [sqlite3_bind_blob|sqlite3_bind()]. A zero 3325** is returned if no matching parameter is found. The parameter 3326** name must be given in UTF-8 even if the original statement 3327** was prepared from UTF-16 text using [sqlite3_prepare16_v2()]. 3328** 3329** See also: [sqlite3_bind_blob|sqlite3_bind()], 3330** [sqlite3_bind_parameter_count()], and 3331** [sqlite3_bind_parameter_index()]. 3332** 3333** INVARIANTS: 3334** 3335** {H13641} The [sqlite3_bind_parameter_index(S,N)] interface returns 3336** the index of SQL parameter in the [prepared statement] 3337** S whose name matches the UTF-8 string N, or 0 if there is 3338** no match. 3339*/ 3340int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); 3341 3342/* 3343** CAPI3REF: Reset All Bindings On A Prepared Statement {H13660} <S70300> 3344** 3345** Contrary to the intuition of many, [sqlite3_reset()] does not reset 3346** the [sqlite3_bind_blob | bindings] on a [prepared statement]. 3347** Use this routine to reset all host parameters to NULL. 3348** 3349** INVARIANTS: 3350** 3351** {H13661} The [sqlite3_clear_bindings(S)] interface resets all SQL 3352** parameter bindings in the [prepared statement] S back to NULL. 3353*/ 3354int sqlite3_clear_bindings(sqlite3_stmt*); 3355 3356/* 3357** CAPI3REF: Number Of Columns In A Result Set {H13710} <S10700> 3358** 3359** Return the number of columns in the result set returned by the 3360** [prepared statement]. This routine returns 0 if pStmt is an SQL 3361** statement that does not return data (for example an [UPDATE]). 3362** 3363** INVARIANTS: 3364** 3365** {H13711} The [sqlite3_column_count(S)] interface returns the number of 3366** columns in the result set generated by the [prepared statement] S, 3367** or 0 if S does not generate a result set. 3368*/ 3369int sqlite3_column_count(sqlite3_stmt *pStmt); 3370 3371/* 3372** CAPI3REF: Column Names In A Result Set {H13720} <S10700> 3373** 3374** These routines return the name assigned to a particular column 3375** in the result set of a [SELECT] statement. The sqlite3_column_name() 3376** interface returns a pointer to a zero-terminated UTF-8 string 3377** and sqlite3_column_name16() returns a pointer to a zero-terminated 3378** UTF-16 string. The first parameter is the [prepared statement] 3379** that implements the [SELECT] statement. The second parameter is the 3380** column number. The leftmost column is number 0. 3381** 3382** The returned string pointer is valid until either the [prepared statement] 3383** is destroyed by [sqlite3_finalize()] or until the next call to 3384** sqlite3_column_name() or sqlite3_column_name16() on the same column. 3385** 3386** If sqlite3_malloc() fails during the processing of either routine 3387** (for example during a conversion from UTF-8 to UTF-16) then a 3388** NULL pointer is returned. 3389** 3390** The name of a result column is the value of the "AS" clause for 3391** that column, if there is an AS clause. If there is no AS clause 3392** then the name of the column is unspecified and may change from 3393** one release of SQLite to the next. 3394** 3395** INVARIANTS: 3396** 3397** {H13721} A successful invocation of the [sqlite3_column_name(S,N)] 3398** interface returns the name of the Nth column (where 0 is 3399** the leftmost column) for the result set of the 3400** [prepared statement] S as a zero-terminated UTF-8 string. 3401** 3402** {H13723} A successful invocation of the [sqlite3_column_name16(S,N)] 3403** interface returns the name of the Nth column (where 0 is 3404** the leftmost column) for the result set of the 3405** [prepared statement] S as a zero-terminated UTF-16 string 3406** in the native byte order. 3407** 3408** {H13724} The [sqlite3_column_name()] and [sqlite3_column_name16()] 3409** interfaces return a NULL pointer if they are unable to 3410** allocate memory to hold their normal return strings. 3411** 3412** {H13725} If the N parameter to [sqlite3_column_name(S,N)] or 3413** [sqlite3_column_name16(S,N)] is out of range, then the 3414** interfaces return a NULL pointer. 3415** 3416** {H13726} The strings returned by [sqlite3_column_name(S,N)] and 3417** [sqlite3_column_name16(S,N)] are valid until the next 3418** call to either routine with the same S and N parameters 3419** or until [sqlite3_finalize(S)] is called. 3420** 3421** {H13727} When a result column of a [SELECT] statement contains 3422** an AS clause, the name of that column is the identifier 3423** to the right of the AS keyword. 3424*/ 3425const char *sqlite3_column_name(sqlite3_stmt*, int N); 3426const void *sqlite3_column_name16(sqlite3_stmt*, int N); 3427 3428/* 3429** CAPI3REF: Source Of Data In A Query Result {H13740} <S10700> 3430** 3431** These routines provide a means to determine what column of what 3432** table in which database a result of a [SELECT] statement comes from. 3433** The name of the database or table or column can be returned as 3434** either a UTF-8 or UTF-16 string. The _database_ routines return 3435** the database name, the _table_ routines return the table name, and 3436** the origin_ routines return the column name. 3437** The returned string is valid until the [prepared statement] is destroyed 3438** using [sqlite3_finalize()] or until the same information is requested 3439** again in a different encoding. 3440** 3441** The names returned are the original un-aliased names of the 3442** database, table, and column. 3443** 3444** The first argument to the following calls is a [prepared statement]. 3445** These functions return information about the Nth column returned by 3446** the statement, where N is the second function argument. 3447** 3448** If the Nth column returned by the statement is an expression or 3449** subquery and is not a column value, then all of these functions return 3450** NULL. These routine might also return NULL if a memory allocation error 3451** occurs. Otherwise, they return the name of the attached database, table 3452** and column that query result column was extracted from. 3453** 3454** As with all other SQLite APIs, those postfixed with "16" return 3455** UTF-16 encoded strings, the other functions return UTF-8. {END} 3456** 3457** These APIs are only available if the library was compiled with the 3458** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined. 3459** 3460** {A13751} 3461** If two or more threads call one or more of these routines against the same 3462** prepared statement and column at the same time then the results are 3463** undefined. 3464** 3465** INVARIANTS: 3466** 3467** {H13741} The [sqlite3_column_database_name(S,N)] interface returns either 3468** the UTF-8 zero-terminated name of the database from which the 3469** Nth result column of the [prepared statement] S is extracted, 3470** or NULL if the Nth column of S is a general expression 3471** or if unable to allocate memory to store the name. 3472** 3473** {H13742} The [sqlite3_column_database_name16(S,N)] interface returns either 3474** the UTF-16 native byte order zero-terminated name of the database 3475** from which the Nth result column of the [prepared statement] S is 3476** extracted, or NULL if the Nth column of S is a general expression 3477** or if unable to allocate memory to store the name. 3478** 3479** {H13743} The [sqlite3_column_table_name(S,N)] interface returns either 3480** the UTF-8 zero-terminated name of the table from which the 3481** Nth result column of the [prepared statement] S is extracted, 3482** or NULL if the Nth column of S is a general expression 3483** or if unable to allocate memory to store the name. 3484** 3485** {H13744} The [sqlite3_column_table_name16(S,N)] interface returns either 3486** the UTF-16 native byte order zero-terminated name of the table 3487** from which the Nth result column of the [prepared statement] S is 3488** extracted, or NULL if the Nth column of S is a general expression 3489** or if unable to allocate memory to store the name. 3490** 3491** {H13745} The [sqlite3_column_origin_name(S,N)] interface returns either 3492** the UTF-8 zero-terminated name of the table column from which the 3493** Nth result column of the [prepared statement] S is extracted, 3494** or NULL if the Nth column of S is a general expression 3495** or if unable to allocate memory to store the name. 3496** 3497** {H13746} The [sqlite3_column_origin_name16(S,N)] interface returns either 3498** the UTF-16 native byte order zero-terminated name of the table 3499** column from which the Nth result column of the 3500** [prepared statement] S is extracted, or NULL if the Nth column 3501** of S is a general expression or if unable to allocate memory 3502** to store the name. 3503** 3504** {H13748} The return values from 3505** [sqlite3_column_database_name | column metadata interfaces] 3506** are valid for the lifetime of the [prepared statement] 3507** or until the encoding is changed by another metadata 3508** interface call for the same prepared statement and column. 3509** 3510** ASSUMPTIONS: 3511** 3512** {A13751} If two or more threads call one or more 3513** [sqlite3_column_database_name | column metadata interfaces] 3514** for the same [prepared statement] and result column 3515** at the same time then the results are undefined. 3516*/ 3517const char *sqlite3_column_database_name(sqlite3_stmt*,int); 3518const void *sqlite3_column_database_name16(sqlite3_stmt*,int); 3519const char *sqlite3_column_table_name(sqlite3_stmt*,int); 3520const void *sqlite3_column_table_name16(sqlite3_stmt*,int); 3521const char *sqlite3_column_origin_name(sqlite3_stmt*,int); 3522const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); 3523 3524/* 3525** CAPI3REF: Declared Datatype Of A Query Result {H13760} <S10700> 3526** 3527** The first parameter is a [prepared statement]. 3528** If this statement is a [SELECT] statement and the Nth column of the 3529** returned result set of that [SELECT] is a table column (not an 3530** expression or subquery) then the declared type of the table 3531** column is returned. If the Nth column of the result set is an 3532** expression or subquery, then a NULL pointer is returned. 3533** The returned string is always UTF-8 encoded. {END} 3534** 3535** For example, given the database schema: 3536** 3537** CREATE TABLE t1(c1 VARIANT); 3538** 3539** and the following statement to be compiled: 3540** 3541** SELECT c1 + 1, c1 FROM t1; 3542** 3543** this routine would return the string "VARIANT" for the second result 3544** column (i==1), and a NULL pointer for the first result column (i==0). 3545** 3546** SQLite uses dynamic run-time typing. So just because a column 3547** is declared to contain a particular type does not mean that the 3548** data stored in that column is of the declared type. SQLite is 3549** strongly typed, but the typing is dynamic not static. Type 3550** is associated with individual values, not with the containers 3551** used to hold those values. 3552** 3553** INVARIANTS: 3554** 3555** {H13761} A successful call to [sqlite3_column_decltype(S,N)] returns a 3556** zero-terminated UTF-8 string containing the declared datatype 3557** of the table column that appears as the Nth column (numbered 3558** from 0) of the result set to the [prepared statement] S. 3559** 3560** {H13762} A successful call to [sqlite3_column_decltype16(S,N)] 3561** returns a zero-terminated UTF-16 native byte order string 3562** containing the declared datatype of the table column that appears 3563** as the Nth column (numbered from 0) of the result set to the 3564** [prepared statement] S. 3565** 3566** {H13763} If N is less than 0 or N is greater than or equal to 3567** the number of columns in the [prepared statement] S, 3568** or if the Nth column of S is an expression or subquery rather 3569** than a table column, or if a memory allocation failure 3570** occurs during encoding conversions, then 3571** calls to [sqlite3_column_decltype(S,N)] or 3572** [sqlite3_column_decltype16(S,N)] return NULL. 3573*/ 3574const char *sqlite3_column_decltype(sqlite3_stmt*,int); 3575const void *sqlite3_column_decltype16(sqlite3_stmt*,int); 3576 3577/* 3578** CAPI3REF: Evaluate An SQL Statement {H13200} <S10000> 3579** 3580** After a [prepared statement] has been prepared using either 3581** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy 3582** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function 3583** must be called one or more times to evaluate the statement. 3584** 3585** The details of the behavior of the sqlite3_step() interface depend 3586** on whether the statement was prepared using the newer "v2" interface 3587** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy 3588** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the 3589** new "v2" interface is recommended for new applications but the legacy 3590** interface will continue to be supported. 3591** 3592** In the legacy interface, the return value will be either [SQLITE_BUSY], 3593** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. 3594** With the "v2" interface, any of the other [result codes] or 3595** [extended result codes] might be returned as well. 3596** 3597** [SQLITE_BUSY] means that the database engine was unable to acquire the 3598** database locks it needs to do its job. If the statement is a [COMMIT] 3599** or occurs outside of an explicit transaction, then you can retry the 3600** statement. If the statement is not a [COMMIT] and occurs within a 3601** explicit transaction then you should rollback the transaction before 3602** continuing. 3603** 3604** [SQLITE_DONE] means that the statement has finished executing 3605** successfully. sqlite3_step() should not be called again on this virtual 3606** machine without first calling [sqlite3_reset()] to reset the virtual 3607** machine back to its initial state. 3608** 3609** If the SQL statement being executed returns any data, then [SQLITE_ROW] 3610** is returned each time a new row of data is ready for processing by the 3611** caller. The values may be accessed using the [column access functions]. 3612** sqlite3_step() is called again to retrieve the next row of data. 3613** 3614** [SQLITE_ERROR] means that a run-time error (such as a constraint 3615** violation) has occurred. sqlite3_step() should not be called again on 3616** the VM. More information may be found by calling [sqlite3_errmsg()]. 3617** With the legacy interface, a more specific error code (for example, 3618** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth) 3619** can be obtained by calling [sqlite3_reset()] on the 3620** [prepared statement]. In the "v2" interface, 3621** the more specific error code is returned directly by sqlite3_step(). 3622** 3623** [SQLITE_MISUSE] means that the this routine was called inappropriately. 3624** Perhaps it was called on a [prepared statement] that has 3625** already been [sqlite3_finalize | finalized] or on one that had 3626** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could 3627** be the case that the same database connection is being used by two or 3628** more threads at the same moment in time. 3629** 3630** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step() 3631** API always returns a generic error code, [SQLITE_ERROR], following any 3632** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call 3633** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the 3634** specific [error codes] that better describes the error. 3635** We admit that this is a goofy design. The problem has been fixed 3636** with the "v2" interface. If you prepare all of your SQL statements 3637** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead 3638** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces, 3639** then the more specific [error codes] are returned directly 3640** by sqlite3_step(). The use of the "v2" interface is recommended. 3641** 3642** INVARIANTS: 3643** 3644** {H13202} If the [prepared statement] S is ready to be run, then 3645** [sqlite3_step(S)] advances that prepared statement until 3646** completion or until it is ready to return another row of the 3647** result set, or until an [sqlite3_interrupt | interrupt] 3648** or a run-time error occurs. 3649** 3650** {H15304} When a call to [sqlite3_step(S)] causes the [prepared statement] 3651** S to run to completion, the function returns [SQLITE_DONE]. 3652** 3653** {H15306} When a call to [sqlite3_step(S)] stops because it is ready to 3654** return another row of the result set, it returns [SQLITE_ROW]. 3655** 3656** {H15308} If a call to [sqlite3_step(S)] encounters an 3657** [sqlite3_interrupt | interrupt] or a run-time error, 3658** it returns an appropriate error code that is not one of 3659** [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE]. 3660** 3661** {H15310} If an [sqlite3_interrupt | interrupt] or a run-time error 3662** occurs during a call to [sqlite3_step(S)] 3663** for a [prepared statement] S created using 3664** legacy interfaces [sqlite3_prepare()] or 3665** [sqlite3_prepare16()], then the function returns either 3666** [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE]. 3667*/ 3668int sqlite3_step(sqlite3_stmt*); 3669 3670/* 3671** CAPI3REF: Number of columns in a result set {H13770} <S10700> 3672** 3673** Returns the number of values in the current row of the result set. 3674** 3675** INVARIANTS: 3676** 3677** {H13771} After a call to [sqlite3_step(S)] that returns [SQLITE_ROW], 3678** the [sqlite3_data_count(S)] routine will return the same value 3679** as the [sqlite3_column_count(S)] function. 3680** 3681** {H13772} After [sqlite3_step(S)] has returned any value other than 3682** [SQLITE_ROW] or before [sqlite3_step(S)] has been called on the 3683** [prepared statement] for the first time since it was 3684** [sqlite3_prepare | prepared] or [sqlite3_reset | reset], 3685** the [sqlite3_data_count(S)] routine returns zero. 3686*/ 3687int sqlite3_data_count(sqlite3_stmt *pStmt); 3688 3689/* 3690** CAPI3REF: Fundamental Datatypes {H10265} <S10110><S10120> 3691** KEYWORDS: SQLITE_TEXT 3692** 3693** {H10266} Every value in SQLite has one of five fundamental datatypes: 3694** 3695** <ul> 3696** <li> 64-bit signed integer 3697** <li> 64-bit IEEE floating point number 3698** <li> string 3699** <li> BLOB 3700** <li> NULL 3701** </ul> {END} 3702** 3703** These constants are codes for each of those types. 3704** 3705** Note that the SQLITE_TEXT constant was also used in SQLite version 2 3706** for a completely different meaning. Software that links against both 3707** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not 3708** SQLITE_TEXT. 3709*/ 3710#define SQLITE_INTEGER 1 3711#define SQLITE_FLOAT 2 3712#define SQLITE_BLOB 4 3713#define SQLITE_NULL 5 3714#ifdef SQLITE_TEXT 3715# undef SQLITE_TEXT 3716#else 3717# define SQLITE_TEXT 3 3718#endif 3719#define SQLITE3_TEXT 3 3720 3721/* 3722** CAPI3REF: Result Values From A Query {H13800} <S10700> 3723** KEYWORDS: {column access functions} 3724** 3725** These routines form the "result set query" interface. 3726** 3727** These routines return information about a single column of the current 3728** result row of a query. In every case the first argument is a pointer 3729** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*] 3730** that was returned from [sqlite3_prepare_v2()] or one of its variants) 3731** and the second argument is the index of the column for which information 3732** should be returned. The leftmost column of the result set has the index 0. 3733** 3734** If the SQL statement does not currently point to a valid row, or if the 3735** column index is out of range, the result is undefined. 3736** These routines may only be called when the most recent call to 3737** [sqlite3_step()] has returned [SQLITE_ROW] and neither 3738** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently. 3739** If any of these routines are called after [sqlite3_reset()] or 3740** [sqlite3_finalize()] or after [sqlite3_step()] has returned 3741** something other than [SQLITE_ROW], the results are undefined. 3742** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()] 3743** are called from a different thread while any of these routines 3744** are pending, then the results are undefined. 3745** 3746** The sqlite3_column_type() routine returns the 3747** [SQLITE_INTEGER | datatype code] for the initial data type 3748** of the result column. The returned value is one of [SQLITE_INTEGER], 3749** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value 3750** returned by sqlite3_column_type() is only meaningful if no type 3751** conversions have occurred as described below. After a type conversion, 3752** the value returned by sqlite3_column_type() is undefined. Future 3753** versions of SQLite may change the behavior of sqlite3_column_type() 3754** following a type conversion. 3755** 3756** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 3757** routine returns the number of bytes in that BLOB or string. 3758** If the result is a UTF-16 string, then sqlite3_column_bytes() converts 3759** the string to UTF-8 and then returns the number of bytes. 3760** If the result is a numeric value then sqlite3_column_bytes() uses 3761** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns 3762** the number of bytes in that string. 3763** The value returned does not include the zero terminator at the end 3764** of the string. For clarity: the value returned is the number of 3765** bytes in the string, not the number of characters. 3766** 3767** Strings returned by sqlite3_column_text() and sqlite3_column_text16(), 3768** even empty strings, are always zero terminated. The return 3769** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary 3770** pointer, possibly even a NULL pointer. 3771** 3772** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() 3773** but leaves the result in UTF-16 in native byte order instead of UTF-8. 3774** The zero terminator is not included in this count. 3775** 3776** The object returned by [sqlite3_column_value()] is an 3777** [unprotected sqlite3_value] object. An unprotected sqlite3_value object 3778** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()]. 3779** If the [unprotected sqlite3_value] object returned by 3780** [sqlite3_column_value()] is used in any other way, including calls 3781** to routines like [sqlite3_value_int()], [sqlite3_value_text()], 3782** or [sqlite3_value_bytes()], then the behavior is undefined. 3783** 3784** These routines attempt to convert the value where appropriate. For 3785** example, if the internal representation is FLOAT and a text result 3786** is requested, [sqlite3_snprintf()] is used internally to perform the 3787** conversion automatically. The following table details the conversions 3788** that are applied: 3789** 3790** <blockquote> 3791** <table border="1"> 3792** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion 3793** 3794** <tr><td> NULL <td> INTEGER <td> Result is 0 3795** <tr><td> NULL <td> FLOAT <td> Result is 0.0 3796** <tr><td> NULL <td> TEXT <td> Result is NULL pointer 3797** <tr><td> NULL <td> BLOB <td> Result is NULL pointer 3798** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float 3799** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer 3800** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT 3801** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer 3802** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float 3803** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT 3804** <tr><td> TEXT <td> INTEGER <td> Use atoi() 3805** <tr><td> TEXT <td> FLOAT <td> Use atof() 3806** <tr><td> TEXT <td> BLOB <td> No change 3807** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi() 3808** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof() 3809** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed 3810** </table> 3811** </blockquote> 3812** 3813** The table above makes reference to standard C library functions atoi() 3814** and atof(). SQLite does not really use these functions. It has its 3815** own equivalent internal routines. The atoi() and atof() names are 3816** used in the table for brevity and because they are familiar to most 3817** C programmers. 3818** 3819** Note that when type conversions occur, pointers returned by prior 3820** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or 3821** sqlite3_column_text16() may be invalidated. 3822** Type conversions and pointer invalidations might occur 3823** in the following cases: 3824** 3825** <ul> 3826** <li> The initial content is a BLOB and sqlite3_column_text() or 3827** sqlite3_column_text16() is called. A zero-terminator might 3828** need to be added to the string.</li> 3829** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or 3830** sqlite3_column_text16() is called. The content must be converted 3831** to UTF-16.</li> 3832** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or 3833** sqlite3_column_text() is called. The content must be converted 3834** to UTF-8.</li> 3835** </ul> 3836** 3837** Conversions between UTF-16be and UTF-16le are always done in place and do 3838** not invalidate a prior pointer, though of course the content of the buffer 3839** that the prior pointer points to will have been modified. Other kinds 3840** of conversion are done in place when it is possible, but sometimes they 3841** are not possible and in those cases prior pointers are invalidated. 3842** 3843** The safest and easiest to remember policy is to invoke these routines 3844** in one of the following ways: 3845** 3846** <ul> 3847** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li> 3848** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li> 3849** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li> 3850** </ul> 3851** 3852** In other words, you should call sqlite3_column_text(), 3853** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result 3854** into the desired format, then invoke sqlite3_column_bytes() or 3855** sqlite3_column_bytes16() to find the size of the result. Do not mix calls 3856** to sqlite3_column_text() or sqlite3_column_blob() with calls to 3857** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() 3858** with calls to sqlite3_column_bytes(). 3859** 3860** The pointers returned are valid until a type conversion occurs as 3861** described above, or until [sqlite3_step()] or [sqlite3_reset()] or 3862** [sqlite3_finalize()] is called. The memory space used to hold strings 3863** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned 3864** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into 3865** [sqlite3_free()]. 3866** 3867** If a memory allocation error occurs during the evaluation of any 3868** of these routines, a default value is returned. The default value 3869** is either the integer 0, the floating point number 0.0, or a NULL 3870** pointer. Subsequent calls to [sqlite3_errcode()] will return 3871** [SQLITE_NOMEM]. 3872** 3873** INVARIANTS: 3874** 3875** {H13803} The [sqlite3_column_blob(S,N)] interface converts the 3876** Nth column in the current row of the result set for 3877** the [prepared statement] S into a BLOB and then returns a 3878** pointer to the converted value. 3879** 3880** {H13806} The [sqlite3_column_bytes(S,N)] interface returns the 3881** number of bytes in the BLOB or string (exclusive of the 3882** zero terminator on the string) that was returned by the 3883** most recent call to [sqlite3_column_blob(S,N)] or 3884** [sqlite3_column_text(S,N)]. 3885** 3886** {H13809} The [sqlite3_column_bytes16(S,N)] interface returns the 3887** number of bytes in the string (exclusive of the 3888** zero terminator on the string) that was returned by the 3889** most recent call to [sqlite3_column_text16(S,N)]. 3890** 3891** {H13812} The [sqlite3_column_double(S,N)] interface converts the 3892** Nth column in the current row of the result set for the 3893** [prepared statement] S into a floating point value and 3894** returns a copy of that value. 3895** 3896** {H13815} The [sqlite3_column_int(S,N)] interface converts the 3897** Nth column in the current row of the result set for the 3898** [prepared statement] S into a 64-bit signed integer and 3899** returns the lower 32 bits of that integer. 3900** 3901** {H13818} The [sqlite3_column_int64(S,N)] interface converts the 3902** Nth column in the current row of the result set for the 3903** [prepared statement] S into a 64-bit signed integer and 3904** returns a copy of that integer. 3905** 3906** {H13821} The [sqlite3_column_text(S,N)] interface converts the 3907** Nth column in the current row of the result set for 3908** the [prepared statement] S into a zero-terminated UTF-8 3909** string and returns a pointer to that string. 3910** 3911** {H13824} The [sqlite3_column_text16(S,N)] interface converts the 3912** Nth column in the current row of the result set for the 3913** [prepared statement] S into a zero-terminated 2-byte 3914** aligned UTF-16 native byte order string and returns 3915** a pointer to that string. 3916** 3917** {H13827} The [sqlite3_column_type(S,N)] interface returns 3918** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT], 3919** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for 3920** the Nth column in the current row of the result set for 3921** the [prepared statement] S. 3922** 3923** {H13830} The [sqlite3_column_value(S,N)] interface returns a 3924** pointer to an [unprotected sqlite3_value] object for the 3925** Nth column in the current row of the result set for 3926** the [prepared statement] S. 3927*/ 3928const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); 3929int sqlite3_column_bytes(sqlite3_stmt*, int iCol); 3930int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); 3931double sqlite3_column_double(sqlite3_stmt*, int iCol); 3932int sqlite3_column_int(sqlite3_stmt*, int iCol); 3933sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); 3934const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); 3935const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); 3936int sqlite3_column_type(sqlite3_stmt*, int iCol); 3937sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); 3938 3939/* 3940** CAPI3REF: Destroy A Prepared Statement Object {H13300} <S70300><S30100> 3941** 3942** The sqlite3_finalize() function is called to delete a [prepared statement]. 3943** If the statement was executed successfully or not executed at all, then 3944** SQLITE_OK is returned. If execution of the statement failed then an 3945** [error code] or [extended error code] is returned. 3946** 3947** This routine can be called at any point during the execution of the 3948** [prepared statement]. If the virtual machine has not 3949** completed execution when this routine is called, that is like 3950** encountering an error or an [sqlite3_interrupt | interrupt]. 3951** Incomplete updates may be rolled back and transactions canceled, 3952** depending on the circumstances, and the 3953** [error code] returned will be [SQLITE_ABORT]. 3954** 3955** INVARIANTS: 3956** 3957** {H11302} The [sqlite3_finalize(S)] interface destroys the 3958** [prepared statement] S and releases all 3959** memory and file resources held by that object. 3960** 3961** {H11304} If the most recent call to [sqlite3_step(S)] for the 3962** [prepared statement] S returned an error, 3963** then [sqlite3_finalize(S)] returns that same error. 3964*/ 3965int sqlite3_finalize(sqlite3_stmt *pStmt); 3966 3967/* 3968** CAPI3REF: Reset A Prepared Statement Object {H13330} <S70300> 3969** 3970** The sqlite3_reset() function is called to reset a [prepared statement] 3971** object back to its initial state, ready to be re-executed. 3972** Any SQL statement variables that had values bound to them using 3973** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. 3974** Use [sqlite3_clear_bindings()] to reset the bindings. 3975** 3976** {H11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S 3977** back to the beginning of its program. 3978** 3979** {H11334} If the most recent call to [sqlite3_step(S)] for the 3980** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE], 3981** or if [sqlite3_step(S)] has never before been called on S, 3982** then [sqlite3_reset(S)] returns [SQLITE_OK]. 3983** 3984** {H11336} If the most recent call to [sqlite3_step(S)] for the 3985** [prepared statement] S indicated an error, then 3986** [sqlite3_reset(S)] returns an appropriate [error code]. 3987** 3988** {H11338} The [sqlite3_reset(S)] interface does not change the values 3989** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S. 3990*/ 3991int sqlite3_reset(sqlite3_stmt *pStmt); 3992 3993/* 3994** CAPI3REF: Create Or Redefine SQL Functions {H16100} <S20200> 3995** KEYWORDS: {function creation routines} 3996** KEYWORDS: {application-defined SQL function} 3997** KEYWORDS: {application-defined SQL functions} 3998** 3999** These two functions (collectively known as "function creation routines") 4000** are used to add SQL functions or aggregates or to redefine the behavior 4001** of existing SQL functions or aggregates. The only difference between the 4002** two is that the second parameter, the name of the (scalar) function or 4003** aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16 4004** for sqlite3_create_function16(). 4005** 4006** The first parameter is the [database connection] to which the SQL 4007** function is to be added. If a single program uses more than one database 4008** connection internally, then SQL functions must be added individually to 4009** each database connection. 4010** 4011** The second parameter is the name of the SQL function to be created or 4012** redefined. The length of the name is limited to 255 bytes, exclusive of 4013** the zero-terminator. Note that the name length limit is in bytes, not 4014** characters. Any attempt to create a function with a longer name 4015** will result in [SQLITE_ERROR] being returned. 4016** 4017** The third parameter (nArg) 4018** is the number of arguments that the SQL function or 4019** aggregate takes. If this parameter is negative, then the SQL function or 4020** aggregate may take any number of arguments. 4021** 4022** The fourth parameter, eTextRep, specifies what 4023** [SQLITE_UTF8 | text encoding] this SQL function prefers for 4024** its parameters. Any SQL function implementation should be able to work 4025** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be 4026** more efficient with one encoding than another. It is allowed to 4027** invoke sqlite3_create_function() or sqlite3_create_function16() multiple 4028** times with the same function but with different values of eTextRep. 4029** When multiple implementations of the same function are available, SQLite 4030** will pick the one that involves the least amount of data conversion. 4031** If there is only a single implementation which does not care what text 4032** encoding is used, then the fourth argument should be [SQLITE_ANY]. 4033** 4034** The fifth parameter is an arbitrary pointer. The implementation of the 4035** function can gain access to this pointer using [sqlite3_user_data()]. 4036** 4037** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are 4038** pointers to C-language functions that implement the SQL function or 4039** aggregate. A scalar SQL function requires an implementation of the xFunc 4040** callback only, NULL pointers should be passed as the xStep and xFinal 4041** parameters. An aggregate SQL function requires an implementation of xStep 4042** and xFinal and NULL should be passed for xFunc. To delete an existing 4043** SQL function or aggregate, pass NULL for all three function callbacks. 4044** 4045** It is permitted to register multiple implementations of the same 4046** functions with the same name but with either differing numbers of 4047** arguments or differing preferred text encodings. SQLite will use 4048** the implementation most closely matches the way in which the 4049** SQL function is used. A function implementation with a non-negative 4050** nArg parameter is a better match than a function implementation with 4051** a negative nArg. A function where the preferred text encoding 4052** matches the database encoding is a better 4053** match than a function where the encoding is different. 4054** A function where the encoding difference is between UTF16le and UTF16be 4055** is a closer match than a function where the encoding difference is 4056** between UTF8 and UTF16. 4057** 4058** Built-in functions may be overloaded by new application-defined functions. 4059** The first application-defined function with a given name overrides all 4060** built-in functions in the same [database connection] with the same name. 4061** Subsequent application-defined functions of the same name only override 4062** prior application-defined functions that are an exact match for the 4063** number of parameters and preferred encoding. 4064** 4065** An application-defined function is permitted to call other 4066** SQLite interfaces. However, such calls must not 4067** close the database connection nor finalize or reset the prepared 4068** statement in which the function is running. 4069** 4070** INVARIANTS: 4071** 4072** {H16103} The [sqlite3_create_function16(D,X,...)] interface shall behave 4073** as [sqlite3_create_function(D,X,...)] in every way except that it 4074** interprets the X argument as zero-terminated UTF-16 4075** native byte order instead of as zero-terminated UTF-8. 4076** 4077** {H16106} A successful invocation of the 4078** [sqlite3_create_function(D,X,N,E,...)] interface shall register 4079** or replaces callback functions in the [database connection] D 4080** used to implement the SQL function named X with N parameters 4081** and having a preferred text encoding of E. 4082** 4083** {H16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)] 4084** shall replace the P, F, S, and L values from any prior calls with 4085** the same D, X, N, and E values. 4086** 4087** {H16112} The [sqlite3_create_function(D,X,...)] interface shall fail 4088** if the SQL function name X is 4089** longer than 255 bytes exclusive of the zero terminator. 4090** 4091** {H16118} The [sqlite3_create_function(D,X,N,E,P,F,S,L)] interface 4092** shall fail unless either F is NULL and S and L are non-NULL or 4093*** F is non-NULL and S and L are NULL. 4094** 4095** {H16121} The [sqlite3_create_function(D,...)] interface shall fails with an 4096** error code of [SQLITE_BUSY] if there exist [prepared statements] 4097** associated with the [database connection] D. 4098** 4099** {H16124} The [sqlite3_create_function(D,X,N,...)] interface shall fail with 4100** an error code of [SQLITE_ERROR] if parameter N is less 4101** than -1 or greater than 127. 4102** 4103** {H16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)] 4104** interface shall register callbacks to be invoked for the 4105** SQL function 4106** named X when the number of arguments to the SQL function is 4107** exactly N. 4108** 4109** {H16130} When N is -1, the [sqlite3_create_function(D,X,N,...)] 4110** interface shall register callbacks to be invoked for the SQL 4111** function named X with any number of arguments. 4112** 4113** {H16133} When calls to [sqlite3_create_function(D,X,N,...)] 4114** specify multiple implementations of the same function X 4115** and when one implementation has N>=0 and the other has N=(-1) 4116** the implementation with a non-zero N shall be preferred. 4117** 4118** {H16136} When calls to [sqlite3_create_function(D,X,N,E,...)] 4119** specify multiple implementations of the same function X with 4120** the same number of arguments N but with different 4121** encodings E, then the implementation where E matches the 4122** database encoding shall preferred. 4123** 4124** {H16139} For an aggregate SQL function created using 4125** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finalizer 4126** function L shall always be invoked exactly once if the 4127** step function S is called one or more times. 4128** 4129** {H16142} When SQLite invokes either the xFunc or xStep function of 4130** an application-defined SQL function or aggregate created 4131** by [sqlite3_create_function()] or [sqlite3_create_function16()], 4132** then the array of [sqlite3_value] objects passed as the 4133** third parameter shall be [protected sqlite3_value] objects. 4134*/ 4135int sqlite3_create_function( 4136 sqlite3 *db, 4137 const char *zFunctionName, 4138 int nArg, 4139 int eTextRep, 4140 void *pApp, 4141 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 4142 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 4143 void (*xFinal)(sqlite3_context*) 4144); 4145int sqlite3_create_function16( 4146 sqlite3 *db, 4147 const void *zFunctionName, 4148 int nArg, 4149 int eTextRep, 4150 void *pApp, 4151 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 4152 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 4153 void (*xFinal)(sqlite3_context*) 4154); 4155 4156/* 4157** CAPI3REF: Text Encodings {H10267} <S50200> <H16100> 4158** 4159** These constant define integer codes that represent the various 4160** text encodings supported by SQLite. 4161*/ 4162#define SQLITE_UTF8 1 4163#define SQLITE_UTF16LE 2 4164#define SQLITE_UTF16BE 3 4165#define SQLITE_UTF16 4 /* Use native byte order */ 4166#define SQLITE_ANY 5 /* sqlite3_create_function only */ 4167#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ 4168 4169/* 4170** CAPI3REF: Deprecated Functions 4171** DEPRECATED 4172** 4173** These functions are [deprecated]. In order to maintain 4174** backwards compatibility with older code, these functions continue 4175** to be supported. However, new applications should avoid 4176** the use of these functions. To help encourage people to avoid 4177** using these functions, we are not going to tell you what they do. 4178*/ 4179#ifndef SQLITE_OMIT_DEPRECATED 4180SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*); 4181SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*); 4182SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); 4183SQLITE_DEPRECATED int sqlite3_global_recover(void); 4184SQLITE_DEPRECATED void sqlite3_thread_cleanup(void); 4185SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); 4186#endif 4187 4188/* 4189** CAPI3REF: Obtaining SQL Function Parameter Values {H15100} <S20200> 4190** 4191** The C-language implementation of SQL functions and aggregates uses 4192** this set of interface routines to access the parameter values on 4193** the function or aggregate. 4194** 4195** The xFunc (for scalar functions) or xStep (for aggregates) parameters 4196** to [sqlite3_create_function()] and [sqlite3_create_function16()] 4197** define callbacks that implement the SQL functions and aggregates. 4198** The 4th parameter to these callbacks is an array of pointers to 4199** [protected sqlite3_value] objects. There is one [sqlite3_value] object for 4200** each parameter to the SQL function. These routines are used to 4201** extract values from the [sqlite3_value] objects. 4202** 4203** These routines work only with [protected sqlite3_value] objects. 4204** Any attempt to use these routines on an [unprotected sqlite3_value] 4205** object results in undefined behavior. 4206** 4207** These routines work just like the corresponding [column access functions] 4208** except that these routines take a single [protected sqlite3_value] object 4209** pointer instead of a [sqlite3_stmt*] pointer and an integer column number. 4210** 4211** The sqlite3_value_text16() interface extracts a UTF-16 string 4212** in the native byte-order of the host machine. The 4213** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces 4214** extract UTF-16 strings as big-endian and little-endian respectively. 4215** 4216** The sqlite3_value_numeric_type() interface attempts to apply 4217** numeric affinity to the value. This means that an attempt is 4218** made to convert the value to an integer or floating point. If 4219** such a conversion is possible without loss of information (in other 4220** words, if the value is a string that looks like a number) 4221** then the conversion is performed. Otherwise no conversion occurs. 4222** The [SQLITE_INTEGER | datatype] after conversion is returned. 4223** 4224** Please pay particular attention to the fact that the pointer returned 4225** from [sqlite3_value_blob()], [sqlite3_value_text()], or 4226** [sqlite3_value_text16()] can be invalidated by a subsequent call to 4227** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], 4228** or [sqlite3_value_text16()]. 4229** 4230** These routines must be called from the same thread as 4231** the SQL function that supplied the [sqlite3_value*] parameters. 4232** 4233** INVARIANTS: 4234** 4235** {H15103} The [sqlite3_value_blob(V)] interface converts the 4236** [protected sqlite3_value] object V into a BLOB and then 4237** returns a pointer to the converted value. 4238** 4239** {H15106} The [sqlite3_value_bytes(V)] interface returns the 4240** number of bytes in the BLOB or string (exclusive of the 4241** zero terminator on the string) that was returned by the 4242** most recent call to [sqlite3_value_blob(V)] or 4243** [sqlite3_value_text(V)]. 4244** 4245** {H15109} The [sqlite3_value_bytes16(V)] interface returns the 4246** number of bytes in the string (exclusive of the 4247** zero terminator on the string) that was returned by the 4248** most recent call to [sqlite3_value_text16(V)], 4249** [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)]. 4250** 4251** {H15112} The [sqlite3_value_double(V)] interface converts the 4252** [protected sqlite3_value] object V into a floating point value and 4253** returns a copy of that value. 4254** 4255** {H15115} The [sqlite3_value_int(V)] interface converts the 4256** [protected sqlite3_value] object V into a 64-bit signed integer and 4257** returns the lower 32 bits of that integer. 4258** 4259** {H15118} The [sqlite3_value_int64(V)] interface converts the 4260** [protected sqlite3_value] object V into a 64-bit signed integer and 4261** returns a copy of that integer. 4262** 4263** {H15121} The [sqlite3_value_text(V)] interface converts the 4264** [protected sqlite3_value] object V into a zero-terminated UTF-8 4265** string and returns a pointer to that string. 4266** 4267** {H15124} The [sqlite3_value_text16(V)] interface converts the 4268** [protected sqlite3_value] object V into a zero-terminated 2-byte 4269** aligned UTF-16 native byte order 4270** string and returns a pointer to that string. 4271** 4272** {H15127} The [sqlite3_value_text16be(V)] interface converts the 4273** [protected sqlite3_value] object V into a zero-terminated 2-byte 4274** aligned UTF-16 big-endian 4275** string and returns a pointer to that string. 4276** 4277** {H15130} The [sqlite3_value_text16le(V)] interface converts the 4278** [protected sqlite3_value] object V into a zero-terminated 2-byte 4279** aligned UTF-16 little-endian 4280** string and returns a pointer to that string. 4281** 4282** {H15133} The [sqlite3_value_type(V)] interface returns 4283** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT], 4284** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for 4285** the [sqlite3_value] object V. 4286** 4287** {H15136} The [sqlite3_value_numeric_type(V)] interface converts 4288** the [protected sqlite3_value] object V into either an integer or 4289** a floating point value if it can do so without loss of 4290** information, and returns one of [SQLITE_NULL], 4291** [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or 4292** [SQLITE_BLOB] as appropriate for the 4293** [protected sqlite3_value] object V after the conversion attempt. 4294*/ 4295const void *sqlite3_value_blob(sqlite3_value*); 4296int sqlite3_value_bytes(sqlite3_value*); 4297int sqlite3_value_bytes16(sqlite3_value*); 4298double sqlite3_value_double(sqlite3_value*); 4299int sqlite3_value_int(sqlite3_value*); 4300sqlite3_int64 sqlite3_value_int64(sqlite3_value*); 4301const unsigned char *sqlite3_value_text(sqlite3_value*); 4302const void *sqlite3_value_text16(sqlite3_value*); 4303const void *sqlite3_value_text16le(sqlite3_value*); 4304const void *sqlite3_value_text16be(sqlite3_value*); 4305int sqlite3_value_type(sqlite3_value*); 4306int sqlite3_value_numeric_type(sqlite3_value*); 4307 4308/* 4309** CAPI3REF: Obtain Aggregate Function Context {H16210} <S20200> 4310** 4311** The implementation of aggregate SQL functions use this routine to allocate 4312** a structure for storing their state. 4313** 4314** The first time the sqlite3_aggregate_context() routine is called for a 4315** particular aggregate, SQLite allocates nBytes of memory, zeroes out that 4316** memory, and returns a pointer to it. On second and subsequent calls to 4317** sqlite3_aggregate_context() for the same aggregate function index, 4318** the same buffer is returned. The implementation of the aggregate can use 4319** the returned buffer to accumulate data. 4320** 4321** SQLite automatically frees the allocated buffer when the aggregate 4322** query concludes. 4323** 4324** The first parameter should be a copy of the 4325** [sqlite3_context | SQL function context] that is the first parameter 4326** to the callback routine that implements the aggregate function. 4327** 4328** This routine must be called from the same thread in which 4329** the aggregate SQL function is running. 4330** 4331** INVARIANTS: 4332** 4333** {H16211} The first invocation of [sqlite3_aggregate_context(C,N)] for 4334** a particular instance of an aggregate function (for a particular 4335** context C) causes SQLite to allocate N bytes of memory, 4336** zero that memory, and return a pointer to the allocated memory. 4337** 4338** {H16213} If a memory allocation error occurs during 4339** [sqlite3_aggregate_context(C,N)] then the function returns 0. 4340** 4341** {H16215} Second and subsequent invocations of 4342** [sqlite3_aggregate_context(C,N)] for the same context pointer C 4343** ignore the N parameter and return a pointer to the same 4344** block of memory returned by the first invocation. 4345** 4346** {H16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is 4347** automatically freed on the next call to [sqlite3_reset()] 4348** or [sqlite3_finalize()] for the [prepared statement] containing 4349** the aggregate function associated with context C. 4350*/ 4351void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); 4352 4353/* 4354** CAPI3REF: User Data For Functions {H16240} <S20200> 4355** 4356** The sqlite3_user_data() interface returns a copy of 4357** the pointer that was the pUserData parameter (the 5th parameter) 4358** of the [sqlite3_create_function()] 4359** and [sqlite3_create_function16()] routines that originally 4360** registered the application defined function. {END} 4361** 4362** This routine must be called from the same thread in which 4363** the application-defined function is running. 4364** 4365** INVARIANTS: 4366** 4367** {H16243} The [sqlite3_user_data(C)] interface returns a copy of the 4368** P pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)] 4369** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that 4370** registered the SQL function associated with [sqlite3_context] C. 4371*/ 4372void *sqlite3_user_data(sqlite3_context*); 4373 4374/* 4375** CAPI3REF: Database Connection For Functions {H16250} <S60600><S20200> 4376** 4377** The sqlite3_context_db_handle() interface returns a copy of 4378** the pointer to the [database connection] (the 1st parameter) 4379** of the [sqlite3_create_function()] 4380** and [sqlite3_create_function16()] routines that originally 4381** registered the application defined function. 4382** 4383** INVARIANTS: 4384** 4385** {H16253} The [sqlite3_context_db_handle(C)] interface returns a copy of the 4386** D pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)] 4387** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that 4388** registered the SQL function associated with [sqlite3_context] C. 4389*/ 4390sqlite3 *sqlite3_context_db_handle(sqlite3_context*); 4391 4392/* 4393** CAPI3REF: Function Auxiliary Data {H16270} <S20200> 4394** 4395** The following two functions may be used by scalar SQL functions to 4396** associate metadata with argument values. If the same value is passed to 4397** multiple invocations of the same SQL function during query execution, under 4398** some circumstances the associated metadata may be preserved. This may 4399** be used, for example, to add a regular-expression matching scalar 4400** function. The compiled version of the regular expression is stored as 4401** metadata associated with the SQL value passed as the regular expression 4402** pattern. The compiled regular expression can be reused on multiple 4403** invocations of the same function so that the original pattern string 4404** does not need to be recompiled on each invocation. 4405** 4406** The sqlite3_get_auxdata() interface returns a pointer to the metadata 4407** associated by the sqlite3_set_auxdata() function with the Nth argument 4408** value to the application-defined function. If no metadata has been ever 4409** been set for the Nth argument of the function, or if the corresponding 4410** function parameter has changed since the meta-data was set, 4411** then sqlite3_get_auxdata() returns a NULL pointer. 4412** 4413** The sqlite3_set_auxdata() interface saves the metadata 4414** pointed to by its 3rd parameter as the metadata for the N-th 4415** argument of the application-defined function. Subsequent 4416** calls to sqlite3_get_auxdata() might return this data, if it has 4417** not been destroyed. 4418** If it is not NULL, SQLite will invoke the destructor 4419** function given by the 4th parameter to sqlite3_set_auxdata() on 4420** the metadata when the corresponding function parameter changes 4421** or when the SQL statement completes, whichever comes first. 4422** 4423** SQLite is free to call the destructor and drop metadata on any 4424** parameter of any function at any time. The only guarantee is that 4425** the destructor will be called before the metadata is dropped. 4426** 4427** In practice, metadata is preserved between function calls for 4428** expressions that are constant at compile time. This includes literal 4429** values and SQL variables. 4430** 4431** These routines must be called from the same thread in which 4432** the SQL function is running. 4433** 4434** INVARIANTS: 4435** 4436** {H16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer 4437** to metadata associated with the Nth parameter of the SQL function 4438** whose context is C, or NULL if there is no metadata associated 4439** with that parameter. 4440** 4441** {H16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata 4442** pointer P to the Nth parameter of the SQL function with context C. 4443** 4444** {H16276} SQLite will invoke the destructor D with a single argument 4445** which is the metadata pointer P following a call to 4446** [sqlite3_set_auxdata(C,N,P,D)] when SQLite ceases to hold 4447** the metadata. 4448** 4449** {H16277} SQLite ceases to hold metadata for an SQL function parameter 4450** when the value of that parameter changes. 4451** 4452** {H16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor 4453** is called for any prior metadata associated with the same function 4454** context C and parameter N. 4455** 4456** {H16279} SQLite will call destructors for any metadata it is holding 4457** in a particular [prepared statement] S when either 4458** [sqlite3_reset(S)] or [sqlite3_finalize(S)] is called. 4459*/ 4460void *sqlite3_get_auxdata(sqlite3_context*, int N); 4461void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*)); 4462 4463 4464/* 4465** CAPI3REF: Constants Defining Special Destructor Behavior {H10280} <S30100> 4466** 4467** These are special values for the destructor that is passed in as the 4468** final argument to routines like [sqlite3_result_blob()]. If the destructor 4469** argument is SQLITE_STATIC, it means that the content pointer is constant 4470** and will never change. It does not need to be destroyed. The 4471** SQLITE_TRANSIENT value means that the content will likely change in 4472** the near future and that SQLite should make its own private copy of 4473** the content before returning. 4474** 4475** The typedef is necessary to work around problems in certain 4476** C++ compilers. See ticket #2191. 4477*/ 4478typedef void (*sqlite3_destructor_type)(void*); 4479#define SQLITE_STATIC ((sqlite3_destructor_type)0) 4480#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) 4481 4482/* 4483** CAPI3REF: Setting The Result Of An SQL Function {H16400} <S20200> 4484** 4485** These routines are used by the xFunc or xFinal callbacks that 4486** implement SQL functions and aggregates. See 4487** [sqlite3_create_function()] and [sqlite3_create_function16()] 4488** for additional information. 4489** 4490** These functions work very much like the [parameter binding] family of 4491** functions used to bind values to host parameters in prepared statements. 4492** Refer to the [SQL parameter] documentation for additional information. 4493** 4494** The sqlite3_result_blob() interface sets the result from 4495** an application-defined function to be the BLOB whose content is pointed 4496** to by the second parameter and which is N bytes long where N is the 4497** third parameter. 4498** 4499** The sqlite3_result_zeroblob() interfaces set the result of 4500** the application-defined function to be a BLOB containing all zero 4501** bytes and N bytes in size, where N is the value of the 2nd parameter. 4502** 4503** The sqlite3_result_double() interface sets the result from 4504** an application-defined function to be a floating point value specified 4505** by its 2nd argument. 4506** 4507** The sqlite3_result_error() and sqlite3_result_error16() functions 4508** cause the implemented SQL function to throw an exception. 4509** SQLite uses the string pointed to by the 4510** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16() 4511** as the text of an error message. SQLite interprets the error 4512** message string from sqlite3_result_error() as UTF-8. SQLite 4513** interprets the string from sqlite3_result_error16() as UTF-16 in native 4514** byte order. If the third parameter to sqlite3_result_error() 4515** or sqlite3_result_error16() is negative then SQLite takes as the error 4516** message all text up through the first zero character. 4517** If the third parameter to sqlite3_result_error() or 4518** sqlite3_result_error16() is non-negative then SQLite takes that many 4519** bytes (not characters) from the 2nd parameter as the error message. 4520** The sqlite3_result_error() and sqlite3_result_error16() 4521** routines make a private copy of the error message text before 4522** they return. Hence, the calling function can deallocate or 4523** modify the text after they return without harm. 4524** The sqlite3_result_error_code() function changes the error code 4525** returned by SQLite as a result of an error in a function. By default, 4526** the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error() 4527** or sqlite3_result_error16() resets the error code to SQLITE_ERROR. 4528** 4529** The sqlite3_result_toobig() interface causes SQLite to throw an error 4530** indicating that a string or BLOB is to long to represent. 4531** 4532** The sqlite3_result_nomem() interface causes SQLite to throw an error 4533** indicating that a memory allocation failed. 4534** 4535** The sqlite3_result_int() interface sets the return value 4536** of the application-defined function to be the 32-bit signed integer 4537** value given in the 2nd argument. 4538** The sqlite3_result_int64() interface sets the return value 4539** of the application-defined function to be the 64-bit signed integer 4540** value given in the 2nd argument. 4541** 4542** The sqlite3_result_null() interface sets the return value 4543** of the application-defined function to be NULL. 4544** 4545** The sqlite3_result_text(), sqlite3_result_text16(), 4546** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces 4547** set the return value of the application-defined function to be 4548** a text string which is represented as UTF-8, UTF-16 native byte order, 4549** UTF-16 little endian, or UTF-16 big endian, respectively. 4550** SQLite takes the text result from the application from 4551** the 2nd parameter of the sqlite3_result_text* interfaces. 4552** If the 3rd parameter to the sqlite3_result_text* interfaces 4553** is negative, then SQLite takes result text from the 2nd parameter 4554** through the first zero character. 4555** If the 3rd parameter to the sqlite3_result_text* interfaces 4556** is non-negative, then as many bytes (not characters) of the text 4557** pointed to by the 2nd parameter are taken as the application-defined 4558** function result. 4559** If the 4th parameter to the sqlite3_result_text* interfaces 4560** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that 4561** function as the destructor on the text or BLOB result when it has 4562** finished using that result. 4563** If the 4th parameter to the sqlite3_result_text* interfaces or 4564** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite 4565** assumes that the text or BLOB result is in constant space and does not 4566** copy the it or call a destructor when it has finished using that result. 4567** If the 4th parameter to the sqlite3_result_text* interfaces 4568** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT 4569** then SQLite makes a copy of the result into space obtained from 4570** from [sqlite3_malloc()] before it returns. 4571** 4572** The sqlite3_result_value() interface sets the result of 4573** the application-defined function to be a copy the 4574** [unprotected sqlite3_value] object specified by the 2nd parameter. The 4575** sqlite3_result_value() interface makes a copy of the [sqlite3_value] 4576** so that the [sqlite3_value] specified in the parameter may change or 4577** be deallocated after sqlite3_result_value() returns without harm. 4578** A [protected sqlite3_value] object may always be used where an 4579** [unprotected sqlite3_value] object is required, so either 4580** kind of [sqlite3_value] object can be used with this interface. 4581** 4582** If these routines are called from within the different thread 4583** than the one containing the application-defined function that received 4584** the [sqlite3_context] pointer, the results are undefined. 4585** 4586** INVARIANTS: 4587** 4588** {H16403} The default return value from any SQL function is NULL. 4589** 4590** {H16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the 4591** return value of function C to be a BLOB that is N bytes 4592** in length and with content pointed to by V. 4593** 4594** {H16409} The [sqlite3_result_double(C,V)] interface changes the 4595** return value of function C to be the floating point value V. 4596** 4597** {H16412} The [sqlite3_result_error(C,V,N)] interface changes the return 4598** value of function C to be an exception with error code 4599** [SQLITE_ERROR] and a UTF-8 error message copied from V up to the 4600** first zero byte or until N bytes are read if N is positive. 4601** 4602** {H16415} The [sqlite3_result_error16(C,V,N)] interface changes the return 4603** value of function C to be an exception with error code 4604** [SQLITE_ERROR] and a UTF-16 native byte order error message 4605** copied from V up to the first zero terminator or until N bytes 4606** are read if N is positive. 4607** 4608** {H16418} The [sqlite3_result_error_toobig(C)] interface changes the return 4609** value of the function C to be an exception with error code 4610** [SQLITE_TOOBIG] and an appropriate error message. 4611** 4612** {H16421} The [sqlite3_result_error_nomem(C)] interface changes the return 4613** value of the function C to be an exception with error code 4614** [SQLITE_NOMEM] and an appropriate error message. 4615** 4616** {H16424} The [sqlite3_result_error_code(C,E)] interface changes the return 4617** value of the function C to be an exception with error code E. 4618** The error message text is unchanged. 4619** 4620** {H16427} The [sqlite3_result_int(C,V)] interface changes the 4621** return value of function C to be the 32-bit integer value V. 4622** 4623** {H16430} The [sqlite3_result_int64(C,V)] interface changes the 4624** return value of function C to be the 64-bit integer value V. 4625** 4626** {H16433} The [sqlite3_result_null(C)] interface changes the 4627** return value of function C to be NULL. 4628** 4629** {H16436} The [sqlite3_result_text(C,V,N,D)] interface changes the 4630** return value of function C to be the UTF-8 string 4631** V up to the first zero if N is negative 4632** or the first N bytes of V if N is non-negative. 4633** 4634** {H16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the 4635** return value of function C to be the UTF-16 native byte order 4636** string V up to the first zero if N is negative 4637** or the first N bytes of V if N is non-negative. 4638** 4639** {H16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the 4640** return value of function C to be the UTF-16 big-endian 4641** string V up to the first zero if N is negative 4642** or the first N bytes or V if N is non-negative. 4643** 4644** {H16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the 4645** return value of function C to be the UTF-16 little-endian 4646** string V up to the first zero if N is negative 4647** or the first N bytes of V if N is non-negative. 4648** 4649** {H16448} The [sqlite3_result_value(C,V)] interface changes the 4650** return value of function C to be the [unprotected sqlite3_value] 4651** object V. 4652** 4653** {H16451} The [sqlite3_result_zeroblob(C,N)] interface changes the 4654** return value of function C to be an N-byte BLOB of all zeros. 4655** 4656** {H16454} The [sqlite3_result_error()] and [sqlite3_result_error16()] 4657** interfaces make a copy of their error message strings before 4658** returning. 4659** 4660** {H16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], 4661** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], 4662** [sqlite3_result_text16be(C,V,N,D)], or 4663** [sqlite3_result_text16le(C,V,N,D)] is the constant [SQLITE_STATIC] 4664** then no destructor is ever called on the pointer V and SQLite 4665** assumes that V is immutable. 4666** 4667** {H16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], 4668** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], 4669** [sqlite3_result_text16be(C,V,N,D)], or 4670** [sqlite3_result_text16le(C,V,N,D)] is the constant 4671** [SQLITE_TRANSIENT] then the interfaces makes a copy of the 4672** content of V and retains the copy. 4673** 4674** {H16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], 4675** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], 4676** [sqlite3_result_text16be(C,V,N,D)], or 4677** [sqlite3_result_text16le(C,V,N,D)] is some value other than 4678** the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then 4679** SQLite will invoke the destructor D with V as its only argument 4680** when it has finished with the V value. 4681*/ 4682void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); 4683void sqlite3_result_double(sqlite3_context*, double); 4684void sqlite3_result_error(sqlite3_context*, const char*, int); 4685void sqlite3_result_error16(sqlite3_context*, const void*, int); 4686void sqlite3_result_error_toobig(sqlite3_context*); 4687void sqlite3_result_error_nomem(sqlite3_context*); 4688void sqlite3_result_error_code(sqlite3_context*, int); 4689void sqlite3_result_int(sqlite3_context*, int); 4690void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); 4691void sqlite3_result_null(sqlite3_context*); 4692void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); 4693void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); 4694void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); 4695void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); 4696void sqlite3_result_value(sqlite3_context*, sqlite3_value*); 4697void sqlite3_result_zeroblob(sqlite3_context*, int n); 4698 4699/* 4700** CAPI3REF: Define New Collating Sequences {H16600} <S20300> 4701** 4702** These functions are used to add new collation sequences to the 4703** [database connection] specified as the first argument. 4704** 4705** The name of the new collation sequence is specified as a UTF-8 string 4706** for sqlite3_create_collation() and sqlite3_create_collation_v2() 4707** and a UTF-16 string for sqlite3_create_collation16(). In all cases 4708** the name is passed as the second function argument. 4709** 4710** The third argument may be one of the constants [SQLITE_UTF8], 4711** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied 4712** routine expects to be passed pointers to strings encoded using UTF-8, 4713** UTF-16 little-endian, or UTF-16 big-endian, respectively. The 4714** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that 4715** the routine expects pointers to 16-bit word aligned strings 4716** of UTF-16 in the native byte order of the host computer. 4717** 4718** A pointer to the user supplied routine must be passed as the fifth 4719** argument. If it is NULL, this is the same as deleting the collation 4720** sequence (so that SQLite cannot call it anymore). 4721** Each time the application supplied function is invoked, it is passed 4722** as its first parameter a copy of the void* passed as the fourth argument 4723** to sqlite3_create_collation() or sqlite3_create_collation16(). 4724** 4725** The remaining arguments to the application-supplied routine are two strings, 4726** each represented by a (length, data) pair and encoded in the encoding 4727** that was passed as the third argument when the collation sequence was 4728** registered. {END} The application defined collation routine should 4729** return negative, zero or positive if the first string is less than, 4730** equal to, or greater than the second string. i.e. (STRING1 - STRING2). 4731** 4732** The sqlite3_create_collation_v2() works like sqlite3_create_collation() 4733** except that it takes an extra argument which is a destructor for 4734** the collation. The destructor is called when the collation is 4735** destroyed and is passed a copy of the fourth parameter void* pointer 4736** of the sqlite3_create_collation_v2(). 4737** Collations are destroyed when they are overridden by later calls to the 4738** collation creation functions or when the [database connection] is closed 4739** using [sqlite3_close()]. 4740** 4741** INVARIANTS: 4742** 4743** {H16603} A successful call to the 4744** [sqlite3_create_collation_v2(B,X,E,P,F,D)] interface 4745** registers function F as the comparison function used to 4746** implement collation X on the [database connection] B for 4747** databases having encoding E. 4748** 4749** {H16604} SQLite understands the X parameter to 4750** [sqlite3_create_collation_v2(B,X,E,P,F,D)] as a zero-terminated 4751** UTF-8 string in which case is ignored for ASCII characters and 4752** is significant for non-ASCII characters. 4753** 4754** {H16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)] 4755** with the same values for B, X, and E, override prior values 4756** of P, F, and D. 4757** 4758** {H16609} If the destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)] 4759** is not NULL then it is called with argument P when the 4760** collating function is dropped by SQLite. 4761** 4762** {H16612} A collating function is dropped when it is overloaded. 4763** 4764** {H16615} A collating function is dropped when the database connection 4765** is closed using [sqlite3_close()]. 4766** 4767** {H16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)] 4768** is passed through as the first parameter to the comparison 4769** function F for all subsequent invocations of F. 4770** 4771** {H16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly 4772** the same as a call to [sqlite3_create_collation_v2()] with 4773** the same parameters and a NULL destructor. 4774** 4775** {H16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)], 4776** SQLite uses the comparison function F for all text comparison 4777** operations on the [database connection] B on text values that 4778** use the collating sequence named X. 4779** 4780** {H16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same 4781** as [sqlite3_create_collation(B,X,E,P,F)] except that the 4782** collation name X is understood as UTF-16 in native byte order 4783** instead of UTF-8. 4784** 4785** {H16630} When multiple comparison functions are available for the same 4786** collating sequence, SQLite chooses the one whose text encoding 4787** requires the least amount of conversion from the default 4788** text encoding of the database. 4789*/ 4790int sqlite3_create_collation( 4791 sqlite3*, 4792 const char *zName, 4793 int eTextRep, 4794 void*, 4795 int(*xCompare)(void*,int,const void*,int,const void*) 4796); 4797int sqlite3_create_collation_v2( 4798 sqlite3*, 4799 const char *zName, 4800 int eTextRep, 4801 void*, 4802 int(*xCompare)(void*,int,const void*,int,const void*), 4803 void(*xDestroy)(void*) 4804); 4805int sqlite3_create_collation16( 4806 sqlite3*, 4807 const void *zName, 4808 int eTextRep, 4809 void*, 4810 int(*xCompare)(void*,int,const void*,int,const void*) 4811); 4812 4813/* 4814** CAPI3REF: Collation Needed Callbacks {H16700} <S20300> 4815** 4816** To avoid having to register all collation sequences before a database 4817** can be used, a single callback function may be registered with the 4818** [database connection] to be called whenever an undefined collation 4819** sequence is required. 4820** 4821** If the function is registered using the sqlite3_collation_needed() API, 4822** then it is passed the names of undefined collation sequences as strings 4823** encoded in UTF-8. {H16703} If sqlite3_collation_needed16() is used, 4824** the names are passed as UTF-16 in machine native byte order. 4825** A call to either function replaces any existing callback. 4826** 4827** When the callback is invoked, the first argument passed is a copy 4828** of the second argument to sqlite3_collation_needed() or 4829** sqlite3_collation_needed16(). The second argument is the database 4830** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], 4831** or [SQLITE_UTF16LE], indicating the most desirable form of the collation 4832** sequence function required. The fourth parameter is the name of the 4833** required collation sequence. 4834** 4835** The callback function should register the desired collation using 4836** [sqlite3_create_collation()], [sqlite3_create_collation16()], or 4837** [sqlite3_create_collation_v2()]. 4838** 4839** INVARIANTS: 4840** 4841** {H16702} A successful call to [sqlite3_collation_needed(D,P,F)] 4842** or [sqlite3_collation_needed16(D,P,F)] causes 4843** the [database connection] D to invoke callback F with first 4844** parameter P whenever it needs a comparison function for a 4845** collating sequence that it does not know about. 4846** 4847** {H16704} Each successful call to [sqlite3_collation_needed()] or 4848** [sqlite3_collation_needed16()] overrides the callback registered 4849** on the same [database connection] by prior calls to either 4850** interface. 4851** 4852** {H16706} The name of the requested collating function passed in the 4853** 4th parameter to the callback is in UTF-8 if the callback 4854** was registered using [sqlite3_collation_needed()] and 4855** is in UTF-16 native byte order if the callback was 4856** registered using [sqlite3_collation_needed16()]. 4857*/ 4858int sqlite3_collation_needed( 4859 sqlite3*, 4860 void*, 4861 void(*)(void*,sqlite3*,int eTextRep,const char*) 4862); 4863int sqlite3_collation_needed16( 4864 sqlite3*, 4865 void*, 4866 void(*)(void*,sqlite3*,int eTextRep,const void*) 4867); 4868 4869/* 4870** Specify the key for an encrypted database. This routine should be 4871** called right after sqlite3_open(). 4872** 4873** The code to implement this API is not available in the public release 4874** of SQLite. 4875*/ 4876int sqlite3_key( 4877 sqlite3 *db, /* Database to be rekeyed */ 4878 const void *pKey, int nKey /* The key */ 4879); 4880 4881/* 4882** Change the key on an open database. If the current database is not 4883** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the 4884** database is decrypted. 4885** 4886** The code to implement this API is not available in the public release 4887** of SQLite. 4888*/ 4889int sqlite3_rekey( 4890 sqlite3 *db, /* Database to be rekeyed */ 4891 const void *pKey, int nKey /* The new key */ 4892); 4893 4894/* 4895** CAPI3REF: Suspend Execution For A Short Time {H10530} <S40410> 4896** 4897** The sqlite3_sleep() function causes the current thread to suspend execution 4898** for at least a number of milliseconds specified in its parameter. 4899** 4900** If the operating system does not support sleep requests with 4901** millisecond time resolution, then the time will be rounded up to 4902** the nearest second. The number of milliseconds of sleep actually 4903** requested from the operating system is returned. 4904** 4905** SQLite implements this interface by calling the xSleep() 4906** method of the default [sqlite3_vfs] object. 4907** 4908** INVARIANTS: 4909** 4910** {H10533} The [sqlite3_sleep(M)] interface invokes the xSleep 4911** method of the default [sqlite3_vfs|VFS] in order to 4912** suspend execution of the current thread for at least 4913** M milliseconds. 4914** 4915** {H10536} The [sqlite3_sleep(M)] interface returns the number of 4916** milliseconds of sleep actually requested of the operating 4917** system, which might be larger than the parameter M. 4918*/ 4919int sqlite3_sleep(int); 4920 4921/* 4922** CAPI3REF: Name Of The Folder Holding Temporary Files {H10310} <S20000> 4923** 4924** If this global variable is made to point to a string which is 4925** the name of a folder (a.k.a. directory), then all temporary files 4926** created by SQLite will be placed in that directory. If this variable 4927** is a NULL pointer, then SQLite performs a search for an appropriate 4928** temporary file directory. 4929** 4930** It is not safe to modify this variable once a [database connection] 4931** has been opened. It is intended that this variable be set once 4932** as part of process initialization and before any SQLite interface 4933** routines have been call and remain unchanged thereafter. 4934*/ 4935SQLITE_EXTERN char *sqlite3_temp_directory; 4936 4937/* 4938** CAPI3REF: Test For Auto-Commit Mode {H12930} <S60200> 4939** KEYWORDS: {autocommit mode} 4940** 4941** The sqlite3_get_autocommit() interface returns non-zero or 4942** zero if the given database connection is or is not in autocommit mode, 4943** respectively. Autocommit mode is on by default. 4944** Autocommit mode is disabled by a [BEGIN] statement. 4945** Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK]. 4946** 4947** If certain kinds of errors occur on a statement within a multi-statement 4948** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR], 4949** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the 4950** transaction might be rolled back automatically. The only way to 4951** find out whether SQLite automatically rolled back the transaction after 4952** an error is to use this function. 4953** 4954** INVARIANTS: 4955** 4956** {H12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or 4957** zero if the [database connection] D is or is not in autocommit 4958** mode, respectively. 4959** 4960** {H12932} Autocommit mode is on by default. 4961** 4962** {H12933} Autocommit mode is disabled by a successful [BEGIN] statement. 4963** 4964** {H12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK] 4965** statement. 4966** 4967** ASSUMPTIONS: 4968** 4969** {A12936} If another thread changes the autocommit status of the database 4970** connection while this routine is running, then the return value 4971** is undefined. 4972*/ 4973int sqlite3_get_autocommit(sqlite3*); 4974 4975/* 4976** CAPI3REF: Find The Database Handle Of A Prepared Statement {H13120} <S60600> 4977** 4978** The sqlite3_db_handle interface returns the [database connection] handle 4979** to which a [prepared statement] belongs. The database handle returned by 4980** sqlite3_db_handle is the same database handle that was the first argument 4981** to the [sqlite3_prepare_v2()] call (or its variants) that was used to 4982** create the statement in the first place. 4983** 4984** INVARIANTS: 4985** 4986** {H13123} The [sqlite3_db_handle(S)] interface returns a pointer 4987** to the [database connection] associated with the 4988** [prepared statement] S. 4989*/ 4990sqlite3 *sqlite3_db_handle(sqlite3_stmt*); 4991 4992/* 4993** CAPI3REF: Find the next prepared statement {H13140} <S60600> 4994** 4995** This interface returns a pointer to the next [prepared statement] after 4996** pStmt associated with the [database connection] pDb. If pStmt is NULL 4997** then this interface returns a pointer to the first prepared statement 4998** associated with the database connection pDb. If no prepared statement 4999** satisfies the conditions of this routine, it returns NULL. 5000** 5001** INVARIANTS: 5002** 5003** {H13143} If D is a [database connection] that holds one or more 5004** unfinalized [prepared statements] and S is a NULL pointer, 5005** then [sqlite3_next_stmt(D, S)] routine shall return a pointer 5006** to one of the prepared statements associated with D. 5007** 5008** {H13146} If D is a [database connection] that holds no unfinalized 5009** [prepared statements] and S is a NULL pointer, then 5010** [sqlite3_next_stmt(D, S)] routine shall return a NULL pointer. 5011** 5012** {H13149} If S is a [prepared statement] in the [database connection] D 5013** and S is not the last prepared statement in D, then 5014** [sqlite3_next_stmt(D, S)] routine shall return a pointer 5015** to the next prepared statement in D after S. 5016** 5017** {H13152} If S is the last [prepared statement] in the 5018** [database connection] D then the [sqlite3_next_stmt(D, S)] 5019** routine shall return a NULL pointer. 5020** 5021** ASSUMPTIONS: 5022** 5023** {A13154} The [database connection] pointer D in a call to 5024** [sqlite3_next_stmt(D,S)] must refer to an open database 5025** connection and in particular must not be a NULL pointer. 5026*/ 5027sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt); 5028 5029/* 5030** CAPI3REF: Commit And Rollback Notification Callbacks {H12950} <S60400> 5031** 5032** The sqlite3_commit_hook() interface registers a callback 5033** function to be invoked whenever a transaction is committed. 5034** Any callback set by a previous call to sqlite3_commit_hook() 5035** for the same database connection is overridden. 5036** The sqlite3_rollback_hook() interface registers a callback 5037** function to be invoked whenever a transaction is committed. 5038** Any callback set by a previous call to sqlite3_commit_hook() 5039** for the same database connection is overridden. 5040** The pArg argument is passed through to the callback. 5041** If the callback on a commit hook function returns non-zero, 5042** then the commit is converted into a rollback. 5043** 5044** If another function was previously registered, its 5045** pArg value is returned. Otherwise NULL is returned. 5046** 5047** The callback implementation must not do anything that will modify 5048** the database connection that invoked the callback. Any actions 5049** to modify the database connection must be deferred until after the 5050** completion of the [sqlite3_step()] call that triggered the commit 5051** or rollback hook in the first place. 5052** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their 5053** database connections for the meaning of "modify" in this paragraph. 5054** 5055** Registering a NULL function disables the callback. 5056** 5057** For the purposes of this API, a transaction is said to have been 5058** rolled back if an explicit "ROLLBACK" statement is executed, or 5059** an error or constraint causes an implicit rollback to occur. 5060** The rollback callback is not invoked if a transaction is 5061** automatically rolled back because the database connection is closed. 5062** The rollback callback is not invoked if a transaction is 5063** rolled back because a commit callback returned non-zero. 5064** <todo> Check on this </todo> 5065** 5066** INVARIANTS: 5067** 5068** {H12951} The [sqlite3_commit_hook(D,F,P)] interface registers the 5069** callback function F to be invoked with argument P whenever 5070** a transaction commits on the [database connection] D. 5071** 5072** {H12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P argument 5073** from the previous call with the same [database connection] D, 5074** or NULL on the first call for a particular database connection D. 5075** 5076** {H12953} Each call to [sqlite3_commit_hook()] overwrites the callback 5077** registered by prior calls. 5078** 5079** {H12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL 5080** then the commit hook callback is canceled and no callback 5081** is invoked when a transaction commits. 5082** 5083** {H12955} If the commit callback returns non-zero then the commit is 5084** converted into a rollback. 5085** 5086** {H12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the 5087** callback function F to be invoked with argument P whenever 5088** a transaction rolls back on the [database connection] D. 5089** 5090** {H12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P 5091** argument from the previous call with the same 5092** [database connection] D, or NULL on the first call 5093** for a particular database connection D. 5094** 5095** {H12963} Each call to [sqlite3_rollback_hook()] overwrites the callback 5096** registered by prior calls. 5097** 5098** {H12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL 5099** then the rollback hook callback is canceled and no callback 5100** is invoked when a transaction rolls back. 5101*/ 5102void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); 5103void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); 5104 5105/* 5106** CAPI3REF: Data Change Notification Callbacks {H12970} <S60400> 5107** 5108** The sqlite3_update_hook() interface registers a callback function 5109** with the [database connection] identified by the first argument 5110** to be invoked whenever a row is updated, inserted or deleted. 5111** Any callback set by a previous call to this function 5112** for the same database connection is overridden. 5113** 5114** The second argument is a pointer to the function to invoke when a 5115** row is updated, inserted or deleted. 5116** The first argument to the callback is a copy of the third argument 5117** to sqlite3_update_hook(). 5118** The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE], 5119** or [SQLITE_UPDATE], depending on the operation that caused the callback 5120** to be invoked. 5121** The third and fourth arguments to the callback contain pointers to the 5122** database and table name containing the affected row. 5123** The final callback parameter is the [rowid] of the row. 5124** In the case of an update, this is the [rowid] after the update takes place. 5125** 5126** The update hook is not invoked when internal system tables are 5127** modified (i.e. sqlite_master and sqlite_sequence). 5128** 5129** The update hook implementation must not do anything that will modify 5130** the database connection that invoked the update hook. Any actions 5131** to modify the database connection must be deferred until after the 5132** completion of the [sqlite3_step()] call that triggered the update hook. 5133** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their 5134** database connections for the meaning of "modify" in this paragraph. 5135** 5136** If another function was previously registered, its pArg value 5137** is returned. Otherwise NULL is returned. 5138** 5139** INVARIANTS: 5140** 5141** {H12971} The [sqlite3_update_hook(D,F,P)] interface causes the callback 5142** function F to be invoked with first parameter P whenever 5143** a table row is modified, inserted, or deleted on 5144** the [database connection] D. 5145** 5146** {H12973} The [sqlite3_update_hook(D,F,P)] interface returns the value 5147** of P for the previous call on the same [database connection] D, 5148** or NULL for the first call. 5149** 5150** {H12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)] 5151** is NULL then the no update callbacks are made. 5152** 5153** {H12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls 5154** to the same interface on the same [database connection] D. 5155** 5156** {H12979} The update hook callback is not invoked when internal system 5157** tables such as sqlite_master and sqlite_sequence are modified. 5158** 5159** {H12981} The second parameter to the update callback 5160** is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], 5161** depending on the operation that caused the callback to be invoked. 5162** 5163** {H12983} The third and fourth arguments to the callback contain pointers 5164** to zero-terminated UTF-8 strings which are the names of the 5165** database and table that is being updated. 5166 5167** {H12985} The final callback parameter is the [rowid] of the row after 5168** the change occurs. 5169*/ 5170void *sqlite3_update_hook( 5171 sqlite3*, 5172 void(*)(void *,int ,char const *,char const *,sqlite3_int64), 5173 void* 5174); 5175 5176/* 5177** CAPI3REF: Enable Or Disable Shared Pager Cache {H10330} <S30900> 5178** KEYWORDS: {shared cache} {shared cache mode} 5179** 5180** This routine enables or disables the sharing of the database cache 5181** and schema data structures between [database connection | connections] 5182** to the same database. Sharing is enabled if the argument is true 5183** and disabled if the argument is false. 5184** 5185** Cache sharing is enabled and disabled for an entire process. {END} 5186** This is a change as of SQLite version 3.5.0. In prior versions of SQLite, 5187** sharing was enabled or disabled for each thread separately. 5188** 5189** The cache sharing mode set by this interface effects all subsequent 5190** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. 5191** Existing database connections continue use the sharing mode 5192** that was in effect at the time they were opened. 5193** 5194** Virtual tables cannot be used with a shared cache. When shared 5195** cache is enabled, the [sqlite3_create_module()] API used to register 5196** virtual tables will always return an error. 5197** 5198** This routine returns [SQLITE_OK] if shared cache was enabled or disabled 5199** successfully. An [error code] is returned otherwise. 5200** 5201** Shared cache is disabled by default. But this might change in 5202** future releases of SQLite. Applications that care about shared 5203** cache setting should set it explicitly. 5204** 5205** INVARIANTS: 5206** 5207** {H10331} A successful invocation of [sqlite3_enable_shared_cache(B)] 5208** will enable or disable shared cache mode for any subsequently 5209** created [database connection] in the same process. 5210** 5211** {H10336} When shared cache is enabled, the [sqlite3_create_module()] 5212** interface will always return an error. 5213** 5214** {H10337} The [sqlite3_enable_shared_cache(B)] interface returns 5215** [SQLITE_OK] if shared cache was enabled or disabled successfully. 5216** 5217** {H10339} Shared cache is disabled by default. 5218*/ 5219int sqlite3_enable_shared_cache(int); 5220 5221/* 5222** CAPI3REF: Attempt To Free Heap Memory {H17340} <S30220> 5223** 5224** The sqlite3_release_memory() interface attempts to free N bytes 5225** of heap memory by deallocating non-essential memory allocations 5226** held by the database library. {END} Memory used to cache database 5227** pages to improve performance is an example of non-essential memory. 5228** sqlite3_release_memory() returns the number of bytes actually freed, 5229** which might be more or less than the amount requested. 5230** 5231** INVARIANTS: 5232** 5233** {H17341} The [sqlite3_release_memory(N)] interface attempts to 5234** free N bytes of heap memory by deallocating non-essential 5235** memory allocations held by the database library. 5236** 5237** {H16342} The [sqlite3_release_memory(N)] returns the number 5238** of bytes actually freed, which might be more or less 5239** than the amount requested. 5240*/ 5241int sqlite3_release_memory(int); 5242 5243/* 5244** CAPI3REF: Impose A Limit On Heap Size {H17350} <S30220> 5245** 5246** The sqlite3_soft_heap_limit() interface places a "soft" limit 5247** on the amount of heap memory that may be allocated by SQLite. 5248** If an internal allocation is requested that would exceed the 5249** soft heap limit, [sqlite3_release_memory()] is invoked one or 5250** more times to free up some space before the allocation is performed. 5251** 5252** The limit is called "soft", because if [sqlite3_release_memory()] 5253** cannot free sufficient memory to prevent the limit from being exceeded, 5254** the memory is allocated anyway and the current operation proceeds. 5255** 5256** A negative or zero value for N means that there is no soft heap limit and 5257** [sqlite3_release_memory()] will only be called when memory is exhausted. 5258** The default value for the soft heap limit is zero. 5259** 5260** SQLite makes a best effort to honor the soft heap limit. 5261** But if the soft heap limit cannot be honored, execution will 5262** continue without error or notification. This is why the limit is 5263** called a "soft" limit. It is advisory only. 5264** 5265** Prior to SQLite version 3.5.0, this routine only constrained the memory 5266** allocated by a single thread - the same thread in which this routine 5267** runs. Beginning with SQLite version 3.5.0, the soft heap limit is 5268** applied to all threads. The value specified for the soft heap limit 5269** is an upper bound on the total memory allocation for all threads. In 5270** version 3.5.0 there is no mechanism for limiting the heap usage for 5271** individual threads. 5272** 5273** INVARIANTS: 5274** 5275** {H16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit 5276** of N bytes on the amount of heap memory that may be allocated 5277** using [sqlite3_malloc()] or [sqlite3_realloc()] at any point 5278** in time. 5279** 5280** {H16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would 5281** cause the total amount of allocated memory to exceed the 5282** soft heap limit, then [sqlite3_release_memory()] is invoked 5283** in an attempt to reduce the memory usage prior to proceeding 5284** with the memory allocation attempt. 5285** 5286** {H16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger 5287** attempts to reduce memory usage through the soft heap limit 5288** mechanism continue even if the attempt to reduce memory 5289** usage is unsuccessful. 5290** 5291** {H16354} A negative or zero value for N in a call to 5292** [sqlite3_soft_heap_limit(N)] means that there is no soft 5293** heap limit and [sqlite3_release_memory()] will only be 5294** called when memory is completely exhausted. 5295** 5296** {H16355} The default value for the soft heap limit is zero. 5297** 5298** {H16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the 5299** values set by all prior calls. 5300*/ 5301void sqlite3_soft_heap_limit(int); 5302 5303/* 5304** CAPI3REF: Extract Metadata About A Column Of A Table {H12850} <S60300> 5305** 5306** This routine returns metadata about a specific column of a specific 5307** database table accessible using the [database connection] handle 5308** passed as the first function argument. 5309** 5310** The column is identified by the second, third and fourth parameters to 5311** this function. The second parameter is either the name of the database 5312** (i.e. "main", "temp" or an attached database) containing the specified 5313** table or NULL. If it is NULL, then all attached databases are searched 5314** for the table using the same algorithm used by the database engine to 5315** resolve unqualified table references. 5316** 5317** The third and fourth parameters to this function are the table and column 5318** name of the desired column, respectively. Neither of these parameters 5319** may be NULL. 5320** 5321** Metadata is returned by writing to the memory locations passed as the 5th 5322** and subsequent parameters to this function. Any of these arguments may be 5323** NULL, in which case the corresponding element of metadata is omitted. 5324** 5325** <blockquote> 5326** <table border="1"> 5327** <tr><th> Parameter <th> Output<br>Type <th> Description 5328** 5329** <tr><td> 5th <td> const char* <td> Data type 5330** <tr><td> 6th <td> const char* <td> Name of default collation sequence 5331** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint 5332** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY 5333** <tr><td> 9th <td> int <td> True if column is [AUTOINCREMENT] 5334** </table> 5335** </blockquote> 5336** 5337** The memory pointed to by the character pointers returned for the 5338** declaration type and collation sequence is valid only until the next 5339** call to any SQLite API function. 5340** 5341** If the specified table is actually a view, an [error code] is returned. 5342** 5343** If the specified column is "rowid", "oid" or "_rowid_" and an 5344** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output 5345** parameters are set for the explicitly declared column. If there is no 5346** explicitly declared [INTEGER PRIMARY KEY] column, then the output 5347** parameters are set as follows: 5348** 5349** <pre> 5350** data type: "INTEGER" 5351** collation sequence: "BINARY" 5352** not null: 0 5353** primary key: 1 5354** auto increment: 0 5355** </pre> 5356** 5357** This function may load one or more schemas from database files. If an 5358** error occurs during this process, or if the requested table or column 5359** cannot be found, an [error code] is returned and an error message left 5360** in the [database connection] (to be retrieved using sqlite3_errmsg()). 5361** 5362** This API is only available if the library was compiled with the 5363** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined. 5364*/ 5365int sqlite3_table_column_metadata( 5366 sqlite3 *db, /* Connection handle */ 5367 const char *zDbName, /* Database name or NULL */ 5368 const char *zTableName, /* Table name */ 5369 const char *zColumnName, /* Column name */ 5370 char const **pzDataType, /* OUTPUT: Declared data type */ 5371 char const **pzCollSeq, /* OUTPUT: Collation sequence name */ 5372 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ 5373 int *pPrimaryKey, /* OUTPUT: True if column part of PK */ 5374 int *pAutoinc /* OUTPUT: True if column is auto-increment */ 5375); 5376 5377/* 5378** CAPI3REF: Load An Extension {H12600} <S20500> 5379** 5380** This interface loads an SQLite extension library from the named file. 5381** 5382** {H12601} The sqlite3_load_extension() interface attempts to load an 5383** SQLite extension library contained in the file zFile. 5384** 5385** {H12602} The entry point is zProc. 5386** 5387** {H12603} zProc may be 0, in which case the name of the entry point 5388** defaults to "sqlite3_extension_init". 5389** 5390** {H12604} The sqlite3_load_extension() interface shall return 5391** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. 5392** 5393** {H12605} If an error occurs and pzErrMsg is not 0, then the 5394** [sqlite3_load_extension()] interface shall attempt to 5395** fill *pzErrMsg with error message text stored in memory 5396** obtained from [sqlite3_malloc()]. {END} The calling function 5397** should free this memory by calling [sqlite3_free()]. 5398** 5399** {H12606} Extension loading must be enabled using 5400** [sqlite3_enable_load_extension()] prior to calling this API, 5401** otherwise an error will be returned. 5402*/ 5403int sqlite3_load_extension( 5404 sqlite3 *db, /* Load the extension into this database connection */ 5405 const char *zFile, /* Name of the shared library containing extension */ 5406 const char *zProc, /* Entry point. Derived from zFile if 0 */ 5407 char **pzErrMsg /* Put error message here if not 0 */ 5408); 5409 5410/* 5411** CAPI3REF: Enable Or Disable Extension Loading {H12620} <S20500> 5412** 5413** So as not to open security holes in older applications that are 5414** unprepared to deal with extension loading, and as a means of disabling 5415** extension loading while evaluating user-entered SQL, the following API 5416** is provided to turn the [sqlite3_load_extension()] mechanism on and off. 5417** 5418** Extension loading is off by default. See ticket #1863. 5419** 5420** {H12621} Call the sqlite3_enable_load_extension() routine with onoff==1 5421** to turn extension loading on and call it with onoff==0 to turn 5422** it back off again. 5423** 5424** {H12622} Extension loading is off by default. 5425*/ 5426int sqlite3_enable_load_extension(sqlite3 *db, int onoff); 5427 5428/* 5429** CAPI3REF: Automatically Load An Extensions {H12640} <S20500> 5430** 5431** This API can be invoked at program startup in order to register 5432** one or more statically linked extensions that will be available 5433** to all new [database connections]. {END} 5434** 5435** This routine stores a pointer to the extension in an array that is 5436** obtained from [sqlite3_malloc()]. If you run a memory leak checker 5437** on your program and it reports a leak because of this array, invoke 5438** [sqlite3_reset_auto_extension()] prior to shutdown to free the memory. 5439** 5440** {H12641} This function registers an extension entry point that is 5441** automatically invoked whenever a new [database connection] 5442** is opened using [sqlite3_open()], [sqlite3_open16()], 5443** or [sqlite3_open_v2()]. 5444** 5445** {H12642} Duplicate extensions are detected so calling this routine 5446** multiple times with the same extension is harmless. 5447** 5448** {H12643} This routine stores a pointer to the extension in an array 5449** that is obtained from [sqlite3_malloc()]. 5450** 5451** {H12644} Automatic extensions apply across all threads. 5452*/ 5453int sqlite3_auto_extension(void (*xEntryPoint)(void)); 5454 5455/* 5456** CAPI3REF: Reset Automatic Extension Loading {H12660} <S20500> 5457** 5458** This function disables all previously registered automatic 5459** extensions. {END} It undoes the effect of all prior 5460** [sqlite3_auto_extension()] calls. 5461** 5462** {H12661} This function disables all previously registered 5463** automatic extensions. 5464** 5465** {H12662} This function disables automatic extensions in all threads. 5466*/ 5467void sqlite3_reset_auto_extension(void); 5468 5469/* 5470****** EXPERIMENTAL - subject to change without notice ************** 5471** 5472** The interface to the virtual-table mechanism is currently considered 5473** to be experimental. The interface might change in incompatible ways. 5474** If this is a problem for you, do not use the interface at this time. 5475** 5476** When the virtual-table mechanism stabilizes, we will declare the 5477** interface fixed, support it indefinitely, and remove this comment. 5478*/ 5479 5480/* 5481** Structures used by the virtual table interface 5482*/ 5483typedef struct sqlite3_vtab sqlite3_vtab; 5484typedef struct sqlite3_index_info sqlite3_index_info; 5485typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; 5486typedef struct sqlite3_module sqlite3_module; 5487 5488/* 5489** CAPI3REF: Virtual Table Object {H18000} <S20400> 5490** KEYWORDS: sqlite3_module 5491** EXPERIMENTAL 5492** 5493** A module is a class of virtual tables. Each module is defined 5494** by an instance of the following structure. This structure consists 5495** mostly of methods for the module. 5496** 5497** This interface is experimental and is subject to change or 5498** removal in future releases of SQLite. 5499*/ 5500struct sqlite3_module { 5501 int iVersion; 5502 int (*xCreate)(sqlite3*, void *pAux, 5503 int argc, const char *const*argv, 5504 sqlite3_vtab **ppVTab, char**); 5505 int (*xConnect)(sqlite3*, void *pAux, 5506 int argc, const char *const*argv, 5507 sqlite3_vtab **ppVTab, char**); 5508 int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); 5509 int (*xDisconnect)(sqlite3_vtab *pVTab); 5510 int (*xDestroy)(sqlite3_vtab *pVTab); 5511 int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor); 5512 int (*xClose)(sqlite3_vtab_cursor*); 5513 int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr, 5514 int argc, sqlite3_value **argv); 5515 int (*xNext)(sqlite3_vtab_cursor*); 5516 int (*xEof)(sqlite3_vtab_cursor*); 5517 int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int); 5518 int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid); 5519 int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *); 5520 int (*xBegin)(sqlite3_vtab *pVTab); 5521 int (*xSync)(sqlite3_vtab *pVTab); 5522 int (*xCommit)(sqlite3_vtab *pVTab); 5523 int (*xRollback)(sqlite3_vtab *pVTab); 5524 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, 5525 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), 5526 void **ppArg); 5527 int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); 5528}; 5529 5530/* 5531** CAPI3REF: Virtual Table Indexing Information {H18100} <S20400> 5532** KEYWORDS: sqlite3_index_info 5533** EXPERIMENTAL 5534** 5535** The sqlite3_index_info structure and its substructures is used to 5536** pass information into and receive the reply from the xBestIndex 5537** method of an sqlite3_module. The fields under **Inputs** are the 5538** inputs to xBestIndex and are read-only. xBestIndex inserts its 5539** results into the **Outputs** fields. 5540** 5541** The aConstraint[] array records WHERE clause constraints of the form: 5542** 5543** <pre>column OP expr</pre> 5544** 5545** where OP is =, <, <=, >, or >=. The particular operator is 5546** stored in aConstraint[].op. The index of the column is stored in 5547** aConstraint[].iColumn. aConstraint[].usable is TRUE if the 5548** expr on the right-hand side can be evaluated (and thus the constraint 5549** is usable) and false if it cannot. 5550** 5551** The optimizer automatically inverts terms of the form "expr OP column" 5552** and makes other simplifications to the WHERE clause in an attempt to 5553** get as many WHERE clause terms into the form shown above as possible. 5554** The aConstraint[] array only reports WHERE clause terms in the correct 5555** form that refer to the particular virtual table being queried. 5556** 5557** Information about the ORDER BY clause is stored in aOrderBy[]. 5558** Each term of aOrderBy records a column of the ORDER BY clause. 5559** 5560** The xBestIndex method must fill aConstraintUsage[] with information 5561** about what parameters to pass to xFilter. If argvIndex>0 then 5562** the right-hand side of the corresponding aConstraint[] is evaluated 5563** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit 5564** is true, then the constraint is assumed to be fully handled by the 5565** virtual table and is not checked again by SQLite. 5566** 5567** The idxNum and idxPtr values are recorded and passed into xFilter. 5568** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true. 5569** 5570** The orderByConsumed means that output from xFilter will occur in 5571** the correct order to satisfy the ORDER BY clause so that no separate 5572** sorting step is required. 5573** 5574** The estimatedCost value is an estimate of the cost of doing the 5575** particular lookup. A full scan of a table with N entries should have 5576** a cost of N. A binary search of a table of N entries should have a 5577** cost of approximately log(N). 5578** 5579** This interface is experimental and is subject to change or 5580** removal in future releases of SQLite. 5581*/ 5582struct sqlite3_index_info { 5583 /* Inputs */ 5584 int nConstraint; /* Number of entries in aConstraint */ 5585 struct sqlite3_index_constraint { 5586 int iColumn; /* Column on left-hand side of constraint */ 5587 unsigned char op; /* Constraint operator */ 5588 unsigned char usable; /* True if this constraint is usable */ 5589 int iTermOffset; /* Used internally - xBestIndex should ignore */ 5590 } *aConstraint; /* Table of WHERE clause constraints */ 5591 int nOrderBy; /* Number of terms in the ORDER BY clause */ 5592 struct sqlite3_index_orderby { 5593 int iColumn; /* Column number */ 5594 unsigned char desc; /* True for DESC. False for ASC. */ 5595 } *aOrderBy; /* The ORDER BY clause */ 5596 /* Outputs */ 5597 struct sqlite3_index_constraint_usage { 5598 int argvIndex; /* if >0, constraint is part of argv to xFilter */ 5599 unsigned char omit; /* Do not code a test for this constraint */ 5600 } *aConstraintUsage; 5601 int idxNum; /* Number used to identify the index */ 5602 char *idxStr; /* String, possibly obtained from sqlite3_malloc */ 5603 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ 5604 int orderByConsumed; /* True if output is already ordered */ 5605 double estimatedCost; /* Estimated cost of using this index */ 5606}; 5607#define SQLITE_INDEX_CONSTRAINT_EQ 2 5608#define SQLITE_INDEX_CONSTRAINT_GT 4 5609#define SQLITE_INDEX_CONSTRAINT_LE 8 5610#define SQLITE_INDEX_CONSTRAINT_LT 16 5611#define SQLITE_INDEX_CONSTRAINT_GE 32 5612#define SQLITE_INDEX_CONSTRAINT_MATCH 64 5613 5614/* 5615** CAPI3REF: Register A Virtual Table Implementation {H18200} <S20400> 5616** EXPERIMENTAL 5617** 5618** This routine is used to register a new module name with a 5619** [database connection]. Module names must be registered before 5620** creating new virtual tables on the module, or before using 5621** preexisting virtual tables of the module. 5622** 5623** This interface is experimental and is subject to change or 5624** removal in future releases of SQLite. 5625*/ 5626SQLITE_EXPERIMENTAL int sqlite3_create_module( 5627 sqlite3 *db, /* SQLite connection to register module with */ 5628 const char *zName, /* Name of the module */ 5629 const sqlite3_module *, /* Methods for the module */ 5630 void * /* Client data for xCreate/xConnect */ 5631); 5632 5633/* 5634** CAPI3REF: Register A Virtual Table Implementation {H18210} <S20400> 5635** EXPERIMENTAL 5636** 5637** This routine is identical to the [sqlite3_create_module()] method above, 5638** except that it allows a destructor function to be specified. It is 5639** even more experimental than the rest of the virtual tables API. 5640*/ 5641SQLITE_EXPERIMENTAL int sqlite3_create_module_v2( 5642 sqlite3 *db, /* SQLite connection to register module with */ 5643 const char *zName, /* Name of the module */ 5644 const sqlite3_module *, /* Methods for the module */ 5645 void *, /* Client data for xCreate/xConnect */ 5646 void(*xDestroy)(void*) /* Module destructor function */ 5647); 5648 5649/* 5650** CAPI3REF: Virtual Table Instance Object {H18010} <S20400> 5651** KEYWORDS: sqlite3_vtab 5652** EXPERIMENTAL 5653** 5654** Every module implementation uses a subclass of the following structure 5655** to describe a particular instance of the module. Each subclass will 5656** be tailored to the specific needs of the module implementation. 5657** The purpose of this superclass is to define certain fields that are 5658** common to all module implementations. 5659** 5660** Virtual tables methods can set an error message by assigning a 5661** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should 5662** take care that any prior string is freed by a call to [sqlite3_free()] 5663** prior to assigning a new string to zErrMsg. After the error message 5664** is delivered up to the client application, the string will be automatically 5665** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note 5666** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field 5667** since virtual tables are commonly implemented in loadable extensions which 5668** do not have access to sqlite3MPrintf() or sqlite3Free(). 5669** 5670** This interface is experimental and is subject to change or 5671** removal in future releases of SQLite. 5672*/ 5673struct sqlite3_vtab { 5674 const sqlite3_module *pModule; /* The module for this virtual table */ 5675 int nRef; /* Used internally */ 5676 char *zErrMsg; /* Error message from sqlite3_mprintf() */ 5677 /* Virtual table implementations will typically add additional fields */ 5678}; 5679 5680/* 5681** CAPI3REF: Virtual Table Cursor Object {H18020} <S20400> 5682** KEYWORDS: sqlite3_vtab_cursor 5683** EXPERIMENTAL 5684** 5685** Every module implementation uses a subclass of the following structure 5686** to describe cursors that point into the virtual table and are used 5687** to loop through the virtual table. Cursors are created using the 5688** xOpen method of the module. Each module implementation will define 5689** the content of a cursor structure to suit its own needs. 5690** 5691** This superclass exists in order to define fields of the cursor that 5692** are common to all implementations. 5693** 5694** This interface is experimental and is subject to change or 5695** removal in future releases of SQLite. 5696*/ 5697struct sqlite3_vtab_cursor { 5698 sqlite3_vtab *pVtab; /* Virtual table of this cursor */ 5699 /* Virtual table implementations will typically add additional fields */ 5700}; 5701 5702/* 5703** CAPI3REF: Declare The Schema Of A Virtual Table {H18280} <S20400> 5704** EXPERIMENTAL 5705** 5706** The xCreate and xConnect methods of a module use the following API 5707** to declare the format (the names and datatypes of the columns) of 5708** the virtual tables they implement. 5709** 5710** This interface is experimental and is subject to change or 5711** removal in future releases of SQLite. 5712*/ 5713SQLITE_EXPERIMENTAL int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); 5714 5715/* 5716** CAPI3REF: Overload A Function For A Virtual Table {H18300} <S20400> 5717** EXPERIMENTAL 5718** 5719** Virtual tables can provide alternative implementations of functions 5720** using the xFindFunction method. But global versions of those functions 5721** must exist in order to be overloaded. 5722** 5723** This API makes sure a global version of a function with a particular 5724** name and number of parameters exists. If no such function exists 5725** before this API is called, a new function is created. The implementation 5726** of the new function always causes an exception to be thrown. So 5727** the new function is not good for anything by itself. Its only 5728** purpose is to be a placeholder function that can be overloaded 5729** by virtual tables. 5730** 5731** This API should be considered part of the virtual table interface, 5732** which is experimental and subject to change. 5733*/ 5734SQLITE_EXPERIMENTAL int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); 5735 5736/* 5737** The interface to the virtual-table mechanism defined above (back up 5738** to a comment remarkably similar to this one) is currently considered 5739** to be experimental. The interface might change in incompatible ways. 5740** If this is a problem for you, do not use the interface at this time. 5741** 5742** When the virtual-table mechanism stabilizes, we will declare the 5743** interface fixed, support it indefinitely, and remove this comment. 5744** 5745****** EXPERIMENTAL - subject to change without notice ************** 5746*/ 5747 5748/* 5749** CAPI3REF: A Handle To An Open BLOB {H17800} <S30230> 5750** KEYWORDS: {BLOB handle} {BLOB handles} 5751** 5752** An instance of this object represents an open BLOB on which 5753** [sqlite3_blob_open | incremental BLOB I/O] can be performed. 5754** Objects of this type are created by [sqlite3_blob_open()] 5755** and destroyed by [sqlite3_blob_close()]. 5756** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces 5757** can be used to read or write small subsections of the BLOB. 5758** The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes. 5759*/ 5760typedef struct sqlite3_blob sqlite3_blob; 5761 5762/* 5763** CAPI3REF: Open A BLOB For Incremental I/O {H17810} <S30230> 5764** 5765** This interfaces opens a [BLOB handle | handle] to the BLOB located 5766** in row iRow, column zColumn, table zTable in database zDb; 5767** in other words, the same BLOB that would be selected by: 5768** 5769** <pre> 5770** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow; 5771** </pre> {END} 5772** 5773** If the flags parameter is non-zero, the the BLOB is opened for read 5774** and write access. If it is zero, the BLOB is opened for read access. 5775** 5776** Note that the database name is not the filename that contains 5777** the database but rather the symbolic name of the database that 5778** is assigned when the database is connected using [ATTACH]. 5779** For the main database file, the database name is "main". 5780** For TEMP tables, the database name is "temp". 5781** 5782** On success, [SQLITE_OK] is returned and the new [BLOB handle] is written 5783** to *ppBlob. Otherwise an [error code] is returned and any value written 5784** to *ppBlob should not be used by the caller. 5785** This function sets the [database connection] error code and message 5786** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. 5787** 5788** If the row that a BLOB handle points to is modified by an 5789** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects 5790** then the BLOB handle is marked as "expired". 5791** This is true if any column of the row is changed, even a column 5792** other than the one the BLOB handle is open on. 5793** Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for 5794** a expired BLOB handle fail with an return code of [SQLITE_ABORT]. 5795** Changes written into a BLOB prior to the BLOB expiring are not 5796** rollback by the expiration of the BLOB. Such changes will eventually 5797** commit if the transaction continues to completion. 5798** 5799** INVARIANTS: 5800** 5801** {H17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)] 5802** interface shall open an [sqlite3_blob] object P on the BLOB 5803** in column C of the table T in the database B on 5804** the [database connection] D. 5805** 5806** {H17814} A successful invocation of [sqlite3_blob_open(D,...)] shall start 5807** a new transaction on the [database connection] D if that 5808** connection is not already in a transaction. 5809** 5810** {H17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface shall open 5811** the BLOB for read and write access if and only if the F 5812** parameter is non-zero. 5813** 5814** {H17819} The [sqlite3_blob_open()] interface shall return [SQLITE_OK] on 5815** success and an appropriate [error code] on failure. 5816** 5817** {H17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)] 5818** then subsequent calls to [sqlite3_errcode(D)], 5819** [sqlite3_extended_errcode()], 5820** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return 5821** information appropriate for that error. 5822** 5823** {H17824} If any column in the row that a [sqlite3_blob] has open is 5824** changed by a separate [UPDATE] or [DELETE] statement or by 5825** an [ON CONFLICT] side effect, then the [sqlite3_blob] shall 5826** be marked as invalid. 5827*/ 5828int sqlite3_blob_open( 5829 sqlite3*, 5830 const char *zDb, 5831 const char *zTable, 5832 const char *zColumn, 5833 sqlite3_int64 iRow, 5834 int flags, 5835 sqlite3_blob **ppBlob 5836); 5837 5838/* 5839** CAPI3REF: Close A BLOB Handle {H17830} <S30230> 5840** 5841** Closes an open [BLOB handle]. 5842** 5843** Closing a BLOB shall cause the current transaction to commit 5844** if there are no other BLOBs, no pending prepared statements, and the 5845** database connection is in [autocommit mode]. 5846** If any writes were made to the BLOB, they might be held in cache 5847** until the close operation if they will fit. {END} 5848** 5849** Closing the BLOB often forces the changes 5850** out to disk and so if any I/O errors occur, they will likely occur 5851** at the time when the BLOB is closed. {H17833} Any errors that occur during 5852** closing are reported as a non-zero return value. 5853** 5854** The BLOB is closed unconditionally. Even if this routine returns 5855** an error code, the BLOB is still closed. 5856** 5857** INVARIANTS: 5858** 5859** {H17833} The [sqlite3_blob_close(P)] interface closes an [sqlite3_blob] 5860** object P previously opened using [sqlite3_blob_open()]. 5861** 5862** {H17836} Closing an [sqlite3_blob] object using 5863** [sqlite3_blob_close()] shall cause the current transaction to 5864** commit if there are no other open [sqlite3_blob] objects 5865** or [prepared statements] on the same [database connection] and 5866** the database connection is in [autocommit mode]. 5867** 5868** {H17839} The [sqlite3_blob_close(P)] interfaces shall close the 5869** [sqlite3_blob] object P unconditionally, even if 5870** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK]. 5871*/ 5872int sqlite3_blob_close(sqlite3_blob *); 5873 5874/* 5875** CAPI3REF: Return The Size Of An Open BLOB {H17840} <S30230> 5876** 5877** Returns the size in bytes of the BLOB accessible via the open 5878** []BLOB handle] in its only argument. 5879** 5880** INVARIANTS: 5881** 5882** {H17843} The [sqlite3_blob_bytes(P)] interface returns the size 5883** in bytes of the BLOB that the [sqlite3_blob] object P 5884** refers to. 5885*/ 5886int sqlite3_blob_bytes(sqlite3_blob *); 5887 5888/* 5889** CAPI3REF: Read Data From A BLOB Incrementally {H17850} <S30230> 5890** 5891** This function is used to read data from an open [BLOB handle] into a 5892** caller-supplied buffer. N bytes of data are copied into buffer Z 5893** from the open BLOB, starting at offset iOffset. 5894** 5895** If offset iOffset is less than N bytes from the end of the BLOB, 5896** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is 5897** less than zero, [SQLITE_ERROR] is returned and no data is read. 5898** 5899** An attempt to read from an expired [BLOB handle] fails with an 5900** error code of [SQLITE_ABORT]. 5901** 5902** On success, SQLITE_OK is returned. 5903** Otherwise, an [error code] or an [extended error code] is returned. 5904** 5905** INVARIANTS: 5906** 5907** {H17853} A successful invocation of [sqlite3_blob_read(P,Z,N,X)] 5908** shall reads N bytes of data out of the BLOB referenced by 5909** [BLOB handle] P beginning at offset X and store those bytes 5910** into buffer Z. 5911** 5912** {H17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the BLOB 5913** is less than N+X bytes, then the function shall leave the 5914** Z buffer unchanged and return [SQLITE_ERROR]. 5915** 5916** {H17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero 5917** then the function shall leave the Z buffer unchanged 5918** and return [SQLITE_ERROR]. 5919** 5920** {H17862} The [sqlite3_blob_read(P,Z,N,X)] interface shall return [SQLITE_OK] 5921** if N bytes are successfully read into buffer Z. 5922** 5923** {H17863} If the [BLOB handle] P is expired and X and N are within bounds 5924** then [sqlite3_blob_read(P,Z,N,X)] shall leave the Z buffer 5925** unchanged and return [SQLITE_ABORT]. 5926** 5927** {H17865} If the requested read could not be completed, 5928** the [sqlite3_blob_read(P,Z,N,X)] interface shall return an 5929** appropriate [error code] or [extended error code]. 5930** 5931** {H17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)] 5932** then subsequent calls to [sqlite3_errcode(D)], 5933** [sqlite3_extended_errcode()], 5934** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return 5935** information appropriate for that error, where D is the 5936** [database connection] that was used to open the [BLOB handle] P. 5937*/ 5938int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); 5939 5940/* 5941** CAPI3REF: Write Data Into A BLOB Incrementally {H17870} <S30230> 5942** 5943** This function is used to write data into an open [BLOB handle] from a 5944** caller-supplied buffer. N bytes of data are copied from the buffer Z 5945** into the open BLOB, starting at offset iOffset. 5946** 5947** If the [BLOB handle] passed as the first argument was not opened for 5948** writing (the flags parameter to [sqlite3_blob_open()] was zero), 5949** this function returns [SQLITE_READONLY]. 5950** 5951** This function may only modify the contents of the BLOB; it is 5952** not possible to increase the size of a BLOB using this API. 5953** If offset iOffset is less than N bytes from the end of the BLOB, 5954** [SQLITE_ERROR] is returned and no data is written. If N is 5955** less than zero [SQLITE_ERROR] is returned and no data is written. 5956** 5957** An attempt to write to an expired [BLOB handle] fails with an 5958** error code of [SQLITE_ABORT]. Writes to the BLOB that occurred 5959** before the [BLOB handle] expired are not rolled back by the 5960** expiration of the handle, though of course those changes might 5961** have been overwritten by the statement that expired the BLOB handle 5962** or by other independent statements. 5963** 5964** On success, SQLITE_OK is returned. 5965** Otherwise, an [error code] or an [extended error code] is returned. 5966** 5967** INVARIANTS: 5968** 5969** {H17873} A successful invocation of [sqlite3_blob_write(P,Z,N,X)] 5970** shall write N bytes of data from buffer Z into the BLOB 5971** referenced by [BLOB handle] P beginning at offset X into 5972** the BLOB. 5973** 5974** {H17874} In the absence of other overridding changes, the changes 5975** written to a BLOB by [sqlite3_blob_write()] shall 5976** remain in effect after the associated [BLOB handle] expires. 5977** 5978** {H17875} If the [BLOB handle] P was opened for reading only then 5979** an invocation of [sqlite3_blob_write(P,Z,N,X)] shall leave 5980** the referenced BLOB unchanged and return [SQLITE_READONLY]. 5981** 5982** {H17876} If the size of the BLOB referenced by [BLOB handle] P is 5983** less than N+X bytes then [sqlite3_blob_write(P,Z,N,X)] shall 5984** leave the BLOB unchanged and return [SQLITE_ERROR]. 5985** 5986** {H17877} If the [BLOB handle] P is expired and X and N are within bounds 5987** then [sqlite3_blob_read(P,Z,N,X)] shall leave the BLOB 5988** unchanged and return [SQLITE_ABORT]. 5989** 5990** {H17879} If X or N are less than zero then [sqlite3_blob_write(P,Z,N,X)] 5991** shall leave the BLOB referenced by [BLOB handle] P unchanged 5992** and return [SQLITE_ERROR]. 5993** 5994** {H17882} The [sqlite3_blob_write(P,Z,N,X)] interface shall return 5995** [SQLITE_OK] if N bytes where successfully written into the BLOB. 5996** 5997** {H17885} If the requested write could not be completed, 5998** the [sqlite3_blob_write(P,Z,N,X)] interface shall return an 5999** appropriate [error code] or [extended error code]. 6000** 6001** {H17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)] 6002** then subsequent calls to [sqlite3_errcode(D)], 6003** [sqlite3_extended_errcode()], 6004** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return 6005** information appropriate for that error. 6006*/ 6007int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); 6008 6009/* 6010** CAPI3REF: Virtual File System Objects {H11200} <S20100> 6011** 6012** A virtual filesystem (VFS) is an [sqlite3_vfs] object 6013** that SQLite uses to interact 6014** with the underlying operating system. Most SQLite builds come with a 6015** single default VFS that is appropriate for the host computer. 6016** New VFSes can be registered and existing VFSes can be unregistered. 6017** The following interfaces are provided. 6018** 6019** The sqlite3_vfs_find() interface returns a pointer to a VFS given its name. 6020** Names are case sensitive. 6021** Names are zero-terminated UTF-8 strings. 6022** If there is no match, a NULL pointer is returned. 6023** If zVfsName is NULL then the default VFS is returned. 6024** 6025** New VFSes are registered with sqlite3_vfs_register(). 6026** Each new VFS becomes the default VFS if the makeDflt flag is set. 6027** The same VFS can be registered multiple times without injury. 6028** To make an existing VFS into the default VFS, register it again 6029** with the makeDflt flag set. If two different VFSes with the 6030** same name are registered, the behavior is undefined. If a 6031** VFS is registered with a name that is NULL or an empty string, 6032** then the behavior is undefined. 6033** 6034** Unregister a VFS with the sqlite3_vfs_unregister() interface. 6035** If the default VFS is unregistered, another VFS is chosen as 6036** the default. The choice for the new VFS is arbitrary. 6037** 6038** INVARIANTS: 6039** 6040** {H11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the 6041** registered [sqlite3_vfs] object whose name exactly matches 6042** the zero-terminated UTF-8 string N, or it returns NULL if 6043** there is no match. 6044** 6045** {H11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then 6046** the function returns a pointer to the default [sqlite3_vfs] 6047** object if there is one, or NULL if there is no default 6048** [sqlite3_vfs] object. 6049** 6050** {H11209} The [sqlite3_vfs_register(P,F)] interface registers the 6051** well-formed [sqlite3_vfs] object P using the name given 6052** by the zName field of the object. 6053** 6054** {H11212} Using the [sqlite3_vfs_register(P,F)] interface to register 6055** the same [sqlite3_vfs] object multiple times is a harmless no-op. 6056** 6057** {H11215} The [sqlite3_vfs_register(P,F)] interface makes the [sqlite3_vfs] 6058** object P the default [sqlite3_vfs] object if F is non-zero. 6059** 6060** {H11218} The [sqlite3_vfs_unregister(P)] interface unregisters the 6061** [sqlite3_vfs] object P so that it is no longer returned by 6062** subsequent calls to [sqlite3_vfs_find()]. 6063*/ 6064sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); 6065int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); 6066int sqlite3_vfs_unregister(sqlite3_vfs*); 6067 6068/* 6069** CAPI3REF: Mutexes {H17000} <S20000> 6070** 6071** The SQLite core uses these routines for thread 6072** synchronization. Though they are intended for internal 6073** use by SQLite, code that links against SQLite is 6074** permitted to use any of these routines. 6075** 6076** The SQLite source code contains multiple implementations 6077** of these mutex routines. An appropriate implementation 6078** is selected automatically at compile-time. The following 6079** implementations are available in the SQLite core: 6080** 6081** <ul> 6082** <li> SQLITE_MUTEX_OS2 6083** <li> SQLITE_MUTEX_PTHREAD 6084** <li> SQLITE_MUTEX_W32 6085** <li> SQLITE_MUTEX_NOOP 6086** </ul> 6087** 6088** The SQLITE_MUTEX_NOOP implementation is a set of routines 6089** that does no real locking and is appropriate for use in 6090** a single-threaded application. The SQLITE_MUTEX_OS2, 6091** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations 6092** are appropriate for use on OS/2, Unix, and Windows. 6093** 6094** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor 6095** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex 6096** implementation is included with the library. In this case the 6097** application must supply a custom mutex implementation using the 6098** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function 6099** before calling sqlite3_initialize() or any other public sqlite3_ 6100** function that calls sqlite3_initialize(). 6101** 6102** {H17011} The sqlite3_mutex_alloc() routine allocates a new 6103** mutex and returns a pointer to it. {H17012} If it returns NULL 6104** that means that a mutex could not be allocated. {H17013} SQLite 6105** will unwind its stack and return an error. {H17014} The argument 6106** to sqlite3_mutex_alloc() is one of these integer constants: 6107** 6108** <ul> 6109** <li> SQLITE_MUTEX_FAST 6110** <li> SQLITE_MUTEX_RECURSIVE 6111** <li> SQLITE_MUTEX_STATIC_MASTER 6112** <li> SQLITE_MUTEX_STATIC_MEM 6113** <li> SQLITE_MUTEX_STATIC_MEM2 6114** <li> SQLITE_MUTEX_STATIC_PRNG 6115** <li> SQLITE_MUTEX_STATIC_LRU 6116** <li> SQLITE_MUTEX_STATIC_LRU2 6117** </ul> 6118** 6119** {H17015} The first two constants cause sqlite3_mutex_alloc() to create 6120** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE 6121** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END} 6122** The mutex implementation does not need to make a distinction 6123** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does 6124** not want to. {H17016} But SQLite will only request a recursive mutex in 6125** cases where it really needs one. {END} If a faster non-recursive mutex 6126** implementation is available on the host platform, the mutex subsystem 6127** might return such a mutex in response to SQLITE_MUTEX_FAST. 6128** 6129** {H17017} The other allowed parameters to sqlite3_mutex_alloc() each return 6130** a pointer to a static preexisting mutex. {END} Four static mutexes are 6131** used by the current version of SQLite. Future versions of SQLite 6132** may add additional static mutexes. Static mutexes are for internal 6133** use by SQLite only. Applications that use SQLite mutexes should 6134** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or 6135** SQLITE_MUTEX_RECURSIVE. 6136** 6137** {H17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST 6138** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() 6139** returns a different mutex on every call. {H17034} But for the static 6140** mutex types, the same mutex is returned on every call that has 6141** the same type number. 6142** 6143** {H17019} The sqlite3_mutex_free() routine deallocates a previously 6144** allocated dynamic mutex. {H17020} SQLite is careful to deallocate every 6145** dynamic mutex that it allocates. {A17021} The dynamic mutexes must not be in 6146** use when they are deallocated. {A17022} Attempting to deallocate a static 6147** mutex results in undefined behavior. {H17023} SQLite never deallocates 6148** a static mutex. {END} 6149** 6150** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt 6151** to enter a mutex. {H17024} If another thread is already within the mutex, 6152** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return 6153** SQLITE_BUSY. {H17025} The sqlite3_mutex_try() interface returns [SQLITE_OK] 6154** upon successful entry. {H17026} Mutexes created using 6155** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. 6156** {H17027} In such cases the, 6157** mutex must be exited an equal number of times before another thread 6158** can enter. {A17028} If the same thread tries to enter any other 6159** kind of mutex more than once, the behavior is undefined. 6160** {H17029} SQLite will never exhibit 6161** such behavior in its own use of mutexes. 6162** 6163** Some systems (for example, Windows 95) do not support the operation 6164** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() 6165** will always return SQLITE_BUSY. {H17030} The SQLite core only ever uses 6166** sqlite3_mutex_try() as an optimization so this is acceptable behavior. 6167** 6168** {H17031} The sqlite3_mutex_leave() routine exits a mutex that was 6169** previously entered by the same thread. {A17032} The behavior 6170** is undefined if the mutex is not currently entered by the 6171** calling thread or is not currently allocated. {H17033} SQLite will 6172** never do either. {END} 6173** 6174** If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or 6175** sqlite3_mutex_leave() is a NULL pointer, then all three routines 6176** behave as no-ops. 6177** 6178** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. 6179*/ 6180sqlite3_mutex *sqlite3_mutex_alloc(int); 6181void sqlite3_mutex_free(sqlite3_mutex*); 6182void sqlite3_mutex_enter(sqlite3_mutex*); 6183int sqlite3_mutex_try(sqlite3_mutex*); 6184void sqlite3_mutex_leave(sqlite3_mutex*); 6185 6186/* 6187** CAPI3REF: Mutex Methods Object {H17120} <S20130> 6188** EXPERIMENTAL 6189** 6190** An instance of this structure defines the low-level routines 6191** used to allocate and use mutexes. 6192** 6193** Usually, the default mutex implementations provided by SQLite are 6194** sufficient, however the user has the option of substituting a custom 6195** implementation for specialized deployments or systems for which SQLite 6196** does not provide a suitable implementation. In this case, the user 6197** creates and populates an instance of this structure to pass 6198** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option. 6199** Additionally, an instance of this structure can be used as an 6200** output variable when querying the system for the current mutex 6201** implementation, using the [SQLITE_CONFIG_GETMUTEX] option. 6202** 6203** The xMutexInit method defined by this structure is invoked as 6204** part of system initialization by the sqlite3_initialize() function. 6205** {H17001} The xMutexInit routine shall be called by SQLite once for each 6206** effective call to [sqlite3_initialize()]. 6207** 6208** The xMutexEnd method defined by this structure is invoked as 6209** part of system shutdown by the sqlite3_shutdown() function. The 6210** implementation of this method is expected to release all outstanding 6211** resources obtained by the mutex methods implementation, especially 6212** those obtained by the xMutexInit method. {H17003} The xMutexEnd() 6213** interface shall be invoked once for each call to [sqlite3_shutdown()]. 6214** 6215** The remaining seven methods defined by this structure (xMutexAlloc, 6216** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and 6217** xMutexNotheld) implement the following interfaces (respectively): 6218** 6219** <ul> 6220** <li> [sqlite3_mutex_alloc()] </li> 6221** <li> [sqlite3_mutex_free()] </li> 6222** <li> [sqlite3_mutex_enter()] </li> 6223** <li> [sqlite3_mutex_try()] </li> 6224** <li> [sqlite3_mutex_leave()] </li> 6225** <li> [sqlite3_mutex_held()] </li> 6226** <li> [sqlite3_mutex_notheld()] </li> 6227** </ul> 6228** 6229** The only difference is that the public sqlite3_XXX functions enumerated 6230** above silently ignore any invocations that pass a NULL pointer instead 6231** of a valid mutex handle. The implementations of the methods defined 6232** by this structure are not required to handle this case, the results 6233** of passing a NULL pointer instead of a valid mutex handle are undefined 6234** (i.e. it is acceptable to provide an implementation that segfaults if 6235** it is passed a NULL pointer). 6236*/ 6237typedef struct sqlite3_mutex_methods sqlite3_mutex_methods; 6238struct sqlite3_mutex_methods { 6239 int (*xMutexInit)(void); 6240 int (*xMutexEnd)(void); 6241 sqlite3_mutex *(*xMutexAlloc)(int); 6242 void (*xMutexFree)(sqlite3_mutex *); 6243 void (*xMutexEnter)(sqlite3_mutex *); 6244 int (*xMutexTry)(sqlite3_mutex *); 6245 void (*xMutexLeave)(sqlite3_mutex *); 6246 int (*xMutexHeld)(sqlite3_mutex *); 6247 int (*xMutexNotheld)(sqlite3_mutex *); 6248}; 6249 6250/* 6251** CAPI3REF: Mutex Verification Routines {H17080} <S20130> <S30800> 6252** 6253** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines 6254** are intended for use inside assert() statements. {H17081} The SQLite core 6255** never uses these routines except inside an assert() and applications 6256** are advised to follow the lead of the core. {H17082} The core only 6257** provides implementations for these routines when it is compiled 6258** with the SQLITE_DEBUG flag. {A17087} External mutex implementations 6259** are only required to provide these routines if SQLITE_DEBUG is 6260** defined and if NDEBUG is not defined. 6261** 6262** {H17083} These routines should return true if the mutex in their argument 6263** is held or not held, respectively, by the calling thread. 6264** 6265** {X17084} The implementation is not required to provided versions of these 6266** routines that actually work. If the implementation does not provide working 6267** versions of these routines, it should at least provide stubs that always 6268** return true so that one does not get spurious assertion failures. 6269** 6270** {H17085} If the argument to sqlite3_mutex_held() is a NULL pointer then 6271** the routine should return 1. {END} This seems counter-intuitive since 6272** clearly the mutex cannot be held if it does not exist. But the 6273** the reason the mutex does not exist is because the build is not 6274** using mutexes. And we do not want the assert() containing the 6275** call to sqlite3_mutex_held() to fail, so a non-zero return is 6276** the appropriate thing to do. {H17086} The sqlite3_mutex_notheld() 6277** interface should also return 1 when given a NULL pointer. 6278*/ 6279int sqlite3_mutex_held(sqlite3_mutex*); 6280int sqlite3_mutex_notheld(sqlite3_mutex*); 6281 6282/* 6283** CAPI3REF: Mutex Types {H17001} <H17000> 6284** 6285** The [sqlite3_mutex_alloc()] interface takes a single argument 6286** which is one of these integer constants. 6287** 6288** The set of static mutexes may change from one SQLite release to the 6289** next. Applications that override the built-in mutex logic must be 6290** prepared to accommodate additional static mutexes. 6291*/ 6292#define SQLITE_MUTEX_FAST 0 6293#define SQLITE_MUTEX_RECURSIVE 1 6294#define SQLITE_MUTEX_STATIC_MASTER 2 6295#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ 6296#define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */ 6297#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ 6298#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ 6299#define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */ 6300 6301/* 6302** CAPI3REF: Retrieve the mutex for a database connection {H17002} <H17000> 6303** 6304** This interface returns a pointer the [sqlite3_mutex] object that 6305** serializes access to the [database connection] given in the argument 6306** when the [threading mode] is Serialized. 6307** If the [threading mode] is Single-thread or Multi-thread then this 6308** routine returns a NULL pointer. 6309*/ 6310sqlite3_mutex *sqlite3_db_mutex(sqlite3*); 6311 6312/* 6313** CAPI3REF: Low-Level Control Of Database Files {H11300} <S30800> 6314** 6315** {H11301} The [sqlite3_file_control()] interface makes a direct call to the 6316** xFileControl method for the [sqlite3_io_methods] object associated 6317** with a particular database identified by the second argument. {H11302} The 6318** name of the database is the name assigned to the database by the 6319** <a href="lang_attach.html">ATTACH</a> SQL command that opened the 6320** database. {H11303} To control the main database file, use the name "main" 6321** or a NULL pointer. {H11304} The third and fourth parameters to this routine 6322** are passed directly through to the second and third parameters of 6323** the xFileControl method. {H11305} The return value of the xFileControl 6324** method becomes the return value of this routine. 6325** 6326** {H11306} If the second parameter (zDbName) does not match the name of any 6327** open database file, then SQLITE_ERROR is returned. {H11307} This error 6328** code is not remembered and will not be recalled by [sqlite3_errcode()] 6329** or [sqlite3_errmsg()]. {A11308} The underlying xFileControl method might 6330** also return SQLITE_ERROR. {A11309} There is no way to distinguish between 6331** an incorrect zDbName and an SQLITE_ERROR return from the underlying 6332** xFileControl method. {END} 6333** 6334** See also: [SQLITE_FCNTL_LOCKSTATE] 6335*/ 6336int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); 6337 6338/* 6339** CAPI3REF: Testing Interface {H11400} <S30800> 6340** 6341** The sqlite3_test_control() interface is used to read out internal 6342** state of SQLite and to inject faults into SQLite for testing 6343** purposes. The first parameter is an operation code that determines 6344** the number, meaning, and operation of all subsequent parameters. 6345** 6346** This interface is not for use by applications. It exists solely 6347** for verifying the correct operation of the SQLite library. Depending 6348** on how the SQLite library is compiled, this interface might not exist. 6349** 6350** The details of the operation codes, their meanings, the parameters 6351** they take, and what they do are all subject to change without notice. 6352** Unlike most of the SQLite API, this function is not guaranteed to 6353** operate consistently from one release to the next. 6354*/ 6355int sqlite3_test_control(int op, ...); 6356 6357/* 6358** CAPI3REF: Testing Interface Operation Codes {H11410} <H11400> 6359** 6360** These constants are the valid operation code parameters used 6361** as the first argument to [sqlite3_test_control()]. 6362** 6363** These parameters and their meanings are subject to change 6364** without notice. These values are for testing purposes only. 6365** Applications should not use any of these parameters or the 6366** [sqlite3_test_control()] interface. 6367*/ 6368#define SQLITE_TESTCTRL_PRNG_SAVE 5 6369#define SQLITE_TESTCTRL_PRNG_RESTORE 6 6370#define SQLITE_TESTCTRL_PRNG_RESET 7 6371#define SQLITE_TESTCTRL_BITVEC_TEST 8 6372#define SQLITE_TESTCTRL_FAULT_INSTALL 9 6373#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 6374 6375/* 6376** CAPI3REF: SQLite Runtime Status {H17200} <S60200> 6377** EXPERIMENTAL 6378** 6379** This interface is used to retrieve runtime status information 6380** about the preformance of SQLite, and optionally to reset various 6381** highwater marks. The first argument is an integer code for 6382** the specific parameter to measure. Recognized integer codes 6383** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...]. 6384** The current value of the parameter is returned into *pCurrent. 6385** The highest recorded value is returned in *pHighwater. If the 6386** resetFlag is true, then the highest record value is reset after 6387** *pHighwater is written. Some parameters do not record the highest 6388** value. For those parameters 6389** nothing is written into *pHighwater and the resetFlag is ignored. 6390** Other parameters record only the highwater mark and not the current 6391** value. For these latter parameters nothing is written into *pCurrent. 6392** 6393** This routine returns SQLITE_OK on success and a non-zero 6394** [error code] on failure. 6395** 6396** This routine is threadsafe but is not atomic. This routine can 6397** called while other threads are running the same or different SQLite 6398** interfaces. However the values returned in *pCurrent and 6399** *pHighwater reflect the status of SQLite at different points in time 6400** and it is possible that another thread might change the parameter 6401** in between the times when *pCurrent and *pHighwater are written. 6402** 6403** See also: [sqlite3_db_status()] 6404*/ 6405SQLITE_EXPERIMENTAL int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); 6406 6407 6408/* 6409** CAPI3REF: Status Parameters {H17250} <H17200> 6410** EXPERIMENTAL 6411** 6412** These integer constants designate various run-time status parameters 6413** that can be returned by [sqlite3_status()]. 6414** 6415** <dl> 6416** <dt>SQLITE_STATUS_MEMORY_USED</dt> 6417** <dd>This parameter is the current amount of memory checked out 6418** using [sqlite3_malloc()], either directly or indirectly. The 6419** figure includes calls made to [sqlite3_malloc()] by the application 6420** and internal memory usage by the SQLite library. Scratch memory 6421** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache 6422** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in 6423** this parameter. The amount returned is the sum of the allocation 6424** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd> 6425** 6426** <dt>SQLITE_STATUS_MALLOC_SIZE</dt> 6427** <dd>This parameter records the largest memory allocation request 6428** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their 6429** internal equivalents). Only the value returned in the 6430** *pHighwater parameter to [sqlite3_status()] is of interest. 6431** The value written into the *pCurrent parameter is undefined.</dd> 6432** 6433** <dt>SQLITE_STATUS_PAGECACHE_USED</dt> 6434** <dd>This parameter returns the number of pages used out of the 6435** [pagecache memory allocator] that was configured using 6436** [SQLITE_CONFIG_PAGECACHE]. The 6437** value returned is in pages, not in bytes.</dd> 6438** 6439** <dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt> 6440** <dd>This parameter returns the number of bytes of page cache 6441** allocation which could not be statisfied by the [SQLITE_CONFIG_PAGECACHE] 6442** buffer and where forced to overflow to [sqlite3_malloc()]. The 6443** returned value includes allocations that overflowed because they 6444** where too large (they were larger than the "sz" parameter to 6445** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because 6446** no space was left in the page cache.</dd> 6447** 6448** <dt>SQLITE_STATUS_PAGECACHE_SIZE</dt> 6449** <dd>This parameter records the largest memory allocation request 6450** handed to [pagecache memory allocator]. Only the value returned in the 6451** *pHighwater parameter to [sqlite3_status()] is of interest. 6452** The value written into the *pCurrent parameter is undefined.</dd> 6453** 6454** <dt>SQLITE_STATUS_SCRATCH_USED</dt> 6455** <dd>This parameter returns the number of allocations used out of the 6456** [scratch memory allocator] configured using 6457** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not 6458** in bytes. Since a single thread may only have one scratch allocation 6459** outstanding at time, this parameter also reports the number of threads 6460** using scratch memory at the same time.</dd> 6461** 6462** <dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt> 6463** <dd>This parameter returns the number of bytes of scratch memory 6464** allocation which could not be statisfied by the [SQLITE_CONFIG_SCRATCH] 6465** buffer and where forced to overflow to [sqlite3_malloc()]. The values 6466** returned include overflows because the requested allocation was too 6467** larger (that is, because the requested allocation was larger than the 6468** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer 6469** slots were available. 6470** </dd> 6471** 6472** <dt>SQLITE_STATUS_SCRATCH_SIZE</dt> 6473** <dd>This parameter records the largest memory allocation request 6474** handed to [scratch memory allocator]. Only the value returned in the 6475** *pHighwater parameter to [sqlite3_status()] is of interest. 6476** The value written into the *pCurrent parameter is undefined.</dd> 6477** 6478** <dt>SQLITE_STATUS_PARSER_STACK</dt> 6479** <dd>This parameter records the deepest parser stack. It is only 6480** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd> 6481** </dl> 6482** 6483** New status parameters may be added from time to time. 6484*/ 6485#define SQLITE_STATUS_MEMORY_USED 0 6486#define SQLITE_STATUS_PAGECACHE_USED 1 6487#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2 6488#define SQLITE_STATUS_SCRATCH_USED 3 6489#define SQLITE_STATUS_SCRATCH_OVERFLOW 4 6490#define SQLITE_STATUS_MALLOC_SIZE 5 6491#define SQLITE_STATUS_PARSER_STACK 6 6492#define SQLITE_STATUS_PAGECACHE_SIZE 7 6493#define SQLITE_STATUS_SCRATCH_SIZE 8 6494 6495/* 6496** CAPI3REF: Database Connection Status {H17500} <S60200> 6497** EXPERIMENTAL 6498** 6499** This interface is used to retrieve runtime status information 6500** about a single [database connection]. The first argument is the 6501** database connection object to be interrogated. The second argument 6502** is the parameter to interrogate. Currently, the only allowed value 6503** for the second parameter is [SQLITE_DBSTATUS_LOOKASIDE_USED]. 6504** Additional options will likely appear in future releases of SQLite. 6505** 6506** The current value of the requested parameter is written into *pCur 6507** and the highest instantaneous value is written into *pHiwtr. If 6508** the resetFlg is true, then the highest instantaneous value is 6509** reset back down to the current value. 6510** 6511** See also: [sqlite3_status()] and [sqlite3_stmt_status()]. 6512*/ 6513SQLITE_EXPERIMENTAL int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg); 6514 6515/* 6516** CAPI3REF: Status Parameters for database connections {H17520} <H17500> 6517** EXPERIMENTAL 6518** 6519** Status verbs for [sqlite3_db_status()]. 6520** 6521** <dl> 6522** <dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt> 6523** <dd>This parameter returns the number of lookaside memory slots currently 6524** checked out.</dd> 6525** </dl> 6526*/ 6527#define SQLITE_DBSTATUS_LOOKASIDE_USED 0 6528 6529 6530/* 6531** CAPI3REF: Prepared Statement Status {H17550} <S60200> 6532** EXPERIMENTAL 6533** 6534** Each prepared statement maintains various 6535** [SQLITE_STMTSTATUS_SORT | counters] that measure the number 6536** of times it has performed specific operations. These counters can 6537** be used to monitor the performance characteristics of the prepared 6538** statements. For example, if the number of table steps greatly exceeds 6539** the number of table searches or result rows, that would tend to indicate 6540** that the prepared statement is using a full table scan rather than 6541** an index. 6542** 6543** This interface is used to retrieve and reset counter values from 6544** a [prepared statement]. The first argument is the prepared statement 6545** object to be interrogated. The second argument 6546** is an integer code for a specific [SQLITE_STMTSTATUS_SORT | counter] 6547** to be interrogated. 6548** The current value of the requested counter is returned. 6549** If the resetFlg is true, then the counter is reset to zero after this 6550** interface call returns. 6551** 6552** See also: [sqlite3_status()] and [sqlite3_db_status()]. 6553*/ 6554SQLITE_EXPERIMENTAL int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg); 6555 6556/* 6557** CAPI3REF: Status Parameters for prepared statements {H17570} <H17550> 6558** EXPERIMENTAL 6559** 6560** These preprocessor macros define integer codes that name counter 6561** values associated with the [sqlite3_stmt_status()] interface. 6562** The meanings of the various counters are as follows: 6563** 6564** <dl> 6565** <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt> 6566** <dd>This is the number of times that SQLite has stepped forward in 6567** a table as part of a full table scan. Large numbers for this counter 6568** may indicate opportunities for performance improvement through 6569** careful use of indices.</dd> 6570** 6571** <dt>SQLITE_STMTSTATUS_SORT</dt> 6572** <dd>This is the number of sort operations that have occurred. 6573** A non-zero value in this counter may indicate an opportunity to 6574** improvement performance through careful use of indices.</dd> 6575** 6576** </dl> 6577*/ 6578#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1 6579#define SQLITE_STMTSTATUS_SORT 2 6580 6581/* 6582** CAPI3REF: Custom Page Cache Object 6583** EXPERIMENTAL 6584** 6585** The sqlite3_pcache type is opaque. It is implemented by 6586** the pluggable module. The SQLite core has no knowledge of 6587** its size or internal structure and never deals with the 6588** sqlite3_pcache object except by holding and passing pointers 6589** to the object. 6590** 6591** See [sqlite3_pcache_methods] for additional information. 6592*/ 6593typedef struct sqlite3_pcache sqlite3_pcache; 6594 6595/* 6596** CAPI3REF: Application Defined Page Cache. 6597** EXPERIMENTAL 6598** 6599** The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can 6600** register an alternative page cache implementation by passing in an 6601** instance of the sqlite3_pcache_methods structure. The majority of the 6602** heap memory used by sqlite is used by the page cache to cache data read 6603** from, or ready to be written to, the database file. By implementing a 6604** custom page cache using this API, an application can control more 6605** precisely the amount of memory consumed by sqlite, the way in which 6606** said memory is allocated and released, and the policies used to 6607** determine exactly which parts of a database file are cached and for 6608** how long. 6609** 6610** The contents of the structure are copied to an internal buffer by sqlite 6611** within the call to [sqlite3_config]. 6612** 6613** The xInit() method is called once for each call to [sqlite3_initialize()] 6614** (usually only once during the lifetime of the process). It is passed 6615** a copy of the sqlite3_pcache_methods.pArg value. It can be used to set 6616** up global structures and mutexes required by the custom page cache 6617** implementation. The xShutdown() method is called from within 6618** [sqlite3_shutdown()], if the application invokes this API. It can be used 6619** to clean up any outstanding resources before process shutdown, if required. 6620** 6621** The xCreate() method is used to construct a new cache instance. The 6622** first parameter, szPage, is the size in bytes of the pages that must 6623** be allocated by the cache. szPage will not be a power of two. The 6624** second argument, bPurgeable, is true if the cache being created will 6625** be used to cache database pages read from a file stored on disk, or 6626** false if it is used for an in-memory database. The cache implementation 6627** does not have to do anything special based on the value of bPurgeable, 6628** it is purely advisory. 6629** 6630** The xCachesize() method may be called at any time by SQLite to set the 6631** suggested maximum cache-size (number of pages stored by) the cache 6632** instance passed as the first argument. This is the value configured using 6633** the SQLite "[PRAGMA cache_size]" command. As with the bPurgeable parameter, 6634** the implementation is not required to do anything special with this 6635** value, it is advisory only. 6636** 6637** The xPagecount() method should return the number of pages currently 6638** stored in the cache supplied as an argument. 6639** 6640** The xFetch() method is used to fetch a page and return a pointer to it. 6641** A 'page', in this context, is a buffer of szPage bytes aligned at an 6642** 8-byte boundary. The page to be fetched is determined by the key. The 6643** mimimum key value is 1. After it has been retrieved using xFetch, the page 6644** is considered to be pinned. 6645** 6646** If the requested page is already in the page cache, then a pointer to 6647** the cached buffer should be returned with its contents intact. If the 6648** page is not already in the cache, then the expected behaviour of the 6649** cache is determined by the value of the createFlag parameter passed 6650** to xFetch, according to the following table: 6651** 6652** <table border=1 width=85% align=center> 6653** <tr><th>createFlag<th>Expected Behaviour 6654** <tr><td>0<td>NULL should be returned. No new cache entry is created. 6655** <tr><td>1<td>If createFlag is set to 1, this indicates that 6656** SQLite is holding pinned pages that can be unpinned 6657** by writing their contents to the database file (a 6658** relatively expensive operation). In this situation the 6659** cache implementation has two choices: it can return NULL, 6660** in which case SQLite will attempt to unpin one or more 6661** pages before re-requesting the same page, or it can 6662** allocate a new page and return a pointer to it. If a new 6663** page is allocated, then it must be completely zeroed before 6664** it is returned. 6665** <tr><td>2<td>If createFlag is set to 2, then SQLite is not holding any 6666** pinned pages associated with the specific cache passed 6667** as the first argument to xFetch() that can be unpinned. The 6668** cache implementation should attempt to allocate a new 6669** cache entry and return a pointer to it. Again, the new 6670** page should be zeroed before it is returned. If the xFetch() 6671** method returns NULL when createFlag==2, SQLite assumes that 6672** a memory allocation failed and returns SQLITE_NOMEM to the 6673** user. 6674** </table> 6675** 6676** xUnpin() is called by SQLite with a pointer to a currently pinned page 6677** as its second argument. If the third parameter, discard, is non-zero, 6678** then the page should be evicted from the cache. In this case SQLite 6679** assumes that the next time the page is retrieved from the cache using 6680** the xFetch() method, it will be zeroed. If the discard parameter is 6681** zero, then the page is considered to be unpinned. The cache implementation 6682** may choose to reclaim (free or recycle) unpinned pages at any time. 6683** SQLite assumes that next time the page is retrieved from the cache 6684** it will either be zeroed, or contain the same data that it did when it 6685** was unpinned. 6686** 6687** The cache is not required to perform any reference counting. A single 6688** call to xUnpin() unpins the page regardless of the number of prior calls 6689** to xFetch(). 6690** 6691** The xRekey() method is used to change the key value associated with the 6692** page passed as the second argument from oldKey to newKey. If the cache 6693** previously contains an entry associated with newKey, it should be 6694** discarded. Any prior cache entry associated with newKey is guaranteed not 6695** to be pinned. 6696** 6697** When SQLite calls the xTruncate() method, the cache must discard all 6698** existing cache entries with page numbers (keys) greater than or equal 6699** to the value of the iLimit parameter passed to xTruncate(). If any 6700** of these pages are pinned, they are implicitly unpinned, meaning that 6701** they can be safely discarded. 6702** 6703** The xDestroy() method is used to delete a cache allocated by xCreate(). 6704** All resources associated with the specified cache should be freed. After 6705** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*] 6706** handle invalid, and will not use it with any other sqlite3_pcache_methods 6707** functions. 6708*/ 6709typedef struct sqlite3_pcache_methods sqlite3_pcache_methods; 6710struct sqlite3_pcache_methods { 6711 void *pArg; 6712 int (*xInit)(void*); 6713 void (*xShutdown)(void*); 6714 sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable); 6715 void (*xCachesize)(sqlite3_pcache*, int nCachesize); 6716 int (*xPagecount)(sqlite3_pcache*); 6717 void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag); 6718 void (*xUnpin)(sqlite3_pcache*, void*, int discard); 6719 void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey); 6720 void (*xTruncate)(sqlite3_pcache*, unsigned iLimit); 6721 void (*xDestroy)(sqlite3_pcache*); 6722}; 6723 6724/* 6725** Undo the hack that converts floating point types to integer for 6726** builds on processors without floating point support. 6727*/ 6728#ifdef SQLITE_OMIT_FLOATING_POINT 6729# undef double 6730#endif 6731 6732#ifdef __cplusplus 6733} /* End of the 'extern "C"' block */ 6734#endif 6735#endif 6736