Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Readded erroneously deleted {END} tag and doublechecked {(F,U,X)*}-{END} tag balancing. Minor documentation cleanup. No changes to code. (CVS 5271) |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
b55590501b5b5ada4e22d790e1a36b53 |
User & Date: | mihailim 2008-06-22 10:21:27.000 |
Context
2008-06-22
| ||
12:37 | Fix a bug in the KEYINFO handling within select.c. Change the OP_Move opcode to take a count and to move multiple registers. Initial code for the compound-select merge optimization is added but is incomplete and is commented out. (CVS 5272) (check-in: 663a590e30 user: drh tags: trunk) | |
10:21 | Readded erroneously deleted {END} tag and doublechecked {(F,U,X)*}-{END} tag balancing. Minor documentation cleanup. No changes to code. (CVS 5271) (check-in: b55590501b user: mihailim tags: trunk) | |
09:55 | More documentation spellcheck and cleanup. No changes to code. (CVS 5270) (check-in: 3a88e3ded9 user: mihailim 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.351 2008/06/22 10:21:27 mihailim 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++. |
︙ | ︙ | |||
721 722 723 724 725 726 727 | ** ** 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 | | | 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 | ** ** 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 |
︙ | ︙ | |||
763 764 765 766 767 768 769 770 771 | ** <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 | > | | | | | 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 | ** <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. ** ** {F11148} At least szOsFile bytes of memory are allocated by SQLite ** to hold the [sqlite3_file] structure passed as the third ** argument to xOpen. {END} The xOpen method does not have to ** allocate the structure; it should just fill it in. ** ** {F11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ] ** to test whether a file is at least readable. {END} The file can be a ** directory. ** ** {F11150} SQLite will always allocate at least mxPathname+1 bytes for the ** output buffer 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. Since this is ** handled as a fatal error by SQLite, vfs implementations should endeavor ** to prevent this by setting mxPathname to a sufficiently large value. ** ** The xRandomness(), xSleep(), and xCurrentTime() interfaces ** are not strictly a part of the filesystem, but they are ** included in the VFS structure for completeness. |
︙ | ︙ | |||
825 826 827 828 829 830 831 | }; /* ** 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 | | | | | | | | | 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 | }; /* ** CAPI3REF: Flags for the xAccess VFS method {F11190} ** ** {F11191} These integer constants can be used as the third parameter to ** the xAccess method of an [sqlite3_vfs] object. {END} They determine ** what kind of permissions the xAccess method is looking for. ** {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method ** simply checks whether the file exists. ** {F11193} With SQLITE_ACCESS_READWRITE, the xAccess method ** checks whether the file is both readable and writable. ** {F11194} With SQLITE_ACCESS_READ, the xAccess method ** checks whether the file is readable. */ #define SQLITE_ACCESS_EXISTS 0 #define SQLITE_ACCESS_READWRITE 1 #define SQLITE_ACCESS_READ 2 /* ** CAPI3REF: Initialize The SQLite Library {F10130} |
︙ | ︙ | |||
1603 1604 1605 1606 1607 1608 1609 | ** ** These routines are workalikes of the "printf()" family of functions ** from the standard C library. ** ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their ** results into memory obtained from [sqlite3_malloc()]. ** The strings returned by these two routines should be | | | 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 | ** ** These routines are workalikes of the "printf()" family of functions ** from the standard C library. ** ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their ** results into memory obtained from [sqlite3_malloc()]. ** The strings returned by these two routines should be ** released by [sqlite3_free()]. Both routines return a ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough ** memory to hold the resulting string. ** ** In sqlite3_snprintf() routine is similar to "snprintf()" from ** the standard C library. The result is written into the ** buffer supplied as the second parameter whose size is given by ** the first parameter. Note that the order of the |
︙ | ︙ | |||
1671 1672 1673 1674 1675 1676 1677 | ** ** This second example is an SQL syntax error. As a general rule you should ** always use %q instead of %s when inserting text into a string literal. ** ** The %Q option works like %q except it also adds single quotes around ** the outside of the total string. Additionally, if the parameter in the ** argument list is a NULL pointer, %Q substitutes the text "NULL" (without | | < | 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 | ** ** This second example is an SQL syntax error. As a general rule you should ** always use %q instead of %s when inserting text into a string literal. ** ** The %Q option works like %q except it also adds single quotes around ** the outside of the total string. Additionally, if the parameter in the ** argument list is a NULL pointer, %Q substitutes the text "NULL" (without ** single quotes) in place of the %Q option. So, for example, one could say: ** ** <blockquote><pre> ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText); ** sqlite3_exec(db, zSQL, 0, 0, 0); ** sqlite3_free(zSQL); ** </pre></blockquote> ** |
︙ | ︙ | |||
2190 2191 2192 2193 2194 2195 2196 | ** the callback. If N is less than 1, sqlite3_progress_handler() ** acts as if a NULL progress handler had been specified. ** ** {F12913} The progress callback itself is identified by the third ** argument to sqlite3_progress_handler(). ** ** {F12914} The fourth argument to sqlite3_progress_handler() is a | | | < | | 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 | ** the callback. If N is less than 1, sqlite3_progress_handler() ** acts as if a NULL progress handler had been specified. ** ** {F12913} The progress callback itself is identified by the third ** argument to sqlite3_progress_handler(). ** ** {F12914} The fourth argument to sqlite3_progress_handler() is a ** void pointer passed to the progress callback ** function each time it is invoked. ** ** {F12915} If a call to [sqlite3_step()] results in fewer than N opcodes ** being executed, then the progress callback is never invoked. ** ** {F12916} Every call to [sqlite3_progress_handler()] ** overwrites any previously registered progress handler. ** ** {F12917} If the progress handler callback is NULL then no progress ** handler is invoked. ** |
︙ | ︙ | |||
2548 2549 2550 2551 2552 2553 2554 | ** ** The first argument, "db", is a [database connection] obtained from a ** prior call to [sqlite3_open()], [sqlite3_open_v2()] or [sqlite3_open16()]. ** ** The second argument, "zSql", is the statement to be compiled, encoded ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() ** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2() | | | | | | 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 2599 2600 2601 2602 2603 2604 | ** ** The first argument, "db", is a [database connection] obtained from a ** prior call to [sqlite3_open()], [sqlite3_open_v2()] or [sqlite3_open16()]. ** ** The second argument, "zSql", is the statement to be compiled, encoded ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() ** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2() ** use UTF-16. ** ** If the nByte argument is less than zero, then zSql is read up to the ** first zero terminator. If nByte is non-negative, then it is the maximum ** number of bytes read from zSql. When nByte is non-negative, the ** zSql string ends at either the first '\000' or '\u0000' character or ** the nByte-th byte, whichever comes first. If the caller knows ** that the supplied string is nul-terminated, then there is a small ** performance advantage to be gained by passing an nByte parameter that ** is equal to the number of bytes in the input string <i>including</i> ** the nul-terminator bytes. ** ** *pzTail is made to point to the first byte past the end of the ** first SQL statement in zSql. These routines only compile the first ** statement in zSql, so *pzTail is left pointing to what remains ** uncompiled. ** ** *ppStmt is left pointing to a compiled [prepared statement] that can be ** executed using [sqlite3_step()]. If there is an error, *ppStmt is set ** to NULL. If the input text contains no SQL (if the input is an empty ** string or a comment) then *ppStmt is set to NULL. ** {U13018} The calling procedure is responsible for deleting the compiled ** SQL statement using [sqlite3_finalize()] after it has finished with it. ** ** On success, [SQLITE_OK] is returned, otherwise an [error code] is returned. ** ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are ** recommended for all new programs. The two older interfaces are retained ** for backwards compatibility, but their use is discouraged. ** In the "v2" interfaces, the prepared statement ** that is returned (the [sqlite3_stmt] object) contains a copy of the ** original SQL text. This causes the [sqlite3_step()] interface to ** behave a differently in two ways: ** ** <ol> ** <li> ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it ** always used to do, [sqlite3_step()] will automatically recompile the SQL ** statement and try to run it again. If the schema has changed in ** a way that makes the statement no longer valid, [sqlite3_step()] will still ** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is ** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the ** error go away. Note: use [sqlite3_errmsg()] to find the text ** of the parsing error that results in an [SQLITE_SCHEMA] return. ** </li> ** ** <li> ** When an error occurs, [sqlite3_step()] will return one of the detailed ** [error codes] or [extended error codes]. The legacy behavior was that ** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code ** and you would have to make a second call to [sqlite3_reset()] in order |
︙ | ︙ | |||
3227 3228 3229 3230 3231 3232 3233 | ** calls to [sqlite3_column_decltype(S,N)] or ** [sqlite3_column_decltype16(S,N)] return NULL. */ const char *sqlite3_column_decltype(sqlite3_stmt*,int); const void *sqlite3_column_decltype16(sqlite3_stmt*,int); /* | | | 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 | ** calls to [sqlite3_column_decltype(S,N)] or ** [sqlite3_column_decltype16(S,N)] return NULL. */ const char *sqlite3_column_decltype(sqlite3_stmt*,int); const void *sqlite3_column_decltype16(sqlite3_stmt*,int); /* ** CAPI3REF: Evaluate An SQL Statement {F13200} ** ** After a [prepared statement] has been prepared using either ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function ** must be called one or more times to evaluate the statement. ** ** The details of the behavior of the sqlite3_step() interface depend |
︙ | ︙ | |||
3418 3419 3420 3421 3422 3423 3424 | ** the number of bytes in that string. ** The value returned does not include the zero terminator at the end ** of the string. For clarity: the value returned is the number of ** bytes in the string, not the number of characters. ** ** Strings returned by sqlite3_column_text() and sqlite3_column_text16(), ** even empty strings, are always zero terminated. The return | | | 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 | ** the number of bytes in that string. ** The value returned does not include the zero terminator at the end ** of the string. For clarity: the value returned is the number of ** bytes in the string, not the number of characters. ** ** Strings returned by sqlite3_column_text() and sqlite3_column_text16(), ** even empty strings, are always zero terminated. The return ** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary ** pointer, possibly even a NULL pointer. ** ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() ** but leaves the result in UTF-16 in native byte order instead of UTF-8. ** The zero terminator is not included in this count. ** ** The object returned by [sqlite3_column_value()] is an |
︙ | ︙ | |||
3512 3513 3514 3515 3516 3517 3518 | ** to sqlite3_column_text() or sqlite3_column_blob() with calls to ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() ** with calls to sqlite3_column_bytes(). ** ** The pointers returned are valid until a type conversion occurs as ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or ** [sqlite3_finalize()] is called. The memory space used to hold strings | | | 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 | ** to sqlite3_column_text() or sqlite3_column_blob() with calls to ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() ** with calls to sqlite3_column_bytes(). ** ** The pointers returned are valid until a type conversion occurs as ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or ** [sqlite3_finalize()] is called. The memory space used to hold strings ** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned ** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into ** [sqlite3_free()]. ** ** If a memory allocation error occurs during the evaluation of any ** of these routines, a default value is returned. The default value ** is either the integer 0, the floating point number 0.0, or a NULL ** pointer. Subsequent calls to [sqlite3_errcode()] will return |
︙ | ︙ | |||
4354 4355 4356 4357 4358 4359 4360 | ** Each time the application supplied function is invoked, it is passed ** as its first parameter a copy of the void* passed as the fourth argument ** to sqlite3_create_collation() or sqlite3_create_collation16(). ** ** 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 | | | 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 | ** Each time the application supplied function is invoked, it is passed ** as its first parameter a copy of the void* passed as the fourth argument ** to sqlite3_create_collation() or sqlite3_create_collation16(). ** ** The remaining arguments to the application-supplied routine are two strings, ** each represented by a (length, data) pair and encoded in the encoding ** that was passed as the third argument when the collation sequence was ** registered. {END} The application defined collation routine should ** return negative, zero or positive if the first string is less than, ** equal to, or greater than the second string. i.e. (STRING1 - STRING2). ** ** The sqlite3_create_collation_v2() works like sqlite3_create_collation() ** except that it takes an extra argument which is a destructor for ** the collation. The destructor is called when the collation is ** destroyed and is passed a copy of the fourth parameter void* pointer |
︙ | ︙ | |||
4521 4522 4523 4524 4525 4526 4527 | */ int sqlite3_rekey( sqlite3 *db, /* Database to be rekeyed */ const void *pKey, int nKey /* The new key */ ); /* | | | 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 | */ int sqlite3_rekey( sqlite3 *db, /* Database to be rekeyed */ const void *pKey, int nKey /* The new key */ ); /* ** CAPI3REF: Suspend Execution For A Short Time {F10530} ** ** The sqlite3_sleep() function causes the current thread to suspend execution ** for at least a number of milliseconds specified in its parameter. ** ** If the operating system does not support sleep requests with ** millisecond time resolution, then the time will be rounded up to ** the nearest second. The number of milliseconds of sleep actually |
︙ | ︙ | |||
4548 4549 4550 4551 4552 4553 4554 | ** {F10536} The [sqlite3_sleep(M)] interface returns the number of ** milliseconds of sleep actually requested of the operating ** system, which might be larger than the parameter M. */ int sqlite3_sleep(int); /* | | | | 4547 4548 4549 4550 4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 | ** {F10536} The [sqlite3_sleep(M)] interface returns the number of ** milliseconds of sleep actually requested of the operating ** system, which might be larger than the parameter M. */ int sqlite3_sleep(int); /* ** CAPI3REF: Name Of The Folder Holding Temporary Files {F10310} ** ** If this global variable is made to point to a string which is ** the name of a folder (a.k.a. directory), then all temporary files ** created by SQLite will be placed in that directory. If this variable ** is a NULL pointer, then SQLite performs a search for an appropriate ** temporary file directory. ** ** It is not safe to modify this variable once a [database connection] ** has been opened. It is intended that this variable be set once ** as part of process initialization and before any SQLite interface ** routines have been call and remain unchanged thereafter. */ SQLITE_EXTERN char *sqlite3_temp_directory; /* ** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode {F12930} ** KEYWORDS: {autocommit mode} ** ** The sqlite3_get_autocommit() interface returns non-zero or ** zero if the given database connection is or is not in autocommit mode, ** respectively. Autocommit mode is on by default. ** Autocommit mode is disabled by a [BEGIN] statement. ** Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK]. ** ** If certain kinds of errors occur on a statement within a multi-statement ** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR], ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the ** transaction might be rolled back automatically. The only way to |
︙ | ︙ | |||
4594 4595 4596 4597 4598 4599 4600 | ** ** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement. ** ** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK] ** statement. ** ** LIMITATIONS: | | | | | 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 | ** ** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement. ** ** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK] ** statement. ** ** LIMITATIONS: ** ** {U12936} If another thread changes the autocommit status of the database ** connection while this routine is running, then the return value ** is undefined. */ int sqlite3_get_autocommit(sqlite3*); /* ** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120} ** ** The sqlite3_db_handle interface returns the [database connection] handle ** to which a [prepared statement] belongs. The database handle returned by ** sqlite3_db_handle is the same database handle that was the first argument ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to ** create the statement in the first place. ** ** INVARIANTS: ** ** {F13123} The [sqlite3_db_handle(S)] interface returns a pointer ** to the [database connection] associated with the ** [prepared statement] S. */ sqlite3 *sqlite3_db_handle(sqlite3_stmt*); /* ** CAPI3REF: Find the next prepared statement {F13140} ** ** This interface returns a pointer to the next [prepared statement] after ** pStmt associated with the [database connection] pDb. If pStmt is NULL ** then this interface returns a pointer to the first prepared statement ** associated with the database connection pDb. If no prepared statement ** satisfies the conditions of this routine, it returns NULL. ** |
︙ | ︙ | |||
4784 4785 4786 4787 4788 4789 4790 | void *sqlite3_update_hook( sqlite3*, void(*)(void *,int ,char const *,char const *,sqlite3_int64), void* ); /* | | | 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 | void *sqlite3_update_hook( sqlite3*, void(*)(void *,int ,char const *,char const *,sqlite3_int64), void* ); /* ** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330} ** KEYWORDS: {shared cache} {shared cache mode} ** ** This routine enables or disables the sharing of the database cache ** and schema data structures between [database connection | connections] ** to the same database. Sharing is enabled if the argument is true ** and disabled if the argument is false. ** |
︙ | ︙ | |||
4829 4830 4831 4832 4833 4834 4835 | ** [SQLITE_OK] if shared cache was enabled or disabled successfully. ** ** {F10339} Shared cache is disabled by default. */ int sqlite3_enable_shared_cache(int); /* | | | | | | < | | | | 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 4858 4859 4860 4861 4862 4863 4864 | ** [SQLITE_OK] if shared cache was enabled or disabled successfully. ** ** {F10339} Shared cache is disabled by default. */ int sqlite3_enable_shared_cache(int); /* ** CAPI3REF: Attempt To Free Heap Memory {F17340} ** ** The sqlite3_release_memory() interface attempts to free N bytes ** of heap memory by deallocating non-essential memory allocations ** held by the database library. {END} Memory used to cache database ** pages to improve performance is an example of non-essential memory. ** sqlite3_release_memory() returns the number of bytes actually freed, ** which might be more or less than the amount requested. ** ** INVARIANTS: ** ** {F17341} The [sqlite3_release_memory(N)] interface attempts to ** free N bytes of heap memory by deallocating non-essential ** memory allocations held by the database library. ** ** {F16342} The [sqlite3_release_memory(N)] returns the number ** of bytes actually freed, which might be more or less ** than the amount requested. */ int sqlite3_release_memory(int); /* ** CAPI3REF: Impose A Limit On Heap Size {F17350} ** ** The sqlite3_soft_heap_limit() interface places a "soft" limit ** on the amount of heap memory that may be allocated by SQLite. ** If an internal allocation is requested that would exceed the ** soft heap limit, [sqlite3_release_memory()] is invoked one or ** more times to free up some space before the allocation is performed. ** |
︙ | ︙ | |||
5044 5045 5046 5047 5048 5049 5050 | int sqlite3_enable_load_extension(sqlite3 *db, int onoff); /* ** CAPI3REF: Make Arrangements To Automatically Load An Extension {F12640} ** ** This API can be invoked at program startup in order to register ** one or more statically linked extensions that will be available | | < < < > > > | 5042 5043 5044 5045 5046 5047 5048 5049 5050 5051 5052 5053 5054 5055 5056 5057 5058 5059 5060 5061 5062 5063 5064 | int sqlite3_enable_load_extension(sqlite3 *db, int onoff); /* ** CAPI3REF: Make Arrangements To Automatically Load An Extension {F12640} ** ** This API can be invoked at program startup in order to register ** one or more statically linked extensions that will be available ** to all new [database connections]. {END} ** ** This routine stores a pointer to the extension in an array that is ** obtained from [sqlite3_malloc()]. If you run a memory leak checker ** on your program and it reports a leak because of this array, invoke ** [sqlite3_reset_auto_extension()] prior to shutdown to free the memory. ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. ** ** INVARIANTS: ** ** {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()]. |
︙ | ︙ | |||
5074 5075 5076 5077 5078 5079 5080 | ** {F12644} Automatic extensions apply across all threads. */ int sqlite3_auto_extension(void *xEntryPoint); /* ** CAPI3REF: Reset Automatic Extension Loading {F12660} ** | | > | | | 5072 5073 5074 5075 5076 5077 5078 5079 5080 5081 5082 5083 5084 5085 5086 5087 5088 5089 5090 5091 5092 5093 5094 5095 5096 5097 5098 | ** {F12644} Automatic extensions apply across all threads. */ int sqlite3_auto_extension(void *xEntryPoint); /* ** CAPI3REF: Reset Automatic Extension Loading {F12660} ** ** This function disables all previously registered automatic ** extensions. {END} It undoes the effect of all prior ** [sqlite3_auto_extension()] calls. ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. ** ** INVARIANTS: ** ** {F12661} This function disables all previously registered ** automatic extensions. ** ** {F12662} This function disables automatic extensions in all threads. */ void sqlite3_reset_auto_extension(void); /* ****** EXPERIMENTAL - subject to change without notice ************** ** ** The interface to the virtual-table mechanism is currently considered |
︙ | ︙ | |||
5379 5380 5381 5382 5383 5384 5385 | ** The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes. */ typedef struct sqlite3_blob sqlite3_blob; /* ** CAPI3REF: Open A BLOB For Incremental I/O {F17810} ** | | | 5378 5379 5380 5381 5382 5383 5384 5385 5386 5387 5388 5389 5390 5391 5392 | ** The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes. */ typedef struct sqlite3_blob sqlite3_blob; /* ** CAPI3REF: Open A BLOB For Incremental I/O {F17810} ** ** This interfaces opens a [BLOB handle | handle] to the BLOB located ** in row iRow, column zColumn, table zTable in database zDb; ** in other words, the same BLOB that would be selected by: ** ** <pre> ** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; ** </pre> {END} ** |
︙ | ︙ | |||
5434 5435 5436 5437 5438 5439 5440 | const char *zColumn, sqlite3_int64 iRow, int flags, sqlite3_blob **ppBlob ); /* | | | | < | 5433 5434 5435 5436 5437 5438 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 5454 5455 5456 5457 5458 5459 5460 5461 5462 5463 5464 5465 5466 5467 5468 | const char *zColumn, sqlite3_int64 iRow, int flags, sqlite3_blob **ppBlob ); /* ** CAPI3REF: Close A BLOB Handle {F17830} ** ** Closes an open [BLOB handle]. ** ** Closing a BLOB shall cause the current transaction to commit ** if there are no other BLOBs, no pending prepared statements, and the ** database connection is in [autocommit mode]. ** If any writes were made to the BLOB, they might be held in cache ** until the close operation if they will fit. {END} ** ** Closing the BLOB often forces the changes ** out to disk and so if any I/O errors occur, they will likely occur ** at the time when the BLOB is closed. {F17833} Any errors that occur during ** closing are reported as a non-zero return value. ** ** The BLOB is closed unconditionally. Even if this routine returns ** an error code, the BLOB is still closed. ** ** INVARIANTS: ** ** {F17833} The [sqlite3_blob_close(P)] interface closes an [sqlite3_blob] ** object P previously opened using [sqlite3_blob_open()]. ** ** {F17836} Closing an [sqlite3_blob] object using ** [sqlite3_blob_close()] shall cause the current transaction to ** commit if there are no other open [sqlite3_blob] objects ** or [prepared statements] on the same [database connection] and ** the database connection is in [autocommit mode]. ** |
︙ | ︙ | |||
5528 5529 5530 5531 5532 5533 5534 | ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return ** information appropriate for that error, where D is the ** [database connection] that was used to open the [BLOB handle] P. */ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); /* | | | 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5537 5538 5539 5540 | ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return ** information appropriate for that error, where D is the ** [database connection] that was used to open the [BLOB handle] P. */ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); /* ** CAPI3REF: Write Data Into A BLOB Incrementally {F17870} ** ** This function is used to write data into an open [BLOB handle] from a ** caller-supplied buffer. N bytes of data are copied from the buffer Z ** into the open BLOB, starting at offset iOffset. ** ** If the [BLOB handle] passed as the first argument was not opened for ** writing (the flags parameter to [sqlite3_blob_open()] was zero), |
︙ | ︙ | |||
5580 5581 5582 5583 5584 5585 5586 | ** then subsequent calls to [sqlite3_errcode(D)], ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return ** information appropriate for that error. */ int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); /* | | | 5578 5579 5580 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 | ** then subsequent calls to [sqlite3_errcode(D)], ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return ** information appropriate for that error. */ int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); /* ** CAPI3REF: Virtual File System Objects {F11200} ** ** A virtual filesystem (VFS) is an [sqlite3_vfs] object ** that SQLite uses to interact ** with the underlying operating system. Most SQLite builds come with a ** single default VFS that is appropriate for the host computer. ** New VFSes can be registered and existing VFSes can be unregistered. ** The following interfaces are provided. |
︙ | ︙ | |||
5687 5688 5689 5690 5691 5692 5693 | ** <li> SQLITE_MUTEX_RECURSIVE ** <li> SQLITE_MUTEX_STATIC_MASTER ** <li> SQLITE_MUTEX_STATIC_MEM ** <li> SQLITE_MUTEX_STATIC_MEM2 ** <li> SQLITE_MUTEX_STATIC_PRNG ** <li> SQLITE_MUTEX_STATIC_LRU ** <li> SQLITE_MUTEX_STATIC_LRU2 | | | 5685 5686 5687 5688 5689 5690 5691 5692 5693 5694 5695 5696 5697 5698 5699 | ** <li> SQLITE_MUTEX_RECURSIVE ** <li> SQLITE_MUTEX_STATIC_MASTER ** <li> SQLITE_MUTEX_STATIC_MEM ** <li> SQLITE_MUTEX_STATIC_MEM2 ** <li> SQLITE_MUTEX_STATIC_PRNG ** <li> SQLITE_MUTEX_STATIC_LRU ** <li> SQLITE_MUTEX_STATIC_LRU2 ** </ul> ** ** {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 |
︙ | ︙ | |||
5711 5712 5713 5714 5715 5716 5717 | ** 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 | | | 5709 5710 5711 5712 5713 5714 5715 5716 5717 5718 5719 5720 5721 5722 5723 | ** 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. ** ** {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} |
︙ | ︙ | |||
5832 5833 5834 5835 5836 5837 5838 | ** 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 | | | < | | < | | 5830 5831 5832 5833 5834 5835 5836 5837 5838 5839 5840 5841 5842 5843 5844 5845 5846 5847 5848 5849 5850 5851 5852 5853 5854 5855 5856 5857 5858 5859 5860 5861 5862 5863 5864 5865 5866 5867 | ** 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. ** ** {X17084} The implementation is not required to provided versions of these ** routines that actually work. If the implementation does not provide working ** versions of these routines, it should at least provide stubs that always ** return true so that one does not get spurious assertion failures. ** ** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then ** the routine should return 1. {END} This seems counter-intuitive since ** clearly the mutex cannot be held if it does not exist. But the ** the reason the mutex does not exist is because the build is not ** using mutexes. And we do not want the assert() containing the ** call to sqlite3_mutex_held() to fail, so a non-zero return is ** the appropriate thing to do. {F17086} The sqlite3_mutex_notheld() ** interface should also return 1 when given a NULL pointer. */ int sqlite3_mutex_held(sqlite3_mutex*); int sqlite3_mutex_notheld(sqlite3_mutex*); /* ** CAPI3REF: Mutex Types {F17001} ** ** {F17002} The [sqlite3_mutex_alloc()] interface takes a single argument ** which is one of these integer constants. */ #define SQLITE_MUTEX_FAST 0 #define SQLITE_MUTEX_RECURSIVE 1 #define SQLITE_MUTEX_STATIC_MASTER 2 #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ #define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */ #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ |
︙ | ︙ |