From: drh <drh@noemail.net>
Date: Fri, 6 Mar 2015 04:37:26 +0000 (+0000)
Subject: Clearification of some documentation text.  Added requirements marks.
X-Git-Tag: version-3.8.9~90
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=8dd7a6a9258dda2339b85c993f30f682ad84e21f;p=thirdparty%2Fsqlite.git

Clearification of some documentation text.  Added requirements marks.

FossilOrigin-Name: 8c1e85aab9e0d90726057e25e2ea0663341c070f
---

diff --git a/manifest b/manifest
index ff068474f4..d6db801e6a 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Clarification\sof\sdocumentation\son\ssqlite3_backup.
-D 2015-03-06T03:31:58.777
+C Clearification\sof\ssome\sdocumentation\stext.\s\sAdded\srequirements\smarks.
+D 2015-03-06T04:37:26.939
 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f
 F Makefile.in 2f643d6968dfc0b82d2e546a0525a39079f9e928
 F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23
@@ -223,7 +223,7 @@ F src/parse.y 0f8e7d60f0ab3cb53d270adef69259ac307d83a8
 F src/pcache.c 10539fb959849ad6efff80050541cab3d25089d4
 F src/pcache.h b44658c9c932d203510279439d891a2a83e12ba8
 F src/pcache1.c 1e77432b40b7d3288327d9cdf399dcdfd2b6d3bf
-F src/pragma.c 7f51aba7fae823ea5e40280844d722e5ac402a32
+F src/pragma.c ac4f3f856b4234e85f55b0f069698a4766011100
 F src/pragma.h 09c89bca58e9a44de2116cc8272b8d454657129f
 F src/prepare.c 173a5a499138451b2561614ecb87d78f9f4644b9
 F src/printf.c 8da9a2687a396daa19860f4dc90975d319304744
@@ -232,7 +232,7 @@ F src/resolve.c f4d79e31ffa5820c2e3d1740baa5e9b190425f2b
 F src/rowset.c eccf6af6d620aaa4579bd3b72c1b6395d9e9fa1e
 F src/select.c e46cef4c224549b439384c88fc7f57ba064dad54
 F src/shell.c cce82ca26392578a4a1ee927dfe55ea3411c7c92
-F src/sqlite.h.in 01d70ea11cfc033f2026e725f22c39936e9ea3d1
+F src/sqlite.h.in 356e69db9500b3fd11705c21ca247e19b95884a3
 F src/sqlite3.rc 992c9f5fb8285ae285d6be28240a7e8d3a7f2bad
 F src/sqlite3ext.h 17d487c3c91b0b8c584a32fbeb393f6f795eea7d
 F src/sqliteInt.h fae682c2b4dfbe489b134d74521c41c088f16ab1
@@ -266,7 +266,7 @@ F src/test_intarray.h 9dc57417fb65bc7835cc18548852cc08cc062202
 F src/test_journal.c 5360fbe1d1e4416ca36290562fd5a2e3f70f32aa
 F src/test_loadext.c a5251f956ab6af21e138dc1f9c0399394a510cb4
 F src/test_malloc.c b9495384e74923aefde8311de974bf9b0f5ba570
-F src/test_multiplex.c 72c0ad1e97af3d6d19975bbd81813072b40c7290
+F src/test_multiplex.c 61edf02530f7511a0529352cd8139ead3af4c401
 F src/test_multiplex.h c08e4e8f8651f0c5e0509b138ff4d5b43ed1f5d3
 F src/test_mutex.c 293042d623ebba969160f471a82aa1551626454f
 F src/test_onefile.c 0396f220561f3b4eedc450cef26d40c593c69a25
@@ -753,7 +753,7 @@ F test/mmapfault.test d4c9eff9cd8c2dc14bc43e71e042f175b0a26fe3
 F test/multiplex.test efd015ca0b5b4a57dc9535b8feb1273eebeadb60
 F test/multiplex2.test 580ca5817c7edbe4cc68fa150609c9473393003a
 F test/multiplex3.test d228f59eac91839a977eac19f21d053f03e4d101
-F test/multiplex4.test d3e8a5a522c51cbf3ed1c5b0bd496be02c29d7b1
+F test/multiplex4.test e8ae4c4bd70606a5727743241f13b5701990abe4
 F test/mutex1.test 78b2b9bb320e51d156c4efdb71b99b051e7a4b41
 F test/mutex2.test bfeaeac2e73095b2ac32285d2756e3a65e681660
 F test/nan.test e9648b9d007c7045242af35e11a984d4b169443a
@@ -803,7 +803,7 @@ F test/quota2.test 7dc12e08b11cbc4c16c9ba2aa2e040ea8d8ab4b8
 F test/quote.test 215897dbe8de1a6f701265836d6601cc6ed103e6
 F test/randexpr1.tcl 40dec52119ed3a2b8b2a773bce24b63a3a746459
 F test/randexpr1.test eda062a97e60f9c38ae8d806b03b0ddf23d796df
-F test/rdonly.test dd30a4858d8e0fbad2304c2bd74a33d4df36412a
+F test/rdonly.test 64e2696c322e3538df0b1ed624e21f9a23ed9ff8
 F test/regexp1.test 497ea812f264d12b6198d6e50a76be4a1973a9d8
 F test/reindex.test 44edd3966b474468b823d481eafef0c305022254
 F test/releasetest.tcl 13f401c10dd4fe1a2fb811ae6ed27fd7d1300d3c
@@ -866,7 +866,7 @@ F test/shell4.test 8a9c08976291e6c6c808b4d718f4a8b299f339f5
 F test/shell5.test c04e9f9f948305706b88377c464c7f08ce7479f9
 F test/shortread1.test bb591ef20f0fd9ed26d0d12e80eee6d7ac8897a3
 F test/show_speedtest1_rtree.tcl 32e6c5f073d7426148a6936a0408f4b5b169aba5
-F test/shrink.test 8c70f62b6e8eb4d54533de6d65bd06b1b9a17868
+F test/shrink.test 06deac10d591186017466ce67d10645150bfdeec
 F test/sidedelete.test f0ad71abe6233e3b153100f3b8d679b19a488329
 F test/skipscan1.test 2ddfe5d168462170c4487f534e2a99fb006b2076
 F test/skipscan2.test d1d1450952b7275f0b0a3a981f0230532743951a
@@ -878,7 +878,7 @@ F test/softheap1.test 843cd84db9891b2d01b9ab64cef3e9020f98d087
 F test/sort.test 3f492e5b7be1d3f756728d2ff6edf4f6091e84cb
 F test/sort2.test 37afbc03f5559f2eb0f18940b55d38dfbb5172ac
 F test/sort3.test 6178ade30810ac9166fcdf14b7065e49c0f534e2
-F test/sort4.test d5e8903194ae551551349ce25dc8d0b40ca2b9c3
+F test/sort4.test 5c34d9623a4ae5921d956dfa2b70e77ed0fc6e5c
 F test/sort5.test a448240a42b49239edc00f85d6d7ac7a1b261e1f
 F test/sortfault.test d4ccf606a0c77498e2beb542764fd9394acb4d66
 F test/speed1.test f2974a91d79f58507ada01864c0e323093065452
@@ -891,7 +891,7 @@ F test/speed4p.explain 6b5f104ebeb34a038b2f714150f51d01143e59aa
 F test/speed4p.test 0e51908951677de5a969b723e03a27a1c45db38b
 F test/speedtest1.c 2b416dca3a155fcaa849540b2e7fc1df12896c23
 F test/spellfix.test 24f676831acddd2f4056a598fd731a72c6311f49
-F test/sqllimits1.test 9014524e7ab16e2a4976b13397db4c29cc29c6d9
+F test/sqllimits1.test e05786eaed7950ff6a2d00031d001d8a26131e68
 F test/stat.test 76fd746b85459e812a0193410fb599f0531f22de
 F test/stmt.test 25d64e3dbf9a3ce89558667d7f39d966fe2a71b9
 F test/subquery.test 666fdecceac258f5fd84bed09a64e49d9f37edd9
@@ -1240,7 +1240,7 @@ F tool/vdbe_profile.tcl 67746953071a9f8f2f668b73fe899074e2c6d8c1
 F tool/warnings-clang.sh f6aa929dc20ef1f856af04a730772f59283631d4
 F tool/warnings.sh 0abfd78ceb09b7f7c27c688c8e3fe93268a13b32
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P e5b13634d9794e4c75378cea89b64c5ecc5aa3e5
-R 2fcf8a15273b53b5f7ba658720892ca0
+P 31d5e9b42e5c96207187dcde1cbbb1e79f26fca2
+R e3bd9c89d1416be2fa13657fae649477
 U drh
-Z 07edb104d96caf5f091f46d1d6c18f99
+Z 0cf6c34744d872d2f1bdb9d1e644babc
diff --git a/manifest.uuid b/manifest.uuid
index 691bf89a4d..aa2a348ab8 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-31d5e9b42e5c96207187dcde1cbbb1e79f26fca2
\ No newline at end of file
+8c1e85aab9e0d90726057e25e2ea0663341c070f
\ No newline at end of file
diff --git a/src/pragma.c b/src/pragma.c
index 875d9ec006..ef11d5840f 100644
--- a/src/pragma.c
+++ b/src/pragma.c
@@ -317,6 +317,17 @@ void sqlite3Pragma(
   /* Send an SQLITE_FCNTL_PRAGMA file-control to the underlying VFS
   ** connection.  If it returns SQLITE_OK, then assume that the VFS
   ** handled the pragma and generate a no-op prepared statement.
+  **
+  ** IMPLEMENTATION-OF: R-12238-55120 Whenever a PRAGMA statement is parsed,
+  ** an SQLITE_FCNTL_PRAGMA file control is sent to the open sqlite3_file
+  ** object corresponding to the database file to which the pragma
+  ** statement refers.
+  **
+  ** IMPLEMENTATION-OF: R-29875-31678 The argument to the SQLITE_FCNTL_PRAGMA
+  ** file control is an array of pointers to strings (char**) in which the
+  ** second element of the array is the name of the pragma and the third
+  ** element is the argument to the pragma or NULL if the pragma has no
+  ** argument.
   */
   aFcntl[0] = 0;
   aFcntl[1] = zLeft;
diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 130c5fb73f..06e0f7eb9f 100644
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -751,14 +751,16 @@ struct sqlite3_io_methods {
 ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
 ** interface.
 **
+** <ul>
+** <li>[[SQLITE_FCNTL_LOCKSTATE]]
 ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
 ** opcode causes the xFileControl method to write the current state of
 ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
 ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
 ** into an integer that the pArg argument points to. This capability
-** is used during testing and only needs to be supported when SQLITE_TEST
-** is defined.
-** <ul>
+** is used during testing and is only available when the SQLITE_TEST
+** compile-time option is used.
+**
 ** <li>[[SQLITE_FCNTL_SIZE_HINT]]
 ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
 ** layer a hint of how large the database file will grow to be during the
@@ -883,7 +885,9 @@ struct sqlite3_io_methods {
 ** [PRAGMA] processing continues.  ^If the [SQLITE_FCNTL_PRAGMA]
 ** file control returns [SQLITE_OK], then the parser assumes that the
 ** VFS has handled the PRAGMA itself and the parser generates a no-op
-** prepared statement.  ^If the [SQLITE_FCNTL_PRAGMA] file control returns
+** prepared statement if result string is NULL, or that returns a copy
+** of the result string if the string is non-NULL.
+** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
 ** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
 ** that the VFS encountered an error while handling the [PRAGMA] and the
 ** compilation of the PRAGMA fails with an error.  ^The [SQLITE_FCNTL_PRAGMA]
diff --git a/src/test_multiplex.c b/src/test_multiplex.c
index 8f204c6694..dbd395d620 100644
--- a/src/test_multiplex.c
+++ b/src/test_multiplex.c
@@ -1004,6 +1004,13 @@ static int multiplexFileControl(sqlite3_file *pConn, int op, void *pArg){
       break;
     case SQLITE_FCNTL_PRAGMA: {
       char **aFcntl = (char**)pArg;
+      /*
+      ** EVIDENCE-OF: R-29875-31678 The argument to the SQLITE_FCNTL_PRAGMA
+      ** file control is an array of pointers to strings (char**) in which the
+      ** second element of the array is the name of the pragma and the third
+      ** element is the argument to the pragma or NULL if the pragma has no
+      ** argument.
+      */
       if( aFcntl[1] && sqlite3_stricmp(aFcntl[1],"multiplex_truncate")==0 ){
         if( aFcntl[2] && aFcntl[2][0] ){
           if( sqlite3_stricmp(aFcntl[2], "on")==0
@@ -1015,6 +1022,12 @@ static int multiplexFileControl(sqlite3_file *pConn, int op, void *pArg){
             pGroup->bTruncate = 0;
           }
         }
+        /* EVIDENCE-OF: R-27806-26076 The handler for an SQLITE_FCNTL_PRAGMA
+        ** file control can optionally make the first element of the char**
+        ** argument point to a string obtained from sqlite3_mprintf() or the
+        ** equivalent and that string will become the result of the pragma
+        ** or the error message if the pragma fails.
+        */
         aFcntl[0] = sqlite3_mprintf(pGroup->bTruncate ? "on" : "off");
         rc = SQLITE_OK;
         break;
diff --git a/test/multiplex4.test b/test/multiplex4.test
index 9c304c314d..2caebeadb7 100644
--- a/test/multiplex4.test
+++ b/test/multiplex4.test
@@ -59,6 +59,14 @@ do_test multiplex4-1.1 {
   multiplex_file_list mx4test
 } {mx4test.db}
 
+# NB:  The PRAGMA multiplex_truncate command is implemented using the
+# SQLITE_FCNTL_PRAGMA file-control...
+#
+# EVIDENCE-OF: R-12238-55120 Whenever a PRAGMA statement is parsed, an
+# SQLITE_FCNTL_PRAGMA file control is sent to the open sqlite3_file
+# object corresponding to the database file to which the pragma
+# statement refers.
+#
 do_test multiplex4-1.2 {
   db eval {PRAGMA multiplex_truncate}
 } {on}
@@ -84,6 +92,16 @@ do_test multiplex4-1.9 {
   db eval {PRAGMA multiplex_truncate=0}
 } {off}
 
+# EVIDENCE-OF: R-26188-08449 If the SQLITE_FCNTL_PRAGMA file control
+# returns SQLITE_OK, then the parser assumes that the VFS has handled
+# the PRAGMA itself and the parser generates a no-op prepared statement
+# if result string is NULL, or that returns a copy of the result string
+# if the string is non-NULL.
+#
+do_test multiplex4-1.9-explain {
+  db eval {EXPLAIN PRAGMA multiplex_truncate=0;}
+} {/String8 \d \d \d off/}
+
 do_test multiplex4-1.10 {
   db eval {
     INSERT INTO t1(x) VALUES(randomblob(250000));
diff --git a/test/rdonly.test b/test/rdonly.test
index 938cc7884c..404c613b21 100644
--- a/test/rdonly.test
+++ b/test/rdonly.test
@@ -32,6 +32,11 @@ do_test rdonly-1.1 {
     SELECT * FROM t1;
   }
 } {1}
+
+# EVIDENCE-OF: R-29639-16887 The sqlite3_db_readonly(D,N) interface
+# returns 1 if the database N of connection D is read-only, 0 if it is
+# read/write, or -1 if N is not the name of a database on connection D.
+#
 do_test rdonly-1.1.1 {
   sqlite3_db_readonly db main
 } {0}
diff --git a/test/shrink.test b/test/shrink.test
index e03ebeeb6e..6cc0786d28 100644
--- a/test/shrink.test
+++ b/test/shrink.test
@@ -24,6 +24,9 @@ do_test shrink-1.1 {
     INSERT INTO t1 VALUES(randomblob(1000000),1);
   }
   set ::baseline sqlite3_memory_used
+  # EVIDENCE-OF: R-58814-63508 The sqlite3_db_release_memory(D) interface
+  # attempts to free as much heap memory as possible from database
+  # connection D.
   sqlite3_db_release_memory db
   expr {$::baseline > [sqlite3_memory_used]+500000}
 } {1}
diff --git a/test/sort4.test b/test/sort4.test
index 7b913610da..13d9a5999a 100644
--- a/test/sort4.test
+++ b/test/sort4.test
@@ -25,7 +25,20 @@ sqlite3 db test.db
 
 
 # Configure the sorter to use 3 background threads.
-db eval {PRAGMA threads=3}
+#
+# EVIDENCE-OF: R-19249-32353 SQLITE_LIMIT_WORKER_THREADS The maximum
+# number of auxiliary worker threads that a single prepared statement
+# may start.
+#
+do_test sort4-init001 {
+  db eval {PRAGMA threads=5}
+  sqlite3_limit db SQLITE_LIMIT_WORKER_THREADS -1
+} {5}
+do_test sort4-init002 {
+  sqlite3_limit db SQLITE_LIMIT_WORKER_THREADS 3
+  db eval {PRAGMA threads}
+} {3}
+
 
 # Minimum number of seconds to run for. If the value is 0, each test
 # is run exactly once. Otherwise, tests are repeated until the timeout
diff --git a/test/sqllimits1.test b/test/sqllimits1.test
index 57fc931f7c..39e3aedd8f 100644
--- a/test/sqllimits1.test
+++ b/test/sqllimits1.test
@@ -250,6 +250,9 @@ do_test sqllimits1-4.10.1 {
 # Test cases sqllimits1-5.* test that the SQLITE_MAX_LENGTH limit
 # is enforced.
 #
+# EVIDENCE-OF: R-61987-00541 SQLITE_LIMIT_LENGTH The maximum size of any
+# string or BLOB or table row, in bytes.
+#
 db close
 sqlite3 db test.db
 set LARGESIZE 99999
@@ -406,6 +409,9 @@ unset strvalue
 # Test cases sqllimits1-6.* test that the SQLITE_MAX_SQL_LENGTH limit
 # is enforced.
 #
+# EVIDENCE-OF: R-09808-17554 SQLITE_LIMIT_SQL_LENGTH The maximum length
+# of an SQL statement, in bytes.
+#
 do_test sqllimits1-6.1 {
   sqlite3_limit db SQLITE_LIMIT_SQL_LENGTH 50000
   set sql "SELECT 1 WHERE 1==1"
@@ -567,6 +573,11 @@ do_test sqllimits1-7.7.4 {
 #--------------------------------------------------------------------
 # Test cases sqllimits1-8.* test the SQLITE_MAX_COLUMN limit.
 #
+# EVIDENCE-OF: R-43996-29471 SQLITE_LIMIT_COLUMN The maximum number of
+# columns in a table definition or in the result set of a SELECT or the
+# maximum number of columns in an index or in an ORDER BY or GROUP BY
+# clause.
+#
 set SQLITE_LIMIT_COLUMN 200
 sqlite3_limit db SQLITE_LIMIT_COLUMN $SQLITE_LIMIT_COLUMN
 do_test sqllimits1-8.1 {
@@ -670,6 +681,9 @@ do_test sqllimits1-8.11 {
 # limit is enforced. The limit refers to the number of terms in 
 # the expression.
 #
+# EVIDENCE-OF: R-12723-08526 SQLITE_LIMIT_EXPR_DEPTH The maximum depth
+# of the parse tree on any expression.
+#
 if {$SQLITE_MAX_EXPR_DEPTH==0} {
   puts -nonewline stderr "WARNING: Compile with -DSQLITE_MAX_EXPR_DEPTH to run "
   puts stderr "tests sqllimits1-9.X"
@@ -729,6 +743,9 @@ if 0 {
 # Test the SQLITE_LIMIT_FUNCTION_ARG limit works. Test case names
 # match the pattern "sqllimits1-11.*".
 #
+# EVIDENCE-OF: R-59001-45278 SQLITE_LIMIT_FUNCTION_ARG The maximum
+# number of arguments on a function.
+#
 for {set max 5} {$max<=$SQLITE_MAX_FUNCTION_ARG} {incr max} {
   do_test sqllimits1-11.$max.1 {
     set vals [list]
@@ -762,6 +779,9 @@ for {set max 5} {$max<=$SQLITE_MAX_FUNCTION_ARG} {incr max} {
 #--------------------------------------------------------------------
 # Test cases sqllimits1-12.*: Test the SQLITE_MAX_ATTACHED limit.
 #
+# EVIDENCE-OF: R-41778-26203 SQLITE_LIMIT_ATTACHED The maximum number of
+# attached databases.
+#
 ifcapable attach {
   do_test sqllimits1-12.1 {
     set max $::SQLITE_MAX_ATTACHED
@@ -785,6 +805,9 @@ ifcapable attach {
 # Test cases sqllimits1-13.*: Check that the SQLITE_MAX_VARIABLE_NUMBER 
 # limit works.
 #
+# EVIDENCE-OF: R-42363-29104 SQLITE_LIMIT_VARIABLE_NUMBER The maximum
+# index number of any parameter in an SQL statement.
+#
 do_test sqllimits1-13.1 {
   set max $::SQLITE_MAX_VARIABLE_NUMBER
   catchsql "SELECT ?[expr {$max+1}] FROM t1"
@@ -806,6 +829,9 @@ do_test sqllimits1-13.2 {
 # implementation by overriding the like() scalar function bypasses
 # this limitation.
 #
+# EVIDENCE-OF: R-12940-37052 SQLITE_LIMIT_LIKE_PATTERN_LENGTH The
+# maximum length of the pattern argument to the LIKE or GLOB operators.
+#
 # These tests check that the limit is not incorrectly applied to
 # the left-hand-side of the LIKE operator (the string being tested
 # against the pattern).