Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Update SQLite to version 3.5.9. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
a85cc7ce8de57cd9df400dc8e253ba93 |
User & Date: | drh 2008-05-15 13:37:49.000 |
Context
2008-05-15
| ||
15:23 | Added 'wiki commit'. Minor stylistic cleanups. ... (check-in: cde6e7a3 user: stephan tags: trunk) | |
13:37 | Update SQLite to version 3.5.9. ... (check-in: a85cc7ce user: drh tags: trunk) | |
13:35 | Fix compiler warnings in wiki.c. ... (check-in: a51699a7 user: drh tags: trunk) | |
Changes
Changes to src/sqlite3.c.
more than 10,000 changes
Changes to src/sqlite3.h.
︙ | ︙ | |||
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.312 2008/05/12 12:39:56 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++. |
︙ | ︙ | |||
65 66 67 68 69 70 71 | /* ** CAPI3REF: Compile-Time Library Version Numbers {F10010} ** ** 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. ** | | | 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 | /* ** CAPI3REF: Compile-Time Library Version Numbers {F10010} ** ** 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 |
︙ | ︙ | |||
89 90 91 92 93 94 95 | ** evaluates to a string literal that is the SQLite version ** with which the header file is associated. ** ** {F10014} The SQLITE_VERSION_NUMBER #define resolves 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. */ | | | | 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 | ** evaluates to a string literal that is the SQLite version ** with which the header file is associated. ** ** {F10014} The SQLITE_VERSION_NUMBER #define resolves 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. */ #define SQLITE_VERSION "3.5.9" #define SQLITE_VERSION_NUMBER 3005009 /* ** CAPI3REF: Run-Time Library Version Numbers {F10020} ** KEYWORDS: sqlite3_version ** ** These features provide the same information as the [SQLITE_VERSION] ** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated |
︙ | ︙ | |||
128 129 130 131 132 133 134 | int sqlite3_libversion_number(void); /* ** CAPI3REF: Test To See If The Library Is Threadsafe {F10100} ** ** SQLite can be compiled with or without mutexes. When ** the SQLITE_THREADSAFE C preprocessor macro is true, mutexes | | | 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 | int sqlite3_libversion_number(void); /* ** CAPI3REF: Test To See If The Library Is Threadsafe {F10100} ** ** 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 from more than one thread. ** ** There is a measurable performance penalty for enabling mutexes. ** So if speed is of utmost importance, it makes sense to disable ** the mutexes. But for maximum safety, mutexes should be enabled. ** The default behavior is for mutexes to be enabled. |
︙ | ︙ | |||
151 152 153 154 155 156 157 | ** SQLite was compiled with its mutexes enabled or zero ** if SQLite was compiled with mutexes disabled. */ int sqlite3_threadsafe(void); /* ** CAPI3REF: Database Connection Handle {F12000} | | | 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 | ** SQLite was compiled with its mutexes enabled or zero ** if SQLite was compiled with mutexes disabled. */ int sqlite3_threadsafe(void); /* ** CAPI3REF: Database Connection Handle {F12000} ** KEYWORDS: {database connection} {database connections} ** ** Each open SQLite database is represented by 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 |
︙ | ︙ | |||
330 331 332 333 334 335 336 | ** allocated using the equivalent of [sqlite3_mprintf()] and ** *errmsg is made to point to that message. ** ** {F12134} The [sqlite3_exec()] routine does not change the value of ** *errmsg if errmsg is NULL or if there are no errors. ** ** {F12137} The [sqlite3_exec()] function sets the error code and message | | > | 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 | ** allocated using the equivalent of [sqlite3_mprintf()] and ** *errmsg is made to point to that message. ** ** {F12134} The [sqlite3_exec()] routine does not change the value of ** *errmsg if errmsg is NULL or if there are no errors. ** ** {F12137} The [sqlite3_exec()] function sets the error code and message ** accessible via [sqlite3_errcode()], [sqlite3_errmsg()], and ** [sqlite3_errmsg16()]. ** ** LIMITATIONS: ** ** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open ** [database connection]. ** ** {U12142} The database connection must not be closed while |
︙ | ︙ | |||
429 430 431 432 433 434 435 | ** a related primary result code as a prefix. ** ** {F10224} Primary result code names contain a single "_" character. ** ** {F10225} Extended result code names contain two or more "_" characters. ** ** {F10226} The numeric value of an extended result code contains the | | | | 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 | ** a related primary result code as a prefix. ** ** {F10224} Primary result code names contain a single "_" character. ** ** {F10225} Extended result code names contain two or more "_" characters. ** ** {F10226} The numeric value of an extended result code contains 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)) /* ** CAPI3REF: Flags For File Open Operations {F10230} ** ** 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 #define SQLITE_OPEN_READWRITE 0x00000002 #define SQLITE_OPEN_CREATE 0x00000004 |
︙ | ︙ | |||
515 516 517 518 519 520 521 | #define SQLITE_LOCK_PENDING 3 #define SQLITE_LOCK_EXCLUSIVE 4 /* ** CAPI3REF: Synchronization Type Flags {F10260} ** ** When SQLite invokes the xSync() method of an | | | | 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 | #define SQLITE_LOCK_PENDING 3 #define SQLITE_LOCK_EXCLUSIVE 4 /* ** CAPI3REF: Synchronization Type Flags {F10260} ** ** 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 |
︙ | ︙ | |||
548 549 550 551 552 553 554 | const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ }; /* ** CAPI3REF: OS Interface File Virtual Methods Object {F11120} ** ** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to | | | 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 | const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ }; /* ** CAPI3REF: OS Interface File Virtual Methods Object {F11120} ** ** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to ** an instance of this object. This object defines the ** methods used to perform various operations against the open file. ** ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). * The second choice is an ** OS-X style fullsync. The SQLITE_SYNC_DATA flag may be ORed in to ** indicate that only the data of the file and not its inode needs to be |
︙ | ︙ | |||
646 647 648 649 650 651 652 | ** CAPI3REF: Standard File Control Opcodes {F11310} ** ** These integer constants are opcodes for the xFileControl method ** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()] ** interface. ** ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This | | | 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 | ** CAPI3REF: Standard File Control Opcodes {F11310} ** ** These integer constants are opcodes for the xFileControl method ** of the [sqlite3_io_methods] object and to 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 |
︙ | ︙ | |||
682 683 684 685 686 687 688 | ** versions of SQLite. Additional fields may be appended to this ** object when the iVersion value is increased. ** ** The szOsFile field is the size of the subclassed [sqlite3_file] ** structure used by this VFS. mxPathname is the maximum length of ** a pathname in this VFS. ** | | | | 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 | ** versions of SQLite. Additional fields may be appended to this ** object when the iVersion value is increased. ** ** The szOsFile field is the size of the subclassed [sqlite3_file] ** structure used by this VFS. mxPathname is the maximum length of ** a pathname in this VFS. ** ** Registered sqlite3_vfs objects are kept on a linked list formed by ** the pNext pointer. The [sqlite3_vfs_register()] ** and [sqlite3_vfs_unregister()] interfaces manage this list ** in a thread-safe way. The [sqlite3_vfs_find()] interface ** searches the list. ** ** The pNext field is the only field in the sqlite3_vfs ** structure that SQLite will ever modify. SQLite will only access ** 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. |
︙ | ︙ | |||
726 727 728 729 730 731 732 | ** <li> [SQLITE_OPEN_TRANSIENT_DB] ** <li> [SQLITE_OPEN_SUBJOURNAL] ** <li> [SQLITE_OPEN_MASTER_JOURNAL] ** </ul> {END} ** ** The file I/O implementation can use the object type flags to ** changes the way it deals with files. For example, an application | | | | | | | | | | | 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 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 778 779 780 781 782 783 784 785 786 787 788 789 | ** <li> [SQLITE_OPEN_TRANSIENT_DB] ** <li> [SQLITE_OPEN_SUBJOURNAL] ** <li> [SQLITE_OPEN_MASTER_JOURNAL] ** </ul> {END} ** ** The file I/O implementation can use the object type flags to ** changes the way it deals with files. For example, an application ** that does not care about crash recovery or rollback might make ** the open of a journal file a no-op. Writes to this journal would ** also be no-ops, and any attempt to read the journal would return ** SQLITE_IOERR. Or the implementation might recognize that a database ** file will be doing page-aligned sector reads and writes in a random ** order and set up its I/O subsystem accordingly. ** ** SQLite might also add one of the following flags to the xOpen ** method: ** ** <ul> ** <li> [SQLITE_OPEN_DELETEONCLOSE] ** <li> [SQLITE_OPEN_EXCLUSIVE] ** </ul> ** ** {F11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be ** deleted when it is closed. {F11146} The [SQLITE_OPEN_DELETEONCLOSE] ** will be set for TEMP databases, journals and for subjournals. ** {F11147} 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. {END} ** ** {F11148} 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. ** ** {F11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] ** to test for the existance of a file, ** or [SQLITE_ACCESS_READWRITE] to test to see ** if a file is readable and writable, or [SQLITE_ACCESS_READ] ** to test to see if a file is at least readable. {END} The file can be a ** directory. ** ** {F11150} SQLite will always allocate at least mxPathname+1 bytes for ** the output buffers for xGetTempname and xFullPathname. {F11151} 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. As 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 ** included in the VFS structure for completeness. ** The xRandomness() function attempts to return nBytes bytes ** of good-quality randomness into zOut. The return value is ** the actual number of bytes of randomness obtained. The ** xSleep() method causes the calling thread to sleep for at ** least the number of microseconds given. The xCurrentTime() ** method returns a Julian Day Number for the current date and ** time. */ typedef struct sqlite3_vfs sqlite3_vfs; struct sqlite3_vfs { int iVersion; /* Structure version number */ |
︙ | ︙ | |||
809 810 811 812 813 814 815 | }; /* ** CAPI3REF: Flags for the xAccess VFS method {F11190} ** ** {F11191} These integer constants can be used as the third parameter to ** the xAccess method of an [sqlite3_vfs] object. {END} They determine | | | 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 | }; /* ** CAPI3REF: Flags for the xAccess VFS method {F11190} ** ** {F11191} 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. {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method ** simply checks to see if the file exists. {F11193} With ** SQLITE_ACCESS_READWRITE, the xAccess method checks to see ** if the file is both readable and writable. {F11194} With ** SQLITE_ACCESS_READ the xAccess method ** checks to see if the file is readable. */ |
︙ | ︙ | |||
850 851 852 853 854 855 856 | ** CAPI3REF: Last Insert Rowid {F12220} ** ** 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 | | | 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 | ** CAPI3REF: Last Insert Rowid {F12220} ** ** 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. ** ** This routine returns the rowid of the most recent ** successful INSERT into the database from the database connection ** shown in the first argument. If no successful inserts ** have ever occurred on this database connection, zero is returned. ** ** If an INSERT occurs within a trigger, then the rowid of the |
︙ | ︙ | |||
890 891 892 893 894 895 896 | ** ** {F12223} The [sqlite3_last_insert_rowid()] function returns ** same value when called from the same trigger context ** immediately before and after a ROLLBACK. ** ** LIMITATIONS: ** | | | | 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 | ** ** {F12223} The [sqlite3_last_insert_rowid()] function returns ** same value when called from the same trigger context ** immediately before and after a ROLLBACK. ** ** LIMITATIONS: ** ** {U12232} If a separate thread does 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 {F12240} ** ** This function returns the number of database rows that were changed ** or inserted or deleted by the most recently completed SQL statement ** on the 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 ** to find the total number of changes including changes caused by triggers. ** ** A "row change" is a change to a single row of a single table ** caused by an INSERT, DELETE, or UPDATE statement. Rows that ** are changed as side effects of REPLACE constraint resolution, ** rollback, ABORT processing, DROP TABLE, or by any other ** mechanisms do not count as direct row changes. ** ** A "trigger context" is a scope of execution that begins and ** ends with the script of a trigger. Most SQL statements are |
︙ | ︙ | |||
982 983 984 985 986 987 988 | ** are counted as soon as the statement that makes them is completed ** (when the statement handle is passed to [sqlite3_reset()] or ** [sqlite3_finalize()]). ** ** SQLite implements the command "DELETE FROM table" without ** a WHERE clause by dropping and recreating the table. (This is much ** faster than going | | | 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 | ** are counted as soon as the statement that makes them is completed ** (when the statement handle is passed to [sqlite3_reset()] or ** [sqlite3_finalize()]). ** ** SQLite implements the command "DELETE FROM table" without ** a WHERE clause by dropping and recreating the table. (This is much ** faster than going ** through and deleting individual elements from the table.) Because of ** this optimization, the change count for "DELETE FROM table" will be ** zero 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. ** ** See also the [sqlite3_changes()] interface. ** |
︙ | ︙ | |||
1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 | ** [sqlite3_memory_highwater()] is true. The value returned ** by [sqlite3_memory_highwater(1)] is the highwater mark ** prior to the reset. */ sqlite3_int64 sqlite3_memory_used(void); sqlite3_int64 sqlite3_memory_highwater(int resetFlag); /* ** CAPI3REF: Compile-Time Authorization Callbacks {F12500} ** ** This routine registers a authorizer callback with a particular | > > > > > > > > > > > > > > > > > > > > > > > > > | | | | | | > | | > > > > > | 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 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 1672 1673 1674 1675 1676 1677 1678 1679 | ** [sqlite3_memory_highwater()] is true. The value returned ** by [sqlite3_memory_highwater(1)] is the highwater mark ** prior to the reset. */ sqlite3_int64 sqlite3_memory_used(void); sqlite3_int64 sqlite3_memory_highwater(int resetFlag); /* ** CAPI3REF: Pseudo-Random Number Generator {F17390} ** ** 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 ** appliations 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: ** ** {F17392} 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 {F12500} ** ** 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 ** to perform various actions, the authorizer callback is invoked to ** see if those actions are allowed. The authorizer callback should ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the ** specific action but allow the SQL statement to continue to be ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be ** rejected with an error. If the authorizer callback returns ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] ** then [sqlite3_prepare_v2()] or equivalent call that triggered ** the authorizer will fail with an error message. ** ** When the callback returns [SQLITE_OK], that means the operation ** requested is ok. When the callback returns [SQLITE_DENY], the ** [sqlite3_prepare_v2()] or equivalent call that triggered the ** authorizer will fail with an error message explaining that ** access is denied. If the authorizer code is [SQLITE_READ] ** and the callback returns [SQLITE_IGNORE] then the ** [prepared statement] statement is constructed to substitute ** a NULL value in place of the table column that would have ** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE] ** return can be used to deny an untrusted user access to individual ** columns of a table. ** ** The first parameter to the authorizer callback is a copy of ** the third parameter to the sqlite3_set_authorizer() interface. ** The second parameter to the callback is an integer ** [SQLITE_COPY | action code] that specifies the particular action ** to be authorized. The third through sixth ** parameters to the callback are zero-terminated strings that contain ** additional details about the action to be authorized. ** ** An authorizer is used when [sqlite3_prepare | preparing] ** SQL statements from an untrusted ** source, to ensure that the SQL statements do not try to access data ** that they are not allowed to see, or that they do not try to ** execute malicious statements that damage the database. For ** example, an application may allow a user to enter arbitrary ** SQL queries for evaluation by a database. But the application does ** not want the user to be able to make arbitrary changes to the ** database. An authorizer could then be put in place while the ** user-entered SQL is being [sqlite3_prepare | prepared] that ** disallows everything except [SELECT] statements. ** ** Applications that need to process SQL from untrusted sources ** might also consider lowering resource limits using [sqlite3_limit()] ** and limiting database size using the [max_page_count] [PRAGMA] ** in addition to using an authorizer. ** ** Only a single authorizer can be in place on a database connection ** at a time. Each call to sqlite3_set_authorizer overrides the ** previous call. Disable the authorizer by installing a NULL callback. ** The authorizer is disabled by default. ** ** Note that the authorizer callback is invoked only during |
︙ | ︙ | |||
1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 | ** if the file is write protected. In either case the database ** must already exist or an error is returned. The third option ** opens the database for reading and writing and creates it if it does ** not already exist. ** The third options is behavior that is always used for [sqlite3_open()] ** and [sqlite3_open16()]. ** ** If the filename is ":memory:", then an private ** in-memory database is created for the connection. This in-memory ** database will vanish when the database connection is closed. Future ** version of SQLite might make use of additional special filenames ** that begin with the ":" character. It is recommended that ** when a database filename really does begin with ** ":" that you prefix the filename with a pathname like "./" to | > > > | 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 | ** if the file is write protected. In either case the database ** must already exist or an error is returned. The third option ** opens the database for reading and writing and creates it if it does ** not already exist. ** The third options is behavior that is always used for [sqlite3_open()] ** and [sqlite3_open16()]. ** ** If the 3rd parameter to [sqlite3_open_v2()] is not one of the ** combinations shown above then the behavior is undefined. ** ** If the filename is ":memory:", then an private ** in-memory database is created for the connection. This in-memory ** database will vanish when the database connection is closed. Future ** version of SQLite might make use of additional special filenames ** that begin with the ":" character. It is recommended that ** when a database filename really does begin with ** ":" that you prefix the filename with a pathname like "./" to |
︙ | ︙ | |||
2026 2027 2028 2029 2030 2031 2032 | ** ** {F12717} 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> ** | | | | 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 | ** ** {F12717} 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> ** ** {F12719} If the filename is NULL or an empty string, then a private, ** ephermeral on-disk database will be created. ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required ** in sqlite3_open_v2()?</todo> ** ** {F12721} 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 is V is a NULL pointer. |
︙ | ︙ | |||
2065 2066 2067 2068 2069 2070 2071 | ** 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 UTF8 or UTF16 respectively. ** Memory to hold the error message string is managed internally. ** The application does not need to worry with freeing the result. | | | | < < < < | | < < < < | 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 | ** 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 UTF8 or UTF16 respectively. ** Memory to hold the error message string is managed internally. ** The application does not need to worry with freeing the result. ** However, the error string might be overwritten or deallocated by ** subsequent calls to other SQLite interface functions. ** ** INVARIANTS: ** ** {F12801} The [sqlite3_errcode(D)] interface returns the numeric ** [SQLITE_OK | result code] or ** [SQLITE_IOERR_READ | extended result code] ** for the most recently failed interface call associated ** with [database connection] D. ** ** {F12803} 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 UTF8 or UTF16 respectively. ** ** {F12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()] ** are valid until the next SQLite interface call. ** ** {F12808} 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()]. ** ** {F12809} Interfaces that are not associated with a specific |
︙ | ︙ | |||
2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 | ** </ol> ** ** Refer to documentation on individual methods above for additional ** information. */ typedef struct sqlite3_stmt sqlite3_stmt; /* ** CAPI3REF: Compiling An SQL Statement {F13010} ** ** 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 an [database connection] ** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()] ** or [sqlite3_open16()]. ** The second argument "zSql" is the statement to be compiled, encoded ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2() ** use UTF-16. {END} ** ** If the nByte argument is less ** than zero, then zSql is read up to the first zero terminator. ** If nByte is non-negative, then it is the maximum number of ** bytes read from zSql. When nByte is non-negative, the ** zSql string ends at either the first '\000' or '\u0000' character or | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | > > > > | | 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 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 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 | ** </ol> ** ** Refer to documentation on individual methods above for additional ** information. */ typedef struct sqlite3_stmt sqlite3_stmt; /* ** CAPI3REF: Run-time Limits {F12760} ** ** 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. ** ** If the new limit is a negative number, the limit is unchanged. ** For the limit category of SQLITE_LIMIT_XYZ there is a hard upper ** bound set by a compile-time C-preprocess macro named SQLITE_MAX_XYZ. ** (The "_LIMIT_" in the name is changed to "_MAX_".) ** Attempts to increase a limit above its hard upper bound are ** silently truncated to the hard upper limit. ** ** Run time limits are intended for use in applications that manage ** both their own internal database and also databases that are controlled ** by untrusted external sources. An example application might be a ** webbrowser that has its own databases for storing history and ** separate databases controlled by javascript applications downloaded ** off the internet. The internal databases can be given the ** large, default limits. Databases managed by external sources can ** be given much smaller limits designed to prevent a denial of service ** attach. Developers might also want to use the [sqlite3_set_authorizer()] ** interface to further control untrusted SQL. The size of the database ** created by an untrusted script can be contained using the ** [max_page_count] [PRAGMA]. ** ** This interface is currently considered experimental and is subject ** to change or removal without prior notice. ** ** INVARIANTS: ** ** {F12762} A successful call to [sqlite3_limit(D,C,V)] where V is ** positive changes the ** limit on the size of construct C in [database connection] D ** to the lessor of V and the hard upper bound on the size ** of C that is set at compile-time. ** ** {F12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative ** leaves the state of [database connection] D unchanged. ** ** {F12769} A successful call to [sqlite3_limit(D,C,V)] returns the ** value of the limit on the size of construct C in ** in [database connection] D as it was prior to the call. */ int sqlite3_limit(sqlite3*, int id, int newVal); /* ** CAPI3REF: Run-Time Limit Categories {F12790} ** 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> ** <dt>SQLITE_LIMIT_LENGTH</dt> ** <dd>The maximum size of any ** string or blob or table row.<dd> ** ** <dt>SQLITE_LIMIT_SQL_LENGTH</dt> ** <dd>The maximum length of an SQL statement.</dd> ** ** <dt>SQLITE_LIMIT_COLUMN</dt> ** <dd>The maximum number of columns in a table definition or in the ** result set of a SELECT or the maximum number of columns in an index ** or in an ORDER BY or GROUP BY clause.</dd> ** ** <dt>SQLITE_LIMIT_EXPR_DEPTH</dt> ** <dd>The maximum depth of the parse tree on any expression.</dd> ** ** <dt>SQLITE_LIMIT_COMPOUND_SELECT</dt> ** <dd>The maximum number of terms in a compound SELECT statement.</dd> ** ** <dt>SQLITE_LIMIT_VDBE_OP</dt> ** <dd>The maximum number of instructions in a virtual machine program ** used to implement an SQL statement.</dd> ** ** <dt>SQLITE_LIMIT_FUNCTION_ARG</dt> ** <dd>The maximum number of arguments on a function.</dd> ** ** <dt>SQLITE_LIMIT_ATTACHED</dt> ** <dd>The maximum number of attached databases.</dd> ** ** <dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt> ** <dd>The maximum length of the pattern argument to the LIKE or ** GLOB operators.</dd> ** ** <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt> ** <dd>The maximum number of variables in an SQL statement that can ** be bound.</dd> ** </dl> */ #define SQLITE_LIMIT_LENGTH 0 #define SQLITE_LIMIT_SQL_LENGTH 1 #define SQLITE_LIMIT_COLUMN 2 #define SQLITE_LIMIT_EXPR_DEPTH 3 #define SQLITE_LIMIT_COMPOUND_SELECT 4 #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 {F13010} ** ** 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 an [database connection] ** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()] ** or [sqlite3_open16()]. ** The second argument "zSql" is the statement to be compiled, encoded ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2() ** use UTF-16. {END} ** ** If the nByte argument is less ** than zero, then zSql is read up to the first zero terminator. ** If nByte is non-negative, then it is the maximum number of ** bytes read from zSql. When nByte is non-negative, the ** zSql string ends at either the first '\000' or '\u0000' character or ** the nByte-th byte, whichever comes first. If the caller knows ** that the supplied string is nul-terminated, then there is a small ** performance advantage to be had by passing an nByte parameter that ** is equal to the number of bytes in the input string <i>including</i> ** the nul-terminator bytes.{END} ** ** *pzTail is made to point to the first byte past the end of the ** first SQL statement in zSql. These routines only compiles the first ** statement in zSql, so *pzTail is left pointing to what remains ** uncompiled. ** ** *ppStmt is left pointing to a compiled [prepared statement] that can be ** executed using [sqlite3_step()]. Or if there is an error, *ppStmt is ** set to NULL. If the input text contains no SQL (if the input ** is and empty string or a comment) then *ppStmt is set to NULL. ** {U13018} The calling procedure is responsible for deleting the ** compiled SQL statement ** using [sqlite3_finalize()] after it has finished with it. ** ** On success, [SQLITE_OK] is returned. Otherwise an |
︙ | ︙ | |||
2218 2219 2220 2221 2222 2223 2224 | ** text in their zSql parameter as UTF-16 in the native byte order. ** ** {F13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] ** and its variants is less than zero, then SQL text is ** read from zSql is read up to the first zero terminator. ** ** {F13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] | | > > > > | 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 | ** text in their zSql parameter as UTF-16 in the native byte order. ** ** {F13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] ** and its variants is less than zero, then SQL text is ** read from zSql is read up to the first zero terminator. ** ** {F13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] ** and its variants is non-negative, then at most nBytes bytes ** SQL text is read from zSql. ** ** {F13015} 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> ** ** {F13016} 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. ** ** {F13019} The [sqlite3_prepare_v2()] interface and its variants return ** [SQLITE_OK] or an appropriate [error code] upon failure. ** ** {F13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its ** variants returns an error (any value other than [SQLITE_OK]) ** it first sets *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. */ sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
︙ | ︙ | |||
2293 2294 2295 2296 2297 2298 2299 2300 2301 | ** {F13103} 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 {F15000} ** ** SQLite uses the sqlite3_value object to represent all values | > | > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 | ** {F13103} 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 {F15000} ** 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 ** be integers, floating point values, strings, BLOBs, or NULL. ** ** An sqlite3_value object may be either "protected" or "unprotected". ** Some interfaces require a protected sqlite3_value. Other interfaces ** will accept either a protected or an unprotected sqlite3_value. ** Every interface that accepts sqlite3_value arguments specifies ** whether or not it requires a protected sqlite3_value. ** ** The terms "protected" and "unprotected" refer to whether or not ** a mutex is held. A internal mutex is held for a protected ** sqlite3_value object but no mutex is held for an unprotected ** sqlite3_value object. If SQLite is compiled to be single-threaded ** (with SQLITE_THREADSAFE=0 and with [sqlite3_threadsafe()] returning 0) ** then there is no distinction between ** protected and unprotected sqlite3_value objects and they can be ** used interchangable. However, for maximum code portability it ** is recommended that applications make the distinction between ** between protected and unprotected sqlite3_value objects even if ** they are single threaded. ** ** The sqlite3_value objects that are passed as parameters into the ** implementation of application-defined SQL functions are protected. ** The sqlite3_value object returned by ** [sqlite3_column_value()] is unprotected. ** Unprotected sqlite3_value objects may only be used with ** [sqlite3_result_value()] and [sqlite3_bind_value()]. All other ** interfaces that use sqlite3_value require protected sqlite3_value objects. */ typedef struct Mem sqlite3_value; /* ** CAPI3REF: SQL Function Context Object {F16001} ** ** The context in which an SQL function executes is stored in an |
︙ | ︙ | |||
2350 2351 2352 2353 2354 2355 2356 | ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). ** ** The third argument is the value to bind to the parameter. ** ** In those ** routines that have a fourth argument, its value is the number of bytes ** in the parameter. To be clear: the value is the number of <u>bytes</u> | | < | 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 | ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). ** ** The third argument is the value to bind to the parameter. ** ** In those ** routines that have a fourth argument, its value is the number of bytes ** in the parameter. To be clear: the value is the number of <u>bytes</u> ** in the value, not the number of characters. ** If the fourth parameter is negative, the length of the string is ** number of bytes up to the first zero terminator. ** ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or ** string after SQLite has finished with it. If the fifth argument is ** the special value [SQLITE_STATIC], then SQLite assumes that the |
︙ | ︙ | |||
2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 | ** [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 ** V value after it has finished using the V value. ** ** {F13548} 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. */ 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*)); | > > > > | 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 | ** [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 ** V value after it has finished using the V value. ** ** {F13548} 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. ** ** {F13551} 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*)); |
︙ | ︙ | |||
2503 2504 2505 2506 2507 2508 2509 | int sqlite3_bind_parameter_count(sqlite3_stmt*); /* ** CAPI3REF: Name Of A Host Parameter {F13620} ** ** This routine returns a pointer to the name of the n-th ** SQL parameter in a [prepared statement]. | | | > | | | < | 2675 2676 2677 2678 2679 2680 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 | int sqlite3_bind_parameter_count(sqlite3_stmt*); /* ** CAPI3REF: Name Of A Host Parameter {F13620} ** ** 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 "?" ** is included as part of the name. ** Parameters of the form "?" without a following integer have no name. ** ** The first host parameter has an index of 1, not 0. ** ** If the value n is out of range or if the n-th parameter is ** nameless, then NULL is returned. The returned string is ** always in the UTF-8 encoding even if the named parameter was ** originally specified as UTF-16 in [sqlite3_prepare16()] or ** [sqlite3_prepare16_v2()]. ** ** See also: [sqlite3_bind_blob|sqlite3_bind()], ** [sqlite3_bind_parameter_count()], and ** [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** ** {F13621} The [sqlite3_bind_parameter_name(S,N)] interface returns ** a UTF-8 rendering of the name of the SQL parameter in ** [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 {F13640} ** ** Return the index of an SQL parameter given its name. The |
︙ | ︙ | |||
2825 2826 2827 2828 2829 2830 2831 | ** The details of the behavior of this sqlite3_step() interface depend ** on whether the statement was prepared using the newer "v2" interface ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the ** new "v2" interface is recommended for new applications but the legacy ** interface will continue to be supported. ** | | | 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 | ** The details of the behavior of this sqlite3_step() interface depend ** on whether the statement was prepared using the newer "v2" interface ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the ** new "v2" interface is recommended for new applications but the legacy ** interface will continue to be supported. ** ** In the legacy interface, the return value will be either [SQLITE_BUSY], ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. ** With the "v2" interface, any of the other [SQLITE_OK | result code] ** or [SQLITE_IOERR_READ | extended result code] might be returned as ** well. ** ** [SQLITE_BUSY] means that the database engine was unable to acquire the ** database locks it needs to do its job. If the statement is a COMMIT |
︙ | ︙ | |||
3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 | ** even empty strings, are always zero terminated. The return ** value from sqlite3_column_blob() for a zero-length blob is an arbitrary ** pointer, possibly even a NULL pointer. ** ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() ** but leaves the result in UTF-16 in native byte order instead of UTF-8. ** The zero terminator is not included in this count. ** ** These routines attempt to convert the value where appropriate. For ** example, if the internal representation is FLOAT and a text result ** is requested, [sqlite3_snprintf()] is used internally to do the conversion ** automatically. The following table details the conversions that ** are applied: ** | > > > > > > > > > | 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 | ** even empty strings, are always zero terminated. The return ** value from sqlite3_column_blob() for a zero-length blob is an arbitrary ** pointer, possibly even a NULL pointer. ** ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() ** but leaves the result in UTF-16 in native byte order instead of UTF-8. ** The zero terminator is not included in this count. ** ** The object returned by [sqlite3_column_value()] is an ** [unprotected sqlite3_value] object. An unprotected sqlite3_value object ** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()]. ** If the [unprotected sqlite3_value] object returned by ** [sqlite3_column_value()] is used in any other way, including calls ** to routines like ** [sqlite3_value_int()], [sqlite3_value_text()], or [sqlite3_value_bytes()], ** then the behavior is undefined. ** ** These routines attempt to convert the value where appropriate. For ** example, if the internal representation is FLOAT and a text result ** is requested, [sqlite3_snprintf()] is used internally to do the conversion ** automatically. The following table details the conversions that ** are applied: ** |
︙ | ︙ | |||
3133 3134 3135 3136 3137 3138 3139 | ** {F13812} The [sqlite3_column_double(S,N)] interface converts the ** Nth column in the current row of the result set for ** [prepared statement] S into a floating point value and ** returns a copy of that value. ** ** {F13815} The [sqlite3_column_int(S,N)] interface converts the ** Nth column in the current row of the result set for | | | | 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 | ** {F13812} The [sqlite3_column_double(S,N)] interface converts the ** Nth column in the current row of the result set for ** [prepared statement] S into a floating point value and ** returns a copy of that value. ** ** {F13815} The [sqlite3_column_int(S,N)] interface converts the ** Nth column in the current row of the result set for ** [prepared statement] S into a 64-bit signed integer and ** returns the lower 32 bits of that integer. ** ** {F13818} The [sqlite3_column_int64(S,N)] interface converts the ** Nth column in the current row of the result set for ** [prepared statement] S into a 64-bit signed integer and ** returns a copy of that integer. ** ** {F13821} The [sqlite3_column_text(S,N)] interface converts the |
︙ | ︙ | |||
3159 3160 3161 3162 3163 3164 3165 | ** {F13827} 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 ** [prepared statement] S. ** ** {F13830} The [sqlite3_column_value(S,N)] interface returns a | | | 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 | ** {F13827} 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 ** [prepared statement] S. ** ** {F13830} 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 ** [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); |
︙ | ︙ | |||
3242 3243 3244 3245 3246 3247 3248 | ** 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 ** difference only between the two is that the second parameter, the ** name of the (scalar) function or aggregate, is encoded in UTF-8 for ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). ** | | | | | < | 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 | ** 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 ** difference only between the two is that the second parameter, the ** name of the (scalar) function or aggregate, is encoded in UTF-8 for ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). ** ** The first parameter is the [database connection] to which the SQL ** function is to be added. If a single ** program uses more than one [database connection] internally, then SQL ** functions must be added individually to each [database connection]. ** ** The second parameter is the name of the SQL function to be created ** or redefined. ** The length of the name is limited to 255 bytes, exclusive of the ** zero-terminator. Note that the name length limit is in bytes, not ** characters. Any attempt to create a function with a longer name ** will result in an SQLITE_ERROR error. |
︙ | ︙ | |||
3299 3300 3301 3302 3303 3304 3305 | ** ** {F16103} 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 a ** zero-terminated UTF-8. ** | | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 | ** ** {F16103} 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 a ** zero-terminated UTF-8. ** ** {F16106} A successful invocation of ** the [sqlite3_create_function(D,X,N,E,...)] interface registers ** or replaces callback functions in [database connection] D ** used to implement the SQL function named X with N parameters ** and having a perferred text encoding of E. ** ** {F16109} 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. ** ** {F16112} 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. ** ** {F16118} 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]. ** ** {F16121} 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. ** ** {F16124} 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. ** ** {F16127} 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. ** ** {F16130} 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. ** ** {F16133} 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. ** ** {F16136} 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. ** ** {F16139} For an aggregate SQL function created using ** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finializer ** function L will always be invoked exactly once if the ** step function S is called one or more times. ** ** {F16142} 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, const char *zFunctionName, int nArg, int eTextRep, void *pApp, |
︙ | ︙ | |||
3362 3363 3364 3365 3366 3367 3368 | ** 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()] ** define callbacks that implement the SQL functions and aggregates. ** The 4th parameter to these callbacks is an array of pointers to | | > > > > | | | 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 | ** 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()] ** define callbacks that implement the SQL functions and aggregates. ** The 4th parameter to these callbacks is an array of pointers to ** [protected sqlite3_value] objects. There is one [sqlite3_value] object for ** each parameter to the SQL function. These routines are used to ** extract values from the [sqlite3_value] objects. ** ** These routines work only with [protected sqlite3_value] objects. ** Any attempt to use these routines on an [unprotected sqlite3_value] ** object results in undefined behavior. ** ** These routines work just like the corresponding ** [sqlite3_column_blob | sqlite3_column_* routines] except that ** these routines take a single [protected sqlite3_value] object pointer ** instead of an [sqlite3_stmt*] pointer and an integer column number. ** ** The sqlite3_value_text16() interface extracts a UTF16 string ** in the native byte-order of the host machine. The ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces ** extract UTF16 strings as big-endian and little-endian respectively. ** ** The sqlite3_value_numeric_type() interface attempts to apply |
︙ | ︙ | |||
3391 3392 3393 3394 3395 3396 3397 | ** Please pay particular attention to the fact that the pointer that ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or ** [sqlite3_value_text16()] can be invalidated by a subsequent call to ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], ** or [sqlite3_value_text16()]. ** ** These routines must be called from the same thread as | | > > > > > > > > > > > > | > | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | > > > > > > > | | | | | > > > > > > > > > > > > > > > > > > > > > | | > > > > > > > > > > > > > > > > > > > > > > > > > > > < | | | | | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 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 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 | ** Please pay particular attention to the fact that the pointer that ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or ** [sqlite3_value_text16()] can be invalidated by a subsequent call to ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], ** or [sqlite3_value_text16()]. ** ** These routines must be called from the same thread as ** the SQL function that supplied the [sqlite3_value*] parameters. ** ** ** INVARIANTS: ** ** {F15103} 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. ** ** {F15106} 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)]. ** ** {F15109} 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)]. ** ** {F15112} 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. ** ** {F15115} 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. ** ** {F15118} 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. ** ** {F15121} 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. ** ** {F15124} 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. ** ** {F15127} 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. ** ** {F15130} 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. ** ** {F15133} 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. ** ** {F15136} 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. */ const void *sqlite3_value_blob(sqlite3_value*); int sqlite3_value_bytes(sqlite3_value*); int sqlite3_value_bytes16(sqlite3_value*); double sqlite3_value_double(sqlite3_value*); int sqlite3_value_int(sqlite3_value*); sqlite3_int64 sqlite3_value_int64(sqlite3_value*); const unsigned char *sqlite3_value_text(sqlite3_value*); 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 {F16210} ** ** 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 ** is called for a particular aggregate, SQLite allocates nBytes of memory ** zeros that memory, and returns a pointer to it. ** On second and subsequent calls to sqlite3_aggregate_context() ** for the same aggregate function index, the same buffer is returned. ** The implementation ** of the aggregate can use the returned buffer to accumulate data. ** ** SQLite automatically frees the allocated buffer when the aggregate ** query concludes. ** ** The first parameter should be a copy of the ** [sqlite3_context | SQL function context] that is the first ** parameter 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: ** ** {F16211} 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 allocation N bytes of memory, ** zero that memory, and return a pointer to the allocationed ** memory. ** ** {F16213} If a memory allocation error occurs during ** [sqlite3_aggregate_context(C,N)] then the function returns 0. ** ** {F16215} 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. ** ** {F16217} 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 {F16240} ** ** The sqlite3_user_data() interface returns a copy of ** the pointer that was the pUserData parameter (the 5th parameter) ** of the 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: ** ** {F16243} 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 {F16250} ** ** The sqlite3_context_db_handle() interface returns a copy of ** the pointer to the [database connection] (the 1st parameter) ** of the the [sqlite3_create_function()] ** and [sqlite3_create_function16()] routines that originally ** registered the application defined function. ** ** INVARIANTS: ** ** {F16253} 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 {F16270} ** ** The following two functions may be used by scalar SQL functions to ** associate meta-data 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 meta-data 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 ** meta-data associated with the SQL value passed as the regular expression ** pattern. The compiled regular expression can be reused on multiple ** invocations of the same function so that the original pattern string ** does not need to be recompiled on each invocation. ** ** The sqlite3_get_auxdata() interface returns a pointer to the meta-data ** associated by the sqlite3_set_auxdata() function with the Nth argument ** value to the application-defined function. ** If no meta-data has been ever been set for the Nth ** argument of the function, or if the cooresponding function parameter ** has changed since the meta-data was set, then sqlite3_get_auxdata() ** returns a NULL pointer. ** ** The sqlite3_set_auxdata() interface saves the meta-data ** pointed to by its 3rd parameter as the meta-data for the N-th ** argument of the application-defined function. Subsequent ** calls to sqlite3_get_auxdata() might return this data, if it has ** not been destroyed. ** If it is not NULL, SQLite will invoke the destructor ** function given by the 4th parameter to sqlite3_set_auxdata() on ** the meta-data when the corresponding function parameter changes ** or when the SQL statement completes, whichever comes first. ** ** SQLite is free to call the destructor and drop meta-data on ** any parameter of any function at any time. The only guarantee ** is that the destructor will be called before the metadata is ** dropped. ** ** In practice, meta-data is preserved between function calls for ** expressions that are constant at compile time. This includes literal ** values and SQL variables. ** ** These routines must be called from the same thread in which ** the SQL function is running. ** ** INVARIANTS: ** ** {F16272} 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. ** ** {F16274} 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. ** ** {F16276} 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. ** ** {F16277} SQLite ceases to hold metadata for an SQL function parameter ** when the value of that parameter changes. ** ** {F16278} 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. ** ** {F16279} 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 {F10280} |
︙ | ︙ | |||
3527 3528 3529 3530 3531 3532 3533 | ** These functions work very much like the ** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used ** to bind values to host parameters in prepared statements. ** Refer to the ** [sqlite3_bind_blob | sqlite3_bind_* documentation] for ** additional information. ** | | | | | | | | | | | | > > > > | | | | | | | | | | | | | | | > > > | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > < < | < | < | | < < | | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 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 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 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 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 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 4201 4202 4203 4204 4205 4206 4207 4208 4209 4210 4211 4212 4213 4214 4215 | ** These functions work very much like the ** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used ** to bind values to host parameters in prepared statements. ** Refer to the ** [sqlite3_bind_blob | sqlite3_bind_* documentation] for ** additional information. ** ** The sqlite3_result_blob() interface sets the result from ** an application defined function to be the BLOB whose content is pointed ** to by the second parameter and which is N bytes long where N is the ** third parameter. ** The sqlite3_result_zeroblob() inerfaces set the result of ** the application defined function to be a BLOB containing all zero ** bytes and N bytes in size, where N is the value of the 2nd parameter. ** ** The sqlite3_result_double() interface sets the result from ** an application defined function to be a floating point value specified ** by its 2nd argument. ** ** The sqlite3_result_error() and sqlite3_result_error16() functions ** cause the implemented SQL function to throw an exception. ** SQLite uses the string pointed to by the ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16() ** as the text of an error message. SQLite interprets the error ** message string from sqlite3_result_error() as UTF8. SQLite ** interprets the string from sqlite3_result_error16() as UTF16 in native ** byte order. If the third parameter to sqlite3_result_error() ** or sqlite3_result_error16() is negative then SQLite takes as the error ** message all text up through the first zero character. ** If the third parameter to sqlite3_result_error() or ** sqlite3_result_error16() is non-negative then SQLite takes that many ** bytes (not characters) from the 2nd parameter as the error message. ** The sqlite3_result_error() and sqlite3_result_error16() ** routines make a copy private copy of the error message text before ** they return. Hence, the calling function can deallocate or ** modify the text after they return without harm. ** The sqlite3_result_error_code() function changes the error code ** returned by SQLite as a result of an error in a function. By default, ** the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error() ** or sqlite3_result_error16() resets the error code to SQLITE_ERROR. ** ** The sqlite3_result_toobig() interface causes SQLite ** to throw an error indicating that a string or BLOB is to long ** to represent. The sqlite3_result_nomem() interface ** causes SQLite to throw an exception indicating that the a ** memory allocation failed. ** ** The sqlite3_result_int() interface sets the return value ** of the application-defined function to be the 32-bit signed integer ** value given in the 2nd argument. ** The sqlite3_result_int64() interface sets the return value ** of the application-defined function to be the 64-bit signed integer ** value given in the 2nd argument. ** ** The sqlite3_result_null() interface sets the return value ** of the application-defined function to be NULL. ** ** The sqlite3_result_text(), sqlite3_result_text16(), ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces ** set the return value of the application-defined function to be ** a text string which is represented as UTF-8, UTF-16 native byte order, ** UTF-16 little endian, or UTF-16 big endian, respectively. ** SQLite takes the text result from the application from ** the 2nd parameter of the sqlite3_result_text* interfaces. ** If the 3rd parameter to the sqlite3_result_text* interfaces ** is negative, then SQLite takes result text from the 2nd parameter ** through the first zero character. ** If the 3rd parameter to the sqlite3_result_text* interfaces ** is non-negative, then as many bytes (not characters) of the text ** pointed to by the 2nd parameter are taken as the application-defined ** function result. ** If the 4th parameter to the sqlite3_result_text* interfaces ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that ** function as the destructor on the text or blob result when it has ** finished using that result. ** If the 4th parameter to the sqlite3_result_text* interfaces ** or sqlite3_result_blob is the special constant SQLITE_STATIC, then ** SQLite assumes that the text or blob result is constant space and ** does not copy the space or call a destructor when it has ** finished using that result. ** If the 4th parameter to the sqlite3_result_text* interfaces ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT ** then SQLite makes a copy of the result into space obtained from ** from [sqlite3_malloc()] before it returns. ** ** The sqlite3_result_value() interface sets the result of ** the application-defined function to be a copy the ** [unprotected sqlite3_value] object specified by the 2nd parameter. The ** sqlite3_result_value() interface makes a copy of the [sqlite3_value] ** so that [sqlite3_value] specified in the parameter may change or ** be deallocated after sqlite3_result_value() returns without harm. ** A [protected sqlite3_value] object may always be used where an ** [unprotected sqlite3_value] object is required, so either ** kind of [sqlite3_value] object can be used with this interface. ** ** If these routines are called from within the different thread ** than the one containing the application-defined function that recieved ** the [sqlite3_context] pointer, the results are undefined. ** ** INVARIANTS: ** ** {F16403} The default return value from any SQL function is NULL. ** ** {F16406} 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. ** ** {F16409} The [sqlite3_result_double(C,V)] interface changes the ** return value of function C to be the floating point value V. ** ** {F16412} 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 UTF8 error message copied from V up to the ** first zero byte or until N bytes are read if N is positive. ** ** {F16415} 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 UTF16 native byte order error message ** copied from V up to the first zero terminator or until N bytes ** are read if N is positive. ** ** {F16418} 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. ** ** {F16421} 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. ** ** {F16424} 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. ** ** {F16427} The [sqlite3_result_int(C,V)] interface changes the ** return value of function C to be the 32-bit integer value V. ** ** {F16430} The [sqlite3_result_int64(C,V)] interface changes the ** return value of function C to be the 64-bit integer value V. ** ** {F16433} The [sqlite3_result_null(C)] interface changes the ** return value of function C to be NULL. ** ** {F16436} The [sqlite3_result_text(C,V,N,D)] interface changes the ** return value of function C to be the UTF8 string ** V up to the first zero if N is negative ** or the first N bytes of V if N is non-negative. ** ** {F16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the ** return value of function C to be the UTF16 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. ** ** {F16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the ** return value of function C to be the UTF16 big-endian ** string V up to the first zero if N is ** is negative or the first N bytes or V if N is non-negative. ** ** {F16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the ** return value of function C to be the UTF16 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. ** ** {F16448} The [sqlite3_result_value(C,V)] interface changes the ** return value of function C to be [unprotected sqlite3_value] ** object V. ** ** {F16451} The [sqlite3_result_zeroblob(C,N)] interface changes the ** return value of function C to be an N-byte blob of all zeros. ** ** {F16454} The [sqlite3_result_error()] and [sqlite3_result_error16()] ** interfaces make a copy of their error message strings before ** returning. ** ** {F16457} 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. ** ** {F16460} 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. ** ** {F16463} 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. */ void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); void sqlite3_result_double(sqlite3_context*, double); void sqlite3_result_error(sqlite3_context*, const char*, int); void sqlite3_result_error16(sqlite3_context*, const void*, int); void sqlite3_result_error_toobig(sqlite3_context*); void sqlite3_result_error_nomem(sqlite3_context*); void sqlite3_result_error_code(sqlite3_context*, int); void sqlite3_result_int(sqlite3_context*, int); void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); void sqlite3_result_null(sqlite3_context*); void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); 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 {F16600} ** ** These functions are used to add new collation sequences to the ** [sqlite3*] handle 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 ** the name is passed as the second function argument. ** ** The third argument may be one of the constants [SQLITE_UTF8], ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied ** routine expects to be passed pointers to strings encoded using UTF-8, ** UTF-16 little-endian or UTF-16 big-endian respectively. The ** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that ** the routine expects pointers to 16-bit word aligned strings ** of UTF16 in the native byte order of the host computer. ** ** A pointer to the user supplied routine must be passed as the fifth ** argument. If it is NULL, this is the same as deleting the collation ** sequence (so that SQLite cannot call it anymore). ** Each time the application ** supplied function is invoked, it is passed a copy of the void* passed as ** the fourth argument to sqlite3_create_collation() or ** sqlite3_create_collation16() as its first parameter. ** ** The remaining arguments to the application-supplied routine are two strings, ** each represented by a (length, data) pair and encoded in the encoding ** that was passed as the third argument when the collation sequence was ** registered. {END} The application defined collation routine should ** return negative, zero or positive if ** the first string is less than, equal to, or greater than the second ** string. i.e. (STRING1 - STRING2). ** ** The sqlite3_create_collation_v2() works like sqlite3_create_collation() ** excapt that it takes an extra argument which is a destructor for ** the collation. The destructor is called when the collation is ** destroyed and is passed a copy of the fourth parameter void* pointer ** of the sqlite3_create_collation_v2(). ** Collations are destroyed when ** they are overridden by later calls to the collation creation functions ** or when the [sqlite3*] database handle is closed using [sqlite3_close()]. ** ** INVARIANTS: ** ** {F16603} 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 [database connection] B for ** databases having encoding E. ** ** {F16604} 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. ** ** {F16606} 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. ** ** {F16609} 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. ** ** {F16612} A collating function is dropped when it is overloaded. ** ** {F16615} A collating function is dropped when the database connection ** is closed using [sqlite3_close()]. ** ** {F16618} 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. ** ** {F16621} 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. ** ** {F16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)], ** SQLite uses the comparison function F for all text comparison ** operations on [database connection] B on text values that ** use the collating sequence name X. ** ** {F16627} 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. ** ** {F16630} 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, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*) |
︙ | ︙ | |||
3704 3705 3706 3707 3708 3709 3710 | void*, int(*xCompare)(void*,int,const void*,int,const void*) ); /* ** CAPI3REF: Collation Needed Callbacks {F16700} ** | < < | | | | | | > > > > > > > > > > > > > > > > > > > > > | 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 | void*, int(*xCompare)(void*,int,const void*,int,const void*) ); /* ** CAPI3REF: Collation Needed Callbacks {F16700} ** ** To avoid having to register all collation sequences before a database ** can be used, a single callback function may be registered with the ** database handle 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. {F16703} 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 ** handle. 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: ** ** {F16702} 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. ** ** {F16704} 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. ** ** {F16706} 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*, void*, void(*)(void*,sqlite3*,int eTextRep,const char*) ); int sqlite3_collation_needed16( |
︙ | ︙ | |||
3769 3770 3771 3772 3773 3774 3775 | sqlite3 *db, /* Database to be rekeyed */ const void *pKey, int nKey /* The new key */ ); /* ** CAPI3REF: Suspend Execution For A Short Time {F10530} ** | | | | | | > > > > > > > > > > > | 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 | sqlite3 *db, /* Database to be rekeyed */ const void *pKey, int nKey /* The new key */ ); /* ** CAPI3REF: Suspend Execution For A Short Time {F10530} ** ** 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: ** ** {F10533} 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. ** ** {F10536} 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 {F10310} ** ** If this global variable is made to point to a string which is |
︙ | ︙ | |||
3817 3818 3819 3820 3821 3822 3823 | ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the ** transaction might be rolled back automatically. The only way to ** find out if SQLite automatically rolled back the transaction after ** an error is to use this function. ** ** INVARIANTS: ** | | | | 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 | ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the ** transaction might be rolled back automatically. The only way to ** find out if SQLite automatically rolled back the transaction after ** an error is to use this function. ** ** INVARIANTS: ** ** {F12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or ** zero if the [database connection] D is or is not in autocommit ** mode, respectively. ** ** {F12932} Autocommit mode is on by default. ** ** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement. ** ** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK] |
︙ | ︙ | |||
3840 3841 3842 3843 3844 3845 3846 | ** is undefined. */ int sqlite3_get_autocommit(sqlite3*); /* ** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120} ** | | | > > > > > > | | | | | | | | | | | | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | | | | | | | | | | | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > < < | < | | | | | | | | > > > > > > > > > > > > > > | | > > > > > > > > > > | | | | < | | | | | > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 4416 4417 4418 4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432 4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 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 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 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 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 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 | ** is undefined. */ int sqlite3_get_autocommit(sqlite3*); /* ** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120} ** ** The sqlite3_db_handle interface ** returns the [sqlite3*] database 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()] or its variants ** that was used to create the statement in the first place. ** ** INVARIANTS: ** ** {F13123} The [sqlite3_db_handle(S)] interface returns a pointer ** to the [database connection] associated with ** [prepared statement] S. */ sqlite3 *sqlite3_db_handle(sqlite3_stmt*); /* ** CAPI3REF: Commit And Rollback Notification Callbacks {F12950} ** ** 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. ** Any callback set by a previous call to sqlite3_commit_hook() ** for the same database connection is overridden. ** The pArg argument is passed through ** to the callback. If the callback on a commit hook function ** returns non-zero, then the commit is converted into a rollback. ** ** If another function was previously registered, its ** pArg value is returned. Otherwise NULL is returned. ** ** Registering a NULL function disables the callback. ** ** For the purposes of this API, a transaction is said to have been ** rolled back if an explicit "ROLLBACK" statement is executed, or ** an error or constraint causes an implicit rollback to occur. ** The rollback callback is not invoked if a transaction is ** 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> ** ** These are experimental interfaces and are subject to change. ** ** INVARIANTS: ** ** {F12951} The [sqlite3_commit_hook(D,F,P)] interface registers the ** callback function F to be invoked with argument P whenever ** a transaction commits on [database connection] D. ** ** {F12952} 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. ** ** {F12953} Each call to [sqlite3_commit_hook()] overwrites the callback ** registered by prior calls. ** ** {F12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL ** then the commit hook callback is cancelled and no callback ** is invoked when a transaction commits. ** ** {F12955} If the commit callback returns non-zero then the commit is ** converted into a rollback. ** ** {F12961} 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 [database connection] D. ** ** {F12962} 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. ** ** {F12963} Each call to [sqlite3_rollback_hook()] overwrites the callback ** registered by prior calls. ** ** {F12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL ** then the rollback hook callback is cancelled 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 {F12970} ** ** 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. ** ** The second argument is a pointer to the function to invoke when a ** row is updated, inserted or deleted. ** The first argument to the callback is ** a copy of the third argument to sqlite3_update_hook(). ** The second callback ** argument is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], ** depending on the operation that caused the callback to be invoked. ** The third and ** fourth arguments to the callback contain pointers to the database and ** table name containing the affected row. ** The final callback parameter is ** the rowid of the row. ** In the case of an update, this is the rowid after ** the update takes place. ** ** The update hook is not invoked when internal system tables are ** modified (i.e. sqlite_master and sqlite_sequence). ** ** If another function was previously registered, its pArg value ** is returned. Otherwise NULL is returned. ** ** INVARIANTS: ** ** {F12971} The [sqlite3_update_hook(D,F,P)] interface causes callback ** function F to be invoked with first parameter P whenever ** a table row is modified, inserted, or deleted on ** [database connection] D. ** ** {F12973} 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. ** ** {F12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)] ** is NULL then the no update callbacks are made. ** ** {F12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls ** to the same interface on the same [database connection] D. ** ** {F12979} The update hook callback is not invoked when internal system ** tables such as sqlite_master and sqlite_sequence are modified. ** ** {F12981} 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. ** ** {F12983} 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. ** {F12985} 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 {F10330} ** ** This routine enables or disables the sharing of the database cache ** and schema data structures between connections to the same database. ** Sharing is enabled if the argument is true and disabled if the argument ** is false. ** ** Cache sharing is enabled and disabled ** for an entire process. {END} This is a change as of SQLite version 3.5.0. ** In prior versions of SQLite, sharing was ** enabled or disabled for each thread separately. ** ** The cache sharing mode set by this interface effects all subsequent ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. ** Existing database connections continue use the sharing mode ** that was in effect at the time they were opened. ** ** Virtual tables cannot be used with a shared cache. When shared ** cache is enabled, the [sqlite3_create_module()] API used to register ** virtual tables will always return an error. ** ** This routine returns [SQLITE_OK] if shared cache was ** enabled or disabled successfully. An [error code] ** is returned otherwise. ** ** 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: ** ** {F10331} 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. ** ** {F10336} When shared cache is enabled, the [sqlite3_create_module()] ** interface will always return an error. ** ** {F10337} The [sqlite3_enable_shared_cache(B)] interface returns ** [SQLITE_OK] if shared cache was enabled or disabled successfully. ** ** {F10339} Shared cache is disabled by default. */ int sqlite3_enable_shared_cache(int); /* ** CAPI3REF: Attempt To Free Heap Memory {F17340} ** ** The sqlite3_release_memory() interface attempts to ** free N bytes of heap memory by deallocating non-essential memory ** allocations held by the database labrary. {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: ** ** {F17341} The [sqlite3_release_memory(N)] interface attempts to ** free N bytes of heap memory by deallocating non-essential ** memory allocations held by the database labrary. ** ** {F16342} 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 {F17350} ** ** 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 made. ** ** The limit is called "soft", because if ** [sqlite3_release_memory()] cannot ** free sufficient memory to prevent the limit from being exceeded, ** the memory is allocated anyway and the current operation proceeds. ** ** A negative or zero value for N means that there is no soft heap limit and ** [sqlite3_release_memory()] will only be called when memory is exhausted. ** The default value for the soft heap limit is zero. ** ** SQLite makes a best effort to honor the soft heap limit. ** But if the soft heap limit cannot honored, execution will ** continue without error or notification. This is why the limit is ** called a "soft" limit. It is advisory only. ** ** Prior to SQLite version 3.5.0, this routine only constrained the memory ** allocated by a single thread - the same thread in which this routine ** runs. Beginning with SQLite version 3.5.0, the soft heap limit is ** 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: ** ** {F16351} 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. ** ** {F16352} 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. ** ** {F16353} 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. ** ** {F16354} 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. ** ** {F16355} The default value for the soft heap limit is zero. ** ** {F16358} 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 {F12850} ** ** This routine |
︙ | ︙ | |||
4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 | */ 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; /* ** 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. */ struct sqlite3_module { int iVersion; int (*xCreate)(sqlite3*, void *pAux, | > > > | 4867 4868 4869 4870 4871 4872 4873 4874 4875 4876 4877 4878 4879 4880 4881 4882 4883 | */ 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 {F18000} ** 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. */ struct sqlite3_module { int iVersion; int (*xCreate)(sqlite3*, void *pAux, |
︙ | ︙ | |||
4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 | void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), void **ppArg); int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); }; /* ** 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. ** ** The aConstraint[] array records WHERE clause constraints of the | > > > | 4906 4907 4908 4909 4910 4911 4912 4913 4914 4915 4916 4917 4918 4919 4920 4921 4922 | void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), void **ppArg); int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); }; /* ** CAPI3REF: Virtual Table Indexing Information {F18100} ** 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. ** ** The aConstraint[] array records WHERE clause constraints of the |
︙ | ︙ | |||
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 | #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 /* ** This routine is used to register a new module name with an SQLite ** connection. Module names must be registered before creating new ** virtual tables on the module, or before using preexisting virtual ** tables of the module. */ 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 */ ); /* ** 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 */ ); /* ** 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. ** ** Virtual tables methods can set an error message by assigning a | > > > > > > > | 4989 4990 4991 4992 4993 4994 4995 4996 4997 4998 4999 5000 5001 5002 5003 5004 5005 5006 5007 5008 5009 5010 5011 5012 5013 5014 5015 5016 5017 5018 5019 5020 5021 5022 5023 5024 5025 5026 5027 5028 5029 5030 5031 5032 5033 5034 5035 | #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 {F18200} ** ** This routine is used to register a new module name with an SQLite ** connection. Module names must be registered before creating new ** virtual tables on the module, or before using preexisting virtual ** tables of the module. */ 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 {F18210} ** ** 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 {F18010} ** 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. ** ** Virtual tables methods can set an error message by assigning a |
︙ | ︙ | |||
4355 4356 4357 4358 4359 4360 4361 | struct sqlite3_vtab { 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 */ }; | > > > > | > > > > | 5045 5046 5047 5048 5049 5050 5051 5052 5053 5054 5055 5056 5057 5058 5059 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 | struct sqlite3_vtab { 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 {F18020} ** 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. */ 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 {F18280} ** ** 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. */ int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); /* ** CAPI3REF: Overload A Function For A Virtual Table {F18300} ** ** 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 ** before this API is called, a new function is created. The implementation |
︙ | ︙ | |||
4409 4410 4411 4412 4413 4414 4415 | ** ****** EXPERIMENTAL - subject to change without notice ************** */ /* ** CAPI3REF: A Handle To An Open BLOB {F17800} ** | | | > | | | | > > > > > > | | | > > > > | > | > > > > > > > > > > > > > > > | | | > > > > > > > > > > > > > > > > > > | | | > > > > > > | | | | | > > > > > > > > > > > > > > > > > > > > > > > > > > > > | | | | | | | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | | | | | | | | | | | | | | | > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 5162 5163 5164 5165 5166 5167 5168 5169 5170 5171 5172 5173 5174 5175 5176 5177 5178 5179 5180 5181 5182 5183 5184 5185 5186 5187 5188 5189 5190 5191 5192 5193 5194 5195 5196 5197 5198 5199 5200 5201 5202 5203 5204 5205 5206 5207 5208 5209 5210 5211 5212 5213 5214 5215 5216 5217 5218 5219 5220 5221 5222 5223 5224 5225 5226 5227 5228 5229 5230 5231 5232 5233 5234 5235 5236 5237 5238 5239 5240 5241 5242 5243 5244 5245 5246 5247 5248 5249 5250 5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 5261 5262 5263 5264 5265 5266 5267 5268 5269 5270 5271 5272 5273 5274 5275 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 5343 5344 5345 5346 5347 5348 5349 5350 5351 5352 5353 5354 5355 5356 5357 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 | ** ****** EXPERIMENTAL - subject to change without notice ************** */ /* ** CAPI3REF: A Handle To An Open BLOB {F17800} ** ** An instance of this object represents an open BLOB on which ** incremental I/O can be preformed. ** 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 {F17810} ** ** This interfaces opens a 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; ** </pre> {END} ** ** If the flags parameter is non-zero, the blob is opened for ** read and write access. If it is zero, the blob is opened for read ** access. ** ** Note that the database name is not the filename that contains ** the database but rather the symbolic name of the database that ** is assigned when the database is connected using [ATTACH]. ** For the main database file, the database name is "main". For ** TEMP tables, the database name is "temp". ** ** On success, [SQLITE_OK] is returned and the new ** [sqlite3_blob | blob handle] is written to *ppBlob. ** Otherwise an error code is returned and ** any value written to *ppBlob should not be used by the caller. ** This function sets the database-handle error code and message ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. ** ** INVARIANTS: ** ** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)] ** interface opens an [sqlite3_blob] object P on the blob ** in column C of table T in database B on [database connection] D. ** ** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] starts ** a new transaction on [database connection] D if that connection ** is not already in a transaction. ** ** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface opens the blob ** for read and write access if and only if the F parameter ** is non-zero. ** ** {F17819} The [sqlite3_blob_open()] interface returns [SQLITE_OK] on ** success and an appropriate [error code] on failure. ** ** {F17821} 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)] will return ** information approprate for that error. */ 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 {F17830} ** ** Close an open [sqlite3_blob | 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. {F17833} 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: ** ** {F17833} The [sqlite3_blob_close(P)] interface closes an ** [sqlite3_blob] object P previously opened using ** [sqlite3_blob_open()]. ** ** {F17836} 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 ** [sqlite3_get_autocommit | autocommit mode]. ** ** {F17839} The [sqlite3_blob_close(P)] interfaces closes 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 {F17840} ** ** Return the size in bytes of the blob accessible via the open ** [sqlite3_blob] object in its only argument. ** ** INVARIANTS: ** ** {F17843} 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 {F17850} ** ** This function is used to read data from an open ** [sqlite3_blob | 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. ** ** On success, SQLITE_OK is returned. Otherwise, an ** [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** ** {F17853} The [sqlite3_blob_read(P,Z,N,X)] interface reads N bytes ** beginning at offset X from ** the blob that [sqlite3_blob] object P refers to ** and writes those N bytes into buffer Z. ** ** {F17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the blob ** is less than N+X bytes, then the function returns [SQLITE_ERROR] ** and nothing is read from the blob. ** ** {F17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero ** then the function returns [SQLITE_ERROR] ** and nothing is read from the blob. ** ** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface returns [SQLITE_OK] ** if N bytes where successfully read into buffer Z. ** ** {F17865} If the requested read could not be completed, ** the [sqlite3_blob_read(P,Z,N,X)] interface returns an ** appropriate [error code] or [extended error code]. ** ** {F17868} 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)] will return ** information approprate for that error, where D is the ** database handle that was used to open blob handle P. */ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); /* ** CAPI3REF: Write Data Into A BLOB Incrementally {F17870} ** ** This function is used to write data into an open ** [sqlite3_blob | blob-handle] from a user supplied buffer. ** n bytes of data are copied from the buffer ** pointed to by z into the open blob, starting at offset iOffset. ** ** If the [sqlite3_blob | blob-handle] passed as the first argument ** was not opened for writing (the flags parameter to [sqlite3_blob_open()] *** was zero), this function returns [SQLITE_READONLY]. ** ** This function may only modify the contents of the blob; it is ** not possible to increase the size of a blob using this API. ** If offset iOffset is less than n bytes from the end of the blob, ** [SQLITE_ERROR] is returned and no data is written. If n is ** less than zero [SQLITE_ERROR] is returned and no data is written. ** ** On success, SQLITE_OK is returned. Otherwise, an ** [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** ** {F17873} The [sqlite3_blob_write(P,Z,N,X)] interface writes N bytes ** from buffer Z into ** the blob that [sqlite3_blob] object P refers to ** beginning at an offset of X into the blob. ** ** {F17875} The [sqlite3_blob_write(P,Z,N,X)] interface returns ** [SQLITE_READONLY] if the [sqlite3_blob] object P was ** [sqlite3_blob_open | opened] for reading only. ** ** {F17876} In [sqlite3_blob_write(P,Z,N,X)] if the size of the blob ** is less than N+X bytes, then the function returns [SQLITE_ERROR] ** and nothing is written into the blob. ** ** {F17879} In [sqlite3_blob_write(P,Z,N,X)] if X or N is less than zero ** then the function returns [SQLITE_ERROR] ** and nothing is written into the blob. ** ** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface returns [SQLITE_OK] ** if N bytes where successfully written into blob. ** ** {F17885} If the requested write could not be completed, ** the [sqlite3_blob_write(P,Z,N,X)] interface returns an ** appropriate [error code] or [extended error code]. ** ** {F17888} 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)] will return ** information approprate for that error. */ int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); /* ** CAPI3REF: Virtual File System Objects {F11200} ** ** 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. ** ** The sqlite3_vfs_find() interface returns a pointer to ** a VFS given its name. Names are case sensitive. ** Names are zero-terminated UTF-8 strings. ** If there is no match, a NULL ** pointer is returned. If zVfsName is NULL then the default ** VFS is returned. ** ** New VFSes are registered with sqlite3_vfs_register(). ** Each new VFS becomes the default VFS if the makeDflt flag is set. ** The same VFS can be registered multiple times without injury. ** To make an existing VFS into the default VFS, register it again ** with the makeDflt flag set. If two different VFSes with the ** same name are registered, the behavior is undefined. If a ** VFS is registered with a name that is NULL or an empty string, ** then the behavior is undefined. ** ** 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: ** ** {F11203} 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. ** ** {F11206} 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. ** ** {F11209} 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. ** ** {F11212} Using the [sqlite3_vfs_register(P,F)] interface to register ** the same [sqlite3_vfs] object multiple times is a harmless no-op. ** ** {F11215} The [sqlite3_vfs_register(P,F)] interface makes the ** the [sqlite3_vfs] object P the default [sqlite3_vfs] object ** if F is non-zero. ** ** {F11218} 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 {F17000} |
︙ | ︙ | |||
4604 4605 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 | ** <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 ** </ul> {END} ** ** {F17015} 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 | > | 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 | ** <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> {END} ** ** {F17015} 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 |
︙ | ︙ | |||
4716 4717 4718 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 | #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 */ /* ** CAPI3REF: Low-Level Control Of Database Files {F11300} ** ** {F11301} 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. {F11302} The | > | 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 | #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 {F11300} ** ** {F11301} 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. {F11302} The |
︙ | ︙ | |||
4777 4778 4779 4780 4781 4782 4783 | ** Applications should not use any of these parameters or the ** [sqlite3_test_control()] interface. */ #define SQLITE_TESTCTRL_FAULT_CONFIG 1 #define SQLITE_TESTCTRL_FAULT_FAILURES 2 #define SQLITE_TESTCTRL_FAULT_BENIGN_FAILURES 3 #define SQLITE_TESTCTRL_FAULT_PENDING 4 | | | | > | 5614 5615 5616 5617 5618 5619 5620 5621 5622 5623 5624 5625 5626 5627 5628 5629 5630 5631 | ** Applications should not use any of these parameters or the ** [sqlite3_test_control()] interface. */ #define SQLITE_TESTCTRL_FAULT_CONFIG 1 #define SQLITE_TESTCTRL_FAULT_FAILURES 2 #define SQLITE_TESTCTRL_FAULT_BENIGN_FAILURES 3 #define SQLITE_TESTCTRL_FAULT_PENDING 4 #define SQLITE_TESTCTRL_PRNG_SAVE 5 #define SQLITE_TESTCTRL_PRNG_RESTORE 6 #define SQLITE_TESTCTRL_PRNG_RESET 7 #define SQLITE_TESTCTRL_BITVEC_TEST 8 /* ** Undo the hack that converts floating point types to integer for ** builds on processors without floating point support. */ #ifdef SQLITE_OMIT_FLOATING_POINT |
︙ | ︙ |