From: drh <>
Date: Wed, 5 Feb 2025 12:02:43 +0000 (+0000)
Subject: Attempted improvements to the SQLITE_DBCONFIG_... documentation.
X-Git-Tag: version-3.49.0~4
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=b6859b6f2c3eedab12fb46b7295194c818420460;p=thirdparty%2Fsqlite.git

Attempted improvements to the SQLITE_DBCONFIG_... documentation.

FossilOrigin-Name: baac853871ad307b67b4d624b9ee47fc1313f1aa62c9f8072fb49e97aa33db94
---

diff --git a/manifest b/manifest
index 172ff7b118..f5d136df4a 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Detect\sand\sreport\ssigned\sinteger\soverflow\sin\sthe\ssumInverse()\sroutine,\nused\sby\swindow\sfunctions.
-D 2025-02-04T02:38:23.009
+C Attempted\simprovements\sto\sthe\sSQLITE_DBCONFIG_...\sdocumentation.
+D 2025-02-05T12:02:43.871
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md e108e1e69ae8e8a59e93c455654b8ac9356a11720d3345df2a4743e9590fb20d
@@ -782,7 +782,7 @@ F src/resolve.c c8a5372b97b2a2e972a280676f06ddb5b74e885d3b1f5ce383f839907b57ef68
 F src/rowset.c 8432130e6c344b3401a8874c3cb49fefe6873fec593294de077afea2dce5ec97
 F src/select.c 83e88fbb36f89b6703b348777491619554f0fd6f917c9fdf51e4c2e9cda6c04e
 F src/shell.c.in b377a59822f207106424f08aead37e78b609222e98f86f04cc8a03563ccf3237
-F src/sqlite.h.in cc9a2d5a719b7434e2699ff7c28a56209b8aa459b7f80ff1d4d7d8ac6ebfd96e
+F src/sqlite.h.in d2902f13ace94d3d3609646bd6d12a2d7a4f6cbdf6a5a4097580ac305f54c3f0
 F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
 F src/sqlite3ext.h 3f046c04ea3595d6bfda99b781926b17e672fd6d27da2ba6d8d8fc39981dcb54
 F src/sqliteInt.h 9d7052c71f46ca3a1a4880ba4a62590da334651139a38327d488894d9c883f3b
@@ -2209,8 +2209,8 @@ F tool/version-info.c 3b36468a90faf1bbd59c65fd0eb66522d9f941eedd364fabccd7227350
 F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee87c1b31a7
 F tool/warnings.sh 49a486c5069de041aedcbde4de178293e0463ae9918ecad7539eedf0ec77a139
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P 459d8f695ef868d0ec09920ab2035eebd36a66051f9905e2605f4600623faa47
-R 8b24f7285c9d92ca8cf04f526f040713
+P 317e9a470fba2a4b717b9cb66488b8fccb44810a80f3a7deaf1ea81906e2b8d2
+R 70f9a2f7e68a73caf1fe72ecdb3d41d3
 U drh
-Z fc7af611ca9f7a31dcf33650d3dd0378
+Z 5ee06f9c240d54c68e35a361db8f0493
 # Remove this line to create a well-formed Fossil manifest.
diff --git a/manifest.uuid b/manifest.uuid
index f9f95d23cb..af4c4d49c4 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-317e9a470fba2a4b717b9cb66488b8fccb44810a80f3a7deaf1ea81906e2b8d2
+baac853871ad307b67b4d624b9ee47fc1313f1aa62c9f8072fb49e97aa33db94
diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 885f187a43..a9eb5fed72 100644
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -2211,7 +2211,15 @@ struct sqlite3_mem_methods {
 ** CAPI3REF: Database Connection Configuration Options
 **
 ** These constants are the available integer configuration options that
-** can be passed as the second argument to the [sqlite3_db_config()] interface.
+** can be passed as the second parameter to the [sqlite3_db_config()] interface.
+**
+** The [sqlite3_db_config()] interface is a var-args functions.  It takes a
+** variable number of parameters, though always at least two.  The number of
+** parameters passed into sqlite3_db_config() depends on which of these
+** constants is given as the second parameter.  This documentation page
+** refers to parameters beyond the second as "arguments".  Thus, when this
+** page says "the N-th argument" it means "the N-th parameter past the
+** configuration option" or "the (N+2)-th parameter to sqlite3_db_config()".
 **
 ** New configuration options may be added in future releases of SQLite.
 ** Existing configuration options might be discontinued.  Applications
@@ -2228,7 +2236,9 @@ struct sqlite3_mem_methods {
 ** connection.
 ** The arguments to the SQLITE_DBCONFIG_LOOKASIDE option are <i>not</i>
 ** in the [DBCONFIG arguments|usual format].
-** The SQLITE_DBCONFIG_LOOKASIDE option takes three arguments, not two.
+** The SQLITE_DBCONFIG_LOOKASIDE option takes three arguments, not two,
+** so that a call to [sqlite3_db_config()] that uses SQLITE_DBCONFIG_LOOKASIDE
+** should have a total of five parameters.
 ** ^The first argument (the third parameter to [sqlite3_db_config()] is a
 ** pointer to a memory buffer to use for lookaside memory.
 ** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
@@ -2330,12 +2340,13 @@ struct sqlite3_mem_methods {
 ** <dd> ^This option is used to change the name of the "main" database
 ** schema.  This option does not follow the
 ** [DBCONFIG arguments|usual SQLITE_DBCONFIG argument format].
-** This option takes exactly one argument, which ust be a pointer
-** to a constant UTF8 string which will become the new schema name
-** in place of "main".  ^SQLite does not make a copy of the new main
-** schema name string, so the application must ensure that the argument
-** passed into SQLITE_DBCONFIG MAINDBNAME is unchanged
-** until after the database connection closes.
+** This option takes exactly one additional argument so that the 
+** [sqlite3_db_config()] call has a total of three parameters.  The
+** extra argument must be a pointer to a constant UTF8 string which
+** will become the new schema name in place of "main".  ^SQLite does
+** not make a copy of the new main schema name string, so the application
+** must ensure that the argument passed into SQLITE_DBCONFIG MAINDBNAME
+** is unchanged until after the database connection closes.
 ** </dd>
 **
 ** [[SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE]]
@@ -2346,10 +2357,11 @@ struct sqlite3_mem_methods {
 ** connection being closed is the last open connection to the database),
 ** then SQLite performs a [checkpoint] before closing the connection and
 ** deletes the WAL file.  The SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE option can
-** be used to override that behavior. The first parameter passed to this
-** operation is an integer - positive to disable checkpoints-on-close, or
-** zero (the default) to enable them, and negative to leave the setting unchanged.
-** The second parameter is a pointer to an integer
+** be used to override that behavior. The first argument passed to this
+** operation (the third parameter to [sqlite3_db_config()]) is an integer
+** which is positive to disable checkpoints-on-close, or zero (the default)
+** to enable them, and negative to leave the setting unchanged.
+** The second argument (the fourth parameter) is a pointer to an integer
 ** into which is written 0 or 1 to indicate whether checkpoints-on-close
 ** have been disabled - 0 if they are not disabled, 1 if they are.
 ** </dd>
@@ -2587,9 +2599,11 @@ struct sqlite3_mem_methods {
 **
 ** [[DBCONFIG arguments]] <h3>Arguments To SQLITE_DBCONFIG Options</h3>
 **
-** <p>Most of the SQLITE_DBCONFIG options take two arguments: an integer
-** and a pointer to an integer.  If the first integer argument is 1, then
-** the option becomes enabled.  If the first integer argument is 0, then the
+** <p>Most of the SQLITE_DBCONFIG options take two arguments, so that the
+** overall call to [sqlite3_db_config()] has a total of four parameters.
+** The first argument (the third parameter to sqlite3_db_config()) is a integer.
+** The second argument is a pointer to an integer.  If the first argument is 1,
+** then the option becomes enabled.  If the first integer argument is 0, then the
 ** option is disabled.  If the first argument is -1, then the option setting
 ** is unchanged.  The second argument, the pointer to an integer, may be NULL.
 ** If the second argument is not NULL, then a value of 0 or 1 is written into