From adfae6c68b3752c52d188eeed55acb7e77e19c53 Mon Sep 17 00:00:00 2001 From: drh Date: Fri, 10 Oct 2008 17:26:35 +0000 Subject: [PATCH] Documentation updates. No changes to code. (CVS 5793) FossilOrigin-Name: 07b5f70317a0b2d32df86a01bdeec79ead00f68c --- manifest | 12 ++--- manifest.uuid | 2 +- src/sqlite.h.in | 118 ++++++++++++++++++++++++++++++++++++++++-------- 3 files changed, 107 insertions(+), 25 deletions(-) diff --git a/manifest b/manifest index 4983510faa..b4ac387033 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Simplify\sthe\sparser\sreduction\scode\sfor\sthe\sLIMIT\sclause\son\san\sUPDATE\sor\nDELETE.\s(CVS\s5792) -D 2008-10-10T14:27:17 +C Documentation\supdates.\s\sNo\schanges\sto\scode.\s(CVS\s5793) +D 2008-10-10T17:26:35 F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0 F Makefile.in 7fc26e087207e7a4a7723583dbd7997477af3b13 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654 @@ -150,7 +150,7 @@ F src/random.c a87afbd598aa877e23ac676ee92fd8ee5c786a51 F src/resolve.c d45e7b69f9ff653799384d7fcdd0c8d7096908b7 F src/select.c d910d7350df0d918e22286c5bfd39d4ea68ec813 F src/shell.c d83b578a8ccdd3e0e7fef4388a0887ce9f810967 -F src/sqlite.h.in f2640167eca2e9273ec5ea97b37155344290bd2a +F src/sqlite.h.in 28e6466da6b90e56bfbc6c50a1a281931a8c733c F src/sqlite3ext.h 1e3887c9bd3ae66cb599e922824b04cd0d0f2c3e F src/sqliteInt.h 0da9c664d89995d28587548048837e3063fa0be3 F src/sqliteLimit.h f435e728c6b620ef7312814d660a81f9356eb5c8 @@ -645,7 +645,7 @@ F tool/speedtest16.c c8a9c793df96db7e4933f0852abb7a03d48f2e81 F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e -P 43507bbefbf79e8db8fe31319ad621d48247983f -R 0f3d53a6d1c1c43e26912a5b940877e0 +P 3de179630e812396ec29e77f7a06758472d0802f +R 469bda2a774246df2b2a212f34becf13 U drh -Z 451d4561ebde2fb2ef1d789ddc49a01c +Z 4f5f403cd825b04b1721f4c2665a843f diff --git a/manifest.uuid b/manifest.uuid index d79fd5e4cd..935d9c90a2 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -3de179630e812396ec29e77f7a06758472d0802f \ No newline at end of file +07b5f70317a0b2d32df86a01bdeec79ead00f68c \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index 114c2e3d18..af1fda6d59 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -30,7 +30,7 @@ ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** -** @(#) $Id: sqlite.h.in,v 1.401 2008/10/07 23:46:38 drh Exp $ +** @(#) $Id: sqlite.h.in,v 1.402 2008/10/10 17:26:35 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ @@ -173,16 +173,11 @@ int sqlite3_libversion_number(void); ** ** INVARIANTS: ** -** {H10101} The [sqlite3_threadsafe()] function shall return nonzero if -** and only if -** SQLite was compiled with the its mutexes enabled by default. +** {H10101} The [sqlite3_threadsafe()] function shall return zero if +** and only if SQLite was compiled with mutexing code omitted. ** ** {H10102} The value returned by the [sqlite3_threadsafe()] function -** shall not change when mutex setting are modified at -** runtime using the [sqlite3_config()] interface and -** especially the [SQLITE_CONFIG_SINGLETHREAD], -** [SQLITE_CONFIG_MULTITHREAD], [SQLITE_CONFIG_SERIALIZED], -** and [SQLITE_CONFIG_MUTEX] verbs. +** shall remain the same across calls to [sqlite3_config()]. */ int sqlite3_threadsafe(void); @@ -279,7 +274,7 @@ typedef sqlite_uint64 sqlite3_uint64; ** an [SQLITE_BUSY] error code. ** ** {H12015} A call to [sqlite3_close(C)] where C is a NULL pointer shall -** return SQLITE_OK. +** be a harmless no-op returning SQLITE_OK. ** ** {H12019} When [sqlite3_close(C)] is invoked on a [database connection] C ** that has a pending transaction, the transaction shall be @@ -911,24 +906,24 @@ struct sqlite3_vfs { ** sqlite3_os_init(). Similarly, sqlite3_shutdown() ** shall invoke sqlite3_os_end(). ** -** The sqlite3_initialize() routine returns SQLITE_OK on success. +** The sqlite3_initialize() routine returns [SQLITE_OK] on success. ** If for some reason, sqlite3_initialize() is unable to initialize ** the library (perhaps it is unable to allocate a needed resource such -** as a mutex) it returns an [error code] other than SQLITE_OK. +** as a mutex) it returns an [error code] other than [SQLITE_OK]. ** ** The sqlite3_initialize() routine is called internally by many other ** SQLite interfaces so that an application usually does not need to ** invoke sqlite3_initialize() directly. For example, [sqlite3_open()] ** calls sqlite3_initialize() so the SQLite library will be automatically ** initialized when [sqlite3_open()] is called if it has not be initialized -** already. However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT +** already. However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT] ** compile-time option, then the automatic calls to sqlite3_initialize() ** are omitted and the application must call sqlite3_initialize() directly ** prior to using any other SQLite interface. For maximum portability, ** it is recommended that applications always invoke sqlite3_initialize() ** directly prior to using any other SQLite interface. Future releases ** of SQLite may require this. In other words, the behavior exhibited -** when SQLite is compiled with SQLITE_OMIT_AUTOINIT might become the +** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the ** default behavior in some future release of SQLite. ** ** The sqlite3_os_init() routine does operating-system specific @@ -946,11 +941,11 @@ struct sqlite3_vfs { ** 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 +** 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() -** must return SQLITE_OK on success and some other [error code] upon +** must return [SQLITE_OK] on success and some other [error code] upon ** failure. */ int sqlite3_initialize(void); @@ -959,7 +954,7 @@ int sqlite3_os_init(void); int sqlite3_os_end(void); /* -** CAPI3REF: Configuring The SQLite Library {H10145} +** CAPI3REF: Configuring The SQLite Library {H14100} ** EXPERIMENTAL ** ** The sqlite3_config() interface is used to make global configuration @@ -982,9 +977,96 @@ int sqlite3_os_end(void); ** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option] ** in the first argument. ** -** When a configuration option is set, sqlite3_config() returns SQLITE_OK. +** 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]. +** +** INVARIANTS: +** +** {H14103} A successful invocation of sqlite3_config() shall return +** SQLITE_OK. +** +** {H14106} The sqlite3_config() interface shall return SQLITE_MISUSE +** if it is invoked in between calls to sqlite3_initialize() and +** sqlite3_shutdown(). +** +** {H14120} A successful call to sqlite3_config(SQLITE_CONFIG_SINGLETHREAD) +** shall set the default [threading mode] to Single-thread. +** +** {H14123} A successful call to sqlite3_config(SQLITE_CONFIG_MULTITHREAD) +** shall set the default [threading mode] to Multi-thread. +** +** {H14126} A successful call to sqlite3_config(SQLITE_CONFIG_SERIALIZED) +** shall set the default [threading mode] to Serialized. +** +** {H14129} A successful call to sqlite3_config(SQLITE_CONFIG_MUTEX,X) +** where X is a pointer to an initialized [sqlite3_mutex_methods] +** object shall cause all subsequent mutex operations performed +** by SQLite to use the mutex methods that were present in X +** during the call to sqlite3_config(). +** +** {H14132} A successful call to sqlite3_config(SQLITE_CONFIG_GETMUTEX,X) +** where X is a pointer to an [sqlite3_mutex_methods] object +** shall overwrite the content of [sqlite3_mutex_methods] object +** with the mutex methods currently in use by SQLite. +** +** {H14135} A successful call to sqlite3_config(SQLITE_CONFIG_MALLOC,M) +** where M is a pointer to an initialized [sqlite3_mem_methods] +** object shall cause all subsequent memory allocation operations +** performed by SQLite to use the methods that were present in +** M during the call to sqlite3_config(). +** +** {H14138} A successful call to sqlite3_config(SQLITE_CONFIG_GETMALLOC,M) +** where M is a pointer to an [sqlite3_mem_methods] object shall +** overwrite the content of [sqlite3_mem_methods] object with +** the memory allocation methods currently in use by +** SQLite. +** +** {H14141} A successful call to sqlite3_config(SQLITE_CONFIG_MEMSTATUS,1) +** shall enable the memory allocation status collection logic. +** +** {H14144} A successful call to sqlite3_config(SQLITE_CONFIG_MEMSTATUS,0) +** shall disable the memory allocation status collection logic. +** +** {H14147} The memory allocation status collection logic shall be +** enabled by default. +** +** {H14150} A successful call to sqlite3_config(SQLITE_CONFIG_SCRATCH,S,Z,N) +** where Z and N are non-negative integers and +** S is a pointer to an aligned memory buffer not less than +** Z*N bytes in size shall cause S to be used by the +** [scratch memory allocator] for as many as N simulataneous +** allocations each of size Z. +** +** {H14153} A successful call to sqlite3_config(SQLITE_CONFIG_SCRATCH,S,Z,N) +** where S is a NULL pointer shall disable the +** [scratch memory allocator]. +** +** {H14156} A successful call to sqlite3_config(SQLITE_CONFIG_PAGECACHE,S,Z,N) +** where Z and N are non-negative integers and +** S is a pointer to an aligned memory buffer not less than +** Z*N bytes in size shall cause S to be used by the +** [pagecache memory allocator] for as many as N simulataneous +** allocations each of size Z. +** +** {H14159} A successful call to sqlite3_config(SQLITE_CONFIG_PAGECACHE,S,Z,N) +** where S is a NULL pointer shall disable the +** [pagecache memory allocator]. +** +** {H14162} A successful call to sqlite3_config(SQLITE_CONFIG_HEAP,H,Z,N) +** where Z and N are non-negative integers and +** H is a pointer to an aligned memory buffer not less than +** Z bytes in size shall enable the [memsys5] memory allocator +** and cause it to use buffer S as its memory source and to use +** a minimum allocation size of N. +** +** {H14165} A successful call to sqlite3_config(SQLITE_CONFIG_HEAP,H,Z,N) +** where H is a NULL pointer shall disable the +** [memsys5] memory allocator. +** +** {H14168} A successful call to sqlite3_config(SQLITE_CONFIG_LOOKASIZE,Z,N) +** shall cause the default [lookaside memory allocator] configuration +** for new [database connections] to be N slots of Z bytes each. */ SQLITE_EXPERIMENTAL int sqlite3_config(int, ...); -- 2.47.2