From 3086529f7c4b59e0f868aae01c302a3c81e4683c Mon Sep 17 00:00:00 2001 From: drh Date: Tue, 12 Jun 2018 19:22:30 +0000 Subject: [PATCH] Documentation updates: clarify the behavior of sqlite3_column and sqlite3_value interfaces following an OOM error. FossilOrigin-Name: 428c581e4bed1d140cfb670633c9c61b36be7bb30a862d2e1ae7eaee26dccb4f --- manifest | 12 ++++++------ manifest.uuid | 2 +- src/sqlite.h.in | 46 +++++++++++++++++++++++++++++++++++++++++----- 3 files changed, 48 insertions(+), 12 deletions(-) diff --git a/manifest b/manifest index 10c89ed3bd..86f566af13 100644 --- 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 826912931d..9bf43ac027 100644 --- 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 3d2effa5b7..ce27c99077 100644 --- 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: +** +** +** +** 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: +** +** +** +** 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*);