Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Documentation updates. No changes to code. (CVS 5451) |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
e58b49779bfd4a9e88e8c6b0a929c971 |
User & Date: | drh 2008-07-22 18:45:09.000 |
Context
2008-07-22
| ||
22:15 | Cleanup the hash functions in FTS2. Backports (4440) from fts3. (CVS 5452) (check-in: e31d2f875c user: shess tags: trunk) | |
18:45 | Documentation updates. No changes to code. (CVS 5451) (check-in: e58b49779b user: drh tags: trunk) | |
05:32 | winGetLastError support added. Consolidated getLastErrorMsg() support. Removed some more WINCE dead code similar to instance in ticket #3232. Added error return on SystemTimeToFileTime() failure. (CVS 5450) (check-in: c0a5cf38ee user: shane tags: trunk) | |
Changes
Changes to src/sqlite.h.in.
︙ | ︙ | |||
26 27 28 29 30 31 32 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** | | | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** ** @(#) $Id: sqlite.h.in,v 1.373 2008/07/22 18:45:09 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ #include <stdarg.h> /* Needed for the definition of va_list */ /* ** Make sure we can call this stuff from C++. |
︙ | ︙ | |||
58 59 60 61 62 63 64 | # undef SQLITE_VERSION #endif #ifdef SQLITE_VERSION_NUMBER # undef SQLITE_VERSION_NUMBER #endif /* | | | | | > | | | | | | | | | 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 | # undef SQLITE_VERSION #endif #ifdef SQLITE_VERSION_NUMBER # undef SQLITE_VERSION_NUMBER #endif /* ** CAPI3REF: Compile-Time Library Version Numbers {H10010}<S60100> ** ** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in ** the sqlite3.h file specify the version of SQLite with which ** that header file is associated. ** ** The "version" of SQLite is a string of the form "X.Y.Z". ** The phrase "alpha" or "beta" might be appended after the Z. ** The X value is major version number always 3 in SQLite3. ** The X value only changes when backwards compatibility is ** broken and we intend to never break backwards compatibility. ** The Y value is the minor version number and only changes when ** there are major feature enhancements that are forwards compatible ** but not backwards compatible. ** The Z value is the release number and is incremented with ** each release but resets back to 0 whenever Y is incremented. ** ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()]. ** ** INVARIANTS: ** ** {H10011} The SQLITE_VERSION #define in the sqlite3.h header file shall ** evaluate to a string literal that is the SQLite version ** with which the header file is associated. <S60100> ** ** {H10014} The SQLITE_VERSION_NUMBER #define shall resolve to an integer ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z ** are the major version, minor version, and release number. ** <S60100> */ #define SQLITE_VERSION "--VERS--" #define SQLITE_VERSION_NUMBER --VERSION-NUMBER-- /* ** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100> ** KEYWORDS: sqlite3_version ** ** These features provide the same information as the [SQLITE_VERSION] ** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated ** with the library instead of the header file. Cautious programmers might ** include a check in their application to verify that ** sqlite3_libversion_number() always returns the value ** [SQLITE_VERSION_NUMBER]. ** ** The sqlite3_libversion() function returns the same information as is ** in the sqlite3_version[] string constant. The function is provided ** for use in DLLs since DLL users usually do not have direct access to string ** constants within the DLL. ** ** INVARIANTS: ** ** {H10021} The [sqlite3_libversion_number()] interface shall return ** an integer equal to [SQLITE_VERSION_NUMBER]. <S60100> ** ** {H10022} The [sqlite3_version] string constant shall contain ** the text of the [SQLITE_VERSION] string. <S60100> ** ** {H10023} The [sqlite3_libversion()] function shall return ** a pointer to the [sqlite3_version] string constant. <S60100> */ SQLITE_EXTERN const char sqlite3_version[]; const char *sqlite3_libversion(void); int sqlite3_libversion_number(void); /* ** CAPI3REF: Test To See If The Library Is Threadsafe {H10100} <S60100> ** ** SQLite can be compiled with or without mutexes. When ** the [SQLITE_THREADSAFE] C preprocessor macro is true, mutexes ** are enabled and SQLite is threadsafe. When that macro is false, ** the mutexes are omitted. Without the mutexes, it is not safe ** to use SQLite concurrently from more than one thread. ** |
︙ | ︙ | |||
150 151 152 153 154 155 156 | ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD], ** or [SQLITE_CONFIG_MUTEX]. The return value of this function shows ** only the default compile-time setting, not any run-time changes ** to that setting. ** ** INVARIANTS: ** | | | | | | | | | | 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 | ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD], ** or [SQLITE_CONFIG_MUTEX]. The return value of this function shows ** only the default compile-time setting, not any run-time changes ** to that setting. ** ** INVARIANTS: ** ** {H10101} The [sqlite3_threadsafe()] function shall return nonzero if ** SQLite was compiled with the its mutexes enabled by default ** or zero if SQLite was compiled such that mutexes are ** permanently disabled. <S60100> ** ** {H10102} The value returned by the [sqlite3_threadsafe()] function ** shall not change when mutex setting are modified at ** runtime using the [sqlite3_config()] interface and ** especially the [SQLITE_CONFIG_SINGLETHREAD], ** [SQLITE_CONFIG_MULTITHREAD], [SQLITE_CONFIG_SERIALIZED], ** and [SQLITE_CONFIG_MUTEX] verbs. <S60100> */ int sqlite3_threadsafe(void); /* ** CAPI3REF: Database Connection Handle {H12000} ** KEYWORDS: {database connection} {database connections} ** ** Each open SQLite database is represented by a pointer to an instance of ** the opaque structure named "sqlite3". It is useful to think of an sqlite3 ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()] ** is its destructor. There are many other interfaces (such as ** [sqlite3_prepare_v2()], [sqlite3_create_function()], and ** [sqlite3_busy_timeout()] to name but three) that are methods on an ** sqlite3 object. */ typedef struct sqlite3 sqlite3; /* ** CAPI3REF: 64-Bit Integer Types {H10200} ** KEYWORDS: sqlite_int64 sqlite_uint64 ** ** Because there is no cross-platform way to specify 64-bit integer types ** SQLite includes typedefs for 64-bit signed and unsigned integers. ** ** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions. ** The sqlite_int64 and sqlite_uint64 types are supported for backwards ** compatibility only. ** ** INVARIANTS: ** ** {H10201} The [sqlite_int64] and [sqlite3_int64] type shall specify ** a 64-bit signed integer. ** ** {H10202} The [sqlite_uint64] and [sqlite3_uint64] type shall specify ** a 64-bit unsigned integer. */ #ifdef SQLITE_INT64_TYPE typedef SQLITE_INT64_TYPE sqlite_int64; typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; #elif defined(_MSC_VER) || defined(__BORLANDC__) typedef __int64 sqlite_int64; |
︙ | ︙ | |||
220 221 222 223 224 225 226 | ** substitute integer for floating-point. */ #ifdef SQLITE_OMIT_FLOATING_POINT # define double sqlite3_int64 #endif /* | | | 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 | ** substitute integer for floating-point. */ #ifdef SQLITE_OMIT_FLOATING_POINT # define double sqlite3_int64 #endif /* ** CAPI3REF: Closing A Database Connection {H12010} ** ** This routine is the destructor for the [sqlite3] object. ** ** Applications should [sqlite3_finalize | finalize] all [prepared statements] ** and [sqlite3_blob_close | close] all [BLOB handles] associated with ** the [sqlite3] object prior to attempting to close the object. ** The [sqlite3_next_stmt()] interface can be used to locate all |
︙ | ︙ | |||
243 244 245 246 247 248 249 | ** </pre></blockquote> ** ** If [sqlite3_close()] is invoked while a transaction is open, ** the transaction is automatically rolled back. ** ** INVARIANTS: ** | | | | | | | | | | 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 | ** </pre></blockquote> ** ** If [sqlite3_close()] is invoked while a transaction is open, ** the transaction is automatically rolled back. ** ** INVARIANTS: ** ** {H12011} A successful call to [sqlite3_close(C)] shall destroy the ** [database connection] object C. ** ** {H12012} A successful call to [sqlite3_close(C)] shall return SQLITE_OK. ** ** {H12013} A successful call to [sqlite3_close(C)] shall release all ** memory and system resources associated with [database connection] ** C. ** ** {H12014} A call to [sqlite3_close(C)] on a [database connection] C that ** has one or more open [prepared statements] shall fail with ** an [SQLITE_BUSY] error code. ** ** {H12015} A call to [sqlite3_close(C)] where C is a NULL pointer shall ** return SQLITE_OK. ** ** {H12019} When [sqlite3_close(C)] is invoked on a [database connection] C ** that has a pending transaction, the transaction shall be ** rolled back. ** ** ASSUMPTIONS: ** ** {A12016} The C parameter to [sqlite3_close(C)] must be either a NULL ** pointer or an [sqlite3] object pointer previously obtained ** from [sqlite3_open()], [sqlite3_open16()], or ** [sqlite3_open_v2()], and not previously closed. */ int sqlite3_close(sqlite3 *); /* ** The type for a callback function. ** This is legacy and deprecated. It is included for historical ** compatibility and is not documented. */ typedef int (*sqlite3_callback)(void*,int,char**, char**); /* ** CAPI3REF: One-Step Query Execution Interface {H12100} ** ** The sqlite3_exec() interface is a convenient way of running one or more ** SQL statements without having to write a lot of C code. The UTF-8 encoded ** SQL statements are passed in as the second parameter to sqlite3_exec(). ** The statements are evaluated one by one until either an error or ** an interrupt is encountered, or until they are all done. The 3rd parameter ** is an optional callback that is invoked once for each row of any query |
︙ | ︙ | |||
308 309 310 311 312 313 314 | ** The sqlite3_exec() interface is implemented in terms of ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. ** The sqlite3_exec() routine does nothing to the database that cannot be done ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. ** ** INVARIANTS: ** | | | | | | | | | | | | | | | | | | 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 | ** The sqlite3_exec() interface is implemented in terms of ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. ** The sqlite3_exec() routine does nothing to the database that cannot be done ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. ** ** INVARIANTS: ** ** {H12101} A successful invocation of [sqlite3_exec(D,S,C,A,E)] ** shall sequentially evaluate all of the UTF-8 encoded, ** semicolon-separated SQL statements in the zero-terminated ** string S within the context of the [database connection] D. ** ** {H12102} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL then ** the actions of the interface shall be the same as if the ** S parameter were an empty string. ** ** {H12104} The return value of [sqlite3_exec()] shall be [SQLITE_OK] if all ** SQL statements run successfully and to completion. ** ** {H12105} The return value of [sqlite3_exec()] shall be an appropriate ** non-zero [error code] if any SQL statement fails. ** ** {H12107} If one or more of the SQL statements handed to [sqlite3_exec()] ** return results and the 3rd parameter is not NULL, then ** the callback function specified by the 3rd parameter shall be ** invoked once for each row of result. ** ** {H12110} If the callback returns a non-zero value then [sqlite3_exec()] ** shall abort the SQL statement it is currently evaluating, ** skip all subsequent SQL statements, and return [SQLITE_ABORT]. ** ** {H12113} The [sqlite3_exec()] routine shall pass its 4th parameter through ** as the 1st parameter of the callback. ** ** {H12116} The [sqlite3_exec()] routine shall set the 2nd parameter of its ** callback to be the number of columns in the current row of ** result. ** ** {H12119} The [sqlite3_exec()] routine shall set the 3rd parameter of its ** callback to be an array of pointers to strings holding the ** values for each column in the current result set row as ** obtained from [sqlite3_column_text()]. ** ** {H12122} The [sqlite3_exec()] routine shall set the 4th parameter of its ** callback to be an array of pointers to strings holding the ** names of result columns as obtained from [sqlite3_column_name()]. ** ** {H12125} If the 3rd parameter to [sqlite3_exec()] is NULL then ** [sqlite3_exec()] shall silently discard query results. ** ** {H12131} If an error occurs while parsing or evaluating any of the SQL ** statements in the S parameter of [sqlite3_exec(D,S,C,A,E)] and if ** the E parameter is not NULL, then [sqlite3_exec()] shall store ** in *E an appropriate error message written into memory obtained ** from [sqlite3_malloc()]. ** ** {H12134} The [sqlite3_exec(D,S,C,A,E)] routine shall set the value of ** *E to NULL if E is not NULL and there are no errors. ** ** {H12137} The [sqlite3_exec(D,S,C,A,E)] function shall set the [error code] ** and message accessible via [sqlite3_errcode()], ** [sqlite3_errmsg()], and [sqlite3_errmsg16()]. ** ** {H12138} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL or an ** empty string or contains nothing other than whitespace, comments, ** and/or semicolons, then results of [sqlite3_errcode()], ** [sqlite3_errmsg()], and [sqlite3_errmsg16()] ** shall reset to indicate no errors. ** ** ASSUMPTIONS: ** ** {A12141} The first parameter to [sqlite3_exec()] must be an valid and open ** [database connection]. ** ** {A12142} The database connection must not be closed while ** [sqlite3_exec()] is running. ** |
︙ | ︙ | |||
394 395 396 397 398 399 400 | const char *sql, /* SQL to be evaluated */ int (*callback)(void*,int,char**,char**), /* Callback function */ void *, /* 1st argument to callback */ char **errmsg /* Error msg written here */ ); /* | | | 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 | const char *sql, /* SQL to be evaluated */ int (*callback)(void*,int,char**,char**), /* Callback function */ void *, /* 1st argument to callback */ char **errmsg /* Error msg written here */ ); /* ** CAPI3REF: Result Codes {H10210} ** KEYWORDS: SQLITE_OK {error code} {error codes} ** KEYWORDS: {result code} {result codes} ** ** Many SQLite functions return an integer result code from the set shown ** here in order to indicates success or failure. ** ** New error codes may be added in future versions of SQLite. |
︙ | ︙ | |||
438 439 440 441 442 443 444 | #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ #define SQLITE_NOTADB 26 /* File opened that is not a database file */ #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ /* end-of-error-codes */ /* | | | 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 | #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ #define SQLITE_NOTADB 26 /* File opened that is not a database file */ #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ /* end-of-error-codes */ /* ** CAPI3REF: Extended Result Codes {H10220} ** KEYWORDS: {extended error code} {extended error codes} ** KEYWORDS: {extended result code} {extended result codes} ** ** In its default configuration, SQLite API routines return one of 26 integer ** [SQLITE_OK | result codes]. However, experience has shown that many of ** these result codes are too coarse-grained. They do not provide as ** much information about problems as programmers might like. In an effort to |
︙ | ︙ | |||
462 463 464 465 466 467 468 | ** to see new result codes in future releases of SQLite. ** ** The SQLITE_OK result code will never be extended. It will always ** be exactly zero. ** ** INVARIANTS: ** | | | | | | | 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 | ** to see new result codes in future releases of SQLite. ** ** The SQLITE_OK result code will never be extended. It will always ** be exactly zero. ** ** INVARIANTS: ** ** {H10223} The symbolic name for an extended result code shall contains ** a related primary result code as a prefix. ** ** {H10224} Primary result code names shall contain a single "_" character. ** ** {H10225} Extended result code names shall contain two or more "_" characters. ** ** {H10226} The numeric value of an extended result code shall contain the ** numeric value of its corresponding primary result code in ** its least significant 8 bits. */ #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) #define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) #define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8)) #define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8)) /* ** CAPI3REF: Flags For File Open Operations {H10230} ** ** These bit values are intended for use in the ** 3rd parameter to the [sqlite3_open_v2()] interface and ** in the 4th parameter to the xOpen method of the ** [sqlite3_vfs] object. */ #define SQLITE_OPEN_READONLY 0x00000001 |
︙ | ︙ | |||
511 512 513 514 515 516 517 | #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 #define SQLITE_OPEN_SUBJOURNAL 0x00002000 #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 #define SQLITE_OPEN_NOMUTEX 0x00008000 /* | | | 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 | #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 #define SQLITE_OPEN_SUBJOURNAL 0x00002000 #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 #define SQLITE_OPEN_NOMUTEX 0x00008000 /* ** CAPI3REF: Device Characteristics {H10240} ** ** The xDeviceCapabilities method of the [sqlite3_io_methods] ** object returns an integer which is a vector of the these ** bit values expressing I/O characteristics of the mass storage ** device that holds the file that the [sqlite3_io_methods] ** refers to. ** |
︙ | ︙ | |||
543 544 545 546 547 548 549 | #define SQLITE_IOCAP_ATOMIC16K 0x00000040 #define SQLITE_IOCAP_ATOMIC32K 0x00000080 #define SQLITE_IOCAP_ATOMIC64K 0x00000100 #define SQLITE_IOCAP_SAFE_APPEND 0x00000200 #define SQLITE_IOCAP_SEQUENTIAL 0x00000400 /* | | | | | | 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 | #define SQLITE_IOCAP_ATOMIC16K 0x00000040 #define SQLITE_IOCAP_ATOMIC32K 0x00000080 #define SQLITE_IOCAP_ATOMIC64K 0x00000100 #define SQLITE_IOCAP_SAFE_APPEND 0x00000200 #define SQLITE_IOCAP_SEQUENTIAL 0x00000400 /* ** CAPI3REF: File Locking Levels {H10250} ** ** SQLite uses one of these integer values as the second ** argument to calls it makes to the xLock() and xUnlock() methods ** of an [sqlite3_io_methods] object. */ #define SQLITE_LOCK_NONE 0 #define SQLITE_LOCK_SHARED 1 #define SQLITE_LOCK_RESERVED 2 #define SQLITE_LOCK_PENDING 3 #define SQLITE_LOCK_EXCLUSIVE 4 /* ** CAPI3REF: Synchronization Type Flags {H10260} ** ** When SQLite invokes the xSync() method of an ** [sqlite3_io_methods] object it uses a combination of ** these integer values as the second argument. ** ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the ** sync operation only needs to flush data to mass storage. Inode ** information need not be flushed. The SQLITE_SYNC_NORMAL flag means ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means ** to use Mac OS-X style fullsync instead of fsync(). */ #define SQLITE_SYNC_NORMAL 0x00002 #define SQLITE_SYNC_FULL 0x00003 #define SQLITE_SYNC_DATAONLY 0x00010 /* ** CAPI3REF: OS Interface Open File Handle {H11110} ** ** An [sqlite3_file] object represents an open file in the OS ** interface layer. Individual OS interface implementations will ** want to subclass this object by appending additional fields ** for their own use. The pMethods entry is a pointer to an ** [sqlite3_io_methods] object that defines methods for performing ** I/O operations on the open file. */ typedef struct sqlite3_file sqlite3_file; struct sqlite3_file { const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ }; /* ** CAPI3REF: OS Interface File Virtual Methods Object {H11120} ** ** Every file opened by the [sqlite3_vfs] xOpen method populates an ** [sqlite3_file] object (or, more commonly, a subclass of the ** [sqlite3_file] object) with a pointer to an instance of this object. ** This object defines the methods used to perform various operations ** against the open file represented by the [sqlite3_file] object. ** |
︙ | ︙ | |||
681 682 683 684 685 686 687 | int (*xFileControl)(sqlite3_file*, int op, void *pArg); int (*xSectorSize)(sqlite3_file*); int (*xDeviceCharacteristics)(sqlite3_file*); /* Additional methods may be added in future releases */ }; /* | | | | | 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 | int (*xFileControl)(sqlite3_file*, int op, void *pArg); int (*xSectorSize)(sqlite3_file*); int (*xDeviceCharacteristics)(sqlite3_file*); /* Additional methods may be added in future releases */ }; /* ** CAPI3REF: Standard File Control Opcodes {H11310} ** ** These integer constants are opcodes for the xFileControl method ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()] ** interface. ** ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This ** opcode causes the xFileControl method to write the current state of ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED], ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE]) ** into an integer that the pArg argument points to. This capability ** is used during testing and only needs to be supported when SQLITE_TEST ** is defined. */ #define SQLITE_FCNTL_LOCKSTATE 1 /* ** CAPI3REF: Mutex Handle {H17110} ** ** The mutex module within SQLite defines [sqlite3_mutex] to be an ** abstract type for a mutex object. The SQLite core never looks ** at the internal representation of an [sqlite3_mutex]. It only ** deals with pointers to the [sqlite3_mutex] object. ** ** Mutexes are created using [sqlite3_mutex_alloc()]. */ typedef struct sqlite3_mutex sqlite3_mutex; /* ** CAPI3REF: OS Interface Object {H11140} ** ** An instance of the sqlite3_vfs object defines the interface between ** the SQLite core and the underlying operating system. The "vfs" ** in the name of the object stands for "virtual file system". ** ** The value of the iVersion field is initially 1 but may be larger in ** future versions of SQLite. Additional fields may be appended to this |
︙ | ︙ | |||
743 744 745 746 747 748 749 | ** or modify this field while holding a particular static mutex. ** The application should never modify anything within the sqlite3_vfs ** object once the object has been registered. ** ** The zName field holds the name of the VFS module. The name must ** be unique across all VFS modules. ** | | | | | 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 | ** or modify this field while holding a particular static mutex. ** The application should never modify anything within the sqlite3_vfs ** object once the object has been registered. ** ** The zName field holds the name of the VFS module. The name must ** be unique across all VFS modules. ** ** {H11141} SQLite will guarantee that the zFilename parameter to xOpen ** is either a NULL pointer or string obtained ** from xFullPathname(). SQLite further guarantees that ** the string will be valid and unchanged until xClose() is ** called. {END} Becasue of the previous sentense, ** the [sqlite3_file] can safely store a pointer to the ** filename if it needs to remember the filename for some reason. ** If the zFilename parameter is xOpen is a NULL pointer then xOpen ** must invite its own temporary name for the file. Whenever the ** xFilename parameter is NULL it will also be the case that the ** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE]. ** ** {H11142} The flags argument to xOpen() includes all bits set in ** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()] ** or [sqlite3_open16()] is used, then flags includes at least ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END} ** If xOpen() opens a file read-only then it sets *pOutFlags to ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set. ** ** {H11143} SQLite will also add one of the following flags to the xOpen() ** call, depending on the object being opened: ** ** <ul> ** <li> [SQLITE_OPEN_MAIN_DB] ** <li> [SQLITE_OPEN_MAIN_JOURNAL] ** <li> [SQLITE_OPEN_TEMP_DB] ** <li> [SQLITE_OPEN_TEMP_JOURNAL] |
︙ | ︙ | |||
791 792 793 794 795 796 797 | ** SQLite might also add one of the following flags to the xOpen method: ** ** <ul> ** <li> [SQLITE_OPEN_DELETEONCLOSE] ** <li> [SQLITE_OPEN_EXCLUSIVE] ** </ul> ** | | | | | | | | | 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 | ** SQLite might also add one of the following flags to the xOpen method: ** ** <ul> ** <li> [SQLITE_OPEN_DELETEONCLOSE] ** <li> [SQLITE_OPEN_EXCLUSIVE] ** </ul> ** ** {H11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be ** deleted when it is closed. {H11146} The [SQLITE_OPEN_DELETEONCLOSE] ** will be set for TEMP databases, journals and for subjournals. ** ** {H11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened ** for exclusive access. This flag is set for all files except ** for the main database file. ** ** {H11148} At least szOsFile bytes of memory are allocated by SQLite ** to hold the [sqlite3_file] structure passed as the third ** argument to xOpen. {END} The xOpen method does not have to ** allocate the structure; it should just fill it in. ** ** {H11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ] ** to test whether a file is at least readable. {END} The file can be a ** directory. ** ** {H11150} SQLite will always allocate at least mxPathname+1 bytes for the ** output buffer xFullPathname. {H11151} The exact size of the output buffer ** is also passed as a parameter to both methods. {END} If the output buffer ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is ** handled as a fatal error by SQLite, vfs implementations should endeavor ** to prevent this by setting mxPathname to a sufficiently large value. ** ** The xRandomness(), xSleep(), and xCurrentTime() interfaces ** are not strictly a part of the filesystem, but they are |
︙ | ︙ | |||
853 854 855 856 857 858 859 | int (*xCurrentTime)(sqlite3_vfs*, double*); int (*xGetLastError)(sqlite3_vfs*, int, char *); /* New fields may be appended in figure versions. The iVersion ** value will increment whenever this happens. */ }; /* | | | | | | | | 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 | int (*xCurrentTime)(sqlite3_vfs*, double*); int (*xGetLastError)(sqlite3_vfs*, int, char *); /* New fields may be appended in figure versions. The iVersion ** value will increment whenever this happens. */ }; /* ** CAPI3REF: Flags for the xAccess VFS method {H11190} ** ** {H11191} These integer constants can be used as the third parameter to ** the xAccess method of an [sqlite3_vfs] object. {END} They determine ** what kind of permissions the xAccess method is looking for. ** {H11192} With SQLITE_ACCESS_EXISTS, the xAccess method ** simply checks whether the file exists. ** {H11193} With SQLITE_ACCESS_READWRITE, the xAccess method ** checks whether the file is both readable and writable. ** {H11194} With SQLITE_ACCESS_READ, the xAccess method ** checks whether the file is readable. */ #define SQLITE_ACCESS_EXISTS 0 #define SQLITE_ACCESS_READWRITE 1 #define SQLITE_ACCESS_READ 2 /* ** CAPI3REF: Initialize The SQLite Library {H10130} ** ** The sqlite3_initialize() routine initializes the ** SQLite library. The sqlite3_shutdown() routine ** deallocates any resources that were allocated by sqlite3_initialize(). ** ** A call to sqlite3_initialize() is an "effective" call if it is ** the first time sqlite3_initialize() is invoked during the lifetime of |
︙ | ︙ | |||
935 936 937 938 939 940 941 | */ int sqlite3_initialize(void); int sqlite3_shutdown(void); int sqlite3_os_init(void); int sqlite3_os_end(void); /* | | | 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 | */ int sqlite3_initialize(void); int sqlite3_shutdown(void); int sqlite3_os_init(void); int sqlite3_os_end(void); /* ** CAPI3REF: Configuring The SQLite Library {H10145} ** ** The sqlite3_config() interface is used to make global configuration ** changes to SQLite in order to tune SQLite to the specific needs of ** the application. The default configuration is recommended for most ** applications and so this routine is usually not necessary. It is ** provided to support rare applications with unusual needs. ** |
︙ | ︙ | |||
968 969 970 971 972 973 974 | ** The sqlite3_config() interface is considered experimental in that ** new configuration options may be added in future releases and existing ** configuration options may be discontinued or modified. */ int sqlite3_config(int, ...); /* | | | 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 | ** The sqlite3_config() interface is considered experimental in that ** new configuration options may be added in future releases and existing ** configuration options may be discontinued or modified. */ int sqlite3_config(int, ...); /* ** CAPI3REF: Memory Allocation Routines {H10155} ** ** An instance of this object defines the interface between SQLite ** and low-level memory allocation routines. ** ** This object is used in only one place in the SQLite interface. ** A pointer to an instance of this object is the argument to ** [sqlite3_config()] when the configuration option is |
︙ | ︙ | |||
1022 1023 1024 1025 1026 1027 1028 | int (*xRoundup)(int); /* Round up request size to allocation size */ int (*xInit)(void*); /* Initialize the memory allocator */ void (*xShutdown)(void*); /* Deinitialize the memory allocator */ void *pAppData; /* Argument to xInit() and xShutdown() */ }; /* | | | 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 | int (*xRoundup)(int); /* Round up request size to allocation size */ int (*xInit)(void*); /* Initialize the memory allocator */ void (*xShutdown)(void*); /* Deinitialize the memory allocator */ void *pAppData; /* Argument to xInit() and xShutdown() */ }; /* ** CAPI3REF: Configuration Options {H10160} ** ** These constants are the available integer configuration options that ** can be passed as the first argument to the [sqlite3_config()] interface. ** ** New configuration options may be added in future releases of SQLite. ** Existing configuration options might be discontinued. Applications ** should check the return code from [sqlite3_config()] to make sure that |
︙ | ︙ | |||
1156 1157 1158 1159 1160 1161 1162 | #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ /* | | | | | | 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 | #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ /* ** CAPI3REF: Enable Or Disable Extended Result Codes {H12200} ** ** The sqlite3_extended_result_codes() routine enables or disables the ** [extended result codes] feature of SQLite. The extended result ** codes are disabled by default for historical compatibility considerations. ** ** INVARIANTS: ** ** {H12201} Each new [database connection] shall have the ** [extended result codes] feature disabled by default. ** ** {H12202} The [sqlite3_extended_result_codes(D,F)] interface shall enable ** [extended result codes] for the [database connection] D ** if the F parameter is true, or disable them if F is false. */ int sqlite3_extended_result_codes(sqlite3*, int onoff); /* ** CAPI3REF: Last Insert Rowid {H12220} ** ** Each entry in an SQLite table has a unique 64-bit signed ** integer key called the "rowid". The rowid is always available ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those ** names are not also used by explicitly declared columns. If ** the table has a column of type INTEGER PRIMARY KEY then that column ** is another alias for the rowid. |
︙ | ︙ | |||
1208 1209 1210 1211 1212 1213 1214 | ** the return value of this interface. ** ** For the purposes of this routine, an INSERT is considered to ** be successful even if it is subsequently rolled back. ** ** INVARIANTS: ** | | | | | | 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 | ** the return value of this interface. ** ** For the purposes of this routine, an INSERT is considered to ** be successful even if it is subsequently rolled back. ** ** INVARIANTS: ** ** {H12221} The [sqlite3_last_insert_rowid()] function returns the rowid ** of the most recent successful INSERT performed on the same ** [database connection] and within the same or higher level ** trigger context, or zero if there have been no qualifying inserts. ** ** {H12223} The [sqlite3_last_insert_rowid()] function returns the ** same value when called from the same trigger context ** immediately before and after a ROLLBACK. ** ** ASSUMPTIONS: ** ** {A12232} If a separate thread performs a new INSERT on the same ** database connection while the [sqlite3_last_insert_rowid()] ** function is running and thus changes the last insert rowid, ** then the value returned by [sqlite3_last_insert_rowid()] is ** unpredictable and might not equal either the old or the new ** last insert rowid. */ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); /* ** CAPI3REF: Count The Number Of Rows Modified {H12240} ** ** This function returns the number of database rows that were changed ** or inserted or deleted by the most recently completed SQL statement ** on the [database connection] specified by the first parameter. ** Only changes that are directly specified by the INSERT, UPDATE, ** or DELETE statement are counted. Auxiliary changes caused by ** triggers are not counted. Use the [sqlite3_total_changes()] function |
︙ | ︙ | |||
1279 1280 1281 1282 1283 1284 1285 | ** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()] ** functions, regardless of the number of elements that were originally ** in the table. To get an accurate count of the number of rows deleted, use ** "DELETE FROM table WHERE 1" instead. ** ** INVARIANTS: ** | | | | | | 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 | ** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()] ** functions, regardless of the number of elements that were originally ** in the table. To get an accurate count of the number of rows deleted, use ** "DELETE FROM table WHERE 1" instead. ** ** INVARIANTS: ** ** {H12241} The [sqlite3_changes()] function shall return the number of ** row changes caused by the most recent INSERT, UPDATE, ** or DELETE statement on the same database connection and ** within the same or higher trigger context, or zero if there have ** not been any qualifying row changes. ** ** {H12243} Statements of the form "DELETE FROM tablename" with no ** WHERE clause shall cause subsequent calls to ** [sqlite3_changes()] to return zero, regardless of the ** number of rows originally in the table. ** ** ASSUMPTIONS: ** ** {A12252} If a separate thread makes changes on the same database connection ** while [sqlite3_changes()] is running then the value returned ** is unpredictable and not meaningful. */ int sqlite3_changes(sqlite3*); /* ** CAPI3REF: Total Number Of Rows Modified {H12260} ** ** This function returns the number of row changes caused by INSERT, ** UPDATE or DELETE statements since the [database connection] was opened. ** The count includes all changes from all trigger contexts. However, ** the count does not include changes used to implement REPLACE constraints, ** do rollbacks or ABORT processing, or DROP table processing. ** The changes are counted as soon as the statement that makes them is |
︙ | ︙ | |||
1323 1324 1325 1326 1327 1328 1329 | ** in the table. To get an accurate count of the number of rows deleted, use ** "DELETE FROM table WHERE 1" instead. ** ** See also the [sqlite3_changes()] interface. ** ** INVARIANTS: ** | | | | | | 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 | ** in the table. To get an accurate count of the number of rows deleted, use ** "DELETE FROM table WHERE 1" instead. ** ** See also the [sqlite3_changes()] interface. ** ** INVARIANTS: ** ** {H12261} The [sqlite3_total_changes()] returns the total number ** of row changes caused by INSERT, UPDATE, and/or DELETE ** statements on the same [database connection], in any ** trigger context, since the database connection was created. ** ** {H12263} Statements of the form "DELETE FROM tablename" with no ** WHERE clause shall not change the value returned ** by [sqlite3_total_changes()]. ** ** ASSUMPTIONS: ** ** {A12264} If a separate thread makes changes on the same database connection ** while [sqlite3_total_changes()] is running then the value ** returned is unpredictable and not meaningful. */ int sqlite3_total_changes(sqlite3*); /* ** CAPI3REF: Interrupt A Long-Running Query {H12270} ** ** This function causes any pending database operation to abort and ** return at its earliest opportunity. This routine is typically ** called in response to a user action such as pressing "Cancel" ** or Ctrl-C where the user wants a long query operation to halt ** immediately. ** |
︙ | ︙ | |||
1368 1369 1370 1371 1372 1373 1374 | ** will be rolled back automatically. ** ** A call to sqlite3_interrupt() has no effect on SQL statements ** that are started after sqlite3_interrupt() returns. ** ** INVARIANTS: ** | | | | | | | | | | 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 | ** will be rolled back automatically. ** ** A call to sqlite3_interrupt() has no effect on SQL statements ** that are started after sqlite3_interrupt() returns. ** ** INVARIANTS: ** ** {H12271} The [sqlite3_interrupt()] interface will force all running ** SQL statements associated with the same database connection ** to halt after processing at most one additional row of data. ** ** {H12272} Any SQL statement that is interrupted by [sqlite3_interrupt()] ** will return [SQLITE_INTERRUPT]. ** ** ASSUMPTIONS: ** ** {A12279} If the database connection closes while [sqlite3_interrupt()] ** is running then bad things will likely happen. */ void sqlite3_interrupt(sqlite3*); /* ** CAPI3REF: Determine If An SQL Statement Is Complete {H10510} ** ** These routines are useful for command-line input to determine if the ** currently entered text seems to form complete a SQL statement or ** if additional input is needed before sending the text into ** SQLite for parsing. These routines return true if the input string ** appears to be a complete SQL statement. A statement is judged to be ** complete if it ends with a semicolon token and is not a fragment of a ** CREATE TRIGGER statement. Semicolons that are embedded within ** string literals or quoted identifier names or comments are not ** independent tokens (they are part of the token in which they are ** embedded) and thus do not count as a statement terminator. ** ** These routines do not parse the SQL statements thus ** will not detect syntactically incorrect SQL. ** ** INVARIANTS: ** ** {H10511} A successful evaluation of [sqlite3_complete()] or ** [sqlite3_complete16()] functions shall ** return a numeric 1 if and only if the last non-whitespace ** token in their input is a semicolon that is not in between ** the BEGIN and END of a CREATE TRIGGER statement. ** ** {H10512} If a memory allocation error occurs during an invocation ** of [sqlite3_complete()] or [sqlite3_complete16()] then the ** routine shall return [SQLITE_NOMEM]. ** ** ASSUMPTIONS: ** ** {A10512} The input to [sqlite3_complete()] must be a zero-terminated ** UTF-8 string. ** ** {A10513} The input to [sqlite3_complete16()] must be a zero-terminated ** UTF-16 string in native byte order. */ int sqlite3_complete(const char *sql); int sqlite3_complete16(const void *sql); /* ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {H12310} ** ** This routine sets a callback function that might be invoked whenever ** an attempt is made to open a database table that another thread ** or process has locked. ** ** If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] ** is returned immediately upon encountering the lock. If the busy callback |
︙ | ︙ | |||
1481 1482 1483 1484 1485 1486 1487 | ** There can only be a single busy handler defined for each ** [database connection]. Setting a new busy handler clears any ** previously set handler. Note that calling [sqlite3_busy_timeout()] ** will also set or clear the busy handler. ** ** INVARIANTS: ** | | | | | | | | | | | | | | 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 | ** There can only be a single busy handler defined for each ** [database connection]. Setting a new busy handler clears any ** previously set handler. Note that calling [sqlite3_busy_timeout()] ** will also set or clear the busy handler. ** ** INVARIANTS: ** ** {H12311} The [sqlite3_busy_handler(D,C,A)] function shall replace ** busy callback in the [database connection] D with a new ** a new busy handler C and application data pointer A. ** ** {H12312} Newly created [database connections] shall have a busy ** handler of NULL. ** ** {H12314} When two or more [database connections] share a ** [sqlite3_enable_shared_cache | common cache], ** the busy handler for the database connection currently using ** the cache shall be invoked when the cache encounters a lock. ** ** {H12316} If a busy handler callback returns zero, then the SQLite interface ** that provoked the locking event shall return [SQLITE_BUSY]. ** ** {H12318} SQLite shall invokes the busy handler with two arguments which ** are a copy of the pointer supplied by the 3rd parameter to ** [sqlite3_busy_handler()] and a count of the number of prior ** invocations of the busy handler for the same locking event. ** ** ASSUMPTIONS: ** ** {A12319} A busy handler must not close the database connection ** or [prepared statement] that invoked the busy handler. */ int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); /* ** CAPI3REF: Set A Busy Timeout {H12340} ** ** This routine sets a [sqlite3_busy_handler | busy handler] that sleeps ** for a specified amount of time when a table is locked. The handler ** will sleep multiple times until at least "ms" milliseconds of sleeping ** have accumulated. {H12343} After "ms" milliseconds of sleeping, ** the handler returns 0 which causes [sqlite3_step()] to return ** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. ** ** Calling this routine with an argument less than or equal to zero ** turns off all busy handlers. ** ** There can only be a single busy handler for a particular ** [database connection] any any given moment. If another busy handler ** was defined (using [sqlite3_busy_handler()]) prior to calling ** this routine, that other busy handler is cleared. ** ** INVARIANTS: ** ** {H12341} The [sqlite3_busy_timeout()] function shall override any prior ** [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting ** on the same [database connection]. ** ** {H12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than ** or equal to zero, then the busy handler shall be cleared so that ** all subsequent locking events immediately return [SQLITE_BUSY]. ** ** {H12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive ** number N, then a busy handler shall be set that repeatedly calls ** the xSleep() method in the [sqlite3_vfs | VFS interface] until ** either the lock clears or until the cumulative sleep time ** reported back by xSleep() exceeds N milliseconds. */ int sqlite3_busy_timeout(sqlite3*, int ms); /* ** CAPI3REF: Convenience Routines For Running Queries {H12370} ** ** Definition: A <b>result table</b> is memory data structure created by the ** [sqlite3_get_table()] interface. A result table records the ** complete query results from one or more queries. ** ** The table conceptually has a number of rows and columns. But ** these numbers are not part of the result table itself. These |
︙ | ︙ | |||
1614 1615 1616 1617 1618 1619 1620 | ** to any internal data structures of SQLite. It uses only the public ** interface defined here. As a consequence, errors that occur in the ** wrapper layer outside of the internal [sqlite3_exec()] call are not ** reflected in subsequent calls to [sqlite3_errcode()] or [sqlite3_errmsg()]. ** ** INVARIANTS: ** | | | | | | | | | 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 | ** to any internal data structures of SQLite. It uses only the public ** interface defined here. As a consequence, errors that occur in the ** wrapper layer outside of the internal [sqlite3_exec()] call are not ** reflected in subsequent calls to [sqlite3_errcode()] or [sqlite3_errmsg()]. ** ** INVARIANTS: ** ** {H12371} If a [sqlite3_get_table()] fails a memory allocation, then ** it shall free the result table under construction, abort the ** query in process, skip any subsequent queries, set the ** *pazResult output pointer to NULL and return [SQLITE_NOMEM]. ** ** {H12373} If the pnColumn parameter to [sqlite3_get_table()] is not NULL ** then a successful invocation of [sqlite3_get_table()] shall ** write the number of columns in the ** result set of the query into *pnColumn. ** ** {H12374} If the pnRow parameter to [sqlite3_get_table()] is not NULL ** then a successful invocation of [sqlite3_get_table()] shall ** writes the number of rows in the ** result set of the query into *pnRow. ** ** {H12376} A successful invocation of [sqlite3_get_table()] that computes ** N rows of result with C columns per row shall make *pazResult ** point to an array of pointers to (N+1)*C strings where the first ** C strings are column names as obtained from ** [sqlite3_column_name()] and the rest are column result values ** obtained from [sqlite3_column_text()]. ** ** {H12379} The values in the pazResult array returned by [sqlite3_get_table()] ** shall remain valid until cleared by [sqlite3_free_table()]. ** ** {H12382} When an error occurs during evaluation of [sqlite3_get_table()] ** the function shall set *pazResult to NULL, write an error message ** into memory obtained from [sqlite3_malloc()], make ** **pzErrmsg point to that error message, and return a ** appropriate [error code]. */ int sqlite3_get_table( sqlite3 *db, /* An open database */ const char *zSql, /* SQL to be evaluated */ char ***pazResult, /* Results of the query */ int *pnRow, /* Number of result rows written here */ int *pnColumn, /* Number of result columns written here */ char **pzErrmsg /* Error msg written here */ ); void sqlite3_free_table(char **result); /* ** CAPI3REF: Formatted String Printing Functions {H17400} ** ** These routines are workalikes of the "printf()" family of functions ** from the standard C library. ** ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their ** results into memory obtained from [sqlite3_malloc()]. ** The strings returned by these two routines should be |
︙ | ︙ | |||
1749 1750 1751 1752 1753 1754 1755 | ** ** The "%z" formatting option works exactly like "%s" with the ** addition that after the string has been read and copied into ** the result, [sqlite3_free()] is called on the input string. {END} ** ** INVARIANTS: ** | | | | | | 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 | ** ** The "%z" formatting option works exactly like "%s" with the ** addition that after the string has been read and copied into ** the result, [sqlite3_free()] is called on the input string. {END} ** ** INVARIANTS: ** ** {H17403} The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces ** return either pointers to zero-terminated UTF-8 strings held in ** memory obtained from [sqlite3_malloc()] or NULL pointers if ** a call to [sqlite3_malloc()] fails. ** ** {H17406} The [sqlite3_snprintf()] interface writes a zero-terminated ** UTF-8 string into the buffer pointed to by the second parameter ** provided that the first parameter is greater than zero. ** ** {H17407} The [sqlite3_snprintf()] interface does not write slots of ** its output buffer (the second parameter) outside the range ** of 0 through N-1 (where N is the first parameter) ** regardless of the length of the string ** requested by the format specification. */ char *sqlite3_mprintf(const char*,...); char *sqlite3_vmprintf(const char*, va_list); char *sqlite3_snprintf(int,char*,const char*, ...); /* ** CAPI3REF: Memory Allocation Subsystem {H17300} ** ** The SQLite core uses these three routines for all of its own ** internal memory allocation needs. "Core" in the previous sentence ** does not include operating-system specific VFS implementation. The ** Windows VFS uses native malloc() and free() for some operations. ** ** The sqlite3_malloc() routine returns a pointer to a block |
︙ | ︙ | |||
1816 1817 1818 1819 1820 1821 1822 | ** is not freed. ** ** The memory returned by sqlite3_malloc() and sqlite3_realloc() ** is always aligned to at least an 8 byte boundary. {END} ** ** The default implementation of the memory allocation subsystem uses ** the malloc(), realloc() and free() provided by the standard C library. | | | 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 | ** is not freed. ** ** The memory returned by sqlite3_malloc() and sqlite3_realloc() ** is always aligned to at least an 8 byte boundary. {END} ** ** The default implementation of the memory allocation subsystem uses ** the malloc(), realloc() and free() provided by the standard C library. ** {H17382} However, if SQLite is compiled with the ** SQLITE_MEMORY_SIZE=<i>NNN</i> C preprocessor macro (where <i>NNN</i> ** is an integer), then SQLite create a static array of at least ** <i>NNN</i> bytes in size and uses that array for all of its dynamic ** memory allocation needs. {END} Additional memory allocator options ** may be added in future releases. ** ** In SQLite version 3.5.0 and 3.5.1, it was possible to define |
︙ | ︙ | |||
1838 1839 1840 1841 1842 1843 1844 | ** and whatever filename encoding is used by the particular Windows ** installation. Memory allocation errors are detected, but ** they are reported back as [SQLITE_CANTOPEN] or ** [SQLITE_IOERR] rather than [SQLITE_NOMEM]. ** ** INVARIANTS: ** | | | | | | | | | | | | | | | | | | | | | | 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 | ** and whatever filename encoding is used by the particular Windows ** installation. Memory allocation errors are detected, but ** they are reported back as [SQLITE_CANTOPEN] or ** [SQLITE_IOERR] rather than [SQLITE_NOMEM]. ** ** INVARIANTS: ** ** {H17303} The [sqlite3_malloc(N)] interface returns either a pointer to ** a newly checked-out block of at least N bytes of memory ** that is 8-byte aligned, or it returns NULL if it is unable ** to fulfill the request. ** ** {H17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if ** N is less than or equal to zero. ** ** {H17305} The [sqlite3_free(P)] interface releases memory previously ** returned from [sqlite3_malloc()] or [sqlite3_realloc()], ** making it available for reuse. ** ** {H17306} A call to [sqlite3_free(NULL)] is a harmless no-op. ** ** {H17310} A call to [sqlite3_realloc(0,N)] is equivalent to a call ** to [sqlite3_malloc(N)]. ** ** {H17312} A call to [sqlite3_realloc(P,0)] is equivalent to a call ** to [sqlite3_free(P)]. ** ** {H17315} The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()], ** and [sqlite3_free()] for all of its memory allocation and ** deallocation needs. ** ** {H17318} The [sqlite3_realloc(P,N)] interface returns either a pointer ** to a block of checked-out memory of at least N bytes in size ** that is 8-byte aligned, or a NULL pointer. ** ** {H17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first ** copies the first K bytes of content from P into the newly ** allocated block, where K is the lesser of N and the size of ** the buffer P. ** ** {H17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first ** releases the buffer P. ** ** {H17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is ** not modified or released. ** ** ASSUMPTIONS: ** ** {A17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] ** must be either NULL or else pointers obtained from a prior ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have ** not yet been released. ** ** {A17351} The application must not read or write any part of ** a block of memory after it has been released using ** [sqlite3_free()] or [sqlite3_realloc()]. */ void *sqlite3_malloc(int); void *sqlite3_realloc(void*, int); void sqlite3_free(void*); /* ** CAPI3REF: Memory Allocator Statistics {H17370} ** ** SQLite provides these two interfaces for reporting on the status ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] ** routines, which form the built-in memory allocation subsystem. ** ** INVARIANTS: ** ** {H17371} The [sqlite3_memory_used()] routine returns the number of bytes ** of memory currently outstanding (malloced but not freed). ** ** {H17373} The [sqlite3_memory_highwater()] routine returns the maximum ** value of [sqlite3_memory_used()] since the high-water mark ** was last reset. ** ** {H17374} The values returned by [sqlite3_memory_used()] and ** [sqlite3_memory_highwater()] include any overhead ** added by SQLite in its implementation of [sqlite3_malloc()], ** but not overhead added by the any underlying system library ** routines that [sqlite3_malloc()] may call. ** ** {H17375} The memory high-water mark is reset to the current value of ** [sqlite3_memory_used()] if and only if the parameter to ** [sqlite3_memory_highwater()] is true. The value returned ** by [sqlite3_memory_highwater(1)] is the high-water mark ** prior to the reset. */ sqlite3_int64 sqlite3_memory_used(void); sqlite3_int64 sqlite3_memory_highwater(int resetFlag); /* ** CAPI3REF: Pseudo-Random Number Generator {H17390} ** ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to ** select random ROWIDs when inserting new records into a table that ** already uses the largest possible ROWID. The PRNG is also used for ** the build-in random() and randomblob() SQL functions. This interface allows ** applications to access the same PRNG for other purposes. ** ** A call to this routine stores N bytes of randomness into buffer P. ** ** The first time this routine is invoked (either internally or by ** the application) the PRNG is seeded using randomness obtained ** from the xRandomness method of the default [sqlite3_vfs] object. ** On all subsequent invocations, the pseudo-randomness is generated ** internally and without recourse to the [sqlite3_vfs] xRandomness ** method. ** ** INVARIANTS: ** ** {H17392} The [sqlite3_randomness(N,P)] interface writes N bytes of ** high-quality pseudo-randomness into buffer P. */ void sqlite3_randomness(int N, void *P); /* ** CAPI3REF: Compile-Time Authorization Callbacks {H12500} ** ** This routine registers a authorizer callback with a particular ** [database connection], supplied in the first argument. ** The authorizer callback is invoked as SQL statements are being compiled ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various ** points during the compilation process, as logic is being created |
︙ | ︙ | |||
2013 2014 2015 2016 2017 2018 2019 | ** ** Note that the authorizer callback is invoked only during ** [sqlite3_prepare()] or its variants. Authorization is not ** performed during statement evaluation in [sqlite3_step()]. ** ** INVARIANTS: ** | | | | | | | | | | | | | | | | | | | | | 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 | ** ** Note that the authorizer callback is invoked only during ** [sqlite3_prepare()] or its variants. Authorization is not ** performed during statement evaluation in [sqlite3_step()]. ** ** INVARIANTS: ** ** {H12501} The [sqlite3_set_authorizer(D,...)] interface registers a ** authorizer callback with database connection D. ** ** {H12502} The authorizer callback is invoked as SQL statements are ** being compiled. ** ** {H12503} If the authorizer callback returns any value other than ** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY], then ** the [sqlite3_prepare_v2()] or equivalent call that caused ** the authorizer callback to run shall fail with an ** [SQLITE_ERROR] error code and an appropriate error message. ** ** {H12504} When the authorizer callback returns [SQLITE_OK], the operation ** described is processed normally. ** ** {H12505} When the authorizer callback returns [SQLITE_DENY], the ** [sqlite3_prepare_v2()] or equivalent call that caused the ** authorizer callback to run shall fail ** with an [SQLITE_ERROR] error code and an error message ** explaining that access is denied. ** ** {H12506} If the authorizer code (the 2nd parameter to the authorizer ** callback) is [SQLITE_READ] and the authorizer callback returns ** [SQLITE_IGNORE], then the prepared statement is constructed to ** insert a NULL value in place of the table column that would have ** been read if [SQLITE_OK] had been returned. ** ** {H12507} If the authorizer code (the 2nd parameter to the authorizer ** callback) is anything other than [SQLITE_READ], then ** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY]. ** ** {H12510} The first parameter to the authorizer callback is a copy of ** the third parameter to the [sqlite3_set_authorizer()] interface. ** ** {H12511} The second parameter to the callback is an integer ** [SQLITE_COPY | action code] that specifies the particular action ** to be authorized. ** ** {H12512} The third through sixth parameters to the callback are ** zero-terminated strings that contain ** additional details about the action to be authorized. ** ** {H12520} Each call to [sqlite3_set_authorizer()] overrides ** any previously installed authorizer. ** ** {H12521} A NULL authorizer means that no authorization ** callback is invoked. ** ** {H12522} The default authorizer is NULL. */ int sqlite3_set_authorizer( sqlite3*, int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), void *pUserData ); /* ** CAPI3REF: Authorizer Return Codes {H12590} ** ** The [sqlite3_set_authorizer | authorizer callback function] must ** return either [SQLITE_OK] or one of these two constants in order ** to signal SQLite whether or not the action is permitted. See the ** [sqlite3_set_authorizer | authorizer documentation] for additional ** information. */ #define SQLITE_DENY 1 /* Abort the SQL statement with an error */ #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ /* ** CAPI3REF: Authorizer Action Codes {H12550} ** ** The [sqlite3_set_authorizer()] interface registers a callback function ** that is invoked to authorize certain SQL statement actions. The ** second parameter to the callback is an integer code that specifies ** what action is being authorized. These are the integer action codes that ** the authorizer callback may be passed. ** ** These action code values signify what kind of operation is to be ** authorized. The 3rd and 4th parameters to the authorization ** callback function will be parameters or NULL depending on which of these ** codes is used as the second parameter. The 5th parameter to the ** authorizer callback is the name of the database ("main", "temp", ** etc.) if applicable. The 6th parameter to the authorizer callback ** is the name of the inner-most trigger or view that is responsible for ** the access attempt or NULL if this access attempt is directly from ** top-level SQL code. ** ** INVARIANTS: ** ** {H12551} The second parameter to an ** [sqlite3_set_authorizer | authorizer callback] is always an integer ** [SQLITE_COPY | authorizer code] that specifies what action ** is being authorized. ** ** {H12552} The 3rd and 4th parameters to the ** [sqlite3_set_authorizer | authorization callback] ** will be parameters or NULL depending on which ** [SQLITE_COPY | authorizer code] is used as the second parameter. ** ** {H12553} The 5th parameter to the ** [sqlite3_set_authorizer | authorizer callback] is the name ** of the database (example: "main", "temp", etc.) if applicable. ** ** {H12554} The 6th parameter to the ** [sqlite3_set_authorizer | authorizer callback] is the name ** of the inner-most trigger or view that is responsible for ** the access attempt or NULL if this access attempt is directly from ** top-level SQL code. */ /******************************************* 3rd ************ 4th ***********/ #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ |
︙ | ︙ | |||
2157 2158 2159 2160 2161 2162 2163 | #define SQLITE_ANALYZE 28 /* Table Name NULL */ #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ #define SQLITE_FUNCTION 31 /* Function Name NULL */ #define SQLITE_COPY 0 /* No longer used */ /* | | | 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 | #define SQLITE_ANALYZE 28 /* Table Name NULL */ #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ #define SQLITE_FUNCTION 31 /* Function Name NULL */ #define SQLITE_COPY 0 /* No longer used */ /* ** CAPI3REF: Tracing And Profiling Functions {H12280} ** ** These routines register callback functions that can be used for ** tracing and profiling the execution of SQL statements. ** ** The callback function registered by sqlite3_trace() is invoked at ** various times when an SQL statement is being run by [sqlite3_step()]. ** The callback returns a UTF-8 rendering of the SQL statement text |
︙ | ︙ | |||
2184 2185 2186 2187 2188 2189 2190 | ** The trigger reporting feature of the trace callback is considered ** experimental and is subject to change or removal in future releases. ** Future versions of SQLite might also add new trace callback ** invocations. ** ** INVARIANTS: ** | | | | | | | | | | | | | | | | | | | | | 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 | ** The trigger reporting feature of the trace callback is considered ** experimental and is subject to change or removal in future releases. ** Future versions of SQLite might also add new trace callback ** invocations. ** ** INVARIANTS: ** ** {H12281} The callback function registered by [sqlite3_trace()] is ** whenever an SQL statement first begins to execute and ** whenever a trigger subprogram first begins to run. ** ** {H12282} Each call to [sqlite3_trace()] overrides the previously ** registered trace callback. ** ** {H12283} A NULL trace callback disables tracing. ** ** {H12284} The first argument to the trace callback is a copy of ** the pointer which was the 3rd argument to [sqlite3_trace()]. ** ** {H12285} The second argument to the trace callback is a ** zero-terminated UTF-8 string containing the original text ** of the SQL statement as it was passed into [sqlite3_prepare_v2()] ** or the equivalent, or an SQL comment indicating the beginning ** of a trigger subprogram. ** ** {H12287} The callback function registered by [sqlite3_profile()] is invoked ** as each SQL statement finishes. ** ** {H12288} The first parameter to the profile callback is a copy of ** the 3rd parameter to [sqlite3_profile()]. ** ** {H12289} The second parameter to the profile callback is a ** zero-terminated UTF-8 string that contains the complete text of ** the SQL statement as it was processed by [sqlite3_prepare_v2()] ** or the equivalent. ** ** {H12290} The third parameter to the profile callback is an estimate ** of the number of nanoseconds of wall-clock time required to ** run the SQL statement from start to finish. */ void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); void *sqlite3_profile(sqlite3*, void(*xProfile)(void*,const char*,sqlite3_uint64), void*); /* ** CAPI3REF: Query Progress Callbacks {H12910} ** ** This routine configures a callback function - the ** progress callback - that is invoked periodically during long ** running calls to [sqlite3_exec()], [sqlite3_step()] and ** [sqlite3_get_table()]. An example use for this ** interface is to keep a GUI updated during a large query. ** ** If the progress callback returns non-zero, the operation is ** interrupted. This feature can be used to implement a ** "Cancel" button on a GUI dialog box. ** ** INVARIANTS: ** ** {H12911} The callback function registered by sqlite3_progress_handler() ** is invoked periodically during long running calls to ** [sqlite3_step()]. ** ** {H12912} The progress callback is invoked once for every N virtual ** machine opcodes, where N is the second argument to ** the [sqlite3_progress_handler()] call that registered ** the callback. If N is less than 1, sqlite3_progress_handler() ** acts as if a NULL progress handler had been specified. ** ** {H12913} The progress callback itself is identified by the third ** argument to sqlite3_progress_handler(). ** ** {H12914} The fourth argument to sqlite3_progress_handler() is a ** void pointer passed to the progress callback ** function each time it is invoked. ** ** {H12915} If a call to [sqlite3_step()] results in fewer than N opcodes ** being executed, then the progress callback is never invoked. ** ** {H12916} Every call to [sqlite3_progress_handler()] ** overwrites any previously registered progress handler. ** ** {H12917} If the progress handler callback is NULL then no progress ** handler is invoked. ** ** {H12918} If the progress callback returns a result other than 0, then ** the behavior is a if [sqlite3_interrupt()] had been called. */ void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); /* ** CAPI3REF: Opening A New Database Connection {H12700} ** ** These routines open an SQLite database file whose name is given by the ** filename argument. The filename argument is interpreted as UTF-8 for ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte ** order for sqlite3_open16(). A [database connection] handle is usually ** returned in *ppDb, even if an error occurs. The only exception is that ** if SQLite is unable to allocate memory to hold the [sqlite3] object, |
︙ | ︙ | |||
2350 2351 2352 2353 2354 2355 2356 | ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever ** codepage is currently defined. Filenames containing international ** characters must be converted to UTF-8 prior to passing them into ** sqlite3_open() or sqlite3_open_v2(). ** ** INVARIANTS: ** | | | | | | | | | | | | | | | | | | | | | | | | 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 | ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever ** codepage is currently defined. Filenames containing international ** characters must be converted to UTF-8 prior to passing them into ** sqlite3_open() or sqlite3_open_v2(). ** ** INVARIANTS: ** ** {H12701} The [sqlite3_open()], [sqlite3_open16()], and ** [sqlite3_open_v2()] interfaces create a new ** [database connection] associated with ** the database file given in their first parameter. ** ** {H12702} The filename argument is interpreted as UTF-8 ** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16 ** in the native byte order for [sqlite3_open16()]. ** ** {H12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()], ** or [sqlite3_open_v2()] writes a pointer to a new ** [database connection] into *ppDb. ** ** {H12704} The [sqlite3_open()], [sqlite3_open16()], and ** [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success, ** or an appropriate [error code] on failure. ** ** {H12706} The default text encoding for a new database created using ** [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8. ** ** {H12707} The default text encoding for a new database created using ** [sqlite3_open16()] will be UTF-16. ** ** {H12709} The [sqlite3_open(F,D)] interface is equivalent to ** [sqlite3_open_v2(F,D,G,0)] where the G parameter is ** [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE]. ** ** {H12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the ** bit value [SQLITE_OPEN_READONLY] then the database is opened ** for reading only. ** ** {H12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the ** bit value [SQLITE_OPEN_READWRITE] then the database is opened ** reading and writing if possible, or for reading only if the ** file is write protected by the operating system. ** ** {H12713} If the G parameter to [sqlite3_open(v2(F,D,G,V)] omits the ** bit value [SQLITE_OPEN_CREATE] and the database does not ** previously exist, an error is returned. ** ** {H12714} If the G parameter to [sqlite3_open(v2(F,D,G,V)] contains the ** bit value [SQLITE_OPEN_CREATE] and the database does not ** previously exist, then an attempt is made to create and ** initialize the database. ** ** {H12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()], ** or [sqlite3_open_v2()] is ":memory:", then an private, ** ephemeral, in-memory database is created for the connection. ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required ** in sqlite3_open_v2()?</todo> ** ** {H12719} If the filename is NULL or an empty string, then a private, ** ephemeral on-disk database will be created. ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required ** in sqlite3_open_v2()?</todo> ** ** {H12721} The [database connection] created by [sqlite3_open_v2(F,D,G,V)] ** will use the [sqlite3_vfs] object identified by the V parameter, ** or the default [sqlite3_vfs] object if V is a NULL pointer. ** ** {H12723} Two [database connections] will share a common cache if both were ** opened with the same VFS while [shared cache mode] was enabled and ** if both filenames compare equal using memcmp() after having been ** processed by the [sqlite3_vfs | xFullPathname] method of the VFS. */ int sqlite3_open( const char *filename, /* Database filename (UTF-8) */ sqlite3 **ppDb /* OUT: SQLite db handle */ ); int sqlite3_open16( const void *filename, /* Database filename (UTF-16) */ sqlite3 **ppDb /* OUT: SQLite db handle */ ); int sqlite3_open_v2( const char *filename, /* Database filename (UTF-8) */ sqlite3 **ppDb, /* OUT: SQLite db handle */ int flags, /* Flags */ const char *zVfs /* Name of VFS module to use */ ); /* ** CAPI3REF: Error Codes And Messages {H12800} ** ** The sqlite3_errcode() interface returns the numeric [result code] or ** [extended result code] for the most recent failed sqlite3_* API call ** associated with a [database connection]. If a prior API call failed ** but the most recent API call succeeded, the return value from ** sqlite3_errcode() is undefined. ** ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language ** text that describes the error, as either UTF-8 or UTF-16 respectively. ** Memory to hold the error message string is managed internally. ** The application does not need to worry about freeing the result. ** However, the error string might be overwritten or deallocated by ** subsequent calls to other SQLite interface functions. ** ** If an interface fails with SQLITE_MISUSE, that means the interface ** was invoked incorrectly by the application. In that case, the ** error code and message may or may not be set. ** ** INVARIANTS: ** ** {H12801} The [sqlite3_errcode(D)] interface returns the numeric ** [result code] or [extended result code] for the most recently ** failed interface call associated with the [database connection] D. ** ** {H12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)] ** interfaces return English-language text that describes ** the error in the mostly recently failed interface call, ** encoded as either UTF-8 or UTF-16 respectively. ** ** {H12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()] ** are valid until the next SQLite interface call. ** ** {H12808} Calls to API routines that do not return an error code ** (example: [sqlite3_data_count()]) do not ** change the error code or message returned by ** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()]. ** ** {H12809} Interfaces that are not associated with a specific ** [database connection] (examples: ** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()] ** do not change the values returned by ** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()]. */ int sqlite3_errcode(sqlite3 *db); const char *sqlite3_errmsg(sqlite3*); const void *sqlite3_errmsg16(sqlite3*); /* ** CAPI3REF: SQL Statement Object {H13000} ** KEYWORDS: {prepared statement} {prepared statements} ** ** An instance of this object represents a single SQL statement. ** This object is variously known as a "prepared statement" or a ** "compiled SQL statement" or simply as a "statement". ** ** The life of a statement object goes something like this: |
︙ | ︙ | |||
2506 2507 2508 2509 2510 2511 2512 | ** ** Refer to documentation on individual methods above for additional ** information. */ typedef struct sqlite3_stmt sqlite3_stmt; /* | | | 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 | ** ** Refer to documentation on individual methods above for additional ** information. */ typedef struct sqlite3_stmt sqlite3_stmt; /* ** CAPI3REF: Run-time Limits {H12760} ** ** This interface allows the size of various constructs to be limited ** on a connection by connection basis. The first parameter is the ** [database connection] whose limit is to be set or queried. The ** second parameter is one of the [limit categories] that define a ** class of constructs to be size limited. The third parameter is the ** new limit for that construct. The function returns the old limit. |
︙ | ︙ | |||
2539 2540 2541 2542 2543 2544 2545 | ** created by an untrusted script can be contained using the ** [max_page_count] [PRAGMA]. ** ** New run-time limit categories may be added in future releases. ** ** INVARIANTS: ** | | | | | | 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 | ** created by an untrusted script can be contained using the ** [max_page_count] [PRAGMA]. ** ** New run-time limit categories may be added in future releases. ** ** INVARIANTS: ** ** {H12762} A successful call to [sqlite3_limit(D,C,V)] where V is ** positive changes the limit on the size of construct C in the ** [database connection] D to the lesser of V and the hard upper ** bound on the size of C that is set at compile-time. ** ** {H12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative ** leaves the state of the [database connection] D unchanged. ** ** {H12769} A successful call to [sqlite3_limit(D,C,V)] returns the ** value of the limit on the size of construct C in the ** [database connection] D as it was prior to the call. */ int sqlite3_limit(sqlite3*, int id, int newVal); /* ** CAPI3REF: Run-Time Limit Categories {H12790} ** KEYWORDS: {limit category} {limit categories} ** ** These constants define various aspects of a [database connection] ** that can be limited in size by calls to [sqlite3_limit()]. ** The meanings of the various limits are as follows: ** ** <dl> |
︙ | ︙ | |||
2610 2611 2612 2613 2614 2615 2616 | #define SQLITE_LIMIT_VDBE_OP 5 #define SQLITE_LIMIT_FUNCTION_ARG 6 #define SQLITE_LIMIT_ATTACHED 7 #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8 #define SQLITE_LIMIT_VARIABLE_NUMBER 9 /* | | | 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 | #define SQLITE_LIMIT_VDBE_OP 5 #define SQLITE_LIMIT_FUNCTION_ARG 6 #define SQLITE_LIMIT_ATTACHED 7 #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8 #define SQLITE_LIMIT_VARIABLE_NUMBER 9 /* ** CAPI3REF: Compiling An SQL Statement {H13010} ** KEYWORDS: {SQL statement compiler} ** ** To execute an SQL query, it must first be compiled into a byte-code ** program using one of these routines. ** ** The first argument, "db", is a [database connection] obtained from a ** prior call to [sqlite3_open()], [sqlite3_open_v2()] or [sqlite3_open16()]. |
︙ | ︙ | |||
2680 2681 2682 2683 2684 2685 2686 | ** to find the underlying cause of the problem. With the "v2" prepare ** interfaces, the underlying reason for the error is returned immediately. ** </li> ** </ol> ** ** INVARIANTS: ** | | | | | | | | | | 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 | ** to find the underlying cause of the problem. With the "v2" prepare ** interfaces, the underlying reason for the error is returned immediately. ** </li> ** </ol> ** ** INVARIANTS: ** ** {H13011} The [sqlite3_prepare(db,zSql,...)] and ** [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the ** text in their zSql parameter as UTF-8. ** ** {H13012} The [sqlite3_prepare16(db,zSql,...)] and ** [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the ** text in their zSql parameter as UTF-16 in the native byte order. ** ** {H13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] ** and its variants is less than zero, the SQL text is ** read from zSql is read up to the first zero terminator. ** ** {H13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] ** and its variants is non-negative, then at most nBytes bytes of ** SQL text is read from zSql. ** ** {H13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants ** if the zSql input text contains more than one SQL statement ** and pzTail is not NULL, then *pzTail is made to point to the ** first byte past the end of the first SQL statement in zSql. ** <todo>What does *pzTail point to if there is one statement?</todo> ** ** {H13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)] ** or one of its variants writes into *ppStmt a pointer to a new ** [prepared statement] or a pointer to NULL if zSql contains ** nothing other than whitespace or comments. ** ** {H13019} The [sqlite3_prepare_v2()] interface and its variants return ** [SQLITE_OK] or an appropriate [error code] upon failure. ** ** {H13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its ** variants returns an error (any value other than [SQLITE_OK]), ** they first set *ppStmt to NULL. */ int sqlite3_prepare( sqlite3 *db, /* Database handle */ const char *zSql, /* SQL statement, UTF-8 encoded */ int nByte, /* Maximum length of zSql in bytes. */ |
︙ | ︙ | |||
2744 2745 2746 2747 2748 2749 2750 | const void *zSql, /* SQL statement, UTF-16 encoded */ int nByte, /* Maximum length of zSql in bytes. */ sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const void **pzTail /* OUT: Pointer to unused portion of zSql */ ); /* | | | | | | | 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 | const void *zSql, /* SQL statement, UTF-16 encoded */ int nByte, /* Maximum length of zSql in bytes. */ sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const void **pzTail /* OUT: Pointer to unused portion of zSql */ ); /* ** CAPIREF: Retrieving Statement SQL {H13100} ** ** This interface can be used to retrieve a saved copy of the original ** SQL text used to create a [prepared statement] if that statement was ** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. ** ** INVARIANTS: ** ** {H13101} If the [prepared statement] passed as the argument to ** [sqlite3_sql()] was compiled using either [sqlite3_prepare_v2()] or ** [sqlite3_prepare16_v2()], then [sqlite3_sql()] returns ** a pointer to a zero-terminated string containing a UTF-8 rendering ** of the original SQL statement. ** ** {H13102} If the [prepared statement] passed as the argument to ** [sqlite3_sql()] was compiled using either [sqlite3_prepare()] or ** [sqlite3_prepare16()], then [sqlite3_sql()] returns a NULL pointer. ** ** {H13103} The string returned by [sqlite3_sql(S)] is valid until the ** [prepared statement] S is deleted using [sqlite3_finalize(S)]. */ const char *sqlite3_sql(sqlite3_stmt *pStmt); /* ** CAPI3REF: Dynamically Typed Value Object {H15000} ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} ** ** SQLite uses the sqlite3_value object to represent all values ** that can be stored in a database table. SQLite uses dynamic typing ** for the values it stores. Values stored in sqlite3_value objects ** can be integers, floating point values, strings, BLOBs, or NULL. ** |
︙ | ︙ | |||
2807 2808 2809 2810 2811 2812 2813 | ** [sqlite3_result_value()] and [sqlite3_bind_value()]. ** The [sqlite3_value_blob | sqlite3_value_type()] family of ** interfaces require protected sqlite3_value objects. */ typedef struct Mem sqlite3_value; /* | | | | 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 | ** [sqlite3_result_value()] and [sqlite3_bind_value()]. ** The [sqlite3_value_blob | sqlite3_value_type()] family of ** interfaces require protected sqlite3_value objects. */ typedef struct Mem sqlite3_value; /* ** CAPI3REF: SQL Function Context Object {H16001} ** ** The context in which an SQL function executes is stored in an ** sqlite3_context object. A pointer to an sqlite3_context object ** is always first parameter to [application-defined SQL functions]. ** The application-defined SQL function implementation will pass this ** pointer through into calls to [sqlite3_result_int | sqlite3_result()], ** [sqlite3_aggregate_context()], [sqlite3_user_data()], ** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()], ** and/or [sqlite3_set_auxdata()]. */ typedef struct sqlite3_context sqlite3_context; /* ** CAPI3REF: Binding Values To Prepared Statements {H13500} ** KEYWORDS: {host parameter} {host parameters} {host parameter name} ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding} ** ** In the SQL strings input to [sqlite3_prepare_v2()] and its variants, ** literals may be replaced by a parameter in one of these forms: ** ** <ul> |
︙ | ︙ | |||
2901 2902 2903 2904 2905 2906 2907 | ** panic rather than return SQLITE_MISUSE. ** ** See also: [sqlite3_bind_parameter_count()], ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** | | | | | | | | | | | | | | | | | | | | | 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 | ** panic rather than return SQLITE_MISUSE. ** ** See also: [sqlite3_bind_parameter_count()], ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** ** {H13506} The [SQL statement compiler] recognizes tokens of the forms ** "?", "?NNN", "$VVV", ":VVV", and "@VVV" as SQL parameters, ** where NNN is any sequence of one or more digits ** and where VVV is any sequence of one or more alphanumeric ** characters or "::" optionally followed by a string containing ** no spaces and contained within parentheses. ** ** {H13509} The initial value of an SQL parameter is NULL. ** ** {H13512} The index of an "?" SQL parameter is one larger than the ** largest index of SQL parameter to the left, or 1 if ** the "?" is the leftmost SQL parameter. ** ** {H13515} The index of an "?NNN" SQL parameter is the integer NNN. ** ** {H13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is ** the same as the index of leftmost occurrences of the same ** parameter, or one more than the largest index over all ** parameters to the left if this is the first occurrence ** of this parameter, or 1 if this is the leftmost parameter. ** ** {H13521} The [SQL statement compiler] fails with an [SQLITE_RANGE] ** error if the index of an SQL parameter is less than 1 ** or greater than the compile-time SQLITE_MAX_VARIABLE_NUMBER ** parameter. ** ** {H13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)] ** associate the value V with all SQL parameters having an ** index of N in the [prepared statement] S. ** ** {H13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)] ** override prior calls with the same values of S and N. ** ** {H13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)] ** persist across calls to [sqlite3_reset(S)]. ** ** {H13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L ** bytes of the BLOB or string pointed to by V, when L ** is non-negative. ** ** {H13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters ** from V through the first zero character when L is negative. ** ** {H13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special ** constant [SQLITE_STATIC], SQLite assumes that the value V ** is held in static unmanaged space that will not change ** during the lifetime of the binding. ** ** {H13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special ** constant [SQLITE_TRANSIENT], the routine makes a ** private copy of the value V before it returns. ** ** {H13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to ** a function, SQLite invokes that function to destroy the ** value V after it has finished using the value V. ** ** {H13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound ** is a BLOB of L bytes, or a zero-length BLOB if L is negative. ** ** {H13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may ** be either a [protected sqlite3_value] object or an ** [unprotected sqlite3_value] object. */ int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); int sqlite3_bind_double(sqlite3_stmt*, int, double); int sqlite3_bind_int(sqlite3_stmt*, int, int); int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); int sqlite3_bind_null(sqlite3_stmt*, int); int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); /* ** CAPI3REF: Number Of SQL Parameters {H13600} ** ** This routine can be used to find the number of [SQL parameters] ** in a [prepared statement]. SQL parameters are tokens of the ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as ** placeholders for values that are [sqlite3_bind_blob | bound] ** to the parameters at a later time. ** ** This routine actually returns the index of the largest (rightmost) ** parameter. For all forms except ?NNN, this will correspond to the ** number of unique parameters. If parameters of the ?NNN are used, ** there may be gaps in the list. ** ** See also: [sqlite3_bind_blob|sqlite3_bind()], ** [sqlite3_bind_parameter_name()], and ** [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** ** {H13601} The [sqlite3_bind_parameter_count(S)] interface returns ** the largest index of all SQL parameters in the ** [prepared statement] S, or 0 if S contains no SQL parameters. */ int sqlite3_bind_parameter_count(sqlite3_stmt*); /* ** CAPI3REF: Name Of A Host Parameter {H13620} ** ** This routine returns a pointer to the name of the n-th ** [SQL parameter] in a [prepared statement]. ** SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" ** respectively. ** In other words, the initial ":" or "$" or "@" or "?" |
︙ | ︙ | |||
3036 3037 3038 3039 3040 3041 3042 | ** ** See also: [sqlite3_bind_blob|sqlite3_bind()], ** [sqlite3_bind_parameter_count()], and ** [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** | | | | | | | | | | 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 | ** ** See also: [sqlite3_bind_blob|sqlite3_bind()], ** [sqlite3_bind_parameter_count()], and ** [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** ** {H13621} The [sqlite3_bind_parameter_name(S,N)] interface returns ** a UTF-8 rendering of the name of the SQL parameter in ** the [prepared statement] S having index N, or ** NULL if there is no SQL parameter with index N or if the ** parameter with index N is an anonymous parameter "?". */ const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); /* ** CAPI3REF: Index Of A Parameter With A Given Name {H13640} ** ** Return the index of an SQL parameter given its name. The ** index value returned is suitable for use as the second ** parameter to [sqlite3_bind_blob|sqlite3_bind()]. A zero ** is returned if no matching parameter is found. The parameter ** name must be given in UTF-8 even if the original statement ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()]. ** ** See also: [sqlite3_bind_blob|sqlite3_bind()], ** [sqlite3_bind_parameter_count()], and ** [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** ** {H13641} The [sqlite3_bind_parameter_index(S,N)] interface returns ** the index of SQL parameter in the [prepared statement] ** S whose name matches the UTF-8 string N, or 0 if there is ** no match. */ int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); /* ** CAPI3REF: Reset All Bindings On A Prepared Statement {H13660} ** ** Contrary to the intuition of many, [sqlite3_reset()] does not reset ** the [sqlite3_bind_blob | bindings] on a [prepared statement]. ** Use this routine to reset all host parameters to NULL. ** ** INVARIANTS: ** ** {H13661} The [sqlite3_clear_bindings(S)] interface resets all SQL ** parameter bindings in the [prepared statement] S back to NULL. */ int sqlite3_clear_bindings(sqlite3_stmt*); /* ** CAPI3REF: Number Of Columns In A Result Set {H13710} ** ** Return the number of columns in the result set returned by the ** [prepared statement]. This routine returns 0 if pStmt is an SQL ** statement that does not return data (for example an [UPDATE]). ** ** INVARIANTS: ** ** {H13711} The [sqlite3_column_count(S)] interface returns the number of ** columns in the result set generated by the [prepared statement] S, ** or 0 if S does not generate a result set. */ int sqlite3_column_count(sqlite3_stmt *pStmt); /* ** CAPI3REF: Column Names In A Result Set {H13720} ** ** These routines return the name assigned to a particular column ** in the result set of a [SELECT] statement. The sqlite3_column_name() ** interface returns a pointer to a zero-terminated UTF-8 string ** and sqlite3_column_name16() returns a pointer to a zero-terminated ** UTF-16 string. The first parameter is the [prepared statement] ** that implements the [SELECT] statement. The second parameter is the |
︙ | ︙ | |||
3122 3123 3124 3125 3126 3127 3128 | ** The name of a result column is the value of the "AS" clause for ** that column, if there is an AS clause. If there is no AS clause ** then the name of the column is unspecified and may change from ** one release of SQLite to the next. ** ** INVARIANTS: ** | | | | | | | | | 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 | ** The name of a result column is the value of the "AS" clause for ** that column, if there is an AS clause. If there is no AS clause ** then the name of the column is unspecified and may change from ** one release of SQLite to the next. ** ** INVARIANTS: ** ** {H13721} A successful invocation of the [sqlite3_column_name(S,N)] ** interface returns the name of the Nth column (where 0 is ** the leftmost column) for the result set of the ** [prepared statement] S as a zero-terminated UTF-8 string. ** ** {H13723} A successful invocation of the [sqlite3_column_name16(S,N)] ** interface returns the name of the Nth column (where 0 is ** the leftmost column) for the result set of the ** [prepared statement] S as a zero-terminated UTF-16 string ** in the native byte order. ** ** {H13724} The [sqlite3_column_name()] and [sqlite3_column_name16()] ** interfaces return a NULL pointer if they are unable to ** allocate memory to hold their normal return strings. ** ** {H13725} If the N parameter to [sqlite3_column_name(S,N)] or ** [sqlite3_column_name16(S,N)] is out of range, then the ** interfaces return a NULL pointer. ** ** {H13726} The strings returned by [sqlite3_column_name(S,N)] and ** [sqlite3_column_name16(S,N)] are valid until the next ** call to either routine with the same S and N parameters ** or until [sqlite3_finalize(S)] is called. ** ** {H13727} When a result column of a [SELECT] statement contains ** an AS clause, the name of that column is the identifier ** to the right of the AS keyword. */ const char *sqlite3_column_name(sqlite3_stmt*, int N); const void *sqlite3_column_name16(sqlite3_stmt*, int N); /* ** CAPI3REF: Source Of Data In A Query Result {H13740} ** ** These routines provide a means to determine what column of what ** table in which database a result of a [SELECT] statement comes from. ** The name of the database or table or column can be returned as ** either a UTF-8 or UTF-16 string. The _database_ routines return ** the database name, the _table_ routines return the table name, and ** the origin_ routines return the column name. |
︙ | ︙ | |||
3192 3193 3194 3195 3196 3197 3198 | ** {A13751} ** If two or more threads call one or more of these routines against the same ** prepared statement and column at the same time then the results are ** undefined. ** ** INVARIANTS: ** | | | | | | | | | | | 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 | ** {A13751} ** If two or more threads call one or more of these routines against the same ** prepared statement and column at the same time then the results are ** undefined. ** ** INVARIANTS: ** ** {H13741} The [sqlite3_column_database_name(S,N)] interface returns either ** the UTF-8 zero-terminated name of the database from which the ** Nth result column of the [prepared statement] S is extracted, ** or NULL if the Nth column of S is a general expression ** or if unable to allocate memory to store the name. ** ** {H13742} The [sqlite3_column_database_name16(S,N)] interface returns either ** the UTF-16 native byte order zero-terminated name of the database ** from which the Nth result column of the [prepared statement] S is ** extracted, or NULL if the Nth column of S is a general expression ** or if unable to allocate memory to store the name. ** ** {H13743} The [sqlite3_column_table_name(S,N)] interface returns either ** the UTF-8 zero-terminated name of the table from which the ** Nth result column of the [prepared statement] S is extracted, ** or NULL if the Nth column of S is a general expression ** or if unable to allocate memory to store the name. ** ** {H13744} The [sqlite3_column_table_name16(S,N)] interface returns either ** the UTF-16 native byte order zero-terminated name of the table ** from which the Nth result column of the [prepared statement] S is ** extracted, or NULL if the Nth column of S is a general expression ** or if unable to allocate memory to store the name. ** ** {H13745} The [sqlite3_column_origin_name(S,N)] interface returns either ** the UTF-8 zero-terminated name of the table column from which the ** Nth result column of the [prepared statement] S is extracted, ** or NULL if the Nth column of S is a general expression ** or if unable to allocate memory to store the name. ** ** {H13746} The [sqlite3_column_origin_name16(S,N)] interface returns either ** the UTF-16 native byte order zero-terminated name of the table ** column from which the Nth result column of the ** [prepared statement] S is extracted, or NULL if the Nth column ** of S is a general expression or if unable to allocate memory ** to store the name. ** ** {H13748} The return values from ** [sqlite3_column_database_name | column metadata interfaces] ** are valid for the lifetime of the [prepared statement] ** or until the encoding is changed by another metadata ** interface call for the same prepared statement and column. ** ** ASSUMPTIONS: ** ** {A13751} If two or more threads call one or more ** [sqlite3_column_database_name | column metadata interfaces] ** for the same [prepared statement] and result column ** at the same time then the results are undefined. */ const char *sqlite3_column_database_name(sqlite3_stmt*,int); const void *sqlite3_column_database_name16(sqlite3_stmt*,int); const char *sqlite3_column_table_name(sqlite3_stmt*,int); const void *sqlite3_column_table_name16(sqlite3_stmt*,int); const char *sqlite3_column_origin_name(sqlite3_stmt*,int); const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); /* ** CAPI3REF: Declared Datatype Of A Query Result {H13760} ** ** The first parameter is a [prepared statement]. ** If this statement is a [SELECT] statement and the Nth column of the ** returned result set of that [SELECT] is a table column (not an ** expression or subquery) then the declared type of the table ** column is returned. If the Nth column of the result set is an ** expression or subquery, then a NULL pointer is returned. |
︙ | ︙ | |||
3280 3281 3282 3283 3284 3285 3286 | ** data stored in that column is of the declared type. SQLite is ** strongly typed, but the typing is dynamic not static. Type ** is associated with individual values, not with the containers ** used to hold those values. ** ** INVARIANTS: ** | | | | | | 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 | ** data stored in that column is of the declared type. SQLite is ** strongly typed, but the typing is dynamic not static. Type ** is associated with individual values, not with the containers ** used to hold those values. ** ** INVARIANTS: ** ** {H13761} A successful call to [sqlite3_column_decltype(S,N)] returns a ** zero-terminated UTF-8 string containing the declared datatype ** of the table column that appears as the Nth column (numbered ** from 0) of the result set to the [prepared statement] S. ** ** {H13762} A successful call to [sqlite3_column_decltype16(S,N)] ** returns a zero-terminated UTF-16 native byte order string ** containing the declared datatype of the table column that appears ** as the Nth column (numbered from 0) of the result set to the ** [prepared statement] S. ** ** {H13763} If N is less than 0 or N is greater than or equal to ** the number of columns in the [prepared statement] S, ** or if the Nth column of S is an expression or subquery rather ** than a table column, or if a memory allocation failure ** occurs during encoding conversions, then ** calls to [sqlite3_column_decltype(S,N)] or ** [sqlite3_column_decltype16(S,N)] return NULL. */ const char *sqlite3_column_decltype(sqlite3_stmt*,int); const void *sqlite3_column_decltype16(sqlite3_stmt*,int); /* ** CAPI3REF: Evaluate An SQL Statement {H13200} ** ** After a [prepared statement] has been prepared using either ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function ** must be called one or more times to evaluate the statement. ** ** The details of the behavior of the sqlite3_step() interface depend |
︙ | ︙ | |||
3369 3370 3371 3372 3373 3374 3375 | ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces, ** then the more specific [error codes] are returned directly ** by sqlite3_step(). The use of the "v2" interface is recommended. ** ** INVARIANTS: ** | | | | | | | | | | | | 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 | ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces, ** then the more specific [error codes] are returned directly ** by sqlite3_step(). The use of the "v2" interface is recommended. ** ** INVARIANTS: ** ** {H13202} If the [prepared statement] S is ready to be run, then ** [sqlite3_step(S)] advances that prepared statement until ** completion or until it is ready to return another row of the ** result set, or until an [sqlite3_interrupt | interrupt] ** or a run-time error occurs. ** ** {H15304} When a call to [sqlite3_step(S)] causes the [prepared statement] ** S to run to completion, the function returns [SQLITE_DONE]. ** ** {H15306} When a call to [sqlite3_step(S)] stops because it is ready to ** return another row of the result set, it returns [SQLITE_ROW]. ** ** {H15308} If a call to [sqlite3_step(S)] encounters an ** [sqlite3_interrupt | interrupt] or a run-time error, ** it returns an appropriate error code that is not one of ** [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE]. ** ** {H15310} If an [sqlite3_interrupt | interrupt] or a run-time error ** occurs during a call to [sqlite3_step(S)] ** for a [prepared statement] S created using ** legacy interfaces [sqlite3_prepare()] or ** [sqlite3_prepare16()], then the function returns either ** [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE]. */ int sqlite3_step(sqlite3_stmt*); /* ** CAPI3REF: Number of columns in a result set {H13770} ** ** Returns the number of values in the current row of the result set. ** ** INVARIANTS: ** ** {H13771} After a call to [sqlite3_step(S)] that returns [SQLITE_ROW], ** the [sqlite3_data_count(S)] routine will return the same value ** as the [sqlite3_column_count(S)] function. ** ** {H13772} After [sqlite3_step(S)] has returned any value other than ** [SQLITE_ROW] or before [sqlite3_step(S)] has been called on the ** [prepared statement] for the first time since it was ** [sqlite3_prepare | prepared] or [sqlite3_reset | reset], ** the [sqlite3_data_count(S)] routine returns zero. */ int sqlite3_data_count(sqlite3_stmt *pStmt); /* ** CAPI3REF: Fundamental Datatypes {H10265} ** KEYWORDS: SQLITE_TEXT ** ** {H10266} Every value in SQLite has one of five fundamental datatypes: ** ** <ul> ** <li> 64-bit signed integer ** <li> 64-bit IEEE floating point number ** <li> string ** <li> BLOB ** <li> NULL |
︙ | ︙ | |||
3447 3448 3449 3450 3451 3452 3453 | # undef SQLITE_TEXT #else # define SQLITE_TEXT 3 #endif #define SQLITE3_TEXT 3 /* | | | 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 | # undef SQLITE_TEXT #else # define SQLITE_TEXT 3 #endif #define SQLITE3_TEXT 3 /* ** CAPI3REF: Result Values From A Query {H13800} ** KEYWORDS: {column access functions} ** ** These routines form the "result set query" interface. ** ** These routines return information about a single column of the current ** result row of a query. In every case the first argument is a pointer ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*] |
︙ | ︙ | |||
3600 3601 3602 3603 3604 3605 3606 | ** of these routines, a default value is returned. The default value ** is either the integer 0, the floating point number 0.0, or a NULL ** pointer. Subsequent calls to [sqlite3_errcode()] will return ** [SQLITE_NOMEM]. ** ** INVARIANTS: ** | | | | | | | | | | | | | | | | | | | | | 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 | ** of these routines, a default value is returned. The default value ** is either the integer 0, the floating point number 0.0, or a NULL ** pointer. Subsequent calls to [sqlite3_errcode()] will return ** [SQLITE_NOMEM]. ** ** INVARIANTS: ** ** {H13803} The [sqlite3_column_blob(S,N)] interface converts the ** Nth column in the current row of the result set for ** the [prepared statement] S into a BLOB and then returns a ** pointer to the converted value. ** ** {H13806} The [sqlite3_column_bytes(S,N)] interface returns the ** number of bytes in the BLOB or string (exclusive of the ** zero terminator on the string) that was returned by the ** most recent call to [sqlite3_column_blob(S,N)] or ** [sqlite3_column_text(S,N)]. ** ** {H13809} The [sqlite3_column_bytes16(S,N)] interface returns the ** number of bytes in the string (exclusive of the ** zero terminator on the string) that was returned by the ** most recent call to [sqlite3_column_text16(S,N)]. ** ** {H13812} The [sqlite3_column_double(S,N)] interface converts the ** Nth column in the current row of the result set for the ** [prepared statement] S into a floating point value and ** returns a copy of that value. ** ** {H13815} The [sqlite3_column_int(S,N)] interface converts the ** Nth column in the current row of the result set for the ** [prepared statement] S into a 64-bit signed integer and ** returns the lower 32 bits of that integer. ** ** {H13818} The [sqlite3_column_int64(S,N)] interface converts the ** Nth column in the current row of the result set for the ** [prepared statement] S into a 64-bit signed integer and ** returns a copy of that integer. ** ** {H13821} The [sqlite3_column_text(S,N)] interface converts the ** Nth column in the current row of the result set for ** the [prepared statement] S into a zero-terminated UTF-8 ** string and returns a pointer to that string. ** ** {H13824} The [sqlite3_column_text16(S,N)] interface converts the ** Nth column in the current row of the result set for the ** [prepared statement] S into a zero-terminated 2-byte ** aligned UTF-16 native byte order string and returns ** a pointer to that string. ** ** {H13827} The [sqlite3_column_type(S,N)] interface returns ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT], ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for ** the Nth column in the current row of the result set for ** the [prepared statement] S. ** ** {H13830} The [sqlite3_column_value(S,N)] interface returns a ** pointer to an [unprotected sqlite3_value] object for the ** Nth column in the current row of the result set for ** the [prepared statement] S. */ const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); int sqlite3_column_bytes(sqlite3_stmt*, int iCol); int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); double sqlite3_column_double(sqlite3_stmt*, int iCol); int sqlite3_column_int(sqlite3_stmt*, int iCol); sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); int sqlite3_column_type(sqlite3_stmt*, int iCol); sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); /* ** CAPI3REF: Destroy A Prepared Statement Object {H13300} ** ** The sqlite3_finalize() function is called to delete a [prepared statement]. ** If the statement was executed successfully or not executed at all, then ** SQLITE_OK is returned. If execution of the statement failed then an ** [error code] or [extended error code] is returned. ** ** This routine can be called at any point during the execution of the ** [prepared statement]. If the virtual machine has not ** completed execution when this routine is called, that is like ** encountering an error or an [sqlite3_interrupt | interrupt]. ** Incomplete updates may be rolled back and transactions canceled, ** depending on the circumstances, and the ** [error code] returned will be [SQLITE_ABORT]. ** ** INVARIANTS: ** ** {H11302} The [sqlite3_finalize(S)] interface destroys the ** [prepared statement] S and releases all ** memory and file resources held by that object. ** ** {H11304} If the most recent call to [sqlite3_step(S)] for the ** [prepared statement] S returned an error, ** then [sqlite3_finalize(S)] returns that same error. */ int sqlite3_finalize(sqlite3_stmt *pStmt); /* ** CAPI3REF: Reset A Prepared Statement Object {H13330} ** ** The sqlite3_reset() function is called to reset a [prepared statement] ** object back to its initial state, ready to be re-executed. ** Any SQL statement variables that had values bound to them using ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. ** Use [sqlite3_clear_bindings()] to reset the bindings. ** ** {H11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S ** back to the beginning of its program. ** ** {H11334} If the most recent call to [sqlite3_step(S)] for the ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE], ** or if [sqlite3_step(S)] has never before been called on S, ** then [sqlite3_reset(S)] returns [SQLITE_OK]. ** ** {H11336} If the most recent call to [sqlite3_step(S)] for the ** [prepared statement] S indicated an error, then ** [sqlite3_reset(S)] returns an appropriate [error code]. ** ** {H11338} The [sqlite3_reset(S)] interface does not change the values ** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S. */ int sqlite3_reset(sqlite3_stmt *pStmt); /* ** CAPI3REF: Create Or Redefine SQL Functions {H16100} ** KEYWORDS: {function creation routines} ** KEYWORDS: {application-defined SQL function} ** KEYWORDS: {application-defined SQL functions} ** ** These two functions (collectively known as "function creation routines") ** are used to add SQL functions or aggregates or to redefine the behavior ** of existing SQL functions or aggregates. The only difference between the |
︙ | ︙ | |||
3777 3778 3779 3780 3781 3782 3783 | ** functions with the same name but with either differing numbers of ** arguments or differing preferred text encodings. SQLite will use ** the implementation most closely matches the way in which the ** SQL function is used. ** ** INVARIANTS: ** | | | | | | | | | | | | | | | 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 | ** functions with the same name but with either differing numbers of ** arguments or differing preferred text encodings. SQLite will use ** the implementation most closely matches the way in which the ** SQL function is used. ** ** INVARIANTS: ** ** {H16103} The [sqlite3_create_function16()] interface behaves exactly ** like [sqlite3_create_function()] in every way except that it ** interprets the zFunctionName argument as zero-terminated UTF-16 ** native byte order instead of as zero-terminated UTF-8. ** ** {H16106} A successful invocation of ** the [sqlite3_create_function(D,X,N,E,...)] interface registers ** or replaces callback functions in the [database connection] D ** used to implement the SQL function named X with N parameters ** and having a preferred text encoding of E. ** ** {H16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)] ** replaces the P, F, S, and L values from any prior calls with ** the same D, X, N, and E values. ** ** {H16112} The [sqlite3_create_function(D,X,...)] interface fails with ** a return code of [SQLITE_ERROR] if the SQL function name X is ** longer than 255 bytes exclusive of the zero terminator. ** ** {H16118} Either F must be NULL and S and L are non-NULL or else F ** is non-NULL and S and L are NULL, otherwise ** [sqlite3_create_function(D,X,N,E,P,F,S,L)] returns [SQLITE_ERROR]. ** ** {H16121} The [sqlite3_create_function(D,...)] interface fails with an ** error code of [SQLITE_BUSY] if there exist [prepared statements] ** associated with the [database connection] D. ** ** {H16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an ** error code of [SQLITE_ERROR] if parameter N (specifying the number ** of arguments to the SQL function being registered) is less ** than -1 or greater than 127. ** ** {H16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)] ** interface causes callbacks to be invoked for the SQL function ** named X when the number of arguments to the SQL function is ** exactly N. ** ** {H16130} When N is -1, the [sqlite3_create_function(D,X,N,...)] ** interface causes callbacks to be invoked for the SQL function ** named X with any number of arguments. ** ** {H16133} When calls to [sqlite3_create_function(D,X,N,...)] ** specify multiple implementations of the same function X ** and when one implementation has N>=0 and the other has N=(-1) ** the implementation with a non-zero N is preferred. ** ** {H16136} When calls to [sqlite3_create_function(D,X,N,E,...)] ** specify multiple implementations of the same function X with ** the same number of arguments N but with different ** encodings E, then the implementation where E matches the ** database encoding is preferred. ** ** {H16139} For an aggregate SQL function created using ** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finalizer ** function L will always be invoked exactly once if the ** step function S is called one or more times. ** ** {H16142} When SQLite invokes either the xFunc or xStep function of ** an application-defined SQL function or aggregate created ** by [sqlite3_create_function()] or [sqlite3_create_function16()], ** then the array of [sqlite3_value] objects passed as the ** third parameter are always [protected sqlite3_value] objects. */ int sqlite3_create_function( sqlite3 *db, |
︙ | ︙ | |||
3862 3863 3864 3865 3866 3867 3868 | void *pApp, void (*xFunc)(sqlite3_context*,int,sqlite3_value**), void (*xStep)(sqlite3_context*,int,sqlite3_value**), void (*xFinal)(sqlite3_context*) ); /* | | | 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 | void *pApp, void (*xFunc)(sqlite3_context*,int,sqlite3_value**), void (*xStep)(sqlite3_context*,int,sqlite3_value**), void (*xFinal)(sqlite3_context*) ); /* ** CAPI3REF: Text Encodings {H10267} ** ** These constant define integer codes that represent the various ** text encodings supported by SQLite. */ #define SQLITE_UTF8 1 #define SQLITE_UTF16LE 2 #define SQLITE_UTF16BE 3 |
︙ | ︙ | |||
3891 3892 3893 3894 3895 3896 3897 | int sqlite3_expired(sqlite3_stmt*); int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); int sqlite3_global_recover(void); void sqlite3_thread_cleanup(void); int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); /* | | | 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 | int sqlite3_expired(sqlite3_stmt*); int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); int sqlite3_global_recover(void); void sqlite3_thread_cleanup(void); int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); /* ** CAPI3REF: Obtaining SQL Function Parameter Values {H15100} ** ** The C-language implementation of SQL functions and aggregates uses ** this set of interface routines to access the parameter values on ** the function or aggregate. ** ** The xFunc (for scalar functions) or xStep (for aggregates) parameters ** to [sqlite3_create_function()] and [sqlite3_create_function16()] |
︙ | ︙ | |||
3937 3938 3939 3940 3941 3942 3943 | ** or [sqlite3_value_text16()]. ** ** These routines must be called from the same thread as ** the SQL function that supplied the [sqlite3_value*] parameters. ** ** INVARIANTS: ** | | | | | | | | | | | | | | 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 | ** or [sqlite3_value_text16()]. ** ** These routines must be called from the same thread as ** the SQL function that supplied the [sqlite3_value*] parameters. ** ** INVARIANTS: ** ** {H15103} The [sqlite3_value_blob(V)] interface converts the ** [protected sqlite3_value] object V into a BLOB and then ** returns a pointer to the converted value. ** ** {H15106} The [sqlite3_value_bytes(V)] interface returns the ** number of bytes in the BLOB or string (exclusive of the ** zero terminator on the string) that was returned by the ** most recent call to [sqlite3_value_blob(V)] or ** [sqlite3_value_text(V)]. ** ** {H15109} The [sqlite3_value_bytes16(V)] interface returns the ** number of bytes in the string (exclusive of the ** zero terminator on the string) that was returned by the ** most recent call to [sqlite3_value_text16(V)], ** [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)]. ** ** {H15112} The [sqlite3_value_double(V)] interface converts the ** [protected sqlite3_value] object V into a floating point value and ** returns a copy of that value. ** ** {H15115} The [sqlite3_value_int(V)] interface converts the ** [protected sqlite3_value] object V into a 64-bit signed integer and ** returns the lower 32 bits of that integer. ** ** {H15118} The [sqlite3_value_int64(V)] interface converts the ** [protected sqlite3_value] object V into a 64-bit signed integer and ** returns a copy of that integer. ** ** {H15121} The [sqlite3_value_text(V)] interface converts the ** [protected sqlite3_value] object V into a zero-terminated UTF-8 ** string and returns a pointer to that string. ** ** {H15124} The [sqlite3_value_text16(V)] interface converts the ** [protected sqlite3_value] object V into a zero-terminated 2-byte ** aligned UTF-16 native byte order ** string and returns a pointer to that string. ** ** {H15127} The [sqlite3_value_text16be(V)] interface converts the ** [protected sqlite3_value] object V into a zero-terminated 2-byte ** aligned UTF-16 big-endian ** string and returns a pointer to that string. ** ** {H15130} The [sqlite3_value_text16le(V)] interface converts the ** [protected sqlite3_value] object V into a zero-terminated 2-byte ** aligned UTF-16 little-endian ** string and returns a pointer to that string. ** ** {H15133} The [sqlite3_value_type(V)] interface returns ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT], ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for ** the [sqlite3_value] object V. ** ** {H15136} The [sqlite3_value_numeric_type(V)] interface converts ** the [protected sqlite3_value] object V into either an integer or ** a floating point value if it can do so without loss of ** information, and returns one of [SQLITE_NULL], ** [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or ** [SQLITE_BLOB] as appropriate for the ** [protected sqlite3_value] object V after the conversion attempt. */ |
︙ | ︙ | |||
4011 4012 4013 4014 4015 4016 4017 | const void *sqlite3_value_text16(sqlite3_value*); const void *sqlite3_value_text16le(sqlite3_value*); const void *sqlite3_value_text16be(sqlite3_value*); int sqlite3_value_type(sqlite3_value*); int sqlite3_value_numeric_type(sqlite3_value*); /* | | | 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 | const void *sqlite3_value_text16(sqlite3_value*); const void *sqlite3_value_text16le(sqlite3_value*); const void *sqlite3_value_text16be(sqlite3_value*); int sqlite3_value_type(sqlite3_value*); int sqlite3_value_numeric_type(sqlite3_value*); /* ** CAPI3REF: Obtain Aggregate Function Context {H16210} ** ** The implementation of aggregate SQL functions use this routine to allocate ** a structure for storing their state. ** ** The first time the sqlite3_aggregate_context() routine is called for a ** particular aggregate, SQLite allocates nBytes of memory, zeroes out that ** memory, and returns a pointer to it. On second and subsequent calls to |
︙ | ︙ | |||
4035 4036 4037 4038 4039 4040 4041 | ** to the callback routine that implements the aggregate function. ** ** This routine must be called from the same thread in which ** the aggregate SQL function is running. ** ** INVARIANTS: ** | | | | | | | | | | | 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 | ** to the callback routine that implements the aggregate function. ** ** This routine must be called from the same thread in which ** the aggregate SQL function is running. ** ** INVARIANTS: ** ** {H16211} The first invocation of [sqlite3_aggregate_context(C,N)] for ** a particular instance of an aggregate function (for a particular ** context C) causes SQLite to allocate N bytes of memory, ** zero that memory, and return a pointer to the allocated memory. ** ** {H16213} If a memory allocation error occurs during ** [sqlite3_aggregate_context(C,N)] then the function returns 0. ** ** {H16215} Second and subsequent invocations of ** [sqlite3_aggregate_context(C,N)] for the same context pointer C ** ignore the N parameter and return a pointer to the same ** block of memory returned by the first invocation. ** ** {H16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is ** automatically freed on the next call to [sqlite3_reset()] ** or [sqlite3_finalize()] for the [prepared statement] containing ** the aggregate function associated with context C. */ void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); /* ** CAPI3REF: User Data For Functions {H16240} ** ** The sqlite3_user_data() interface returns a copy of ** the pointer that was the pUserData parameter (the 5th parameter) ** of the [sqlite3_create_function()] ** and [sqlite3_create_function16()] routines that originally ** registered the application defined function. {END} ** ** This routine must be called from the same thread in which ** the application-defined function is running. ** ** INVARIANTS: ** ** {H16243} The [sqlite3_user_data(C)] interface returns a copy of the ** P pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)] ** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that ** registered the SQL function associated with [sqlite3_context] C. */ void *sqlite3_user_data(sqlite3_context*); /* ** CAPI3REF: Database Connection For Functions {H16250} ** ** The sqlite3_context_db_handle() interface returns a copy of ** the pointer to the [database connection] (the 1st parameter) ** of the [sqlite3_create_function()] ** and [sqlite3_create_function16()] routines that originally ** registered the application defined function. ** ** INVARIANTS: ** ** {H16253} The [sqlite3_context_db_handle(C)] interface returns a copy of the ** D pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)] ** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that ** registered the SQL function associated with [sqlite3_context] C. */ sqlite3 *sqlite3_context_db_handle(sqlite3_context*); /* ** CAPI3REF: Function Auxiliary Data {H16270} ** ** The following two functions may be used by scalar SQL functions to ** associate metadata with argument values. If the same value is passed to ** multiple invocations of the same SQL function during query execution, under ** some circumstances the associated metadata may be preserved. This may ** be used, for example, to add a regular-expression matching scalar ** function. The compiled version of the regular expression is stored as |
︙ | ︙ | |||
4138 4139 4140 4141 4142 4143 4144 | ** values and SQL variables. ** ** These routines must be called from the same thread in which ** the SQL function is running. ** ** INVARIANTS: ** | | | | | | | | | | 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 | ** values and SQL variables. ** ** These routines must be called from the same thread in which ** the SQL function is running. ** ** INVARIANTS: ** ** {H16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer ** to metadata associated with the Nth parameter of the SQL function ** whose context is C, or NULL if there is no metadata associated ** with that parameter. ** ** {H16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata ** pointer P to the Nth parameter of the SQL function with context C. ** ** {H16276} SQLite will invoke the destructor D with a single argument ** which is the metadata pointer P following a call to ** [sqlite3_set_auxdata(C,N,P,D)] when SQLite ceases to hold ** the metadata. ** ** {H16277} SQLite ceases to hold metadata for an SQL function parameter ** when the value of that parameter changes. ** ** {H16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor ** is called for any prior metadata associated with the same function ** context C and parameter N. ** ** {H16279} SQLite will call destructors for any metadata it is holding ** in a particular [prepared statement] S when either ** [sqlite3_reset(S)] or [sqlite3_finalize(S)] is called. */ void *sqlite3_get_auxdata(sqlite3_context*, int N); void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*)); /* ** CAPI3REF: Constants Defining Special Destructor Behavior {H10280} ** ** These are special values for the destructor that is passed in as the ** final argument to routines like [sqlite3_result_blob()]. If the destructor ** argument is SQLITE_STATIC, it means that the content pointer is constant ** and will never change. It does not need to be destroyed. The ** SQLITE_TRANSIENT value means that the content will likely change in ** the near future and that SQLite should make its own private copy of ** the content before returning. ** ** The typedef is necessary to work around problems in certain ** C++ compilers. See ticket #2191. */ typedef void (*sqlite3_destructor_type)(void*); #define SQLITE_STATIC ((sqlite3_destructor_type)0) #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) /* ** CAPI3REF: Setting The Result Of An SQL Function {H16400} ** ** These routines are used by the xFunc or xFinal callbacks that ** implement SQL functions and aggregates. See ** [sqlite3_create_function()] and [sqlite3_create_function16()] ** for additional information. ** ** These functions work very much like the [parameter binding] family of |
︙ | ︙ | |||
4290 4291 4292 4293 4294 4295 4296 | ** ** If these routines are called from within the different thread ** than the one containing the application-defined function that received ** the [sqlite3_context] pointer, the results are undefined. ** ** INVARIANTS: ** | | | | | | | | | | | | | | | | | | | | | | | 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 | ** ** If these routines are called from within the different thread ** than the one containing the application-defined function that received ** the [sqlite3_context] pointer, the results are undefined. ** ** INVARIANTS: ** ** {H16403} The default return value from any SQL function is NULL. ** ** {H16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the ** return value of function C to be a BLOB that is N bytes ** in length and with content pointed to by V. ** ** {H16409} The [sqlite3_result_double(C,V)] interface changes the ** return value of function C to be the floating point value V. ** ** {H16412} The [sqlite3_result_error(C,V,N)] interface changes the return ** value of function C to be an exception with error code ** [SQLITE_ERROR] and a UTF-8 error message copied from V up to the ** first zero byte or until N bytes are read if N is positive. ** ** {H16415} The [sqlite3_result_error16(C,V,N)] interface changes the return ** value of function C to be an exception with error code ** [SQLITE_ERROR] and a UTF-16 native byte order error message ** copied from V up to the first zero terminator or until N bytes ** are read if N is positive. ** ** {H16418} The [sqlite3_result_error_toobig(C)] interface changes the return ** value of the function C to be an exception with error code ** [SQLITE_TOOBIG] and an appropriate error message. ** ** {H16421} The [sqlite3_result_error_nomem(C)] interface changes the return ** value of the function C to be an exception with error code ** [SQLITE_NOMEM] and an appropriate error message. ** ** {H16424} The [sqlite3_result_error_code(C,E)] interface changes the return ** value of the function C to be an exception with error code E. ** The error message text is unchanged. ** ** {H16427} The [sqlite3_result_int(C,V)] interface changes the ** return value of function C to be the 32-bit integer value V. ** ** {H16430} The [sqlite3_result_int64(C,V)] interface changes the ** return value of function C to be the 64-bit integer value V. ** ** {H16433} The [sqlite3_result_null(C)] interface changes the ** return value of function C to be NULL. ** ** {H16436} The [sqlite3_result_text(C,V,N,D)] interface changes the ** return value of function C to be the UTF-8 string ** V up to the first zero if N is negative ** or the first N bytes of V if N is non-negative. ** ** {H16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the ** return value of function C to be the UTF-16 native byte order ** string V up to the first zero if N is negative ** or the first N bytes of V if N is non-negative. ** ** {H16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the ** return value of function C to be the UTF-16 big-endian ** string V up to the first zero if N is negative ** or the first N bytes or V if N is non-negative. ** ** {H16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the ** return value of function C to be the UTF-16 little-endian ** string V up to the first zero if N is negative ** or the first N bytes of V if N is non-negative. ** ** {H16448} The [sqlite3_result_value(C,V)] interface changes the ** return value of function C to be the [unprotected sqlite3_value] ** object V. ** ** {H16451} The [sqlite3_result_zeroblob(C,N)] interface changes the ** return value of function C to be an N-byte BLOB of all zeros. ** ** {H16454} The [sqlite3_result_error()] and [sqlite3_result_error16()] ** interfaces make a copy of their error message strings before ** returning. ** ** {H16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], ** [sqlite3_result_text16be(C,V,N,D)], or ** [sqlite3_result_text16le(C,V,N,D)] is the constant [SQLITE_STATIC] ** then no destructor is ever called on the pointer V and SQLite ** assumes that V is immutable. ** ** {H16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], ** [sqlite3_result_text16be(C,V,N,D)], or ** [sqlite3_result_text16le(C,V,N,D)] is the constant ** [SQLITE_TRANSIENT] then the interfaces makes a copy of the ** content of V and retains the copy. ** ** {H16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], ** [sqlite3_result_text16be(C,V,N,D)], or ** [sqlite3_result_text16le(C,V,N,D)] is some value other than ** the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then ** SQLite will invoke the destructor D with V as its only argument ** when it has finished with the V value. */ |
︙ | ︙ | |||
4402 4403 4404 4405 4406 4407 4408 | void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); void sqlite3_result_value(sqlite3_context*, sqlite3_value*); void sqlite3_result_zeroblob(sqlite3_context*, int n); /* | | | 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 4416 4417 | void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); void sqlite3_result_value(sqlite3_context*, sqlite3_value*); void sqlite3_result_zeroblob(sqlite3_context*, int n); /* ** CAPI3REF: Define New Collating Sequences {H16600} ** ** These functions are used to add new collation sequences to the ** [database connection] specified as the first argument. ** ** The name of the new collation sequence is specified as a UTF-8 string ** for sqlite3_create_collation() and sqlite3_create_collation_v2() ** and a UTF-16 string for sqlite3_create_collation16(). In all cases |
︙ | ︙ | |||
4445 4446 4447 4448 4449 4450 4451 | ** of the sqlite3_create_collation_v2(). ** Collations are destroyed when they are overridden by later calls to the ** collation creation functions or when the [database connection] is closed ** using [sqlite3_close()]. ** ** INVARIANTS: ** | | | | | | | | | | | | | 4446 4447 4448 4449 4450 4451 4452 4453 4454 4455 4456 4457 4458 4459 4460 4461 4462 4463 4464 4465 4466 4467 4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499 4500 4501 4502 | ** of the sqlite3_create_collation_v2(). ** Collations are destroyed when they are overridden by later calls to the ** collation creation functions or when the [database connection] is closed ** using [sqlite3_close()]. ** ** INVARIANTS: ** ** {H16603} A successful call to the ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] interface ** registers function F as the comparison function used to ** implement collation X on the [database connection] B for ** databases having encoding E. ** ** {H16604} SQLite understands the X parameter to ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] as a zero-terminated ** UTF-8 string in which case is ignored for ASCII characters and ** is significant for non-ASCII characters. ** ** {H16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)] ** with the same values for B, X, and E, override prior values ** of P, F, and D. ** ** {H16609} If the destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)] ** is not NULL then it is called with argument P when the ** collating function is dropped by SQLite. ** ** {H16612} A collating function is dropped when it is overloaded. ** ** {H16615} A collating function is dropped when the database connection ** is closed using [sqlite3_close()]. ** ** {H16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)] ** is passed through as the first parameter to the comparison ** function F for all subsequent invocations of F. ** ** {H16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly ** the same as a call to [sqlite3_create_collation_v2()] with ** the same parameters and a NULL destructor. ** ** {H16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)], ** SQLite uses the comparison function F for all text comparison ** operations on the [database connection] B on text values that ** use the collating sequence named X. ** ** {H16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same ** as [sqlite3_create_collation(B,X,E,P,F)] except that the ** collation name X is understood as UTF-16 in native byte order ** instead of UTF-8. ** ** {H16630} When multiple comparison functions are available for the same ** collating sequence, SQLite chooses the one whose text encoding ** requires the least amount of conversion from the default ** text encoding of the database. */ int sqlite3_create_collation( sqlite3*, const char *zName, |
︙ | ︙ | |||
4516 4517 4518 4519 4520 4521 4522 | const void *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*) ); /* | | | | | | | 4517 4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4536 4537 4538 4539 4540 4541 4542 4543 4544 4545 4546 4547 4548 4549 4550 4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 | const void *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*) ); /* ** CAPI3REF: Collation Needed Callbacks {H16700} ** ** To avoid having to register all collation sequences before a database ** can be used, a single callback function may be registered with the ** [database connection] to be called whenever an undefined collation ** sequence is required. ** ** If the function is registered using the sqlite3_collation_needed() API, ** then it is passed the names of undefined collation sequences as strings ** encoded in UTF-8. {H16703} If sqlite3_collation_needed16() is used, ** the names are passed as UTF-16 in machine native byte order. ** A call to either function replaces any existing callback. ** ** When the callback is invoked, the first argument passed is a copy ** of the second argument to sqlite3_collation_needed() or ** sqlite3_collation_needed16(). The second argument is the database ** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], ** or [SQLITE_UTF16LE], indicating the most desirable form of the collation ** sequence function required. The fourth parameter is the name of the ** required collation sequence. ** ** The callback function should register the desired collation using ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or ** [sqlite3_create_collation_v2()]. ** ** INVARIANTS: ** ** {H16702} A successful call to [sqlite3_collation_needed(D,P,F)] ** or [sqlite3_collation_needed16(D,P,F)] causes ** the [database connection] D to invoke callback F with first ** parameter P whenever it needs a comparison function for a ** collating sequence that it does not know about. ** ** {H16704} Each successful call to [sqlite3_collation_needed()] or ** [sqlite3_collation_needed16()] overrides the callback registered ** on the same [database connection] by prior calls to either ** interface. ** ** {H16706} The name of the requested collating function passed in the ** 4th parameter to the callback is in UTF-8 if the callback ** was registered using [sqlite3_collation_needed()] and ** is in UTF-16 native byte order if the callback was ** registered using [sqlite3_collation_needed16()]. */ int sqlite3_collation_needed( sqlite3*, |
︙ | ︙ | |||
4597 4598 4599 4600 4601 4602 4603 | */ int sqlite3_rekey( sqlite3 *db, /* Database to be rekeyed */ const void *pKey, int nKey /* The new key */ ); /* | | | | | | | | | | | | | | | | | | | | 4598 4599 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4661 4662 4663 4664 4665 4666 4667 4668 4669 4670 4671 4672 4673 4674 4675 4676 4677 4678 4679 4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 4698 4699 4700 4701 4702 4703 4704 4705 4706 4707 4708 4709 4710 4711 4712 4713 4714 4715 4716 4717 4718 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 4730 4731 4732 4733 4734 4735 4736 4737 4738 4739 4740 4741 | */ int sqlite3_rekey( sqlite3 *db, /* Database to be rekeyed */ const void *pKey, int nKey /* The new key */ ); /* ** CAPI3REF: Suspend Execution For A Short Time {H10530} ** ** The sqlite3_sleep() function causes the current thread to suspend execution ** for at least a number of milliseconds specified in its parameter. ** ** If the operating system does not support sleep requests with ** millisecond time resolution, then the time will be rounded up to ** the nearest second. The number of milliseconds of sleep actually ** requested from the operating system is returned. ** ** SQLite implements this interface by calling the xSleep() ** method of the default [sqlite3_vfs] object. ** ** INVARIANTS: ** ** {H10533} The [sqlite3_sleep(M)] interface invokes the xSleep ** method of the default [sqlite3_vfs|VFS] in order to ** suspend execution of the current thread for at least ** M milliseconds. ** ** {H10536} The [sqlite3_sleep(M)] interface returns the number of ** milliseconds of sleep actually requested of the operating ** system, which might be larger than the parameter M. */ int sqlite3_sleep(int); /* ** CAPI3REF: Name Of The Folder Holding Temporary Files {H10310} ** ** If this global variable is made to point to a string which is ** the name of a folder (a.k.a. directory), then all temporary files ** created by SQLite will be placed in that directory. If this variable ** is a NULL pointer, then SQLite performs a search for an appropriate ** temporary file directory. ** ** It is not safe to modify this variable once a [database connection] ** has been opened. It is intended that this variable be set once ** as part of process initialization and before any SQLite interface ** routines have been call and remain unchanged thereafter. */ SQLITE_EXTERN char *sqlite3_temp_directory; /* ** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode {H12930} ** KEYWORDS: {autocommit mode} ** ** The sqlite3_get_autocommit() interface returns non-zero or ** zero if the given database connection is or is not in autocommit mode, ** respectively. Autocommit mode is on by default. ** Autocommit mode is disabled by a [BEGIN] statement. ** Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK]. ** ** If certain kinds of errors occur on a statement within a multi-statement ** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR], ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the ** transaction might be rolled back automatically. The only way to ** find out whether SQLite automatically rolled back the transaction after ** an error is to use this function. ** ** INVARIANTS: ** ** {H12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or ** zero if the [database connection] D is or is not in autocommit ** mode, respectively. ** ** {H12932} Autocommit mode is on by default. ** ** {H12933} Autocommit mode is disabled by a successful [BEGIN] statement. ** ** {H12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK] ** statement. ** ** ASSUMPTIONS: ** ** {A12936} If another thread changes the autocommit status of the database ** connection while this routine is running, then the return value ** is undefined. */ int sqlite3_get_autocommit(sqlite3*); /* ** CAPI3REF: Find The Database Handle Of A Prepared Statement {H13120} ** ** The sqlite3_db_handle interface returns the [database connection] handle ** to which a [prepared statement] belongs. The database handle returned by ** sqlite3_db_handle is the same database handle that was the first argument ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to ** create the statement in the first place. ** ** INVARIANTS: ** ** {H13123} The [sqlite3_db_handle(S)] interface returns a pointer ** to the [database connection] associated with the ** [prepared statement] S. */ sqlite3 *sqlite3_db_handle(sqlite3_stmt*); /* ** CAPI3REF: Find the next prepared statement {H13140} ** ** This interface returns a pointer to the next [prepared statement] after ** pStmt associated with the [database connection] pDb. If pStmt is NULL ** then this interface returns a pointer to the first prepared statement ** associated with the database connection pDb. If no prepared statement ** satisfies the conditions of this routine, it returns NULL. ** ** INVARIANTS: ** ** {H13143} If D is a [database connection] that holds one or more ** unfinalized [prepared statements] and S is a NULL pointer, ** then [sqlite3_next_stmt(D, S)] routine shall return a pointer ** to one of the prepared statements associated with D. ** ** {H13146} If D is a [database connection] that holds no unfinalized ** [prepared statements] and S is a NULL pointer, then ** [sqlite3_next_stmt(D, S)] routine shall return a NULL pointer. ** ** {H13149} If S is a [prepared statement] in the [database connection] D ** and S is not the last prepared statement in D, then ** [sqlite3_next_stmt(D, S)] routine shall return a pointer ** to the next prepared statement in D after S. ** ** {H13152} If S is the last [prepared statement] in the ** [database connection] D then the [sqlite3_next_stmt(D, S)] ** routine shall return a NULL pointer. */ sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt); /* ** CAPI3REF: Commit And Rollback Notification Callbacks {H12950} ** ** The sqlite3_commit_hook() interface registers a callback ** function to be invoked whenever a transaction is committed. ** Any callback set by a previous call to sqlite3_commit_hook() ** for the same database connection is overridden. ** The sqlite3_rollback_hook() interface registers a callback ** function to be invoked whenever a transaction is committed. |
︙ | ︙ | |||
4756 4757 4758 4759 4760 4761 4762 | ** automatically rolled back because the database connection is closed. ** The rollback callback is not invoked if a transaction is ** rolled back because a commit callback returned non-zero. ** <todo> Check on this </todo> ** ** INVARIANTS: ** | | | | | | | | | | | | 4757 4758 4759 4760 4761 4762 4763 4764 4765 4766 4767 4768 4769 4770 4771 4772 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 | ** automatically rolled back because the database connection is closed. ** The rollback callback is not invoked if a transaction is ** rolled back because a commit callback returned non-zero. ** <todo> Check on this </todo> ** ** INVARIANTS: ** ** {H12951} The [sqlite3_commit_hook(D,F,P)] interface registers the ** callback function F to be invoked with argument P whenever ** a transaction commits on the [database connection] D. ** ** {H12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P argument ** from the previous call with the same [database connection] D, ** or NULL on the first call for a particular database connection D. ** ** {H12953} Each call to [sqlite3_commit_hook()] overwrites the callback ** registered by prior calls. ** ** {H12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL ** then the commit hook callback is canceled and no callback ** is invoked when a transaction commits. ** ** {H12955} If the commit callback returns non-zero then the commit is ** converted into a rollback. ** ** {H12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the ** callback function F to be invoked with argument P whenever ** a transaction rolls back on the [database connection] D. ** ** {H12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P ** argument from the previous call with the same ** [database connection] D, or NULL on the first call ** for a particular database connection D. ** ** {H12963} Each call to [sqlite3_rollback_hook()] overwrites the callback ** registered by prior calls. ** ** {H12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL ** then the rollback hook callback is canceled and no callback ** is invoked when a transaction rolls back. */ void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); /* ** CAPI3REF: Data Change Notification Callbacks {H12970} ** ** The sqlite3_update_hook() interface registers a callback function ** with the [database connection] identified by the first argument ** to be invoked whenever a row is updated, inserted or deleted. ** Any callback set by a previous call to this function ** for the same database connection is overridden. ** |
︙ | ︙ | |||
4822 4823 4824 4825 4826 4827 4828 | ** modified (i.e. sqlite_master and sqlite_sequence). ** ** If another function was previously registered, its pArg value ** is returned. Otherwise NULL is returned. ** ** INVARIANTS: ** | | | | | | | | | | | 4823 4824 4825 4826 4827 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 4858 4859 4860 4861 4862 4863 4864 4865 4866 4867 4868 4869 4870 4871 4872 4873 | ** modified (i.e. sqlite_master and sqlite_sequence). ** ** If another function was previously registered, its pArg value ** is returned. Otherwise NULL is returned. ** ** INVARIANTS: ** ** {H12971} The [sqlite3_update_hook(D,F,P)] interface causes the callback ** function F to be invoked with first parameter P whenever ** a table row is modified, inserted, or deleted on ** the [database connection] D. ** ** {H12973} The [sqlite3_update_hook(D,F,P)] interface returns the value ** of P for the previous call on the same [database connection] D, ** or NULL for the first call. ** ** {H12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)] ** is NULL then the no update callbacks are made. ** ** {H12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls ** to the same interface on the same [database connection] D. ** ** {H12979} The update hook callback is not invoked when internal system ** tables such as sqlite_master and sqlite_sequence are modified. ** ** {H12981} The second parameter to the update callback ** is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], ** depending on the operation that caused the callback to be invoked. ** ** {H12983} The third and fourth arguments to the callback contain pointers ** to zero-terminated UTF-8 strings which are the names of the ** database and table that is being updated. ** {H12985} The final callback parameter is the rowid of the row after ** the change occurs. */ void *sqlite3_update_hook( sqlite3*, void(*)(void *,int ,char const *,char const *,sqlite3_int64), void* ); /* ** CAPI3REF: Enable Or Disable Shared Pager Cache {H10330} ** KEYWORDS: {shared cache} {shared cache mode} ** ** This routine enables or disables the sharing of the database cache ** and schema data structures between [database connection | connections] ** to the same database. Sharing is enabled if the argument is true ** and disabled if the argument is false. ** |
︙ | ︙ | |||
4888 4889 4890 4891 4892 4893 4894 | ** ** Shared cache is disabled by default. But this might change in ** future releases of SQLite. Applications that care about shared ** cache setting should set it explicitly. ** ** INVARIANTS: ** | | | | | | | | | | 4889 4890 4891 4892 4893 4894 4895 4896 4897 4898 4899 4900 4901 4902 4903 4904 4905 4906 4907 4908 4909 4910 4911 4912 4913 4914 4915 4916 4917 4918 4919 4920 4921 4922 4923 4924 4925 4926 4927 4928 4929 4930 4931 4932 4933 4934 4935 4936 4937 4938 4939 4940 | ** ** Shared cache is disabled by default. But this might change in ** future releases of SQLite. Applications that care about shared ** cache setting should set it explicitly. ** ** INVARIANTS: ** ** {H10331} A successful invocation of [sqlite3_enable_shared_cache(B)] ** will enable or disable shared cache mode for any subsequently ** created [database connection] in the same process. ** ** {H10336} When shared cache is enabled, the [sqlite3_create_module()] ** interface will always return an error. ** ** {H10337} The [sqlite3_enable_shared_cache(B)] interface returns ** [SQLITE_OK] if shared cache was enabled or disabled successfully. ** ** {H10339} Shared cache is disabled by default. */ int sqlite3_enable_shared_cache(int); /* ** CAPI3REF: Attempt To Free Heap Memory {H17340} ** ** The sqlite3_release_memory() interface attempts to free N bytes ** of heap memory by deallocating non-essential memory allocations ** held by the database library. {END} Memory used to cache database ** pages to improve performance is an example of non-essential memory. ** sqlite3_release_memory() returns the number of bytes actually freed, ** which might be more or less than the amount requested. ** ** INVARIANTS: ** ** {H17341} The [sqlite3_release_memory(N)] interface attempts to ** free N bytes of heap memory by deallocating non-essential ** memory allocations held by the database library. ** ** {H16342} The [sqlite3_release_memory(N)] returns the number ** of bytes actually freed, which might be more or less ** than the amount requested. */ int sqlite3_release_memory(int); /* ** CAPI3REF: Impose A Limit On Heap Size {H17350} ** ** The sqlite3_soft_heap_limit() interface places a "soft" limit ** on the amount of heap memory that may be allocated by SQLite. ** If an internal allocation is requested that would exceed the ** soft heap limit, [sqlite3_release_memory()] is invoked one or ** more times to free up some space before the allocation is performed. ** |
︙ | ︙ | |||
4956 4957 4958 4959 4960 4961 4962 | ** applied to all threads. The value specified for the soft heap limit ** is an upper bound on the total memory allocation for all threads. In ** version 3.5.0 there is no mechanism for limiting the heap usage for ** individual threads. ** ** INVARIANTS: ** | | | | | | | | | 4957 4958 4959 4960 4961 4962 4963 4964 4965 4966 4967 4968 4969 4970 4971 4972 4973 4974 4975 4976 4977 4978 4979 4980 4981 4982 4983 4984 4985 4986 4987 4988 4989 4990 4991 4992 4993 4994 4995 4996 4997 4998 4999 5000 | ** applied to all threads. The value specified for the soft heap limit ** is an upper bound on the total memory allocation for all threads. In ** version 3.5.0 there is no mechanism for limiting the heap usage for ** individual threads. ** ** INVARIANTS: ** ** {H16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit ** of N bytes on the amount of heap memory that may be allocated ** using [sqlite3_malloc()] or [sqlite3_realloc()] at any point ** in time. ** ** {H16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would ** cause the total amount of allocated memory to exceed the ** soft heap limit, then [sqlite3_release_memory()] is invoked ** in an attempt to reduce the memory usage prior to proceeding ** with the memory allocation attempt. ** ** {H16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger ** attempts to reduce memory usage through the soft heap limit ** mechanism continue even if the attempt to reduce memory ** usage is unsuccessful. ** ** {H16354} A negative or zero value for N in a call to ** [sqlite3_soft_heap_limit(N)] means that there is no soft ** heap limit and [sqlite3_release_memory()] will only be ** called when memory is completely exhausted. ** ** {H16355} The default value for the soft heap limit is zero. ** ** {H16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the ** values set by all prior calls. */ void sqlite3_soft_heap_limit(int); /* ** CAPI3REF: Extract Metadata About A Column Of A Table {H12850} ** ** This routine returns metadata about a specific column of a specific ** database table accessible using the [database connection] handle ** passed as the first function argument. ** ** The column is identified by the second, third and fourth parameters to ** this function. The second parameter is either the name of the database |
︙ | ︙ | |||
5059 5060 5061 5062 5063 5064 5065 | char const **pzCollSeq, /* OUTPUT: Collation sequence name */ int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ int *pPrimaryKey, /* OUTPUT: True if column part of PK */ int *pAutoinc /* OUTPUT: True if column is auto-increment */ ); /* | | | | | | | | | | | | | | | | | | | | 5060 5061 5062 5063 5064 5065 5066 5067 5068 5069 5070 5071 5072 5073 5074 5075 5076 5077 5078 5079 5080 5081 5082 5083 5084 5085 5086 5087 5088 5089 5090 5091 5092 5093 5094 5095 5096 5097 5098 5099 5100 5101 5102 5103 5104 5105 5106 5107 5108 5109 5110 5111 5112 5113 5114 5115 5116 5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 5127 5128 5129 5130 5131 5132 5133 5134 5135 5136 5137 5138 5139 5140 5141 5142 5143 5144 5145 5146 5147 5148 5149 5150 5151 5152 5153 5154 5155 5156 5157 5158 5159 5160 5161 | char const **pzCollSeq, /* OUTPUT: Collation sequence name */ int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ int *pPrimaryKey, /* OUTPUT: True if column part of PK */ int *pAutoinc /* OUTPUT: True if column is auto-increment */ ); /* ** CAPI3REF: Load An Extension {H12600} ** ** This interface loads an SQLite extension library from the named file. ** ** {H12601} The sqlite3_load_extension() interface attempts to load an ** SQLite extension library contained in the file zFile. ** ** {H12602} The entry point is zProc. ** ** {H12603} zProc may be 0, in which case the name of the entry point ** defaults to "sqlite3_extension_init". ** ** {H12604} The sqlite3_load_extension() interface shall return ** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. ** ** {H12605} If an error occurs and pzErrMsg is not 0, then the ** [sqlite3_load_extension()] interface shall attempt to ** fill *pzErrMsg with error message text stored in memory ** obtained from [sqlite3_malloc()]. {END} The calling function ** should free this memory by calling [sqlite3_free()]. ** ** {H12606} Extension loading must be enabled using ** [sqlite3_enable_load_extension()] prior to calling this API, ** otherwise an error will be returned. */ int sqlite3_load_extension( sqlite3 *db, /* Load the extension into this database connection */ const char *zFile, /* Name of the shared library containing extension */ const char *zProc, /* Entry point. Derived from zFile if 0 */ char **pzErrMsg /* Put error message here if not 0 */ ); /* ** CAPI3REF: Enable Or Disable Extension Loading {H12620} ** ** So as not to open security holes in older applications that are ** unprepared to deal with extension loading, and as a means of disabling ** extension loading while evaluating user-entered SQL, the following API ** is provided to turn the [sqlite3_load_extension()] mechanism on and off. ** ** Extension loading is off by default. See ticket #1863. ** ** {H12621} Call the sqlite3_enable_load_extension() routine with onoff==1 ** to turn extension loading on and call it with onoff==0 to turn ** it back off again. ** ** {H12622} Extension loading is off by default. */ int sqlite3_enable_load_extension(sqlite3 *db, int onoff); /* ** CAPI3REF: Make Arrangements To Automatically Load An Extension {H12640} ** ** This API can be invoked at program startup in order to register ** one or more statically linked extensions that will be available ** to all new [database connections]. {END} ** ** This routine stores a pointer to the extension in an array that is ** obtained from [sqlite3_malloc()]. If you run a memory leak checker ** on your program and it reports a leak because of this array, invoke ** [sqlite3_reset_auto_extension()] prior to shutdown to free the memory. ** ** {H12641} This function registers an extension entry point that is ** automatically invoked whenever a new [database connection] ** is opened using [sqlite3_open()], [sqlite3_open16()], ** or [sqlite3_open_v2()]. ** ** {H12642} Duplicate extensions are detected so calling this routine ** multiple times with the same extension is harmless. ** ** {H12643} This routine stores a pointer to the extension in an array ** that is obtained from [sqlite3_malloc()]. ** ** {H12644} Automatic extensions apply across all threads. */ int sqlite3_auto_extension(void *xEntryPoint); /* ** CAPI3REF: Reset Automatic Extension Loading {H12660} ** ** This function disables all previously registered automatic ** extensions. {END} It undoes the effect of all prior ** [sqlite3_auto_extension()] calls. ** ** {H12661} This function disables all previously registered ** automatic extensions. ** ** {H12662} This function disables automatic extensions in all threads. */ void sqlite3_reset_auto_extension(void); /* ****** EXPERIMENTAL - subject to change without notice ************** ** ** The interface to the virtual-table mechanism is currently considered |
︙ | ︙ | |||
5170 5171 5172 5173 5174 5175 5176 | */ typedef struct sqlite3_vtab sqlite3_vtab; typedef struct sqlite3_index_info sqlite3_index_info; typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; typedef struct sqlite3_module sqlite3_module; /* | | | 5171 5172 5173 5174 5175 5176 5177 5178 5179 5180 5181 5182 5183 5184 5185 | */ typedef struct sqlite3_vtab sqlite3_vtab; typedef struct sqlite3_index_info sqlite3_index_info; typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; typedef struct sqlite3_module sqlite3_module; /* ** CAPI3REF: Virtual Table Object {H18000} ** KEYWORDS: sqlite3_module ** ** A module is a class of virtual tables. Each module is defined ** by an instance of the following structure. This structure consists ** mostly of methods for the module. ** ** This interface is experimental and is subject to change or |
︙ | ︙ | |||
5207 5208 5209 5210 5211 5212 5213 | int (*xBegin)(sqlite3_vtab *pVTab); int (*xSync)(sqlite3_vtab *pVTab); int (*xCommit)(sqlite3_vtab *pVTab); int (*xRollback)(sqlite3_vtab *pVTab); int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), void **ppArg); | < | | 5208 5209 5210 5211 5212 5213 5214 5215 5216 5217 5218 5219 5220 5221 5222 5223 5224 5225 5226 | int (*xBegin)(sqlite3_vtab *pVTab); int (*xSync)(sqlite3_vtab *pVTab); int (*xCommit)(sqlite3_vtab *pVTab); int (*xRollback)(sqlite3_vtab *pVTab); int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), void **ppArg); int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); }; /* ** CAPI3REF: Virtual Table Indexing Information {H18100} ** KEYWORDS: sqlite3_index_info ** ** The sqlite3_index_info structure and its substructures is used to ** pass information into and receive the reply from the xBestIndex ** method of an sqlite3_module. The fields under **Inputs** are the ** inputs to xBestIndex and are read-only. xBestIndex inserts its ** results into the **Outputs** fields. |
︙ | ︙ | |||
5276 5277 5278 5279 5280 5281 5282 | int iTermOffset; /* Used internally - xBestIndex should ignore */ } *aConstraint; /* Table of WHERE clause constraints */ int nOrderBy; /* Number of terms in the ORDER BY clause */ struct sqlite3_index_orderby { int iColumn; /* Column number */ unsigned char desc; /* True for DESC. False for ASC. */ } *aOrderBy; /* The ORDER BY clause */ | < | | | | 5276 5277 5278 5279 5280 5281 5282 5283 5284 5285 5286 5287 5288 5289 5290 5291 5292 5293 5294 5295 5296 5297 5298 5299 5300 5301 5302 5303 5304 5305 5306 5307 5308 5309 5310 5311 5312 5313 5314 5315 5316 5317 5318 5319 5320 5321 5322 5323 5324 5325 5326 5327 5328 5329 5330 5331 5332 5333 5334 5335 5336 5337 5338 5339 5340 5341 5342 | int iTermOffset; /* Used internally - xBestIndex should ignore */ } *aConstraint; /* Table of WHERE clause constraints */ int nOrderBy; /* Number of terms in the ORDER BY clause */ struct sqlite3_index_orderby { int iColumn; /* Column number */ unsigned char desc; /* True for DESC. False for ASC. */ } *aOrderBy; /* The ORDER BY clause */ /* Outputs */ struct sqlite3_index_constraint_usage { int argvIndex; /* if >0, constraint is part of argv to xFilter */ unsigned char omit; /* Do not code a test for this constraint */ } *aConstraintUsage; int idxNum; /* Number used to identify the index */ char *idxStr; /* String, possibly obtained from sqlite3_malloc */ int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ int orderByConsumed; /* True if output is already ordered */ double estimatedCost; /* Estimated cost of using this index */ }; #define SQLITE_INDEX_CONSTRAINT_EQ 2 #define SQLITE_INDEX_CONSTRAINT_GT 4 #define SQLITE_INDEX_CONSTRAINT_LE 8 #define SQLITE_INDEX_CONSTRAINT_LT 16 #define SQLITE_INDEX_CONSTRAINT_GE 32 #define SQLITE_INDEX_CONSTRAINT_MATCH 64 /* ** CAPI3REF: Register A Virtual Table Implementation {H18200} ** ** This routine is used to register a new module name with a ** [database connection]. Module names must be registered before ** creating new virtual tables on the module, or before using ** preexisting virtual tables of the module. ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. */ int sqlite3_create_module( sqlite3 *db, /* SQLite connection to register module with */ const char *zName, /* Name of the module */ const sqlite3_module *, /* Methods for the module */ void * /* Client data for xCreate/xConnect */ ); /* ** CAPI3REF: Register A Virtual Table Implementation {H18210} ** ** This routine is identical to the [sqlite3_create_module()] method above, ** except that it allows a destructor function to be specified. It is ** even more experimental than the rest of the virtual tables API. */ int sqlite3_create_module_v2( sqlite3 *db, /* SQLite connection to register module with */ const char *zName, /* Name of the module */ const sqlite3_module *, /* Methods for the module */ void *, /* Client data for xCreate/xConnect */ void(*xDestroy)(void*) /* Module destructor function */ ); /* ** CAPI3REF: Virtual Table Instance Object {H18010} ** KEYWORDS: sqlite3_vtab ** ** Every module implementation uses a subclass of the following structure ** to describe a particular instance of the module. Each subclass will ** be tailored to the specific needs of the module implementation. ** The purpose of this superclass is to define certain fields that are ** common to all module implementations. |
︙ | ︙ | |||
5359 5360 5361 5362 5363 5364 5365 | const sqlite3_module *pModule; /* The module for this virtual table */ int nRef; /* Used internally */ char *zErrMsg; /* Error message from sqlite3_mprintf() */ /* Virtual table implementations will typically add additional fields */ }; /* | | | | | 5358 5359 5360 5361 5362 5363 5364 5365 5366 5367 5368 5369 5370 5371 5372 5373 5374 5375 5376 5377 5378 5379 5380 5381 5382 5383 5384 5385 5386 5387 5388 5389 5390 5391 5392 5393 5394 5395 5396 5397 5398 5399 5400 5401 5402 5403 5404 5405 | const sqlite3_module *pModule; /* The module for this virtual table */ int nRef; /* Used internally */ char *zErrMsg; /* Error message from sqlite3_mprintf() */ /* Virtual table implementations will typically add additional fields */ }; /* ** CAPI3REF: Virtual Table Cursor Object {H18020} ** KEYWORDS: sqlite3_vtab_cursor ** ** Every module implementation uses a subclass of the following structure ** to describe cursors that point into the virtual table and are used ** to loop through the virtual table. Cursors are created using the ** xOpen method of the module. Each module implementation will define ** the content of a cursor structure to suit its own needs. ** ** This superclass exists in order to define fields of the cursor that ** are common to all implementations. ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. */ struct sqlite3_vtab_cursor { sqlite3_vtab *pVtab; /* Virtual table of this cursor */ /* Virtual table implementations will typically add additional fields */ }; /* ** CAPI3REF: Declare The Schema Of A Virtual Table {H18280} ** ** The xCreate and xConnect methods of a module use the following API ** to declare the format (the names and datatypes of the columns) of ** the virtual tables they implement. ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. */ int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); /* ** CAPI3REF: Overload A Function For A Virtual Table {H18300} ** ** Virtual tables can provide alternative implementations of functions ** using the xFindFunction method. But global versions of those functions ** must exist in order to be overloaded. ** ** This API makes sure a global version of a function with a particular ** name and number of parameters exists. If no such function exists |
︙ | ︙ | |||
5424 5425 5426 5427 5428 5429 5430 | ** When the virtual-table mechanism stabilizes, we will declare the ** interface fixed, support it indefinitely, and remove this comment. ** ****** EXPERIMENTAL - subject to change without notice ************** */ /* | | | | 5423 5424 5425 5426 5427 5428 5429 5430 5431 5432 5433 5434 5435 5436 5437 5438 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 | ** When the virtual-table mechanism stabilizes, we will declare the ** interface fixed, support it indefinitely, and remove this comment. ** ****** EXPERIMENTAL - subject to change without notice ************** */ /* ** CAPI3REF: A Handle To An Open BLOB {H17800} ** KEYWORDS: {BLOB handle} {BLOB handles} ** ** An instance of this object represents an open BLOB on which ** [sqlite3_blob_open | incremental BLOB I/O] can be performed. ** Objects of this type are created by [sqlite3_blob_open()] ** and destroyed by [sqlite3_blob_close()]. ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces ** can be used to read or write small subsections of the BLOB. ** The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes. */ typedef struct sqlite3_blob sqlite3_blob; /* ** CAPI3REF: Open A BLOB For Incremental I/O {H17810} ** ** This interfaces opens a [BLOB handle | handle] to the BLOB located ** in row iRow, column zColumn, table zTable in database zDb; ** in other words, the same BLOB that would be selected by: ** ** <pre> ** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; |
︙ | ︙ | |||
5476 5477 5478 5479 5480 5481 5482 | ** a expired BLOB handle fail with an return code of [SQLITE_ABORT]. ** Changes written into a BLOB prior to the BLOB expiring are not ** rollback by the expiration of the BLOB. Such changes will eventually ** commit if the transaction continues to completion. ** ** INVARIANTS: ** | | | | | | | | | | | | | | | | | | | | | | | | 5475 5476 5477 5478 5479 5480 5481 5482 5483 5484 5485 5486 5487 5488 5489 5490 5491 5492 5493 5494 5495 5496 5497 5498 5499 5500 5501 5502 5503 5504 5505 5506 5507 5508 5509 5510 5511 5512 5513 5514 5515 5516 5517 5518 5519 5520 5521 5522 5523 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5537 5538 5539 5540 5541 5542 5543 5544 5545 5546 5547 5548 5549 5550 5551 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 5567 5568 5569 5570 5571 5572 5573 5574 5575 5576 5577 5578 5579 5580 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 5593 5594 5595 5596 5597 5598 5599 5600 5601 5602 5603 5604 5605 5606 5607 5608 5609 5610 5611 5612 5613 5614 5615 5616 5617 5618 5619 5620 5621 5622 5623 5624 5625 5626 5627 | ** a expired BLOB handle fail with an return code of [SQLITE_ABORT]. ** Changes written into a BLOB prior to the BLOB expiring are not ** rollback by the expiration of the BLOB. Such changes will eventually ** commit if the transaction continues to completion. ** ** INVARIANTS: ** ** {H17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)] ** interface shall open an [sqlite3_blob] object P on the BLOB ** in column C of the table T in the database B on ** the [database connection] D. ** ** {H17814} A successful invocation of [sqlite3_blob_open(D,...)] shall start ** a new transaction on the [database connection] D if that ** connection is not already in a transaction. ** ** {H17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface shall open ** the BLOB for read and write access if and only if the F ** parameter is non-zero. ** ** {H17819} The [sqlite3_blob_open()] interface shall return [SQLITE_OK] on ** success and an appropriate [error code] on failure. ** ** {H17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)] ** then subsequent calls to [sqlite3_errcode(D)], ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return ** information appropriate for that error. ** ** {H17824} If any column in the row that a [sqlite3_blob] has open is ** changed by a separate [UPDATE] or [DELETE] statement or by ** an [ON CONFLICT] side effect, then the [sqlite3_blob] shall ** be marked as invalid. */ int sqlite3_blob_open( sqlite3*, const char *zDb, const char *zTable, const char *zColumn, sqlite3_int64 iRow, int flags, sqlite3_blob **ppBlob ); /* ** CAPI3REF: Close A BLOB Handle {H17830} ** ** Closes an open [BLOB handle]. ** ** Closing a BLOB shall cause the current transaction to commit ** if there are no other BLOBs, no pending prepared statements, and the ** database connection is in [autocommit mode]. ** If any writes were made to the BLOB, they might be held in cache ** until the close operation if they will fit. {END} ** ** Closing the BLOB often forces the changes ** out to disk and so if any I/O errors occur, they will likely occur ** at the time when the BLOB is closed. {H17833} Any errors that occur during ** closing are reported as a non-zero return value. ** ** The BLOB is closed unconditionally. Even if this routine returns ** an error code, the BLOB is still closed. ** ** INVARIANTS: ** ** {H17833} The [sqlite3_blob_close(P)] interface closes an [sqlite3_blob] ** object P previously opened using [sqlite3_blob_open()]. ** ** {H17836} Closing an [sqlite3_blob] object using ** [sqlite3_blob_close()] shall cause the current transaction to ** commit if there are no other open [sqlite3_blob] objects ** or [prepared statements] on the same [database connection] and ** the database connection is in [autocommit mode]. ** ** {H17839} The [sqlite3_blob_close(P)] interfaces shall close the ** [sqlite3_blob] object P unconditionally, even if ** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK]. */ int sqlite3_blob_close(sqlite3_blob *); /* ** CAPI3REF: Return The Size Of An Open BLOB {H17840} ** ** Returns the size in bytes of the BLOB accessible via the open ** []BLOB handle] in its only argument. ** ** INVARIANTS: ** ** {H17843} The [sqlite3_blob_bytes(P)] interface returns the size ** in bytes of the BLOB that the [sqlite3_blob] object P ** refers to. */ int sqlite3_blob_bytes(sqlite3_blob *); /* ** CAPI3REF: Read Data From A BLOB Incrementally {H17850} ** ** This function is used to read data from an open [BLOB handle] into a ** caller-supplied buffer. N bytes of data are copied into buffer Z ** from the open BLOB, starting at offset iOffset. ** ** If offset iOffset is less than N bytes from the end of the BLOB, ** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is ** less than zero, [SQLITE_ERROR] is returned and no data is read. ** ** An attempt to read from an expired [BLOB handle] fails with an ** error code of [SQLITE_ABORT]. ** ** On success, SQLITE_OK is returned. ** Otherwise, an [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** ** {H17853} A successful invocation of [sqlite3_blob_read(P,Z,N,X)] ** shall reads N bytes of data out of the BLOB referenced by ** [BLOB handle] P beginning at offset X and store those bytes ** into buffer Z. ** ** {H17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the BLOB ** is less than N+X bytes, then the function shall leave the ** Z buffer unchanged and return [SQLITE_ERROR]. ** ** {H17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero ** then the function shall leave the Z buffer unchanged ** and return [SQLITE_ERROR]. ** ** {H17862} The [sqlite3_blob_read(P,Z,N,X)] interface shall return [SQLITE_OK] ** if N bytes are successfully read into buffer Z. ** ** {H17863} If the [BLOB handle] P is expired and X and N are within bounds ** then [sqlite3_blob_read(P,Z,N,X)] shall leave the Z buffer ** unchanged and return [SQLITE_ABORT]. ** ** {H17865} If the requested read could not be completed, ** the [sqlite3_blob_read(P,Z,N,X)] interface shall return an ** appropriate [error code] or [extended error code]. ** ** {H17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)] ** then subsequent calls to [sqlite3_errcode(D)], ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return ** information appropriate for that error, where D is the ** [database connection] that was used to open the [BLOB handle] P. */ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); /* ** CAPI3REF: Write Data Into A BLOB Incrementally {H17870} ** ** This function is used to write data into an open [BLOB handle] from a ** caller-supplied buffer. N bytes of data are copied from the buffer Z ** into the open BLOB, starting at offset iOffset. ** ** If the [BLOB handle] passed as the first argument was not opened for ** writing (the flags parameter to [sqlite3_blob_open()] was zero), |
︙ | ︙ | |||
5642 5643 5644 5645 5646 5647 5648 | ** or by other independent statements. ** ** On success, SQLITE_OK is returned. ** Otherwise, an [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** | | | | | | | | | | | | 5641 5642 5643 5644 5645 5646 5647 5648 5649 5650 5651 5652 5653 5654 5655 5656 5657 5658 5659 5660 5661 5662 5663 5664 5665 5666 5667 5668 5669 5670 5671 5672 5673 5674 5675 5676 5677 5678 5679 5680 5681 5682 5683 5684 5685 5686 5687 5688 5689 5690 5691 5692 5693 5694 5695 | ** or by other independent statements. ** ** On success, SQLITE_OK is returned. ** Otherwise, an [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** ** {H17873} A successful invocation of [sqlite3_blob_write(P,Z,N,X)] ** shall write N bytes of data from buffer Z into the BLOB ** referenced by [BLOB handle] P beginning at offset X into ** the BLOB. ** ** {H17874} In the absence of other overridding changes, the changes ** written to a BLOB by [sqlite3_blob_write()] shall ** remain in effect after the associated [BLOB handle] expires. ** ** {H17875} If the [BLOB handle] P was opened for reading only then ** an invocation of [sqlite3_blob_write(P,Z,N,X)] shall leave ** the referenced BLOB unchanged and return [SQLITE_READONLY]. ** ** {H17876} If the size of the BLOB referenced by [BLOB handle] P is ** less than N+X bytes then [sqlite3_blob_write(P,Z,N,X)] shall ** leave the BLOB unchanged and return [SQLITE_ERROR]. ** ** {H17877} If the [BLOB handle] P is expired and X and N are within bounds ** then [sqlite3_blob_read(P,Z,N,X)] shall leave the BLOB ** unchanged and return [SQLITE_ABORT]. ** ** {H17879} If X or N are less than zero then [sqlite3_blob_write(P,Z,N,X)] ** shall leave the BLOB referenced by [BLOB handle] P unchanged ** and return [SQLITE_ERROR]. ** ** {H17882} The [sqlite3_blob_write(P,Z,N,X)] interface shall return ** [SQLITE_OK] if N bytes where successfully written into the BLOB. ** ** {H17885} If the requested write could not be completed, ** the [sqlite3_blob_write(P,Z,N,X)] interface shall return an ** appropriate [error code] or [extended error code]. ** ** {H17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)] ** then subsequent calls to [sqlite3_errcode(D)], ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return ** information appropriate for that error. */ int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); /* ** CAPI3REF: Virtual File System Objects {H11200} ** ** A virtual filesystem (VFS) is an [sqlite3_vfs] object ** that SQLite uses to interact ** with the underlying operating system. Most SQLite builds come with a ** single default VFS that is appropriate for the host computer. ** New VFSes can be registered and existing VFSes can be unregistered. ** The following interfaces are provided. |
︙ | ︙ | |||
5712 5713 5714 5715 5716 5717 5718 | ** ** Unregister a VFS with the sqlite3_vfs_unregister() interface. ** If the default VFS is unregistered, another VFS is chosen as ** the default. The choice for the new VFS is arbitrary. ** ** INVARIANTS: ** | | | | | | | | | 5711 5712 5713 5714 5715 5716 5717 5718 5719 5720 5721 5722 5723 5724 5725 5726 5727 5728 5729 5730 5731 5732 5733 5734 5735 5736 5737 5738 5739 5740 5741 5742 5743 5744 5745 5746 5747 5748 5749 5750 5751 5752 5753 5754 | ** ** Unregister a VFS with the sqlite3_vfs_unregister() interface. ** If the default VFS is unregistered, another VFS is chosen as ** the default. The choice for the new VFS is arbitrary. ** ** INVARIANTS: ** ** {H11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the ** registered [sqlite3_vfs] object whose name exactly matches ** the zero-terminated UTF-8 string N, or it returns NULL if ** there is no match. ** ** {H11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then ** the function returns a pointer to the default [sqlite3_vfs] ** object if there is one, or NULL if there is no default ** [sqlite3_vfs] object. ** ** {H11209} The [sqlite3_vfs_register(P,F)] interface registers the ** well-formed [sqlite3_vfs] object P using the name given ** by the zName field of the object. ** ** {H11212} Using the [sqlite3_vfs_register(P,F)] interface to register ** the same [sqlite3_vfs] object multiple times is a harmless no-op. ** ** {H11215} The [sqlite3_vfs_register(P,F)] interface makes the [sqlite3_vfs] ** object P the default [sqlite3_vfs] object if F is non-zero. ** ** {H11218} The [sqlite3_vfs_unregister(P)] interface unregisters the ** [sqlite3_vfs] object P so that it is no longer returned by ** subsequent calls to [sqlite3_vfs_find()]. */ sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); int sqlite3_vfs_unregister(sqlite3_vfs*); /* ** CAPI3REF: Mutexes {H17000} ** ** The SQLite core uses these routines for thread ** synchronization. Though they are intended for internal ** use by SQLite, code that links against SQLite is ** permitted to use any of these routines. ** ** The SQLite source code contains multiple implementations |
︙ | ︙ | |||
5774 5775 5776 5777 5778 5779 5780 | ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex ** implementation is included with the library. In this case the ** application must supply a custom mutex implementation using the ** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function ** before calling sqlite3_initialize() or any other public sqlite3_ ** function that calls sqlite3_initialize(). ** | | | | | | | | | | | | | | | | | | | | | | | | | 5773 5774 5775 5776 5777 5778 5779 5780 5781 5782 5783 5784 5785 5786 5787 5788 5789 5790 5791 5792 5793 5794 5795 5796 5797 5798 5799 5800 5801 5802 5803 5804 5805 5806 5807 5808 5809 5810 5811 5812 5813 5814 5815 5816 5817 5818 5819 5820 5821 5822 5823 5824 5825 5826 5827 5828 5829 5830 5831 5832 5833 5834 5835 5836 5837 5838 5839 5840 5841 5842 5843 5844 5845 5846 5847 5848 5849 5850 5851 5852 5853 5854 5855 5856 5857 5858 5859 5860 5861 5862 5863 5864 5865 5866 5867 5868 5869 5870 5871 5872 5873 5874 5875 5876 5877 5878 5879 5880 5881 5882 5883 5884 5885 5886 5887 5888 5889 5890 5891 5892 5893 5894 5895 5896 | ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex ** implementation is included with the library. In this case the ** application must supply a custom mutex implementation using the ** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function ** before calling sqlite3_initialize() or any other public sqlite3_ ** function that calls sqlite3_initialize(). ** ** {H17011} The sqlite3_mutex_alloc() routine allocates a new ** mutex and returns a pointer to it. {H17012} If it returns NULL ** that means that a mutex could not be allocated. {H17013} SQLite ** will unwind its stack and return an error. {H17014} The argument ** to sqlite3_mutex_alloc() is one of these integer constants: ** ** <ul> ** <li> SQLITE_MUTEX_FAST ** <li> SQLITE_MUTEX_RECURSIVE ** <li> SQLITE_MUTEX_STATIC_MASTER ** <li> SQLITE_MUTEX_STATIC_MEM ** <li> SQLITE_MUTEX_STATIC_MEM2 ** <li> SQLITE_MUTEX_STATIC_PRNG ** <li> SQLITE_MUTEX_STATIC_LRU ** <li> SQLITE_MUTEX_STATIC_LRU2 ** </ul> ** ** {H17015} The first two constants cause sqlite3_mutex_alloc() to create ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE ** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END} ** The mutex implementation does not need to make a distinction ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does ** not want to. {H17016} But SQLite will only request a recursive mutex in ** cases where it really needs one. {END} If a faster non-recursive mutex ** implementation is available on the host platform, the mutex subsystem ** might return such a mutex in response to SQLITE_MUTEX_FAST. ** ** {H17017} The other allowed parameters to sqlite3_mutex_alloc() each return ** a pointer to a static preexisting mutex. {END} Four static mutexes are ** used by the current version of SQLite. Future versions of SQLite ** may add additional static mutexes. Static mutexes are for internal ** use by SQLite only. Applications that use SQLite mutexes should ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or ** SQLITE_MUTEX_RECURSIVE. ** ** {H17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() ** returns a different mutex on every call. {H17034} But for the static ** mutex types, the same mutex is returned on every call that has ** the same type number. ** ** {H17019} The sqlite3_mutex_free() routine deallocates a previously ** allocated dynamic mutex. {H17020} SQLite is careful to deallocate every ** dynamic mutex that it allocates. {A17021} The dynamic mutexes must not be in ** use when they are deallocated. {A17022} Attempting to deallocate a static ** mutex results in undefined behavior. {H17023} SQLite never deallocates ** a static mutex. {END} ** ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt ** to enter a mutex. {H17024} If another thread is already within the mutex, ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return ** SQLITE_BUSY. {H17025} The sqlite3_mutex_try() interface returns [SQLITE_OK] ** upon successful entry. {H17026} Mutexes created using ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. ** {H17027} In such cases the, ** mutex must be exited an equal number of times before another thread ** can enter. {A17028} If the same thread tries to enter any other ** kind of mutex more than once, the behavior is undefined. ** {H17029} SQLite will never exhibit ** such behavior in its own use of mutexes. ** ** Some systems (for example, Windows 95) do not support the operation ** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() ** will always return SQLITE_BUSY. {H17030} The SQLite core only ever uses ** sqlite3_mutex_try() as an optimization so this is acceptable behavior. ** ** {H17031} The sqlite3_mutex_leave() routine exits a mutex that was ** previously entered by the same thread. {A17032} The behavior ** is undefined if the mutex is not currently entered by the ** calling thread or is not currently allocated. {H17033} SQLite will ** never do either. {END} ** ** If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or ** sqlite3_mutex_leave() is a NULL pointer, then all three routines ** behave as no-ops. ** ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. */ sqlite3_mutex *sqlite3_mutex_alloc(int); void sqlite3_mutex_free(sqlite3_mutex*); void sqlite3_mutex_enter(sqlite3_mutex*); int sqlite3_mutex_try(sqlite3_mutex*); void sqlite3_mutex_leave(sqlite3_mutex*); /* ** CAPI3REF: Mutex Methods Object {H17120} ** ** An instance of this structure defines the low-level routines ** used to allocate and use mutexes. ** ** Usually, the default mutex implementations provided by SQLite are ** sufficient, however the user has the option of substituting a custom ** implementation for specialized deployments or systems for which SQLite ** does not provide a suitable implementation. In this case, the user ** creates and populates an instance of this structure to pass ** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option. ** Additionally, an instance of this structure can be used as an ** output variable when querying the system for the current mutex ** implementation, using the [SQLITE_CONFIG_GETMUTEX] option. ** ** The xMutexInit method defined by this structure is invoked as ** part of system initialization by the sqlite3_initialize() function. ** {H17001} The xMutexInit routine shall be called by SQLite once for each ** effective call to [sqlite3_initialize()]. ** ** The xMutexEnd method defined by this structure is invoked as ** part of system shutdown by the sqlite3_shutdown() function. The ** implementation of this method is expected to release all outstanding ** resources obtained by the mutex methods implementation, especially ** those obtained by the xMutexInit method. {H17003} The xMutexEnd() ** interface shall be invoked once for each call to [sqlite3_shutdown()]. ** ** The remaining seven methods defined by this structure (xMutexAlloc, ** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and ** xMutexNotheld) implement the following interfaces (respectively): ** ** <ul> |
︙ | ︙ | |||
5922 5923 5924 5925 5926 5927 5928 | int (*xMutexTry)(sqlite3_mutex *); void (*xMutexLeave)(sqlite3_mutex *); int (*xMutexHeld)(sqlite3_mutex *); int (*xMutexNotheld)(sqlite3_mutex *); }; /* | | | | | | | | | | | | | | | | | | | | | 5921 5922 5923 5924 5925 5926 5927 5928 5929 5930 5931 5932 5933 5934 5935 5936 5937 5938 5939 5940 5941 5942 5943 5944 5945 5946 5947 5948 5949 5950 5951 5952 5953 5954 5955 5956 5957 5958 5959 5960 5961 5962 5963 5964 5965 5966 5967 5968 5969 5970 5971 5972 5973 5974 5975 5976 5977 5978 5979 5980 5981 5982 5983 5984 5985 5986 5987 5988 5989 5990 5991 5992 5993 5994 5995 5996 5997 5998 5999 6000 6001 6002 6003 6004 6005 6006 6007 6008 6009 6010 6011 6012 6013 6014 6015 6016 6017 6018 6019 6020 6021 6022 6023 6024 6025 6026 6027 6028 6029 6030 6031 6032 6033 6034 6035 6036 6037 6038 6039 6040 6041 6042 6043 6044 6045 | int (*xMutexTry)(sqlite3_mutex *); void (*xMutexLeave)(sqlite3_mutex *); int (*xMutexHeld)(sqlite3_mutex *); int (*xMutexNotheld)(sqlite3_mutex *); }; /* ** CAPI3REF: Mutex Verification Routines {H17080} ** ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines ** are intended for use inside assert() statements. {H17081} The SQLite core ** never uses these routines except inside an assert() and applications ** are advised to follow the lead of the core. {H17082} The core only ** provides implementations for these routines when it is compiled ** with the SQLITE_DEBUG flag. {A17087} External mutex implementations ** are only required to provide these routines if SQLITE_DEBUG is ** defined and if NDEBUG is not defined. ** ** {H17083} These routines should return true if the mutex in their argument ** is held or not held, respectively, by the calling thread. ** ** {X17084} The implementation is not required to provided versions of these ** routines that actually work. If the implementation does not provide working ** versions of these routines, it should at least provide stubs that always ** return true so that one does not get spurious assertion failures. ** ** {H17085} If the argument to sqlite3_mutex_held() is a NULL pointer then ** the routine should return 1. {END} This seems counter-intuitive since ** clearly the mutex cannot be held if it does not exist. But the ** the reason the mutex does not exist is because the build is not ** using mutexes. And we do not want the assert() containing the ** call to sqlite3_mutex_held() to fail, so a non-zero return is ** the appropriate thing to do. {H17086} The sqlite3_mutex_notheld() ** interface should also return 1 when given a NULL pointer. */ int sqlite3_mutex_held(sqlite3_mutex*); int sqlite3_mutex_notheld(sqlite3_mutex*); /* ** CAPI3REF: Mutex Types {H17001} ** ** {H17002} The [sqlite3_mutex_alloc()] interface takes a single argument ** which is one of these integer constants. */ #define SQLITE_MUTEX_FAST 0 #define SQLITE_MUTEX_RECURSIVE 1 #define SQLITE_MUTEX_STATIC_MASTER 2 #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ #define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */ #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ #define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */ /* ** CAPI3REF: Low-Level Control Of Database Files {H11300} ** ** {H11301} The [sqlite3_file_control()] interface makes a direct call to the ** xFileControl method for the [sqlite3_io_methods] object associated ** with a particular database identified by the second argument. {H11302} The ** name of the database is the name assigned to the database by the ** <a href="lang_attach.html">ATTACH</a> SQL command that opened the ** database. {H11303} To control the main database file, use the name "main" ** or a NULL pointer. {H11304} The third and fourth parameters to this routine ** are passed directly through to the second and third parameters of ** the xFileControl method. {H11305} The return value of the xFileControl ** method becomes the return value of this routine. ** ** {H11306} If the second parameter (zDbName) does not match the name of any ** open database file, then SQLITE_ERROR is returned. {H11307} This error ** code is not remembered and will not be recalled by [sqlite3_errcode()] ** or [sqlite3_errmsg()]. {A11308} The underlying xFileControl method might ** also return SQLITE_ERROR. {A11309} There is no way to distinguish between ** an incorrect zDbName and an SQLITE_ERROR return from the underlying ** xFileControl method. {END} ** ** See also: [SQLITE_FCNTL_LOCKSTATE] */ int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); /* ** CAPI3REF: Testing Interface {H11400} ** ** The sqlite3_test_control() interface is used to read out internal ** state of SQLite and to inject faults into SQLite for testing ** purposes. The first parameter is an operation code that determines ** the number, meaning, and operation of all subsequent parameters. ** ** This interface is not for use by applications. It exists solely ** for verifying the correct operation of the SQLite library. Depending ** on how the SQLite library is compiled, this interface might not exist. ** ** The details of the operation codes, their meanings, the parameters ** they take, and what they do are all subject to change without notice. ** Unlike most of the SQLite API, this function is not guaranteed to ** operate consistently from one release to the next. */ int sqlite3_test_control(int op, ...); /* ** CAPI3REF: Testing Interface Operation Codes {H11410} ** ** These constants are the valid operation code parameters used ** as the first argument to [sqlite3_test_control()]. ** ** These parameters and their meanings are subject to change ** without notice. These values are for testing purposes only. ** Applications should not use any of these parameters or the ** [sqlite3_test_control()] interface. */ #define SQLITE_TESTCTRL_PRNG_SAVE 5 #define SQLITE_TESTCTRL_PRNG_RESTORE 6 #define SQLITE_TESTCTRL_PRNG_RESET 7 #define SQLITE_TESTCTRL_BITVEC_TEST 8 #define SQLITE_TESTCTRL_FAULT_INSTALL 9 #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 /* ** CAPI3REF: SQLite Runtime Status {H17200} ** ** This interface is used to retrieve runtime status information ** about the preformance of SQLite, and optionally to reset various ** highwater marks. The first argument is an integer code for ** the specific parameter to measure. Recognized integer codes ** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...]. ** The current value of the parameter is returned into *pCurrent. |
︙ | ︙ | |||
6064 6065 6066 6067 6068 6069 6070 | ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. */ int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); /* | | | 6063 6064 6065 6066 6067 6068 6069 6070 6071 6072 6073 6074 6075 6076 6077 | ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. */ int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); /* ** CAPI3REF: Status Parameters {H17250} ** ** These integer constants designate various run-time status parameters ** that can be returned by [sqlite3_status()]. ** ** <dl> ** <dt>SQLITE_STATUS_MEMORY_USED</dt> ** <dd>This parameter is the current amount of memory checked out |
︙ | ︙ |