Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | More documentation spellcheck and cleanup. No changes to code. (CVS 5262) |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
47b7b05e55d35450a14250a00468dfbc |
User & Date: | mihailim 2008-06-21 13:35:57.000 |
Context
2008-06-21
| ||
16:47 | More documentation spellcheck and cleanup. No changes to code. (CVS 5263) (check-in: 3edfc64f27 user: mihailim tags: trunk) | |
13:35 | More documentation spellcheck and cleanup. No changes to code. (CVS 5262) (check-in: 47b7b05e55 user: mihailim tags: trunk) | |
12:15 | Remove mutex2.test. It will be replaced later today by permutations.test. (CVS 5261) (check-in: 98a6a0a30f user: danielk1977 tags: trunk) | |
Changes
Changes to src/sqlite.h.in.
︙ | ︙ | |||
13 14 15 16 17 18 19 | ** presents to client programs. If a C-function, structure, datatype, ** or constant definition does not appear in this file, then it is ** not a published API of SQLite, is subject to change without ** notice, and should not be referenced by programs that use SQLite. ** ** Some of the definitions that are in this file are marked as ** "experimental". Experimental interfaces are normally new | | | | 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | ** presents to client programs. If a C-function, structure, datatype, ** or constant definition does not appear in this file, then it is ** not a published API of SQLite, is subject to change without ** notice, and should not be referenced by programs that use SQLite. ** ** Some of the definitions that are in this file are marked as ** "experimental". Experimental interfaces are normally new ** features recently added to SQLite. We do not anticipate changes ** to experimental interfaces but reserve to make minor changes if ** experience from use "in the wild" suggest such changes are prudent. ** ** The official C-language API documentation for SQLite is derived ** from comments in this file. This file is the authoritative source ** 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.345 2008/06/21 13:35:57 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++. |
︙ | ︙ | |||
290 291 292 293 294 295 296 | ** ** The sqlite3_exec() interface is implemented in terms of ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. ** The sqlite3_exec() routine does nothing to the database that cannot be done ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. ** ** INVARIANTS: | | | | | 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 | ** ** The sqlite3_exec() interface is implemented in terms of ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. ** The sqlite3_exec() routine does nothing to the database that cannot be done ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. ** ** INVARIANTS: ** ** {F12101} A successful invocation of [sqlite3_exec(D,S,C,A,E)] ** shall evaluate all of the UTF-8 encoded, semicolon-separated ** SQL statements in the zero-terminated string S within the ** context of the [database connection] D. ** ** {F12102} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL then ** the actions of the interface shall be the same as if the ** S parameter were an empty string. ** ** {F12104} The return value of [sqlite3_exec()] shall be [SQLITE_OK] if all ** SQL statements run successfully and to completion. ** ** {F12105} The return value of [sqlite3_exec()] shall be an appropriate ** non-zero [error code] if any SQL statement fails. ** ** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()] ** return results and the 3rd parameter is not NULL, then ** the callback function specified by the 3rd parameter shall be ** invoked once for each row of result. ** ** {F12110} If the callback returns a non-zero value then [sqlite3_exec()] ** shall abort the SQL statement it is currently evaluating, ** skip all subsequent SQL statements, and return [SQLITE_ABORT]. ** ** {F12113} The [sqlite3_exec()] routine shall pass its 4th parameter through ** as the 1st parameter of the callback. ** ** {F12116} The [sqlite3_exec()] routine sets the 2nd parameter of its ** callback to be the number of columns in the current row of ** result. ** ** {F12119} The [sqlite3_exec()] routine sets the 3rd parameter of its ** callback to be an array of pointers to strings holding the ** values for each column in the current result set row as ** obtained from [sqlite3_column_text()]. ** ** {F12122} The [sqlite3_exec()] routine sets the 4th parameter of its ** callback to be an array of pointers to strings holding the ** names of result columns as obtained from [sqlite3_column_name()]. |
︙ | ︙ | |||
361 362 363 364 365 366 367 | ** LIMITATIONS: ** ** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open ** [database connection]. ** ** {U12142} The database connection must not be closed while ** [sqlite3_exec()] is running. | | | 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 | ** LIMITATIONS: ** ** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open ** [database connection]. ** ** {U12142} The database connection must not be closed while ** [sqlite3_exec()] is running. ** ** {U12143} The calling function should use [sqlite3_free()] to free ** the memory that *errmsg is left pointing at once the error ** message is no longer needed. ** ** {U12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()] ** must remain unchanged while [sqlite3_exec()] is running. */ |
︙ | ︙ | |||
432 433 434 435 436 437 438 | ** these result codes are too coarse-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. The extended result codes are enabled or disabled ** on a per database connection basis using the ** [sqlite3_extended_result_codes()] API. | | | | 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 | ** these result codes are too coarse-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. The extended result codes are enabled or disabled ** on a per database connection basis using the ** [sqlite3_extended_result_codes()] API. ** ** Some of the available extended result codes are listed here. ** One may expect the number of extended result codes will be expand ** over time. Software that uses extended result codes should expect ** to see new result codes in future releases of SQLite. ** ** The SQLITE_OK result code will never be extended. It will always ** be exactly zero. ** ** INVARIANTS: ** ** {F10223} The symbolic name for an extended result code always contains ** a related primary result code as a prefix. ** ** {F10224} Primary result code names contain a single "_" character. ** |
︙ | ︙ | |||
544 545 546 547 548 549 550 | ** ** When SQLite invokes the xSync() method of an ** [sqlite3_io_methods] object it uses a combination of ** these integer values as the second argument. ** ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the ** sync operation only needs to flush data to mass storage. Inode | | | | 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 | ** ** When SQLite invokes the xSync() method of an ** [sqlite3_io_methods] object it uses a combination of ** these integer values as the second argument. ** ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the ** sync operation only needs to flush data to mass storage. Inode ** information need not be flushed. The SQLITE_SYNC_NORMAL flag means ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means ** to use Mac OS-X style fullsync instead of fsync(). */ #define SQLITE_SYNC_NORMAL 0x00002 #define SQLITE_SYNC_FULL 0x00003 #define SQLITE_SYNC_DATAONLY 0x00010 /* |
︙ | ︙ | |||
579 580 581 582 583 584 585 | ** methods used to perform various operations against the open file. ** ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). ** The second choice is a Mac OS-X style fullsync. The [SQLITE_SYNC_DATAONLY] ** flag may be ORed in to indicate that only the data of the file ** and not its inode needs to be synced. | | | | | | | 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 | ** methods used to perform various operations against the open file. ** ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). ** The second choice is a Mac OS-X style fullsync. The [SQLITE_SYNC_DATAONLY] ** flag may be ORed in to indicate that only the data of the file ** and not its inode needs to be synced. ** ** The integer values to xLock() and xUnlock() are one of ** <ul> ** <li> [SQLITE_LOCK_NONE], ** <li> [SQLITE_LOCK_SHARED], ** <li> [SQLITE_LOCK_RESERVED], ** <li> [SQLITE_LOCK_PENDING], or ** <li> [SQLITE_LOCK_EXCLUSIVE]. ** </ul> ** xLock() increases the lock. xUnlock() decreases the lock. ** The xCheckReservedLock() method checks whether any database connection, ** either in this process or in some other process, is holding a RESERVED, ** PENDING, or EXCLUSIVE lock on the file. It returns true ** if such a lock exists and false otherwise. ** ** The xFileControl() method is a generic interface that allows custom ** VFS implementations to directly control an open file using the ** [sqlite3_file_control()] interface. The second "op" argument is an ** integer opcode. The third argument is a generic pointer intended to ** point to a structure that may contain arguments or space in which to ** write return values. Potential uses for xFileControl() might be ** functions to enable blocking locks with timeouts, to change the ** locking strategy (for example to use dot-file locks), to inquire ** about the status of a lock, or to break stale locks. The SQLite ** core reserves all opcodes less than 100 for its own use. ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. ** Applications that define a custom xFileControl method should use opcodes ** greater than 100 to avoid conflicts. ** ** The xSectorSize() method returns the sector size of the ** device that underlies the file. The sector size is the ** minimum write that can be performed without disturbing |
︙ | ︙ | |||
708 709 710 711 712 713 714 | ** ** Registered sqlite3_vfs objects are kept on a linked list formed by ** the pNext pointer. The [sqlite3_vfs_register()] ** and [sqlite3_vfs_unregister()] interfaces manage this list ** in a thread-safe way. The [sqlite3_vfs_find()] interface ** searches the list. ** | | | 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 | ** ** Registered sqlite3_vfs objects are kept on a linked list formed by ** the pNext pointer. The [sqlite3_vfs_register()] ** and [sqlite3_vfs_unregister()] interfaces manage this list ** in a thread-safe way. The [sqlite3_vfs_find()] interface ** searches the list. ** ** The pNext field is the only field in the sqlite3_vfs ** structure that SQLite will ever modify. SQLite will only access ** or modify this field while holding a particular static mutex. ** The application should never modify anything within the sqlite3_vfs ** object once the object has been registered. ** ** The zName field holds the name of the VFS module. The name must ** be unique across all VFS modules. |
︙ | ︙ | |||
886 887 888 889 890 891 892 | ** ** The sqlite3_os_init() routine does operating-system specific ** initialization of the SQLite library. The sqlite3_os_end() ** routine undoes the effect of sqlite3_os_init(). Typical tasks ** performed by these routines include allocation or deallocation ** of static resources, initialization of global variables, ** setting up a default [sqlite3_vfs] module, or setting up | | | | 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 | ** ** The sqlite3_os_init() routine does operating-system specific ** initialization of the SQLite library. The sqlite3_os_end() ** routine undoes the effect of sqlite3_os_init(). Typical tasks ** performed by these routines include allocation or deallocation ** of static resources, initialization of global variables, ** setting up a default [sqlite3_vfs] module, or setting up ** a default configuration using [sqlite3_config()]. ** ** The application should never invoke either sqlite3_os_init() ** or sqlite3_os_end() directly. The application should only invoke ** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init() ** interface is called automatically by sqlite3_initialize() and ** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate ** implementations for sqlite3_os_init() and sqlite3_os_end() ** are built into SQLite when it is compiled for unix, windows, or os/2. ** When built for other platforms (using the SQLITE_OS_OTHER=1 compile-time ** option) the application must supply a suitable implementation for ** sqlite3_os_init() and sqlite3_os_end(). An application-supplied ** implementation of sqlite3_os_init() or sqlite3_os_end() |
︙ | ︙ | |||
931 932 933 934 935 936 937 | ** The first argument to sqlite3_config() is an integer ** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines ** what property of SQLite is to be configured. Subsequent arguments ** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option] ** in the first argument. ** ** When a configuration option is set, sqlite3_config() returns SQLITE_OK. | | | | 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 | ** The first argument to sqlite3_config() is an integer ** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines ** what property of SQLite is to be configured. Subsequent arguments ** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option] ** in the first argument. ** ** When a configuration option is set, sqlite3_config() returns SQLITE_OK. ** If the option is unknown or SQLite is unable to set the option ** then this routine returns a non-zero [error code]. */ int sqlite3_config(int, ...); /* ** CAPI3REF: Memory Allocation Routines {F10155} ** ** An instance of this object defines the interface between SQLite ** and low-level memory allocation routines. ** ** This object is used in only one place in the SQLite interface. ** A pointer to an instance of this object is the argument to ** [sqlite3_config] when the configuration option is ** [SQLITE_CONFIG_MALLOC]. By creating an instance of this object ** and passing it to [sqlite3_config] during configuration, an ** application can specify an alternative memory allocation subsystem |
︙ | ︙ | |||
969 970 971 972 973 974 975 | ** xSize should return the allocated size of a memory allocation ** previously obtained from xMalloc or xRealloc. The allocated size ** is always at least as big as the requested size but may be larger. ** ** The xRoundup method returns what would be the allocated size of ** a memory allocation given a particular requested size. Most memory ** allocators round up memory allocations at least to the next multiple | | | 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 | ** xSize should return the allocated size of a memory allocation ** previously obtained from xMalloc or xRealloc. The allocated size ** is always at least as big as the requested size but may be larger. ** ** The xRoundup method returns what would be the allocated size of ** a memory allocation given a particular requested size. Most memory ** allocators round up memory allocations at least to the next multiple ** of 8. Some allocators round up to a larger multiple or to a power of 2. ** ** The xInit method initializes the memory allocator. (For example, ** it might allocate any require mutexes or initialize internal data ** structures. The xShutdown method is invoked (indirectly) by ** [sqlite3_shutdown()] and should deallocate any resources acquired ** by xInit. The pAppData pointer is used as the only parameter to ** xInit and xShutdown. |
︙ | ︙ | |||
995 996 997 998 999 1000 1001 | }; /* ** CAPI3REF: Configuration Options {F10160} ** ** These constants are the available integer configuration options that ** can be passed as the first argument to the [sqlite3_config()] interface. | | | 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 | }; /* ** CAPI3REF: Configuration Options {F10160} ** ** These constants are the available integer configuration options that ** can be passed as the first argument to the [sqlite3_config()] interface. ** ** <dl> ** <dt>SQLITE_CONFIG_SINGLETHREAD</dt> ** <dd>There are no arguments to this option. This option disables ** all mutexing and puts SQLite into a mode where it can only be used ** by a single thread.</dd> ** ** <dt>SQLITE_CONFIG_MULTITHREAD</dt> |
︙ | ︙ | |||
1097 1098 1099 1100 1101 1102 1103 | ** [sqlite3_mutex_methods] ** structure is filled with the currently defined mutex routines. ** This option can be used to overload the default mutex allocation ** routines with a wrapper used to track mutex usage for performance ** profiling or testing, for example.</dd> ** ** </dl> | | | 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 | ** [sqlite3_mutex_methods] ** structure is filled with the currently defined mutex routines. ** This option can be used to overload the default mutex allocation ** routines with a wrapper used to track mutex usage for performance ** profiling or testing, for example.</dd> ** ** </dl> */ #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ #define SQLITE_CONFIG_SERIALIZED 3 /* nil */ #define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ #define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ #define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ |
︙ | ︙ | |||
1291 1292 1293 1294 1295 1296 1297 | ** {F12263} Statements of the form "DELETE FROM tablename" with no ** WHERE clause shall not change the value returned ** by [sqlite3_total_changes()]. ** ** LIMITATIONS: ** ** {U12264} If a separate thread makes changes on the same database connection | | | 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 | ** {F12263} Statements of the form "DELETE FROM tablename" with no ** WHERE clause shall not change the value returned ** by [sqlite3_total_changes()]. ** ** LIMITATIONS: ** ** {U12264} If a separate thread makes changes on the same database connection ** while [sqlite3_total_changes()] is running then the value ** returned is unpredictable and not meaningful. */ int sqlite3_total_changes(sqlite3*); /* ** CAPI3REF: Interrupt A Long-Running Query {F12270} ** |
︙ | ︙ | |||
1824 1825 1826 1827 1828 1829 1830 | ** LIMITATIONS: ** ** {U17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] ** must be either NULL or else pointers obtained from a prior ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have ** not yet been released. ** | | | | < | | 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 | ** LIMITATIONS: ** ** {U17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] ** must be either NULL or else pointers obtained from a prior ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have ** not yet been released. ** ** {U17351} The application must not read or write any part of ** a block of memory after it has been released using ** [sqlite3_free()] or [sqlite3_realloc()]. */ void *sqlite3_malloc(int); void *sqlite3_realloc(void*, int); void sqlite3_free(void*); /* ** CAPI3REF: Memory Allocator Statistics {F17370} ** ** SQLite provides these two interfaces for reporting on the status ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] ** routines, which form the built-in memory allocation subsystem. ** ** INVARIANTS: ** ** {F17371} The [sqlite3_memory_used()] routine returns the number of bytes ** of memory currently outstanding (malloced but not freed). ** ** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum ** value of [sqlite3_memory_used()] since the high-water mark ** was last reset. ** ** {F17374} The values returned by [sqlite3_memory_used()] and ** [sqlite3_memory_highwater()] include any overhead ** added by SQLite in its implementation of [sqlite3_malloc()], ** but not overhead added by the any underlying system library ** routines that [sqlite3_malloc()] may call. ** ** {F17375} The memory high-water mark is reset to the current value of ** [sqlite3_memory_used()] if and only if the parameter to ** [sqlite3_memory_highwater()] is true. The value returned ** by [sqlite3_memory_highwater(1)] is the high-water mark ** prior to the reset. */ sqlite3_int64 sqlite3_memory_used(void); |
︙ | ︙ | |||
1903 1904 1905 1906 1907 1908 1909 | ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various ** points during the compilation process, as logic is being created ** to perform various actions, the authorizer callback is invoked to ** see if those actions are allowed. The authorizer callback should ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the ** specific action but allow the SQL statement to continue to be ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be | | | | | < | | | | | 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 | ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various ** points during the compilation process, as logic is being created ** to perform various actions, the authorizer callback is invoked to ** see if those actions are allowed. The authorizer callback should ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the ** specific action but allow the SQL statement to continue to be ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be ** rejected with an error. If the authorizer callback returns ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] ** then the [sqlite3_prepare_v2()] or equivalent call that triggered ** the authorizer will fail with an error message. ** ** When the callback returns [SQLITE_OK], that means the operation ** requested is ok. When the callback returns [SQLITE_DENY], the ** [sqlite3_prepare_v2()] or equivalent call that triggered the ** authorizer will fail with an error message explaining that ** access is denied. If the authorizer code is [SQLITE_READ] ** and the callback returns [SQLITE_IGNORE] then the ** [prepared statement] statement is constructed to substitute ** a NULL value in place of the table column that would have ** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE] ** return can be used to deny an untrusted user access to individual ** columns of a table. ** ** The first parameter to the authorizer callback is a copy of the third ** parameter to the sqlite3_set_authorizer() interface. The second parameter ** to the callback is an integer [SQLITE_COPY | action code] that specifies ** the particular action to be authorized. The third through sixth parameters ** to the callback are zero-terminated strings that contain additional ** details about the action to be authorized. ** ** An authorizer is used when [sqlite3_prepare | preparing] ** SQL statements from an untrusted ** source, to ensure that the SQL statements do not try to access data ** that they are not allowed to see, or that they do not try to ** execute malicious statements that damage the database. For ** example, an application may allow a user to enter arbitrary |
︙ | ︙ | |||
1950 1951 1952 1953 1954 1955 1956 | ** in addition to using an authorizer. ** ** Only a single authorizer can be in place on a database connection ** at a time. Each call to sqlite3_set_authorizer overrides the ** previous call. Disable the authorizer by installing a NULL callback. ** The authorizer is disabled by default. ** | | | | | | | | | | | 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 | ** in addition to using an authorizer. ** ** Only a single authorizer can be in place on a database connection ** at a time. Each call to sqlite3_set_authorizer overrides the ** previous call. Disable the authorizer by installing a NULL callback. ** The authorizer is disabled by default. ** ** Note that the authorizer callback is invoked only during ** [sqlite3_prepare()] or its variants. Authorization is not ** performed during statement evaluation in [sqlite3_step()]. ** ** INVARIANTS: ** ** {F12501} The [sqlite3_set_authorizer(D,...)] interface registers a ** authorizer callback with database connection D. ** ** {F12502} The authorizer callback is invoked as SQL statements are ** being compiled. ** ** {F12503} If the authorizer callback returns any value other than ** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY], then ** the [sqlite3_prepare_v2()] or equivalent call that caused ** the authorizer callback to run shall fail with an ** [SQLITE_ERROR] error code and an appropriate error message. ** ** {F12504} When the authorizer callback returns [SQLITE_OK], the operation ** described is processed normally. ** ** {F12505} When the authorizer callback returns [SQLITE_DENY], the ** [sqlite3_prepare_v2()] or equivalent call that caused the ** authorizer callback to run shall fail ** with an [SQLITE_ERROR] error code and an error message ** explaining that access is denied. ** ** {F12506} If the authorizer code (the 2nd parameter to the authorizer ** callback) is [SQLITE_READ] and the authorizer callback returns ** [SQLITE_IGNORE], then the prepared statement is constructed to ** insert a NULL value in place of the table column that would have ** been read if [SQLITE_OK] had been returned. ** ** {F12507} 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]. ** ** {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. ** ** {F12512} The third through sixth parameters to the callback are ** zero-terminated strings that contain ** additional details about the action to be authorized. ** ** {F12520} Each call to [sqlite3_set_authorizer()] overrides ** any previously installed authorizer. ** ** {F12521} A NULL authorizer means that no authorization ** callback is invoked. ** ** {F12522} The default authorizer is NULL. */ |
︙ | ︙ | |||
2028 2029 2030 2031 2032 2033 2034 | #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 | | | | | | | | | | | 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 | #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 authorize certain SQL statement actions. The ** second parameter to the callback is an integer code that specifies ** what action is being authorized. These are the integer action codes that ** the authorizer callback may be passed. ** ** These action code values signify what kind of operation is to be ** authorized. The 3rd and 4th parameters to the authorization ** callback function will be parameters or NULL depending on which of these ** codes is used as the second parameter. The 5th parameter to the ** authorizer callback is the name of the database ("main", "temp", ** etc.) if applicable. The 6th parameter to the authorizer callback ** is the name of the inner-most trigger or view that is responsible for ** the access attempt or NULL if this access attempt is directly from ** top-level SQL code. ** ** INVARIANTS: ** ** {F12551} The second parameter to an ** [sqlite3_set_authorizer | authorizer callback] is always an integer ** [SQLITE_COPY | authorizer code] that specifies what action ** is being authorized. ** ** {F12552} The 3rd and 4th parameters to the ** [sqlite3_set_authorizer | authorization callback] ** will be parameters or NULL depending on which ** [SQLITE_COPY | authorizer code] is used as the second parameter. ** ** {F12553} The 5th parameter to the ** [sqlite3_set_authorizer | authorizer callback] is the name ** of the database (example: "main", "temp", etc.) if applicable. ** ** {F12554} The 6th parameter to the ** [sqlite3_set_authorizer | authorizer callback] is the name ** of the inner-most trigger or view that is responsible for ** the access attempt or NULL if this access attempt is directly from ** top-level SQL code. */ /******************************************* 3rd ************ 4th ***********/ #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ |
︙ | ︙ | |||
2111 2112 2113 2114 2115 2116 2117 | ** ** The callback function registered by sqlite3_trace() is invoked at ** various times when an SQL statement is being run by [sqlite3_step()]. ** The callback returns a UTF-8 rendering of the SQL statement text ** as the statement first begins executing. Additional callbacks occur ** as each triggered subprogram is entered. The callbacks for triggers ** contain a UTF-8 SQL comment that identifies the trigger. | | | | 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 | ** ** The callback function registered by sqlite3_trace() is invoked at ** various times when an SQL statement is being run by [sqlite3_step()]. ** The callback returns a UTF-8 rendering of the SQL statement text ** as the statement first begins executing. Additional callbacks occur ** as each triggered subprogram is entered. The callbacks for triggers ** contain a UTF-8 SQL comment that identifies the trigger. ** ** The callback function registered by sqlite3_profile() is invoked ** as each SQL statement finishes. The profile callback contains ** the original statement text and an estimate of wall-clock time ** of how long that statement took to run. ** ** The sqlite3_profile() API is currently considered experimental and ** is subject to change or removal in a future release. ** ** The trigger reporting feature of the trace callback is considered ** experimental and is subject to change or removal in future releases. ** Future versions of SQLite might also add new trace callback ** invocations. ** ** INVARIANTS: ** ** {F12281} The callback function registered by [sqlite3_trace()] is ** whenever an SQL statement first begins to execute and ** whenever a trigger subprogram first begins to run. |
︙ | ︙ | |||
2156 2157 2158 2159 2160 2161 2162 | ** 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. ** | | | | | | > | | | | < | < | | | | | | | < | | | | | | | < | | < < > | < < | | | | > > | < | | > | | | | | < | | | | | | | < | | | | 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 | ** 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. */ void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); void *sqlite3_profile(sqlite3*, void(*xProfile)(void*,const char*,sqlite3_uint64), void*); /* ** CAPI3REF: Query Progress Callbacks {F12910} ** ** This routine configures a callback function - the ** progress callback - that is invoked periodically during long ** running calls to [sqlite3_exec()], [sqlite3_step()] and ** [sqlite3_get_table()]. An example use for this ** interface is to keep a GUI updated during a large query. ** ** If the progress callback returns non-zero, the operation is ** interrupted. This feature can be used to implement a ** "Cancel" button on a GUI dialog box. ** ** INVARIANTS: ** ** {F12911} The callback function registered by sqlite3_progress_handler() ** is invoked periodically during long running calls to ** [sqlite3_step()]. ** ** {F12912} The progress callback is invoked once for every N virtual ** machine opcodes, where N is the second argument to ** the [sqlite3_progress_handler()] call that registered ** the callback. If N is less than 1, sqlite3_progress_handler() ** acts as if a NULL progress handler had been specified. ** ** {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. {END} ** ** {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. ** ** {F12918} If the progress callback returns a result other than 0, then ** the behavior is a if [sqlite3_interrupt()] had been called. */ void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); /* ** CAPI3REF: Opening A New Database Connection {F12700} ** ** These routines open an SQLite database file whose name is given by the ** filename argument. The filename argument is interpreted as UTF-8 for ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte ** order for sqlite3_open16(). A [database connection] handle is usually ** returned in *ppDb, even if an error occurs. The only exception is that ** if SQLite is unable to allocate memory to hold the [sqlite3] object, ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3] ** object. If the database is opened (and/or created) successfully, then ** [SQLITE_OK] is returned. Otherwise an error code is returned. The ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain ** an English language description of the error. ** ** The default encoding for the database will be UTF-8 if ** sqlite3_open() or sqlite3_open_v2() is called and ** UTF-16 in the native byte order if sqlite3_open16() is used. ** ** Whether or not an error occurs when it is opened, resources ** associated with the [database connection] handle should be released by ** passing it to [sqlite3_close()] when it is no longer required. ** ** The sqlite3_open_v2() interface works like sqlite3_open() ** except that it accepts two additional parameters for additional control ** over the new database connection. The flags parameter can be one of: ** ** <dl> ** <dt>[SQLITE_OPEN_READONLY]</dt> ** <dd>The database is opened in read-only mode. If the database does not ** already exist, an error is returned.</dd> ** ** <dt>[SQLITE_OPEN_READWRITE]</dt> ** <dd>The database is opened for reading and writing if possible, or reading ** only if the file is write protected by the operating system. In either ** case the database must already exist, otherwise an error is returned.</dd> ** ** <dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt> ** <dd>The database is opened for reading and writing, and is creates it if ** it does not already exist. This is the behavior that is always used for ** sqlite3_open() and sqlite3_open16().</dd> ** </dl> ** ** If the 3rd parameter to sqlite3_open_v2() is not one of the ** combinations shown above then the behavior is undefined. ** ** If the filename is ":memory:", then a private, temporary in-memory database ** is created for the connection. This in-memory database will vanish when ** the database connection is closed. Future versions of SQLite might ** make use of additional special filenames that begin with the ":" character. ** It is recommended that when a database filename actually does begin with ** a ":" character you should prefix the filename with a pathname such as ** "./" to avoid ambiguity. ** ** If the filename is an empty string, then a private, temporary ** on-disk database will be created. This private database will be ** automatically deleted as soon as the database connection is closed. ** ** The fourth parameter to sqlite3_open_v2() is the name of the ** [sqlite3_vfs] object that defines the operating system interface that ** the new database connection should use. If the fourth parameter is ** a NULL pointer then the default [sqlite3_vfs] object is used. ** ** <b>Note to Windows users:</b> The encoding used for the filename argument ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever ** codepage is currently defined. Filenames containing international ** characters must be converted to UTF-8 prior to passing them into ** sqlite3_open() or sqlite3_open_v2(). ** ** INVARIANTS: ** ** {F12701} The [sqlite3_open()], [sqlite3_open16()], and ** [sqlite3_open_v2()] interfaces create a new ** [database connection] associated with ** the database file given in their first parameter. ** ** {F12702} The filename argument is interpreted as UTF-8 ** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16 ** in the native byte order for [sqlite3_open16()]. ** ** {F12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()], ** or [sqlite3_open_v2()] writes a pointer to a new ** [database connection] into *ppDb. ** ** {F12704} The [sqlite3_open()], [sqlite3_open16()], and ** [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success, ** or an appropriate [error code] on failure. ** |
︙ | ︙ | |||
2344 2345 2346 2347 2348 2349 2350 | ** in sqlite3_open_v2()?</todo> ** ** {F12719} If the filename is NULL or an empty string, then a private, ** ephemeral on-disk database will be created. ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required ** in sqlite3_open_v2()?</todo> ** | | < | | | | | | | < < | 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 | ** in sqlite3_open_v2()?</todo> ** ** {F12719} If the filename is NULL or an empty string, then a private, ** ephemeral on-disk database will be created. ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required ** in sqlite3_open_v2()?</todo> ** ** {F12721} The [database connection] created by [sqlite3_open_v2(F,D,G,V)] ** will use the [sqlite3_vfs] object identified by the V parameter, ** or the default [sqlite3_vfs] object if V is a NULL pointer. ** ** {F12723} Two [database connection | database connections] will share ** a common cache if both were opened with the same VFS while ** [sqlite3_enable_shared_cache | shared cache mode was enabled] and ** if both filenames compare equal using memcmp() after having been ** processed by the [sqlite3_vfs | xFullPathname] method of the VFS. */ int sqlite3_open( const char *filename, /* Database filename (UTF-8) */ sqlite3 **ppDb /* OUT: SQLite db handle */ ); int sqlite3_open16( const void *filename, /* Database filename (UTF-16) */ |
︙ | ︙ |