Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Continuing work on the C/C++ interface requirements that appears as comments in sqlite.h.in. (CVS 4594) |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
2130e7125187ca46df3f65237f933b0e |
User & Date: | drh 2007-12-06 02:42:08.000 |
Context
2007-12-06
| ||
13:26 | Use the specified buffer length, not the maximum buffer length in unixFullPathname() and related functions. (CVS 4595) (check-in: f015a38771 user: drh tags: trunk) | |
02:42 | Continuing work on the C/C++ interface requirements that appears as comments in sqlite.h.in. (CVS 4594) (check-in: 2130e71251 user: drh tags: trunk) | |
2007-12-05
| ||
18:05 | Begin adding requirements numbers to the C/C++ interface documentation. (CVS 4593) (check-in: ae1936aadf user: drh tags: trunk) | |
Changes
Changes to src/sqlite.h.in.
︙ | ︙ | |||
26 27 28 29 30 31 32 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** | | | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** ** @(#) $Id: sqlite.h.in,v 1.276 2007/12/06 02:42:08 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++. |
︙ | ︙ | |||
61 62 63 64 65 66 67 | #ifdef SQLITE_VERSION_NUMBER # undef SQLITE_VERSION_NUMBER #endif /* ** CAPI3REF: Compile-Time Library Version Numbers {F10010} ** | | < | < | | | > | | | | | | > | | < | > > | | | | 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | #ifdef SQLITE_VERSION_NUMBER # undef SQLITE_VERSION_NUMBER #endif /* ** CAPI3REF: Compile-Time Library Version Numbers {F10010} ** ** {F10011} The #define in the sqlite3.h header file named ** SQLITE_VERSION resolves to a string literal that identifies ** the version of the SQLite library in the format "X.Y.Z", where ** X is the major version number, Y is the minor version number and Z ** is the release number. The X.Y.Z might be followed by "alpha" or "beta". ** {END} For example "3.1.1beta". ** ** The X value is always 3 in SQLite. The X value only changes when ** backwards compatibility is broken and we intend to never break ** backwards compatibility. The Y value only changes when ** there are major feature enhancements that are forwards compatible ** but not backwards compatible. The Z value is incremented with ** each release but resets back to 0 when Y is incremented. ** ** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are as ** with SQLITE_VERSION. {END} For example, for version "3.1.1beta", ** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using ** version 3.1.1 or greater at compile time, programs may use the test ** (SQLITE_VERSION_NUMBER>=3001001). ** ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()]. */ #define SQLITE_VERSION "--VERS--" #define SQLITE_VERSION_NUMBER --VERSION-NUMBER-- /* ** CAPI3REF: Run-Time Library Version Numbers {F10020} ** ** {F10021} The sqlite3_libversion_number() interface returns an integer ** equal to [SQLITE_VERSION_NUMBER]. {END} The value returned ** by this routine should only be different from the header values ** if the application is compiled using an sqlite3.h header from a ** different version of SQLite than library. Cautious programmers might ** include a check in their application to verify that ** sqlite3_libversion_number() always returns the value ** [SQLITE_VERSION_NUMBER]. ** ** {F10022} The sqlite3_version[] string constant contains the text of the ** [SQLITE_VERSION] string. {F10023} The sqlite3_libversion() function returns ** a pointer to the sqlite3_version[] string constant. {END} The ** sqlite3_libversion() function ** is provided for DLL users who can only access functions and not ** constants within the DLL. */ SQLITE_EXTERN const char sqlite3_version[]; const char *sqlite3_libversion(void); int sqlite3_libversion_number(void); /* ** CAPI3REF: Test To See If The Library Is Threadsafe {F10100} ** ** {F10101} The sqlite3_threadsafe() routine returns nonzero ** if SQLite was compiled with its mutexes enabled or zero if ** SQLite was compiled with mutexes disabled. {END} If this ** routine returns false, then it is not safe for simultaneously ** running threads to both invoke SQLite interfaces. ** ** Really all this routine does is return true if SQLite was ** compiled with the -DSQLITE_THREADSAFE=1 option and false if ** compiled with -DSQLITE_THREADSAFE=0. If SQLite uses an ** application-defined mutex subsystem, malloc subsystem, collating ** sequence, VFS, SQL function, progress callback, commit hook, ** extension, or other accessories and these add-ons are not ** threadsafe, then clearly the combination will not be threadsafe ** either. Hence, this routine never reports that the library ** is guaranteed to be threadsafe, only when it is guaranteed not ** to be. */ int sqlite3_threadsafe(void); /* ** CAPI3REF: Database Connection Handle {F12000} |
︙ | ︙ | |||
183 184 185 186 187 188 189 | #ifdef SQLITE_OMIT_FLOATING_POINT # define double sqlite3_int64 #endif /* ** CAPI3REF: Closing A Database Connection {F12010} ** | | | | | | | | | > | | | | | | 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 | #ifdef SQLITE_OMIT_FLOATING_POINT # define double sqlite3_int64 #endif /* ** CAPI3REF: Closing A Database Connection {F12010} ** ** {F12011} The sqlite3_close() interfaces destroys an [sqlite3] object ** allocated by a prior call to [sqlite3_open()], [sqlite3_open16()], or ** [sqlite3_open_v2()]. {F12012} Sqlite3_close() releases all ** memory used by the connection and closes all open files. {END}. ** ** {F12013} If the database connection contains ** [sqlite3_stmt | prepared statements] that have not been finalized ** by [sqlite3_finalize()], then sqlite3_close() returns SQLITE_BUSY ** and leaves the connection open. {F12014} Giving sqlite3_close() ** a NULL pointer is a harmless no-op. {END} ** ** {U12015} Passing this routine a database connection that has already been ** closed results in undefined behavior. {U12016} If other interfaces that ** reference the same database connection are pending (either in the ** same thread or in different threads) when this routine is called, ** then the behavior is undefined and is almost certainly undesirable. */ int sqlite3_close(sqlite3 *); /* ** The type for a callback function. ** This is legacy and deprecated. It is included for historical ** compatibility and is not documented. */ typedef int (*sqlite3_callback)(void*,int,char**, char**); /* ** CAPI3REF: One-Step Query Execution Interface {F12100} ** ** {F12101} The sqlite3_exec() interface evaluates zero or more ** UTF-8 encoded, semicolon-separated SQL statements in the zero-terminated ** string of its second argument. {F12102} The SQL ** statements are evaluated in the context of the database connection ** specified by in the first argument. ** {F12103} SQL statements are prepared one by one using ** [sqlite3_prepare()] or the equivalent, evaluated ** using one or more calls to [sqlite3_step()], then destroyed ** using [sqlite3_finalize()]. {F12104} The return value of ** sqlite3_exec() is SQLITE_OK if all SQL statement run ** successfully. ** |
︙ | ︙ | |||
239 240 241 242 243 244 245 | ** that is passed through to the callback function as its first parameter. ** ** {F12108} The 2nd parameter to the callback function is the number of ** columns in the query result. {F12109} The 3rd parameter to the callback ** is an array of pointers to strings holding the values for each column ** as extracted using [sqlite3_column_text()]. NULL values in the result ** set result in a NULL pointer. All other value are in their UTF-8 | | | | > > > | > > > > | | | 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 | ** that is passed through to the callback function as its first parameter. ** ** {F12108} The 2nd parameter to the callback function is the number of ** columns in the query result. {F12109} The 3rd parameter to the callback ** is an array of pointers to strings holding the values for each column ** as extracted using [sqlite3_column_text()]. NULL values in the result ** set result in a NULL pointer. All other value are in their UTF-8 ** string representation. {F12117} ** The 4th parameter to the callback is an array of strings ** obtained using [sqlite3_column_name()] and holding ** the names of each column, also in UTF-8. ** ** {F12110} The callback function may be NULL, even for queries. A NULL ** callback is not an error. It just means that no callback ** will be invoked. ** ** {F12112} If an error occurs while parsing or evaluating the SQL ** then an appropriate error message is written into memory obtained ** from [sqlite3_malloc()] and *errmsg is made to point to that message ** assuming errmsg is not NULL. ** {U12113} The calling function is responsible for freeing the memory ** using [sqlite3_free()]. ** {F12116} If [sqlite3_malloc()] fails while attempting to generate ** the error message, *errmsg is set to NULL. ** {F12114} If errmsg is NULL then no attempt is made to generate an ** error message. <todo>Is the return code SQLITE_NOMEM or the original ** error code?</todo> <todo>What happens if there are multiple errors? ** Do we get code for the first error, or is the choice of reported ** error arbitrary?</todo> ** ** {F12115} The return value is is SQLITE_OK if there are no errors and ** some other [SQLITE_OK | return code] if there is an error. ** The particular return value depends on the type of error. {END} */ int sqlite3_exec( sqlite3*, /* An open database */ const char *sql, /* SQL to be evaluted */ int (*callback)(void*,int,char**,char**), /* Callback function */ void *, /* 1st argument to callback */ char **errmsg /* Error msg written here */ ); /* ** CAPI3REF: Result Codes {F10210} ** KEYWORDS: SQLITE_OK ** ** Many SQLite functions return an integer result code from the set shown ** above in order to indicates success or failure. ** ** {F10211} The result codes shown here are the only ones returned ** by SQLite in its default configuration. {F10212} However, the ** [sqlite3_extended_result_codes()] API can be used to set a database ** connectoin to return more detailed result codes. {END} ** ** See also: [SQLITE_IOERR_READ | extended result codes] ** */ #define SQLITE_OK 0 /* Successful result */ |
︙ | ︙ | |||
318 319 320 321 322 323 324 | #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ /* end-of-error-codes */ /* ** CAPI3REF: Extended Result Codes {F10220} ** ** In its default configuration, SQLite API routines return one of 26 integer | | | | 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 | #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ /* end-of-error-codes */ /* ** CAPI3REF: Extended Result Codes {F10220} ** ** In its default configuration, SQLite API routines return one of 26 integer ** [SQLITE_OK | result codes]. However, experience has shown that ** many of these result codes are too course-grained. They do not provide as ** much information about problems as programmers might like. In an effort to ** address this, newer versions of SQLite (version 3.3.8 and later) include ** support for additional result codes that provide more detailed information ** about errors. {F10221} The extended result codes are enabled or disabled ** for each database connection using the [sqlite3_extended_result_codes()] ** API. {END} ** ** Some of the available extended result codes are listed above. |
︙ | ︙ | |||
569 570 571 572 573 574 575 | */ #define SQLITE_FCNTL_LOCKSTATE 1 /* ** CAPI3REF: Mutex Handle {F17110} ** ** The mutex module within SQLite defines [sqlite3_mutex] to be an | | | | 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 | */ #define SQLITE_FCNTL_LOCKSTATE 1 /* ** CAPI3REF: Mutex Handle {F17110} ** ** The mutex module within SQLite defines [sqlite3_mutex] to be an ** abstract type for a mutex object. {F17111} The SQLite core never looks ** at the internal representation of an [sqlite3_mutex]. {END} It only ** deals with pointers to the [sqlite3_mutex] object. ** ** Mutexes are created using [sqlite3_mutex_alloc()]. */ typedef struct sqlite3_mutex sqlite3_mutex; /* |
︙ | ︙ | |||
607 608 609 610 611 612 613 | ** 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. ** | | | | | > | | | | | | | | | > | | < | | | | | | | | 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 | ** 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. ** ** {F11141} SQLite will guarantee that the zFilename string passed to ** xOpen() is a full pathname as generated by xFullPathname() and ** that the string will be valid and unchanged until xClose() is ** called. {END} So the [sqlite3_file] can store a pointer to the ** filename if it needs to remember the filename for some reason. ** ** {F11142} The flags argument to xOpen() includes all bits set in ** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()] ** or [sqlite3_open16()] is used, then flags includes at least ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END} ** If xOpen() opens a file read-only then it sets *pOutFlags to ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be ** set. ** ** {F11143} SQLite will also add one of the following flags to the xOpen() ** call, depending on the object being opened: ** ** <ul> ** <li> [SQLITE_OPEN_MAIN_DB] ** <li> [SQLITE_OPEN_MAIN_JOURNAL] ** <li> [SQLITE_OPEN_TEMP_DB] ** <li> [SQLITE_OPEN_TEMP_JOURNAL] ** <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 are ** also a no-op. Any attempt to read the journal return SQLITE_IOERR. ** Or the implementation might recognize the a database file will ** be doing page-aligned sector reads and writes in a random order ** and set up its I/O subsystem accordingly. ** ** {F11144} 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 is 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 byte 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 |
︙ | ︙ | |||
714 715 716 717 718 719 720 | int (*xSleep)(sqlite3_vfs*, int microseconds); int (*xCurrentTime)(sqlite3_vfs*, double*); /* New fields may be appended in figure versions. The iVersion ** value will increment whenever this happens. */ }; /* | | | | | | | | > > | 724 725 726 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 | int (*xSleep)(sqlite3_vfs*, int microseconds); int (*xCurrentTime)(sqlite3_vfs*, double*); /* New fields may be appended in figure versions. The iVersion ** value will increment whenever this happens. */ }; /* ** 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 ** the kind of 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. */ #define SQLITE_ACCESS_EXISTS 0 #define SQLITE_ACCESS_READWRITE 1 #define SQLITE_ACCESS_READ 2 /* ** CAPI3REF: Enable Or Disable Extended Result Codes {F12200} ** ** {F12201} The sqlite3_extended_result_codes() routine enables or disables the ** [SQLITE_IOERR_READ | extended result codes] feature on a database ** connection if its 2nd parameter is ** non-zero or zero, respectively. {F12202} ** By default, SQLite API routines return one of only 26 integer ** [SQLITE_OK | result codes]. {F12203} When extended result codes ** are enabled by this routine, the repetoire of result codes can be ** much larger and can (hopefully) provide more detailed information ** about the cause of an error. ** ** {F12204} The second argument is a boolean value that turns extended result |
︙ | ︙ | |||
795 796 797 798 799 800 801 | ** or inserted or deleted by the most recently completed SQL statement ** on the connection specified by the first parameter. {F12242} Only ** changes that are directly specified by the INSERT, UPDATE, or ** DELETE statement are counted. Auxiliary changes caused by ** triggers are not counted. {F12243} Use the [sqlite3_total_changes()] function ** to find the total number of changes including changes caused by triggers. ** | | | | | | 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 | ** or inserted or deleted by the most recently completed SQL statement ** on the connection specified by the first parameter. {F12242} Only ** changes that are directly specified by the INSERT, UPDATE, or ** DELETE statement are counted. Auxiliary changes caused by ** triggers are not counted. {F12243} Use the [sqlite3_total_changes()] function ** to find the total number of changes including changes caused by triggers. ** ** {F12244} Within the body of a trigger, the sqlite3_changes() interface ** can be called to find the number of ** changes in the most recently completed INSERT, UPDATE, or DELETE ** statement within the body of the same trigger. ** ** {F12245} All changes are counted, even if they are later undone by a ** ROLLBACK or ABORT. {F12246} Except, changes associated with creating and ** dropping tables are not counted. ** ** {F12247} If a callback invokes [sqlite3_exec()] or [sqlite3_step()] ** recursively, then the changes in the inner, recursive call are ** counted together with the changes in the outer call. ** |
︙ | ︙ | |||
836 837 838 839 840 841 842 | ** statements executed as part of trigger programs. {F12263} All changes ** are counted as soon as the statement that makes them is completed ** (when the statement handle is passed to [sqlite3_reset()] or ** [sqlite3_finalize()]). {END} ** ** See also the [sqlite3_change()] interface. ** | | | > | 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 | ** statements executed as part of trigger programs. {F12263} All changes ** are counted as soon as the statement that makes them is completed ** (when the statement handle is passed to [sqlite3_reset()] or ** [sqlite3_finalize()]). {END} ** ** See also the [sqlite3_change()] interface. ** ** {F12265} 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 form 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. ** ** {U12264} If another thread makes changes on the same database connection |
︙ | ︙ | |||
864 865 866 867 868 869 870 871 | ** immediately. ** ** {F12272} It is safe to call this routine from a thread different from the ** thread that is currently running the database operation. {U12273} But it ** is not safe to call this routine with a database connection that ** is closed or might close before sqlite3_interrupt() returns. ** ** {F12274} The SQL operation that is interrupted will return | > > > | | | > > | | | | 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 | ** immediately. ** ** {F12272} It is safe to call this routine from a thread different from the ** thread that is currently running the database operation. {U12273} But it ** is not safe to call this routine with a database connection that ** is closed or might close before sqlite3_interrupt() returns. ** ** If an SQL is very nearly finished at the time when sqlite3_interrupt() ** is called, then it might not have an opportunity to be interrupted. ** It might continue to completion. ** {F12274} The SQL operation that is interrupted will return ** [SQLITE_INTERRUPT]. {F12275} If the interrupted SQL operation is an ** INSERT, UPDATE, or DELETE that is inside an explicit transaction, ** then the entire transaction will be rolled back automatically. ** {F12276} A call to sqlite3_interrupt() has no effect on SQL statements ** that are started after sqlite3_interrupt() returns. */ void sqlite3_interrupt(sqlite3*); /* ** CAPI3REF: Determine If An SQL Statement Is Complete {F10510} ** ** These routines are useful for command-line input to determine if the ** currently entered text seems to form complete a SQL statement or ** if additional input is needed before sending the text into ** SQLite for parsing. These routines return true if the input string ** appears to be a complete SQL statement. A statement is judged to be ** complete if it ends with a semicolon and is not a fragment of a ** CREATE TRIGGER statement. These routines do not parse the SQL and ** so will not detect syntactically incorrect SQL. ** ** {F10511} These functions return true if the given input string ** ends with a semicolon optionally followed by whitespace or ** comments. {F10512} For sqlite3_complete(), ** the parameter must be a zero-terminated UTF-8 string. {F10513} For ** sqlite3_complete16(), a zero-terminated machine byte order UTF-16 string ** is required. {F10514} These routines return false if the terminal |
︙ | ︙ | |||
905 906 907 908 909 910 911 | /* ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {F12310} ** ** {F12311} This routine identifies a callback function that might be ** invoked whenever an attempt is made to open a database table ** that another thread or process has locked. ** {F12312} If the busy callback is NULL, then [SQLITE_BUSY] | | | | | > > | < | | 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 | /* ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {F12310} ** ** {F12311} This routine identifies a callback function that might be ** invoked whenever an attempt is made to open a database table ** that another thread or process has locked. ** {F12312} If the busy callback is NULL, then [SQLITE_BUSY] ** or [SQLITE_IOERR_BLOCKED] ** is returned immediately upon encountering the lock. ** {F12313} If the busy callback is not NULL, then the ** callback will be invoked with two arguments. {F12314} The ** first argument to the handler is a copy of the void* pointer which ** is the third argument to this routine. {F12315} The second argument to ** the handler is the number of times that the busy handler has ** been invoked for this locking event. {F12316} If the ** busy callback returns 0, then no additional attempts are made to ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. ** {F12317} If the callback returns non-zero, then another attempt ** is made to open the database for reading and the cycle repeats. ** ** The presence of a busy handler does not guarantee that ** it will be invoked when there is lock contention. {F12319} ** If SQLite determines that invoking the busy handler could result in ** a deadlock, it will go ahead and return [SQLITE_BUSY] or ** [SQLITE_IOERR_BLOCKED] instead of invoking the ** busy handler. {END} ** Consider a scenario where one process is holding a read lock that ** it is trying to promote to a reserved lock and ** a second process is holding a reserved lock that it is trying ** to promote to an exclusive lock. The first process cannot proceed ** because it is blocked by the second and the second process cannot ** proceed because it is blocked by the first. If both processes ** invoke the busy handlers, neither will make any progress. Therefore, ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this ** will induce the first process to release its read lock and allow ** the second process to proceed. ** ** {F12321} The default busy callback is NULL. {END} ** ** {F12322} The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] ** when SQLite is in the middle of a large transaction where all the ** changes will not fit into the in-memory cache. {F12323} SQLite will ** already hold a RESERVED lock on the database file, but it needs ** to promote this lock to EXCLUSIVE so that it can spill cache ** pages into the database file without harm to concurrent |
︙ | ︙ | |||
968 969 970 971 972 973 974 | ** the busy handler. ** ** {F12331} When operating in [sqlite3_enable_shared_cache | shared cache mode], ** only a single busy handler can be defined for each database file. ** So if two database connections share a single cache, then changing ** the busy handler on one connection will also change the busy ** handler in the other connection. {F12332} The busy handler is invoked | | > | | 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 | ** the busy handler. ** ** {F12331} When operating in [sqlite3_enable_shared_cache | shared cache mode], ** only a single busy handler can be defined for each database file. ** So if two database connections share a single cache, then changing ** the busy handler on one connection will also change the busy ** handler in the other connection. {F12332} The busy handler is invoked ** in the thread that was running when the lock contention occurs. */ int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); /* ** CAPI3REF: Set A Busy Timeout {F12340} ** ** {F12341} This routine sets a [sqlite3_busy_handler | busy handler] ** that sleeps for a while when a ** table is locked. {F12342} The handler will sleep multiple times until ** at least "ms" milliseconds of sleeping have been done. {F12343} After ** "ms" milliseconds of sleeping, the handler returns 0 which ** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. ** ** {F12344} Calling this routine with an argument less than or equal to zero ** turns off all busy handlers. |
︙ | ︙ | |||
1149 1150 1151 1152 1153 1154 1155 | char *sqlite3_mprintf(const char*,...); char *sqlite3_vmprintf(const char*, va_list); char *sqlite3_snprintf(int,char*,const char*, ...); /* ** CAPI3REF: Memory Allocation Subsystem {F17300} ** | < | | > > | 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 | char *sqlite3_mprintf(const char*,...); char *sqlite3_vmprintf(const char*, va_list); char *sqlite3_snprintf(int,char*,const char*, ...); /* ** CAPI3REF: Memory Allocation Subsystem {F17300} ** ** {F17301} The SQLite core uses these three routines for all of its own ** internal memory allocation needs. {END} "Core" in the previous sentence ** does not include operating-system specific VFS implementation. The ** windows VFS uses native malloc and free for some operations. ** ** {F17302} The sqlite3_malloc() routine returns a pointer to a block ** of memory at least N bytes in length, where N is the parameter. ** {F17303} If sqlite3_malloc() is unable to obtain sufficient free ** memory, it returns a NULL pointer. {F17304} If the parameter N to ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns ** a NULL pointer. |
︙ | ︙ | |||
1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 | ** of at least N bytes in size or NULL if sufficient memory is unavailable. ** {F17314} If M is the size of the prior allocation, then min(N,M) bytes ** of the prior allocation are copied into the beginning of buffer returned ** by sqlite3_realloc() and the prior allocation is freed. ** {F17315} If sqlite3_realloc() returns NULL, then the prior allocation ** is not freed. ** ** {F17381} The default implementation ** of the memory allocation subsystem uses the malloc(), realloc() ** and free() provided by the standard C library. {F17382} However, if ** SQLite is compiled with the following C preprocessor macro ** ** <blockquote> SQLITE_MEMORY_SIZE=<i>NNN</i> </blockquote> ** ** where <i>NNN</i> is an integer, then SQLite create a static ** array of at least <i>NNN</i> bytes in size and use that array ** for all of its dynamic memory allocation needs. {END} Additional ** memory allocator options may be added in future releases. ** ** In SQLite version 3.5.0 and 3.5.1, it was possible to define ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in ** implementation of these routines to be omitted. That capability ** is no longer provided. Only built-in memory allocators can be ** used. ** | > > > | | 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 | ** of at least N bytes in size or NULL if sufficient memory is unavailable. ** {F17314} If M is the size of the prior allocation, then min(N,M) bytes ** of the prior allocation are copied into the beginning of buffer returned ** by sqlite3_realloc() and the prior allocation is freed. ** {F17315} If sqlite3_realloc() returns NULL, then the prior allocation ** is not freed. ** ** {F17316} The memory returned by sqlite3_malloc() and sqlite3_realloc() ** is always aligned to at least an 8 byte boundary. {END} ** ** {F17381} The default implementation ** of the memory allocation subsystem uses the malloc(), realloc() ** and free() provided by the standard C library. {F17382} However, if ** SQLite is compiled with the following C preprocessor macro ** ** <blockquote> SQLITE_MEMORY_SIZE=<i>NNN</i> </blockquote> ** ** where <i>NNN</i> is an integer, then SQLite create a static ** array of at least <i>NNN</i> bytes in size and use that array ** for all of its dynamic memory allocation needs. {END} Additional ** memory allocator options may be added in future releases. ** ** In SQLite version 3.5.0 and 3.5.1, it was possible to define ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in ** implementation of these routines to be omitted. That capability ** is no longer provided. Only built-in memory allocators can be ** used. ** ** The windows OS interface layer calls ** the system malloc() and free() directly when converting ** filenames between the UTF-8 encoding used by SQLite ** and whatever filename encoding is used by the particular windows ** installation. Memory allocation errors are detected, but ** they are reported back as [SQLITE_CANTOPEN] or ** [SQLITE_IOERR] rather than [SQLITE_NOMEM]. */ |
︙ | ︙ | |||
1232 1233 1234 1235 1236 1237 1238 | ** ** {F17371} The sqlite3_memory_used() routine returns the ** number of bytes of memory currently outstanding (malloced but not freed). ** {F17372} The value returned by sqlite3_memory_used() includes ** any overhead added by SQLite, but not overhead added by the ** library malloc() that backs the sqlite3_malloc() implementation. ** {F17373} The sqlite3_memory_highwater() routines returns the | | | | > > | | > > > > > | < > > > | > | | | | | | 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 | ** ** {F17371} The sqlite3_memory_used() routine returns the ** number of bytes of memory currently outstanding (malloced but not freed). ** {F17372} The value returned by sqlite3_memory_used() includes ** any overhead added by SQLite, but not overhead added by the ** library malloc() that backs the sqlite3_malloc() implementation. ** {F17373} The sqlite3_memory_highwater() routines returns the ** maximum number of bytes that have been outstanding at any time ** since the highwater mark was last reset. ** {F17374} The byte count returned by sqlite3_memory_highwater() ** uses the same byte counting rules as sqlite3_memory_used(). {END} ** In other words, overhead added internally by SQLite is counted, ** but overhead from the underlying system malloc is not. ** {F17375} If the parameter to sqlite3_memory_highwater() is true, ** then the highwater mark is reset to the current value of ** sqlite3_memory_used() and the prior highwater mark (before the ** reset) is returned. {F17376} If the parameter to ** sqlite3_memory_highwater() is zero, then the highwater mark is ** unchanged. */ sqlite3_int64 sqlite3_memory_used(void); sqlite3_int64 sqlite3_memory_highwater(int resetFlag); /* ** CAPI3REF: Compile-Time Authorization Callbacks {F12500} ** ** {F12501} This routine registers a authorizer callback with a particular ** database connection, supplied in the first argument. {F12502} ** 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()]. {F12503} 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. {F12504} 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 shall ** fail with an SQLITE_ERROR error code and an appropriate error message. {END} ** ** When the callback returns [SQLITE_OK], that means the operation ** requested is ok. {F12505} When the callback returns [SQLITE_DENY], the ** [sqlite3_prepare_v2()] or equivalent call that triggered the ** authorizer shall fail ** with an SQLITE_ERROR error code and an error message explaining that ** access is denied. {F12506} If the authorizer code (the 2nd parameter ** to the authorizer callback is anything other than [SQLITE_READ], then ** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY]. ** If the authorizer code is [SQLITE_READ] and the callback returns ** [SQLITE_IGNORE] then the prepared statement is constructed to ** insert a NULL value in place of the table column that would have ** been read if [SQLITE_OK] had been returned. {END} ** ** {F12510} The first parameter to the authorizer callback is a copy of ** the third parameter to the sqlite3_set_authorizer() interface. ** {F12511} The second parameter to the callback is an integer ** [SQLITE_COPY | action code] that specifies the particular action ** to be authorized. {END} The available action codes are ** [SQLITE_COPY | documented separately]. {F12512} The third through sixth |
︙ | ︙ | |||
1307 1308 1309 1310 1311 1312 1313 | int sqlite3_set_authorizer( sqlite3*, int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), void *pUserData ); /* | | | | | | | | | | 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 | int sqlite3_set_authorizer( sqlite3*, int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), void *pUserData ); /* ** CAPI3REF: Authorizer Return Codes {F12590} ** ** The [sqlite3_set_authorizer | authorizer callback function] must ** return either [SQLITE_OK] or one of these two constants in order ** to signal SQLite whether or not the action is permitted. See the ** [sqlite3_set_authorizer | authorizer documentation] for additional ** information. */ #define SQLITE_DENY 1 /* Abort the SQL statement with an error */ #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ /* ** CAPI3REF: Authorizer Action Codes {F12550} ** ** The [sqlite3_set_authorizer()] interface registers a callback function ** that is invoked to authorizer certain SQL statement actions. {F12551} The ** second parameter to the callback is an integer code that specifies ** what action is being authorized. These are the integer action codes that ** the authorizer callback may be passed. {END} ** ** These action code values signify what kind of operation is to be ** authorized. {F12552} The 3rd and 4th parameters to the authorization ** callback function will be parameters or NULL depending on which of these ** codes is used as the second parameter. {F12553} The 5th parameter to the ** authorizer callback is the name of the database ("main", "temp", ** etc.) if applicable. {F12554} The 6th parameter to the authorizer callback ** is the name of the inner-most trigger or view that is responsible for ** the access attempt or NULL if this access attempt is directly from ** top-level SQL code. */ /******************************************* 3rd ************ 4th ***********/ #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ |
︙ | ︙ | |||
1372 1373 1374 1375 1376 1377 1378 | #define SQLITE_ANALYZE 28 /* Table Name NULL */ #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ #define SQLITE_FUNCTION 31 /* Function Name NULL */ #define SQLITE_COPY 0 /* No longer used */ /* | | | | | | > > > > > > | | > > > > > > | | | 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 | #define SQLITE_ANALYZE 28 /* Table Name NULL */ #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ #define SQLITE_FUNCTION 31 /* Function Name NULL */ #define SQLITE_COPY 0 /* No longer used */ /* ** CAPI3REF: Tracing And Profiling Functions {F12280} ** ** These routines register callback functions that can be used for ** tracing and profiling the execution of SQL statements. ** ** {F12281} The callback function registered by sqlite3_trace() is invoked ** at the first [sqlite3_step()] for the evaluation of an SQL statement. ** {F12282} Only a single trace callback can be registered at a time. ** Each call to sqlite3_trace() overrides the previous. {F12283} A ** NULL callback for sqlite3_trace() disables tracing. {F12284} The ** first argument to the trace callback is a copy of the pointer which ** was the 3rd argument to sqlite3_trace. {F12285} The second argument ** to the trace callback is a zero-terminated UTF8 string containing ** the original text of the SQL statement as it was passed into ** [sqlite3_prepare_v2()] or the equivalent. {END} Note that the ** host parameter are not expanded in the SQL statement text. ** ** {F12287} The callback function registered by sqlite3_profile() is invoked ** as each SQL statement finishes. {F12288} The first parameter to the ** profile callback is a copy of the 3rd parameter to sqlite3_profile(). ** {F12289} The second parameter to the profile callback is a ** zero-terminated UTF-8 string that contains the complete text of ** the SQL statement as it was processed by [sqlite3_prepare_v2()] or ** the equivalent. {F12290} The third parameter to the profile ** callback is an estimate of the number of nanoseconds of ** wall-clock time required to run the SQL statement from start ** to finish. {END} ** ** The sqlite3_profile() API is currently considered experimental and ** is subject to change. */ void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); void *sqlite3_profile(sqlite3*, void(*xProfile)(void*,const char*,sqlite3_uint64), void*); |
︙ | ︙ | |||
1458 1459 1460 1461 1462 1463 1464 | ** UTF-16 in the native byte order if [sqlite3_open16()] is used. ** ** {F12708} Whether or not an error occurs when it is opened, resources ** associated with the [sqlite3*] handle should be released by passing it ** to [sqlite3_close()] when it is no longer required. ** ** {F12709} The [sqlite3_open_v2()] interface works like [sqlite3_open()] | | | 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 | ** UTF-16 in the native byte order if [sqlite3_open16()] is used. ** ** {F12708} Whether or not an error occurs when it is opened, resources ** associated with the [sqlite3*] handle should be released by passing it ** to [sqlite3_close()] when it is no longer required. ** ** {F12709} The [sqlite3_open_v2()] interface works like [sqlite3_open()] ** except that it acccepts two additional parameters for additional control ** over the new database connection. {F12710} The flags parameter can be ** one of: ** ** <ol> ** <li> [SQLITE_OPEN_READONLY] ** <li> [SQLITE_OPEN_READWRITE] ** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE] |
︙ | ︙ | |||
1559 1560 1561 1562 1563 1564 1565 | int sqlite3_errcode(sqlite3 *db); const char *sqlite3_errmsg(sqlite3*); const void *sqlite3_errmsg16(sqlite3*); /* ** CAPI3REF: SQL Statement Object {F13000} ** | | | | 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 | int sqlite3_errcode(sqlite3 *db); const char *sqlite3_errmsg(sqlite3*); const void *sqlite3_errmsg16(sqlite3*); /* ** CAPI3REF: SQL Statement Object {F13000} ** ** An instance of this object represent single SQL statements. This ** object is variously known as a "prepared statement" or a ** "compiled SQL statement" or simply as a "statement". ** ** The life of a statement object goes something like this: ** ** <ol> ** <li> Create the object using [sqlite3_prepare_v2()] or a related ** function. |
︙ | ︙ | |||
1599 1600 1601 1602 1603 1604 1605 | ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2() ** use UTF-16. {END} ** ** {F13013} If the nByte argument is less ** than zero, then zSql is read up to the first zero terminator. ** {F13014} If nByte is non-negative, then it is the maximum number of ** bytes read from zSql. When nByte is non-negative, the | | | | > | | 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 | ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2() ** use UTF-16. {END} ** ** {F13013} If the nByte argument is less ** than zero, then zSql is read up to the first zero terminator. ** {F13014} 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 ** until the nByte-th byte, whichever comes first. {END} ** ** {F13015} *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. {END} ** ** {F13016} *ppStmt is left pointing to a compiled ** [sqlite3_stmt | SQL statement structure] that can be ** executed using [sqlite3_step()]. Or if there is an error, *ppStmt may be ** set to NULL. {F13017} 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. ** ** {F13019} On success, [SQLITE_OK] is returned. Otherwise an ** [SQLITE_ERROR | error code] is returned. {END} |
︙ | ︙ | |||
1692 1693 1694 1695 1696 1697 1698 | ** {F13101} If the compiled SQL statement passed as an argument was ** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()], ** then this function returns a pointer to a zero-terminated string ** containing a copy of the original SQL statement. {F13102} The ** pointer is valid until the statement ** is deleted using sqlite3_finalize(). ** {F13103} The string returned by sqlite3_sql() is always UTF8 even | | > > > | > | < < | | | | 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 | ** {F13101} If the compiled SQL statement passed as an argument was ** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()], ** then this function returns a pointer to a zero-terminated string ** containing a copy of the original SQL statement. {F13102} The ** pointer is valid until the statement ** is deleted using sqlite3_finalize(). ** {F13103} The string returned by sqlite3_sql() is always UTF8 even ** if a UTF16 string was originally entered using [sqlite3_prepare16_v2()] ** or the equivalent. ** ** {F13104} If the statement was compiled using either of the legacy ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this ** function returns NULL. */ const char *sqlite3_sql(sqlite3_stmt *pStmt); /* ** CAPI3REF: Dynamically Typed Value Object {F15000} ** ** {F15001} SQLite uses the sqlite3_value object to represent all values ** that are or can be stored in a database table. {END} ** SQLite uses dynamic typing for the values it stores. ** {F15002} Values stored in sqlite3_value objects can be ** be integers, floating point values, strings, BLOBs, or NULL. */ typedef struct Mem sqlite3_value; /* ** CAPI3REF: SQL Function Context Object {F16001} ** ** The context in which an SQL function executes is stored in an ** sqlite3_context object. {F16002} A pointer to an sqlite3_context ** object is always first parameter to application-defined SQL functions. */ typedef struct sqlite3_context sqlite3_context; /* ** CAPI3REF: Binding Values To Prepared Statements {F13500} ** ** {F13501} In the SQL strings input to [sqlite3_prepare_v2()] and its ** variants, literals may be replace by a parameter in one ** of these forms: ** ** <ul> ** <li> ? ** <li> ?NNN ** <li> :AAA ** <li> @AAA |
︙ | ︙ | |||
1749 1750 1751 1752 1753 1754 1755 | ** [sqlite3_prepare_v2()] or its variants. {F13503} The second ** argument is the index of the parameter to be set. {F13504} The ** first parameter has an index of 1. {F13505} When the same named ** parameter is used more than once, second and subsequent ** occurrences have the same index as the first occurrence. ** {F13506} The index for named parameters can be looked up using the ** [sqlite3_bind_parameter_name()] API if desired. {F13507} The index | | | 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 | ** [sqlite3_prepare_v2()] or its variants. {F13503} The second ** argument is the index of the parameter to be set. {F13504} The ** first parameter has an index of 1. {F13505} When the same named ** parameter is used more than once, second and subsequent ** occurrences have the same index as the first occurrence. ** {F13506} The index for named parameters can be looked up using the ** [sqlite3_bind_parameter_name()] API if desired. {F13507} The index ** for "?NNN" parameters is the value of NNN. ** {F13508} The NNN value must be between 1 and the compile-time ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). {END} ** See <a href="limits.html">limits.html</a> for additional information. ** ** {F13509} The third argument is the value to bind to the parameter. {END} ** ** {F13510} In those |
︙ | ︙ | |||
1810 1811 1812 1813 1814 1815 1816 | int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); /* ** CAPI3REF: Number Of Host Parameters {F13600} ** ** {F13601} Return the largest host parameter index in the precompiled ** statement given as the argument. {F13602} When the host parameters | | | 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 | int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); /* ** CAPI3REF: Number Of Host Parameters {F13600} ** ** {F13601} Return the largest host parameter index in the precompiled ** statement given as the argument. {F13602} When the host parameters ** are of the forms like ":AAA", "$VVV", "@AAA", or "?", ** then they are assigned sequential increasing numbers beginning ** with one, so the value returned is the number of parameters. ** {F13603} However ** if the same host parameter name is used multiple times, each occurrance ** is given the same number, so the value returned in that case is the number ** of unique host parameter names. {F13604} If host parameters of the ** form "?NNN" are used (where NNN is an integer) then there might be |
︙ | ︙ | |||
1835 1836 1837 1838 1839 1840 1841 | ** CAPI3REF: Name Of A Host Parameter {F13620} ** ** {F13621} This routine returns a pointer to the name of the n-th ** parameter in a [sqlite3_stmt | prepared statement]. {F13622} ** Host parameters of the form ":AAA" or "@AAA" or "$VVV" have a name ** which is the string ":AAA" or "@AAA" or "$VVV". ** In other words, the initial ":" or "$" or "@" | | | | 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 | ** CAPI3REF: Name Of A Host Parameter {F13620} ** ** {F13621} This routine returns a pointer to the name of the n-th ** parameter in a [sqlite3_stmt | prepared statement]. {F13622} ** Host parameters of the form ":AAA" or "@AAA" or "$VVV" have a name ** which is the string ":AAA" or "@AAA" or "$VVV". ** In other words, the initial ":" or "$" or "@" ** is included as part of the name. {F13626} ** Parameters of the form "?" or "?NNN" have no name. ** ** {F13623} The first host parameter has an index of 1, not 0. ** ** {F13624} If the value n is out of range or if the n-th parameter is ** nameless, then NULL is returned. {F13625} 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()]. */ |
︙ | ︙ | |||
1883 1884 1885 1886 1887 1888 1889 | int sqlite3_column_count(sqlite3_stmt *pStmt); /* ** CAPI3REF: Column Names In A Result Set {F13720} ** ** {F13721} These routines return the name assigned to a particular column ** in the result set of a SELECT statement. {F13722} The sqlite3_column_name() | | > | | 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 | int sqlite3_column_count(sqlite3_stmt *pStmt); /* ** CAPI3REF: Column Names In A Result Set {F13720} ** ** {F13721} These routines return the name assigned to a particular column ** in the result set of a SELECT statement. {F13722} The sqlite3_column_name() ** interface returns a pointer to a zero-terminated UTF8 string ** and sqlite3_column_name16() returns a pointer to a zero-terminated ** UTF16 string. {F13723} The first parameter is the ** [sqlite3_stmt | prepared statement] that implements the SELECT statement. ** The second parameter is the column number. The left-most column is ** number 0. ** ** {F13724} The returned string pointer is valid until either the ** [sqlite3_stmt | prepared statement] is destroyed by [sqlite3_finalize()] ** or until the next call sqlite3_column_name() or sqlite3_column_name16() |
︙ | ︙ | |||
1952 1953 1954 1955 1956 1957 1958 | const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); /* ** CAPI3REF: Declared Datatype Of A Query Result {F13760} ** ** The first parameter is a [sqlite3_stmt | compiled SQL statement]. ** {F13761} If this statement is a SELECT statement and the Nth column of the | | | 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 | const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); /* ** CAPI3REF: Declared Datatype Of A Query Result {F13760} ** ** The first parameter is a [sqlite3_stmt | compiled SQL statement]. ** {F13761} If this statement is a SELECT statement and the Nth column of the ** returned result set of that SELECT is a table column (not an ** expression or subquery) then the declared type of the table ** column is returned. {F13762} If the Nth column of the result set is an ** expression or subquery, then a NULL pointer is returned. ** {F13763} The returned string is always UTF-8 encoded. {END} ** For example, in the database schema: ** ** CREATE TABLE t1(c1 VARIANT); |
︙ | ︙ | |||
2068 2069 2070 2071 2072 2073 2074 | ** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been ** called on the [sqlite3_stmt | prepared statement] for the first time, ** this routine returns zero. */ int sqlite3_data_count(sqlite3_stmt *pStmt); /* | | | | 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 | ** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been ** called on the [sqlite3_stmt | prepared statement] for the first time, ** this routine returns zero. */ int sqlite3_data_count(sqlite3_stmt *pStmt); /* ** CAPI3REF: Fundamental Datatypes {F10265} ** ** {F10266}Every value in SQLite has one of five fundamental datatypes: ** ** <ul> ** <li> 64-bit signed integer ** <li> 64-bit IEEE floating point number ** <li> string ** <li> BLOB ** <li> NULL |
︙ | ︙ | |||
2366 2367 2368 2369 2370 2371 2372 | void*, void (*xFunc)(sqlite3_context*,int,sqlite3_value**), void (*xStep)(sqlite3_context*,int,sqlite3_value**), void (*xFinal)(sqlite3_context*) ); /* | | | 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 | void*, void (*xFunc)(sqlite3_context*,int,sqlite3_value**), void (*xStep)(sqlite3_context*,int,sqlite3_value**), void (*xFinal)(sqlite3_context*) ); /* ** CAPI3REF: Text Encodings {F10267} ** ** These constant define integer codes that represent the various ** text encodings supported by SQLite. */ #define SQLITE_UTF8 1 #define SQLITE_UTF16LE 2 #define SQLITE_UTF16BE 3 |
︙ | ︙ | |||
2422 2423 2424 2425 2426 2427 2428 | ** 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 ** numeric affinity to the value. This means that an attempt is ** made to convert the value to an integer or floating point. If | | | | > | > | > | > | | | > > | | | < | | > | > | > > | | | | > | < | > > > | | | 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 | ** 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 ** numeric affinity to the value. This means that an attempt is ** made to convert the value to an integer or floating point. If ** such a conversion is possible without loss of information (in other ** words if the value is a string that looks like a number) ** then the conversion is done. Otherwise no conversion occurs. The ** [SQLITE_INTEGER | datatype] after conversion is returned. ** ** 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. ** Or, if the sqlite3_value* argument comes from the [sqlite3_column_value()] ** interface, then these routines should be called from the same thread ** that ran [sqlite3_column_value()]. ** */ 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. ** {F16211} 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. ** {F16212} On second and subsequent calls to sqlite3_aggregate_context() ** for the same aggregate function index, the same buffer is returned. {END} ** The implementation ** of the aggregate can use the returned buffer to accumulate data. ** ** {F16213} SQLite automatically frees the allocated buffer when the aggregate ** query concludes. {END} ** ** 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. */ void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); /* ** CAPI3REF: User Data For Functions {F16240} ** ** {F16241} 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} ** ** {U16243} This routine must be called from the same thread in which ** the application-defined function is running. */ void *sqlite3_user_data(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. ** ** {F16271} ** 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. ** {F16272} 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. ** ** {F16275} 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. {END} Subsequent ** calls to sqlite3_get_auxdata() might return this data, if it has ** not been destroyed. ** {F16277} 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. {END} ** ** 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. */ 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} ** ** These are special value for the destructor that is passed in as the ** final argument to routines like [sqlite3_result_blob()]. If the destructor |
︙ | ︙ | |||
2558 2559 2560 2561 2562 2563 2564 | ** 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. ** | > > > > > > > > > > > > | | > | | > > > > > > > > > > > > | | | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | > | > > | > | > | | > > | > | > | | > < < < < | 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 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 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 | ** 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. ** ** {F16402} 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. ** {F16403} 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. ** ** {F16407} The sqlite3_result_double() interface sets the result from ** an application defined function to be a floating point value specified ** by its 2nd argument. ** ** {F16409} The sqlite3_result_error() and sqlite3_result_error16() functions ** cause the implemented SQL function to throw an exception. ** {F16411} 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. {F16412} SQLite interprets the error ** message string from sqlite3_result_error() as UTF8. {F16413} SQLite ** interprets the string from sqlite3_result_error16() as UTF16 in native ** byte order. {F16414} 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. ** {F16415} 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. ** {F16417} The sqlite3_result_error() and sqlite3_result_error16() ** routines make a copy private copy of the error message text before ** they return. {END} Hence, the calling function can deallocate or ** modify the text after they return without harm. ** ** {F16421} The sqlite3_result_toobig() interface causes SQLite ** to throw an error indicating that a string or BLOB is to long ** to represent. {F16422} The sqlite3_result_nomem() interface ** causes SQLite to throw an exception indicating that the a ** memory allocation failed. ** ** {F16431} 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. ** {F16432} 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. ** ** {F16437} The sqlite3_result_null() interface sets the return value ** of the application-defined function to be NULL. ** ** {F16441} 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. ** {F16442} SQLite takes the text result from the application from ** the 2nd parameter of the sqlite3_result_text* interfaces. ** {F16444} 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. ** {F16447} 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. ** {F16451} 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. ** {F16453} 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. ** {F16454} 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. ** ** {F16461} The sqlite3_result_value() interface sets the result of ** the application-defined function to be a copy the [sqlite3_value] ** object specified by the 2nd parameter. {F16463} 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. ** ** {U16491} 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. */ 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_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} ** ** {F16601} ** These functions are used to add new collation sequences to the ** [sqlite3*] handle specified as the first argument. ** ** {F16602} ** 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(). {F16603} In all cases ** the name is passed as the second function argument. ** ** {F16604} ** 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. {F16605} 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. ** ** {F16607} ** A pointer to the user supplied routine must be passed as the fifth ** argument. {F16609} If it is NULL, this is the same as deleting the collation ** sequence (so that SQLite cannot call it anymore). ** {F16611} 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. ** ** {F16612} ** 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). ** ** {F16615} ** The sqlite3_create_collation_v2() works like sqlite3_create_collation() ** excapt that it takes an extra argument which is a destructor for ** the collation. {F16617} 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(). ** {F16618} 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()]. */ int sqlite3_create_collation( sqlite3*, const char *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*) |
︙ | ︙ | |||
2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 | 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 | > > | | | | | > | | | | 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 | void*, int(*xCompare)(void*,int,const void*,int,const void*) ); /* ** CAPI3REF: Collation Needed Callbacks {F16700} ** ** {F16701} ** 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. ** ** {F16702} ** 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. {F16704} A call to either ** function replaces any existing callback. ** ** {F16705} When the callback is invoked, the first argument passed is a copy ** of the second argument to sqlite3_collation_needed() or ** sqlite3_collation_needed16(). {F16706} The second argument is the database ** handle. {F16707} The third argument is one of [SQLITE_UTF8], ** [SQLITE_UTF16BE], or [SQLITE_UTF16LE], indicating the most ** desirable form of the collation sequence function required. ** {F16708} The fourth parameter is the name of the ** required collation sequence. {END} ** ** The callback function should register the desired collation using ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or ** [sqlite3_create_collation_v2()]. */ int sqlite3_collation_needed( sqlite3*, |
︙ | ︙ | |||
2719 2720 2721 2722 2723 2724 2725 | sqlite3 *db, /* Database to be rekeyed */ const void *pKey, int nKey /* The new key */ ); /* ** CAPI3REF: Suspend Execution For A Short Time {F10530} ** | > | | | | | | 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 | sqlite3 *db, /* Database to be rekeyed */ const void *pKey, int nKey /* The new key */ ); /* ** CAPI3REF: Suspend Execution For A Short Time {F10530} ** ** {F10531} The sqlite3_sleep() function ** causes the current thread to suspend execution ** for at least a number of milliseconds specified in its parameter. ** ** {F10532} If the operating system does not support sleep requests with ** millisecond time resolution, then the time will be rounded up to ** the nearest second. {F10533} The number of milliseconds of sleep actually ** requested from the operating system is returned. ** ** {F10534} SQLite implements this interface by calling the xSleep() ** method of the default [sqlite3_vfs] object. {END} */ 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 |
︙ | ︙ | |||
2751 2752 2753 2754 2755 2756 2757 | ** routines have been call and remain unchanged thereafter. */ SQLITE_EXTERN char *sqlite3_temp_directory; /* ** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode {F12930} ** | > | | | | | | | | > | > | | | > > > > > > | | | | | | | | | > > > > | | | | > | > | | > | > | > | | | > > | > | > | | | | | | | | > | | | > > > > | | | | | > > | | | | | | | 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 | ** routines have been call and remain unchanged thereafter. */ SQLITE_EXTERN char *sqlite3_temp_directory; /* ** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode {F12930} ** ** {F12931} The sqlite3_get_autocommit() interfaces returns non-zero or ** zero if the given database connection is or is not in autocommit mode, ** respectively. {F12932} Autocommit mode is on ** by default. {F12933} Autocommit mode is disabled by a BEGIN statement. ** {F12934} Autocommit mode is reenabled by a COMMIT or ROLLBACK. {END} ** ** If certain kinds of errors occur on a statement within a multi-statement ** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR], ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the ** transaction might be rolled back automatically. {F12935} The only way to ** find out if SQLite automatically rolled back the transaction after ** an error is to use this function. {END} ** ** {U12936} If another thread changes the autocommit status of the database ** connection while this routine is running, then the return value ** is undefined. {END} */ int sqlite3_get_autocommit(sqlite3*); /* ** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120} ** ** {F13121} The sqlite3_db_handle interface ** returns the [sqlite3*] database handle to which a ** [sqlite3_stmt | prepared statement] belongs. ** {F13122} 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. */ sqlite3 *sqlite3_db_handle(sqlite3_stmt*); /* ** CAPI3REF: Commit And Rollback Notification Callbacks {F12950} ** ** {F12951} The sqlite3_commit_hook() interface registers a callback ** function to be invoked whenever a transaction is committed. ** {F12952} Any callback set by a previous call to sqlite3_commit_hook() ** for the same database connection is overridden. ** {F12953} The sqlite3_rollback_hook() interface registers a callback ** function to be invoked whenever a transaction is committed. ** {F12954} Any callback set by a previous call to sqlite3_commit_hook() ** for the same database connection is overridden. ** {F12956} The pArg argument is passed through ** to the callback. {F12957} If the callback on a commit hook function ** returns non-zero, then the commit is converted into a rollback. ** ** {F12958} If another function was previously registered, its ** pArg value is returned. Otherwise NULL is returned. ** ** {F12959} Registering a NULL function disables the callback. ** ** {F12961} 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. ** {F12962} The rollback callback is not invoked if a transaction is ** automatically rolled back because the database connection is closed. ** {F12964} The rollback callback is not invoked if a transaction is ** rolled back because a commit callback returned non-zero. ** <todo> Check on this </todo> {END} ** ** These are experimental interfaces and are subject to change. */ void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); /* ** CAPI3REF: Data Change Notification Callbacks {F12970} ** ** {F12971} 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. ** {F12972} Any callback set by a previous call to this function for the same ** database connection is overridden. ** ** {F12974} The second argument is a pointer to the function to invoke when a ** row is updated, inserted or deleted. ** {F12976} The first argument to the callback is ** a copy of the third argument to sqlite3_update_hook(). ** {F12977} 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. ** {F12978} The third and ** fourth arguments to the callback contain pointers to the database and ** table name containing the affected row. ** {F12979} The final callback parameter is ** the rowid of the row. ** {F12981} In the case of an update, this is the rowid after ** the update takes place. ** ** {F12983} The update hook is not invoked when internal system tables are ** modified (i.e. sqlite_master and sqlite_sequence). ** ** {F12984} If another function was previously registered, its pArg value ** is returned. {F12985} Otherwise NULL is returned. */ void *sqlite3_update_hook( sqlite3*, void(*)(void *,int ,char const *,char const *,sqlite3_int64), void* ); /* ** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330} ** ** {F10331} ** This routine enables or disables the sharing of the database cache ** and schema data structures between connections to the same database. ** {F10332} ** Sharing is enabled if the argument is true and disabled if the argument ** is false. ** ** {F10333} 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. ** ** {F10334} ** The cache sharing mode set by this interface effects all subsequent ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. ** {F10335} Existing database connections continue use the sharing mode ** that was in effect at the time they were opened. {END} ** ** Virtual tables cannot be used with a shared cache. {F10336} When shared ** cache is enabled, the [sqlite3_create_module()] API used to register ** virtual tables will always return an error. {END} ** ** {F10337} This routine returns [SQLITE_OK] if shared cache was ** enabled or disabled successfully. {F10338} An [SQLITE_ERROR | error code] ** is returned otherwise. {END} ** ** {F10339} Shared cache is disabled by default. {END} But this might change in ** future releases of SQLite. Applications that care about shared ** cache setting should set it explicitly. */ int sqlite3_enable_shared_cache(int); /* ** CAPI3REF: Attempt To Free Heap Memory {F17340} ** ** {F17341} 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. {F16342} sqlite3_release_memory() 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} ** ** {F16351} The sqlite3_soft_heap_limit() interface ** places a "soft" limit on the amount of heap memory that may be allocated ** by SQLite. {F16352} 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. {END} ** ** {F16353} 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. ** ** {F16354} ** 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. ** {F16355} The default value for the soft heap limit is zero. ** ** SQLite makes a best effort to honor the soft heap limit. ** {F16356} But if the soft heap limit cannot honored, execution will ** continue without error or notification. {END} 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. {F16357} The value specified for the soft heap limit ** is an upper bound on the total memory allocation for all threads. {END} In ** version 3.5.0 there is no mechanism for limiting the heap usage for ** individual threads. */ void sqlite3_soft_heap_limit(int); /* ** CAPI3REF: Extract Metadata About A Column Of A Table {F12850} |
︙ | ︙ | |||
2987 2988 2989 2990 2991 2992 2993 | int *pPrimaryKey, /* OUTPUT: True if column part of PK */ int *pAutoinc /* OUTPUT: True if column is auto-increment */ ); /* ** CAPI3REF: Load An Extension {F12600} ** | > | | > | > | > | > > | > | > | | > | | | | | | > | | | 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 | int *pPrimaryKey, /* OUTPUT: True if column part of PK */ int *pAutoinc /* OUTPUT: True if column is auto-increment */ ); /* ** CAPI3REF: Load An Extension {F12600} ** ** {F12601} The sqlite3_load_extension() interface ** attempts to load an SQLite extension library contained in the file ** zFile. {F12602} The entry point is zProc. {F12603} zProc may be 0 ** in which case the name of the entry point defaults ** to "sqlite3_extension_init". ** ** {F12604} The sqlite3_load_extension() interface shall ** return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. ** ** {F12605} ** If an error occurs and pzErrMsg is not 0, then the ** sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with ** error message text stored in memory obtained from [sqlite3_malloc()]. ** {END} The calling function should free this memory ** by calling [sqlite3_free()]. ** ** {F12606} ** Extension loading must be enabled using [sqlite3_enable_load_extension()] ** prior to calling this API or an error will be returned. */ int sqlite3_load_extension( sqlite3 *db, /* Load the extension into this database connection */ const char *zFile, /* Name of the shared library containing extension */ const char *zProc, /* Entry point. Derived from zFile if 0 */ char **pzErrMsg /* Put error message here if not 0 */ ); /* ** CAPI3REF: Enable Or Disable Extension Loading {F12620} ** ** So as not to open security holes in older applications that are ** unprepared to deal with extension loading, and as a means of disabling ** extension loading while evaluating user-entered SQL, the following ** API is provided to turn the [sqlite3_load_extension()] mechanism on and ** off. {F12622} It is off by default. {END} See ticket #1863. ** ** {F12621} Call the sqlite3_enable_load_extension() routine ** with onoff==1 to turn extension loading on ** and call it with onoff==0 to turn it back off again. {END} */ int sqlite3_enable_load_extension(sqlite3 *db, int onoff); /* ** CAPI3REF: Make Arrangements To Automatically Load An Extension {F12640} ** ** {F12641} This function ** registers an extension entry point that is automatically invoked ** whenever a new database connection is opened using ** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()]. {END} ** ** This API can be invoked at program startup in order to register ** one or more statically linked extensions that will be available ** to all new database connections. ** ** {F12642} Duplicate extensions are detected so calling this routine multiple ** times with the same extension is harmless. ** ** {F12643} This routine stores a pointer to the extension in an array ** that is obtained from sqlite_malloc(). {END} If you run a memory leak ** checker on your program and it reports a leak because of this ** array, then invoke [sqlite3_reset_auto_extension()] prior ** to shutdown to free the memory. ** ** {F12644} Automatic extensions apply across all threads. {END} ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. */ int sqlite3_auto_extension(void *xEntryPoint); /* ** CAPI3REF: Reset Automatic Extension Loading {F12660} ** ** {F12661} This function disables all previously registered ** automatic extensions. {END} This ** routine undoes the effect of all prior [sqlite3_automatic_extension()] ** calls. ** ** {F12662} This call disabled automatic extensions in all threads. {END} ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. */ void sqlite3_reset_auto_extension(void); |
︙ | ︙ | |||
3316 3317 3318 3319 3320 3321 3322 | ** blob in bytes. */ typedef struct sqlite3_blob sqlite3_blob; /* ** CAPI3REF: Open A BLOB For Incremental I/O {F17810} ** | | | | | | | | | | | > > | > > | | > | | | > > > > | | | | | | | > | | > > | | | | | | | | | | | | 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 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 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 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 | ** blob in bytes. */ typedef struct sqlite3_blob sqlite3_blob; /* ** CAPI3REF: Open A BLOB For Incremental I/O {F17810} ** ** {F17811} 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} ** ** {F17812} 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. {END} ** ** {F17813} On success, [SQLITE_OK] is returned and the new ** [sqlite3_blob | blob handle] is written to *ppBlob. ** {F17814} Otherwise an error code is returned and ** any value written to *ppBlob should not be used by the caller. ** {F17815} This function sets the database-handle error code and message ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. ** <todo>We should go through and mark all interfaces that behave this ** way with a similar statement</todo> */ 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]. ** ** {F17831} 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. ** {F17832} 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. ** ** {F17839} The BLOB is closed unconditionally. Even if this routine returns ** an error code, the BLOB is still closed. */ int sqlite3_blob_close(sqlite3_blob *); /* ** CAPI3REF: Return The Size Of An Open BLOB {F17805} ** ** {F16806} Return the size in bytes of the blob accessible via the open ** [sqlite3_blob | blob-handle] passed as an argument. */ 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. ** {F17851} n bytes of data are copied into buffer ** z from the open blob, starting at offset iOffset. ** ** {F17852} If offset iOffset is less than n bytes from the end of the blob, ** [SQLITE_ERROR] is returned and no data is read. {F17853} If n is ** less than zero [SQLITE_ERROR] is returned and no data is read. ** ** {F17854} On success, SQLITE_OK is returned. Otherwise, an ** [SQLITE_ERROR | SQLite error code] or an ** [SQLITE_IOERR_READ | extended error code] is returned. */ 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. ** {F17871} n bytes of data are copied from the buffer ** pointed to by z into the open blob, starting at offset iOffset. ** ** {F17872} 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]. ** ** {F17873} This function may only modify the contents of the blob; it is ** not possible to increase the size of a blob using this API. ** {F17874} If offset iOffset is less than n bytes from the end of the blob, ** [SQLITE_ERROR] is returned and no data is written. {F17875} If n is ** less than zero [SQLITE_ERROR] is returned and no data is written. ** ** {F17876} On success, SQLITE_OK is returned. Otherwise, an ** [SQLITE_ERROR | SQLite error code] or an ** [SQLITE_IOERR_READ | extended error code] is returned. */ 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 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. ** ** {F11201} The sqlite3_vfs_find() interface returns a pointer to ** a VFS given its name. {F11202} Names are case sensitive. ** {F11203} Names are zero-terminated UTF-8 strings. ** {F11204} If there is no match, a NULL ** pointer is returned. {F11205} If zVfsName is NULL then the default ** VFS is returned. {END} ** ** {F11210} New VFSes are registered with sqlite3_vfs_register(). ** {F11211} Each new VFS becomes the default VFS if the makeDflt flag is set. ** {F11212} The same VFS can be registered multiple times without injury. ** {F11213} To make an existing VFS into the default VFS, register it again ** with the makeDflt flag set. {U11214} If two different VFSes with the ** same name are registered, the behavior is undefined. {U11215} If a ** VFS is registered with a name that is NULL or an empty string, ** then the behavior is undefined. ** ** {F11220} Unregister a VFS with the sqlite3_vfs_unregister() interface. ** {F11221} If the default VFS is unregistered, another VFS is chosen as ** the default. The choice for the new VFS is arbitrary. */ sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); int sqlite3_vfs_unregister(sqlite3_vfs*); /* |
︙ | ︙ | |||
3474 3475 3476 3477 3478 3479 3480 | ** implementation is included with the library. The ** mutex interface routines defined here become external ** references in the SQLite library for which implementations ** must be provided by the application. This facility allows an ** application that links against SQLite to provide its own mutex ** implementation without having to modify the SQLite core. ** | | | | | | | | | | | | | | | | | | | | | | | | | > | | > | | | | | | | | | 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 | ** implementation is included with the library. The ** mutex interface routines defined here become external ** references in the SQLite library for which implementations ** must be provided by the application. This facility allows an ** application that links against SQLite to provide its own mutex ** implementation without having to modify the SQLite core. ** ** {F17011} The sqlite3_mutex_alloc() routine allocates a new ** mutex and returns a pointer to it. {F17012} If it returns NULL ** that means that a mutex could not be allocated. {F17013} SQLite ** will unwind its stack and return an error. {F17014} The argument ** to sqlite3_mutex_alloc() is one of these integer constants: ** ** <ul> ** <li> SQLITE_MUTEX_FAST ** <li> SQLITE_MUTEX_RECURSIVE ** <li> SQLITE_MUTEX_STATIC_MASTER ** <li> SQLITE_MUTEX_STATIC_MEM ** <li> SQLITE_MUTEX_STATIC_MEM2 ** <li> SQLITE_MUTEX_STATIC_PRNG ** <li> SQLITE_MUTEX_STATIC_LRU ** </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 ** not want to. {F17016} But SQLite will only request a recursive mutex in ** cases where it really needs one. {END} If a faster non-recursive mutex ** implementation is available on the host platform, the mutex subsystem ** might return such a mutex in response to SQLITE_MUTEX_FAST. ** ** {F17017} The other allowed parameters to sqlite3_mutex_alloc() each return ** a pointer to a static preexisting mutex. {END} Four static mutexes are ** used by the current version of SQLite. Future versions of SQLite ** may add additional static mutexes. Static mutexes are for internal ** use by SQLite only. Applications that use SQLite mutexes should ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or ** SQLITE_MUTEX_RECURSIVE. ** ** {F17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() ** returns a different mutex on every call. {F17034} But for the static ** mutex types, the same mutex is returned on every call that has ** the same type number. {END} ** ** {F17019} The sqlite3_mutex_free() routine deallocates a previously ** allocated dynamic mutex. {F17020} SQLite is careful to deallocate every ** dynamic mutex that it allocates. {U17021} The dynamic mutexes must not be in ** use when they are deallocated. {U17022} Attempting to deallocate a static ** mutex results in undefined behavior. {F17023} SQLite never deallocates ** a static mutex. {END} ** ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt ** to enter a mutex. {F17024} If another thread is already within the mutex, ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return ** SQLITE_BUSY. {F17025} The sqlite3_mutex_try() interface returns SQLITE_OK ** upon successful entry. {F17026} Mutexes created using ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. ** {F17027} In such cases the, ** mutex must be exited an equal number of times before another thread ** can enter. {U17028} If the same thread tries to enter any other ** kind of mutex more than once, the behavior is undefined. ** {F17029} SQLite will never exhibit ** such behavior in its own use of mutexes. {END} ** ** Some systems (ex: windows95) do not the operation implemented by ** sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() will ** always return SQLITE_BUSY. {F17030} The SQLite core only ever uses ** sqlite3_mutex_try() as an optimization so this is acceptable behavior. {END} ** ** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was ** previously entered by the same thread. {U17032} The behavior ** is undefined if the mutex is not currently entered by the ** calling thread or is not currently allocated. {F17033} SQLite will ** never do either. {END} ** ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. */ sqlite3_mutex *sqlite3_mutex_alloc(int); void sqlite3_mutex_free(sqlite3_mutex*); void sqlite3_mutex_enter(sqlite3_mutex*); int sqlite3_mutex_try(sqlite3_mutex*); void sqlite3_mutex_leave(sqlite3_mutex*); /* ** CAPI3REF: Mutex Verifcation Routines {F17080} ** ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines ** are intended for use inside assert() statements. {F17081} The SQLite core ** never uses these routines except inside an assert() and applications ** are advised to follow the lead of the core. {F17082} The core only ** provides implementations for these routines when it is compiled ** with the SQLITE_DEBUG flag. {U17087} External mutex implementations ** are only required to provide these routines if SQLITE_DEBUG is ** defined and if NDEBUG is not defined. ** ** {F17083} These routines should return true if the mutex in their argument ** is held or not held, respectively, by the calling thread. {END} ** ** {X17084} The implementation is not required to provided versions of these |
︙ | ︙ | |||
3616 3617 3618 3619 3620 3621 3622 | ** are passed directly through to the second and third parameters of ** the xFileControl method. {F11305} The return value of the xFileControl ** method becomes the return value of this routine. ** ** {F11306} If the second parameter (zDbName) does not match the name of any ** open database file, then SQLITE_ERROR is returned. {F11307} This error ** code is not remembered and will not be recalled by [sqlite3_errcode()] | | | | 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 | ** are passed directly through to the second and third parameters of ** the xFileControl method. {F11305} The return value of the xFileControl ** method becomes the return value of this routine. ** ** {F11306} If the second parameter (zDbName) does not match the name of any ** open database file, then SQLITE_ERROR is returned. {F11307} This error ** code is not remembered and will not be recalled by [sqlite3_errcode()] ** or [sqlite3_errmsg()]. {U11308} The underlying xFileControl method might ** also return SQLITE_ERROR. {U11309} There is no way to distinguish between ** an incorrect zDbName and an SQLITE_ERROR return from the underlying ** xFileControl method. {END} ** ** See also: [SQLITE_FCNTL_LOCKSTATE] */ int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); |
︙ | ︙ |