Add missing comments associated with readonly shm changes.

FossilOrigin-Name: 6a2ea52e6c09a570428161090c2f087c66f714ec

manifest

@@ -1,5 +1,5 @@
-C Merge\slatest\strunk\schanges.\sAdd\sa\scouple\sof\sreadonly\sshm\stests.
-D 2011-05-11T15:53:16.929
+C Add\smissing\scomments\sassociated\swith\sreadonly\sshm\schanges.
+D 2011-05-11T17:36:17.276
 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f
 F Makefile.in 7a4d9524721d40ef9ee26f93f9bd6a51dba106f2
 F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23
@@ -144,7 +144,7 @@ F src/journal.c 552839e54d1bf76fb8f7abe51868b66acacf6a0e
 F src/legacy.c a199d7683d60cef73089e892409113e69c23a99f
 F src/lempar.c 7f026423f4d71d989e719a743f98a1cbd4e6d99e
 F src/loadext.c 3ae0d52da013a6326310655be6473fd472347b85
-F src/main.c 951a1af49d13083da09be9d2464052e49fc25830
+F src/main.c a145cea130adfe945ab1fa7e9543c492e3f2f419
 F src/malloc.c 591aedb20ae40813f1045f2ef253438a334775d9
 F src/mem0.c 6a55ebe57c46ca1a7d98da93aaa07f99f1059645
 F src/mem1.c 00bd8265c81abb665c48fea1e0c234eb3b922206
@@ -179,7 +179,7 @@ F src/resolve.c 1c0f32b64f8e3f555fe1f732f9d6f501a7f05706
 F src/rowset.c 69afa95a97c524ba6faf3805e717b5b7ae85a697
 F src/select.c d9d440809025a58547e39f4f268c2a296bfb56ff
 F src/shell.c 72e7e176bf46d5c6518d15ac4ad6847c4bb5df79
-F src/sqlite.h.in 059514ec27c8f9e11c73695aa57e55d354973e1e
+F src/sqlite.h.in adeb2c8019a3851a10e3872f44b34c95c6e409f2
 F src/sqlite3ext.h c90bd5507099f62043832d73f6425d8d5c5da754
 F src/sqliteInt.h 798fb09648cefc159ac9b3ce5e00f5ada1377ed1
 F src/sqliteLimit.h 164b0e6749d31e0daa1a4589a169d31c0dec7b3d
@@ -245,7 +245,7 @@ F src/vdbeblob.c c3ccb7c8732858c680f442932e66ad06bb036562
 F src/vdbemem.c 0498796b6ffbe45e32960d6a1f5adfb6e419883b
 F src/vdbetrace.c 5d0dc3d5fd54878cc8d6d28eb41deb8d5885b114
 F src/vtab.c 48dcef8bc757c2e7b488f68b5ddebb1650da2450
-F src/wal.c adc6c83b650e67e32159e11d557a46594834853e
+F src/wal.c 6d8ee757f62bca9b0b713724677878dff5bf7e79
 F src/wal.h c1e05cdf3d42ed7c9263739ca8f5cdd8761e7de3
 F src/walker.c 3112bb3afe1d85dc52317cb1d752055e9a781f8f
 F src/where.c 55403ce19c506be6a321c7f129aff693d6103db5
@@ -936,7 +936,7 @@ F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224
 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
 F tool/split-sqlite3c.tcl d9be87f1c340285a3e081eb19b4a247981ed290c
 F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f
-P 671ba5fc59f7a958e5a4138d2425b1173a442ad7 3e490915301216e242a5cdeb0febaff12ed53cb9
-R 1feba9025b47c541dc5cefaffc74e97e
+P cde45a033ee6834900f5f5c272c383408883a74c
+R 77f3671cb0a1ec2771484489a2a100be
 U dan
-Z af31082504210cb42f7a67f58917a8ef
+Z 826df29e354d14eb64673fd89c39c62e

manifest.uuid

@@ -1 +1 @@
-cde45a033ee6834900f5f5c272c383408883a74c
+6a2ea52e6c09a570428161090c2f087c66f714ec

src/main.c

@@ -1803,6 +1803,11 @@ int sqlite3_limit(sqlite3 *db, int limitId, int newLimit){
 ** *pFlags may be updated before returning if the URI filename contains 
 ** "cache=xxx" or "mode=xxx" query parameters.
 **
+** The third argument, pBtflags, points to an integer containing the flags
+** that will be passed as the 5th argument to sqlite3BtreeOpen (BTREE_XXX
+** flags). This value will be edited if the URI filename contains a
+** "readonly_shm=1" or "readonly_shm=0" query parameter.
+**
 ** If successful, SQLITE_OK is returned. In this case *ppVfs is set to point to
 ** the VFS that should be used to open the database file. *pzFile is set to
 ** point to a buffer containing the name of the file to open. It is the 

src/sqlite.h.in

@@ -736,6 +736,27 @@ struct sqlite3_io_methods {
 ** Applications should not call [sqlite3_file_control()] with this
 ** opcode as doing so may disrupt the operation of the specialized VFSes
 ** that do require it.  
+**
+** The [SQLITE_FCNTL_READONLY_SHM] may be generated internally by SQLite if
+** the "readonly_shm=1" URI option is specified when the database is opened.
+** The fourth argument passed to the VFS xFileControl methods is a pointer
+** to a variable of type "int" containing the value 1 or 0. If the variable
+** contains the value 1, then this indicates to the VFS that a read-only
+** mapping of the shared-memory region is acceptable. If it is set to 0, then
+** this indicates that a read-write mapping is required (as normal). If
+** a read-only mapping is returned, then the VFS may also return read-only
+** mappings for any subsequent requests via the same file-descriptor -
+** regardless of the value most recently configured using
+** SQLITE_FCNTL_READONLY_SHM.
+**
+** In practice, if "readonly_shm=1" is specified and the first attempt to
+** map a shared-memory region fails, then this file-control is invoked with
+** the argument variable set to 1 and a second attempt to map the shared-memory
+** region is made. If this mapping succeeds, then the connection continues
+** with the read-only mapping. Otherwise, if it fails, SQLITE_CANTOPEN is
+** returned to the caller. Whether or not the second (read-only) mapping
+** attempt succeeds, the file-control is invoked again with the argument
+** variable set to 0.
 */
 #define SQLITE_FCNTL_LOCKSTATE        1
 #define SQLITE_GET_LOCKPROXYFILE      2
@@ -2444,7 +2465,7 @@ void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
 **
 ** The query component of a URI may contain parameters that are interpreted
 ** either by SQLite itself, or by a [sqlite3_vfs | custom VFS implementation].
-** SQLite interprets the following three query parameters:
+** SQLite interprets the following four query parameters:
 **
 ** <ul>
 **   <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
@@ -2476,6 +2497,22 @@ void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
 **     ^If sqlite3_open_v2() is used and the "cache" parameter is present in
 **     a URI filename, its value overrides any behaviour requested by setting
 **     SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
+**
+**   <li> <b>readonly_shm</b>: ^The readonly_shm parameter may be set to 
+**     either "1" or "0". Setting it to "1" indicates that if the database
+**     is in WAL mode and read-write access to the associated shared 
+**     memory region cannot be obtained, then an attempt should be made to open
+**     the shared-memory in read-only mode instead. If there exist one or
+**     more other database clients that have read-write connections to the
+**     database shared-memory, then a read-only shared-memory connection works 
+**     fine. However, if there exist no clients with read-write connections 
+**     to the shared-memory and the most recent such crashed or was interrupted
+**     by a power failure, then it is possible for a database client using a
+**     read-only connection to return incorrect data, incorrectly report 
+**     database corruption, or return an SQLITE_READONLY error. Or if the
+**     most recent read-write connection shut down cleanly, it may not be
+**     possible to open the shared-memory in read-only mode at all, and SQLite
+**     will return SQLITE_CANTOPEN.
 ** </ul>
 **
 ** ^Specifying an unknown parameter in the query component of a URI is not an

src/wal.c

@@ -406,6 +406,14 @@ struct WalCkptInfo {
 /*
 ** An open write-ahead log file is represented by an instance of the
 ** following object.
+**
+** The readOnlyShm variable is normally set to 0. If it is set to 1, then
+** the connection to shared-memory is read-only. This means it cannot
+** be written at all (even when read-locking the database). If it is set
+** to 2, then the shared-memory region is not yet open, but a read-only
+** connection is acceptable. In this case when the shared-memory is opened
+** (see function walIndexPage()), readOnlyShm is set to either 0 or 1 as
+** appropriate.
 */
 struct Wal {
   sqlite3_vfs *pVfs;         /* The VFS used to create pDbFd */