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