Documentation updates: clarify the behavior of sqlite3_column and

sqlite3_value interfaces following an OOM error.

FossilOrigin-Name: 428c581e4bed1d140cfb670633c9c61b36be7bb30a862d2e1ae7eaee26dccb4f

diff --git a/manifest b/manifest
index 10c89ed3bd2e88e69da451de7d9e6ff8b6474979..86f566af13ec204584b981923f605aa5136626f2 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Improvements\sto\sSCopy\scorrectness\stracking\swhen\sSQLITE_DEBUG\sis\senabled.
-D 2018-06-12T13:52:23.858
+C Documentation\supdates:\sclarify\sthe\sbehavior\sof\ssqlite3_column\sand\nsqlite3_value\sinterfaces\sfollowing\san\sOOM\serror.
+D 2018-06-12T19:22:30.391
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F Makefile.in bfc40f350586923e0419d2ea4b559c37ec10ee4b6e210e08c14401f8e340f0da
@@ -497,7 +497,7 @@ F src/resolve.c 14602f46800ba182ea6a490e0f304127d29ac1f724bdadcc639e25d3223fcf6e
 F src/rowset.c 7b7e7e479212e65b723bf40128c7b36dc5afdfac
 F src/select.c 8d3176c5258cc83942815ebe75b4c1f8dcf62b5e0f4d37373a14ebf23c046f9f
 F src/shell.c.in 4d0ddf10c403710d241bf920163dcf032c21119aebb61e70840942c0eafecdf9
-F src/sqlite.h.in 63b07f76731f2b1e55c48fdb9f0508dcc6fbe3971010b8612ffd847c3c56d9a1
+F src/sqlite.h.in fd614975549a6b5904de35af89fd2d55fe35b4c170d0b355980d7e5872a2d30d
 F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
 F src/sqlite3ext.h 9887b27e69c01e79c2cbe74ef73bf01af5b5703d6a7f0a4371e386d7249cb1c7
 F src/sqliteInt.h c8d304712b6b4e2150cbb5355b1a80427eee7b3ea1a6b5827afadf557360d7fe
@@ -1731,7 +1731,7 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P acd78df61188591d33ddb9b1b8c16bcc015f4dffac66314529caa747d4395c70
-R 93c40cd2c3858b20bb206e515693fb00
+P b2973f2357a2c5e22e0d612c970adbc6d51cbc5e4ff7ac6d2b678722e553e8ec
+R 96ea65e1b8fd0c732cdc45dee2871747
 U drh
-Z 26ce7d0e08fb2667e584724fb5000334
+Z 40fdbbb1f5ad70e2a7a00adf1e075458

diff --git a/manifest.uuid b/manifest.uuid
index 826912931d51c2cf992ccb545f252f23714bf4ba..9bf43ac02744c27716277fa0f61f6aeba27636d8 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-b2973f2357a2c5e22e0d612c970adbc6d51cbc5e4ff7ac6d2b678722e553e8ec
\ No newline at end of file
+428c581e4bed1d140cfb670633c9c61b36be7bb30a862d2e1ae7eaee26dccb4f
\ No newline at end of file

diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 3d2effa5b78127f1291f2ba106de1c59ecdf17e1..ce27c99077678c3ca9ce5f0c2017624f665734e3 100644 (file)
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -4514,11 +4514,25 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
 ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
 ** [sqlite3_free()].
 **
-** ^(If a memory allocation error occurs during the evaluation of any
-** of these routines, a default value is returned.  The default value
-** is either the integer 0, the floating point number 0.0, or a NULL
-** pointer.  Subsequent calls to [sqlite3_errcode()] will return
-** [SQLITE_NOMEM].)^
+** As long as the input parameters are correct, these routines will only
+** fail if an out-of-memory error occurs during a format conversion.
+** Only the following subset of interfaces are subject to out-of-memory
+** errors:
+**
+** <ul>
+** <li> sqlite3_column_blob()
+** <li> sqlite3_column_text()
+** <li> sqlite3_column_text16()
+** <li> sqlite3_column_bytes()
+** <li> sqlite3_column_bytes16()
+** </ul>
+**
+** If an out-of-memory error occurs, then the return value from these
+** routines is the same as if the column had contained an SQL NULL value.
+** Valid SQL NULL returns can be distinguished from out-of-memory errors
+** by invoking the [sqlite3_errcode()] immediately after the suspect
+** return value is obtained and before any
+** other SQLite interface is called on the same [database connection].
 */
 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
 double sqlite3_column_double(sqlite3_stmt*, int iCol);
@@ -4857,6 +4871,28 @@ SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
 **
 ** These routines must be called from the same thread as
 ** the SQL function that supplied the [sqlite3_value*] parameters.
+**
+** As long as the input parameter is correct, these routines can only
+** fail if an out-of-memory error occurs during a format conversion.
+** Only the following subset of interfaces are subject to out-of-memory
+** errors:
+**
+** <ul>
+** <li> sqlite3_value_blob()
+** <li> sqlite3_value_text()
+** <li> sqlite3_value_text16()
+** <li> sqlite3_value_text16le()
+** <li> sqlite3_value_text16be()
+** <li> sqlite3_value_bytes()
+** <li> sqlite3_value_bytes16()
+** </ul>
+**
+** If an out-of-memory error occurs, then the return value from these
+** routines is the same as if the column had contained an SQL NULL value.
+** Valid SQL NULL returns can be distinguished from out-of-memory errors
+** by invoking the [sqlite3_errcode()] immediately after the suspect
+** return value is obtained and before any
+** other SQLite interface is called on the same [database connection].
 */
 const void *sqlite3_value_blob(sqlite3_value*);
 double sqlite3_value_double(sqlite3_value*);