From: drh <>
Date: Tue, 7 Nov 2023 19:15:55 +0000 (+0000)
Subject: Update the documentation to the sqlite3_set_auxdata() and sqlite3_get_auxdata()
X-Git-Tag: version-3.44.1~18
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=6d12b9f850561ac35c2509a5bf2647ddc83a0920;p=thirdparty%2Fsqlite.git

Update the documentation to the sqlite3_set_auxdata() and sqlite3_get_auxdata()
routines to make it clear that they do not work as one might expect when they
are called during query planning, instead of during query execution.  The JSON
routines misuse those interfaces, so add a special flag to JSON routines that
prevents them from being invoked during query planning.

FossilOrigin-Name: 36259009c5b581ea692e8c86f505783336e4615bb5134e3afd5498f10eb36239
---

diff --git a/manifest b/manifest
index bb6cfbdceb..ec8b9d9dad 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Update\sthe\ssrctree-check.tcl\sscript\sand\schild\sscript\sso\sthat\sthey\scan\sbe\srun\non\sa\sread-only\ssource\stree\sand\sso\sthat\sif\sany\sinconsistencies\sare\sfound,\sthe\nscript\sreturns\sa\snon-zero\sexit\scode\sand\sthus\shalts\sthe\sbuild.
-D 2023-11-06T19:08:46.831
+C Update\sthe\sdocumentation\sto\sthe\ssqlite3_set_auxdata()\sand\ssqlite3_get_auxdata()\nroutines\sto\smake\sit\sclear\sthat\sthey\sdo\snot\swork\sas\sone\smight\sexpect\swhen\sthey\nare\scalled\sduring\squery\splanning,\sinstead\sof\sduring\squery\sexecution.\s\sThe\sJSON\nroutines\smisuse\sthose\sinterfaces,\sso\sadd\sa\sspecial\sflag\sto\sJSON\sroutines\sthat\nprevents\sthem\sfrom\sbeing\sinvoked\sduring\squery\splanning.
+D 2023-11-07T19:15:55.602
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -723,10 +723,10 @@ F src/resolve.c 31229276a8eb5b5de1428cd2d80f6f1cf8ffc5248be25e47cf575df12f1b8f23
 F src/rowset.c 8432130e6c344b3401a8874c3cb49fefe6873fec593294de077afea2dce5ec97
 F src/select.c a19daa26e95f7245106a31f288b2f50c72d1f2cc156703f04c8c91450e111515
 F src/shell.c.in aebfbedaa7706d2c73ab7366a19fc8bc40ea68b70d2529f7feef54e6eb077ea2
-F src/sqlite.h.in ef0e41e83ad1ac0dcc9ec9939bf541a44b1c5de821bee2d6c61754c3252f3276
+F src/sqlite.h.in a0fce680a40fe81b13eae3749d001134d9fe0a43aecc09a8986520d5119acfcd
 F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
 F src/sqlite3ext.h 3f046c04ea3595d6bfda99b781926b17e672fd6d27da2ba6d8d8fc39981dcb54
-F src/sqliteInt.h 567e317f8631883897b7d3da43fce778b7c30dd0dd7f714558c9725fc1c1196c
+F src/sqliteInt.h fde93552e5bfc8ed59d689c6ff3b982f05b9944eff57067bdc21adf39a79037c
 F src/sqliteLimit.h 33b1c9baba578d34efe7dfdb43193b366111cdf41476b1e82699e14c11ee1fb6
 F src/status.c 160c445d7d28c984a0eae38c144f6419311ed3eace59b44ac6dafc20db4af749
 F src/table.c 0f141b58a16de7e2fbe81c308379e7279f4c6b50eb08efeec5892794a0ba30d1
@@ -797,7 +797,7 @@ F src/vdbeInt.h 949669dfd8a41550d27dcb905b494f2ccde9a2e6c1b0b04daa1227e2e74c2b2c
 F src/vdbeapi.c fe654b1f54e1feebcaed6c2ae3ed035cc65bfeb9a1169bed866abc42bfc63ff6
 F src/vdbeaux.c dffcf79e7e415fcd6e4c8ac1ec7124cae5257018443adf09551c807655b04993
 F src/vdbeblob.c 13f9287b55b6356b4b1845410382d6bede203ceb29ef69388a4a3d007ffacbe5
-F src/vdbemem.c c936e9002af4993b84c4eb7133d6b1190efe46d391cc86117ecd67ba17b1a04b
+F src/vdbemem.c 0012d5f01cc866833847c2f3ae4c318ac53a1cb3d28acad9c35e688039464cf0
 F src/vdbesort.c 237840ca1947511fa59bd4e18b9eeae93f2af2468c34d2427b059f896230a547
 F src/vdbetrace.c fe0bc29ebd4e02c8bc5c1945f1d2e6be5927ec12c06d89b03ef2a4def34bf823
 F src/vdbevtab.c 2143db7db0ceed69b21422581f434baffc507a08d831565193a7a02882a1b6a7
@@ -2139,10 +2139,9 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 34af510a5615339f2963875eab94d4b07725e766c20819f82add19faa229d552
-Q +58eb5440d75fb13c1a089cb935de6fb94b4322e10e349db8f11f37b9a2fda2fc
-Q +cba9f0601ca995ac6952aa3a83f7264f6d25aaaa2ea36b19e90cbf591077de72
-R 07f5bfdcff7ecaae49d8d3d2bfc1f266
+P a0cc7e8117abf03c8d0ab903f1f4b8ff48b6c0e6de85080c9d2a915fd1c16778
+Q +796a23f9ee33da0803844a2f40c1733db894cc4ef7fbaa1fa94af6af2d3b873b
+R 22e37008c6509682b9b0ed9d482278f2
 U drh
-Z 58004ee5792314b55778e61ab0e49ddd
+Z 4b770f2fdc5ebfd9babe12db0950deb9
 # Remove this line to create a well-formed Fossil manifest.
diff --git a/manifest.uuid b/manifest.uuid
index c73c593e6f..198f26384a 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-a0cc7e8117abf03c8d0ab903f1f4b8ff48b6c0e6de85080c9d2a915fd1c16778
\ No newline at end of file
+36259009c5b581ea692e8c86f505783336e4615bb5134e3afd5498f10eb36239
\ No newline at end of file
diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 01a7f4d4e0..2317d98f79 100644
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -5913,14 +5913,22 @@ sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
 ** <li> ^(when sqlite3_set_auxdata() is invoked again on the same
 **       parameter)^, or
 ** <li> ^(during the original sqlite3_set_auxdata() call when a memory
-**      allocation error occurs.)^ </ul>
+**      allocation error occurs.)^
+** <li> ^(during the original sqlite3_set_auxdata() call if the function
+**      is evaluated during query planning instead of during query execution,
+**      as sometimes happens with [SQLITE_ENABLE_STAT4].)^ </ul>
 **
-** Note the last bullet in particular.  The destructor X in
+** Note the last two bullets in particular.  The destructor X in
 ** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
 ** sqlite3_set_auxdata() interface even returns.  Hence sqlite3_set_auxdata()
 ** should be called near the end of the function implementation and the
 ** function implementation should not make any use of P after
-** sqlite3_set_auxdata() has been called.
+** sqlite3_set_auxdata() has been called.  Furthermore, a call to
+** sqlite3_get_auxdata() that occurs immediately after a corresponding call
+** to sqlite3_set_auxdata() might still return NULL if an out-of-memory
+** condition occurred during the sqlite3_set_auxdata() call or if the
+** function is being evaluated during query planning rather than during
+** query execution.
 **
 ** ^(In practice, auxiliary data is preserved between function calls for
 ** function parameters that are compile-time constants, including literal
diff --git a/src/sqliteInt.h b/src/sqliteInt.h
index dbf01dd139..079f5bd778 100644
--- a/src/sqliteInt.h
+++ b/src/sqliteInt.h
@@ -2014,7 +2014,7 @@ struct FuncDestructor {
 #define SQLITE_FUNC_SLOCHNG  0x2000 /* "Slow Change". Value constant during a
                                     ** single query - might change over time */
 #define SQLITE_FUNC_TEST     0x4000 /* Built-in testing functions */
-/*                           0x8000 -- available for reuse */
+#define SQLITE_FUNC_RUNONLY  0x8000 /* Cannot be used by valueFromFunction */
 #define SQLITE_FUNC_WINDOW   0x00010000 /* Built-in window-only function */
 #define SQLITE_FUNC_INTERNAL 0x00040000 /* For use by NestedParse() only */
 #define SQLITE_FUNC_DIRECT   0x00080000 /* Not for use in TRIGGERs or VIEWs */
@@ -2115,7 +2115,7 @@ struct FuncDestructor {
    xPtr, 0, xFunc, 0, 0, 0, #zName, {0} }
 #define JFUNCTION(zName, nArg, iArg, xFunc) \
   {nArg, SQLITE_FUNC_BUILTIN|SQLITE_DETERMINISTIC|\
-   SQLITE_FUNC_CONSTANT|SQLITE_UTF8, \
+   SQLITE_FUNC_CONSTANT|SQLITE_UTF8|SQLITE_FUNC_RUNONLY, \
    SQLITE_INT_TO_PTR(iArg), 0, xFunc, 0, 0, 0, #zName, {0} }
 #define INLINE_FUNC(zName, nArg, iArg, mFlags) \
   {nArg, SQLITE_FUNC_BUILTIN|\
diff --git a/src/vdbemem.c b/src/vdbemem.c
index eee828143a..d527164685 100644
--- a/src/vdbemem.c
+++ b/src/vdbemem.c
@@ -1515,7 +1515,7 @@ static int valueFromFunction(
 #endif
   assert( pFunc );
   if( (pFunc->funcFlags & (SQLITE_FUNC_CONSTANT|SQLITE_FUNC_SLOCHNG))==0
-   || (pFunc->funcFlags & SQLITE_FUNC_NEEDCOLL)
+   || (pFunc->funcFlags & (SQLITE_FUNC_NEEDCOLL|SQLITE_FUNC_RUNONLY))!=0
   ){
     return SQLITE_OK;
   }