Add new test file e_blobclose.test, containing tests for sqlite3_blob_close().

FossilOrigin-Name: 5a1eac2419b1462e6f21595a3fff26d9cc49d203

manifest

@@ -1,5 +1,5 @@
-C New\stest\scases\sfor\sdeleting\scontent\sout\sfrom\sunder\sa\sSELECT\sstatement.
+C Add\snew\stest\sfile\se_blobclose.test,\scontaining\stests\sfor\ssqlite3_blob_close().
-D 2014-11-10T19:16:59.654
+D 2014-11-11T12:20:35.141
 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f
 F Makefile.in a226317fdf3f4c895fb3cfedc355b4d0868ce1fb
 F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23
@@ -230,7 +230,7 @@ F src/resolve.c 4965007d6497b6a4d7a6d98751cc39712885f952
 F src/rowset.c eccf6af6d620aaa4579bd3b72c1b6395d9e9fa1e
 F src/select.c 428165951748151e87a15295b7357221433e311b
 F src/shell.c bc28d5992109717c87804e2eb1a08a7c8cc7a2fd
-F src/sqlite.h.in 5531c4c69ee0a351c2aa5ad9f3f0f2424a57a9f4
+F src/sqlite.h.in 0e6612f84936cca29166f2c66068e0227a13fdf6
 F src/sqlite3.rc 992c9f5fb8285ae285d6be28240a7e8d3a7f2bad
 F src/sqlite3ext.h 17d487c3c91b0b8c584a32fbeb393f6f795eea7d
 F src/sqliteInt.h 71b0bf1a7fc55b5cb374f7579fd140e730a6e0f4
@@ -453,6 +453,7 @@ F test/descidx3.test 09ddbe3f5295f482d2f8b687cf6db8bad7acd9a2
 F test/diskfull.test 106391384780753ea6896b7b4f005d10e9866b6e
 F test/distinct.test 086e70c765f172e8974e9f83b9ac5ca03c154e77
 F test/distinctagg.test 1a6ef9c87a58669438fc771450d7a72577417376
+F test/e_blobclose.test df756753f571bc30e42e3a6cba2807576e49e716
 F test/e_blobopen.test 234f960d90235a9b51ec3ca1e062e8541dd558d8
 F test/e_blobwrite.test 615b405f29feb2cfb5a1f03dab7933258294fa26
 F test/e_changes.test fd66105385153dbf21fdb35eb8ef6c3e1eade579
@@ -1216,7 +1217,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 1df77e5f1bd82de4dc92fe28359c3e56ab3f9ed4
+P 8289c3e9b47f7c2a606a88839f6bf615f8904ac2
-R 4b8ad408c58c17649b0e1468e9b897aa
+R 5495040e5aa9cb71b6dcdaffde6bd935
-U drh
+U dan
-Z 1daa82bfd52bfa0c612ccd059afbb463
+Z 0fca1fa0cec9033f254d39e73d650ca5

manifest.uuid

@@ -1 +1 @@
-8289c3e9b47f7c2a606a88839f6bf615f8904ac2
+5a1eac2419b1462e6f21595a3fff26d9cc49d203

src/sqlite.h.in

@@ -5754,24 +5754,22 @@ SQLITE_EXPERIMENTAL int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
 /*
 ** CAPI3REF: Close A BLOB Handle
 **
-** ^Closes an open [BLOB handle].
+** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed
+** unconditionally.  Even if this routine returns an error code, the 
+** handle is still closed.)^
 **
-** ^Closing a BLOB shall cause the current transaction to commit
+** ^If the blob handle being closed was opened for read-write access, and if
-** if there are no other BLOBs, no pending prepared statements, and the
+** the database is in auto-commit mode and there are no other open read-write
-** database connection is in [autocommit mode].
+** blob handles or active write statements, the current transaction is
-** ^If any writes were made to the BLOB, they might be held in cache
+** committed. ^If an error occurs while committing the transaction, an error
-** until the close operation if they will fit.
+** code is returned and the transaction rolled back.
 **
-** ^(Closing the BLOB often forces the changes
+** Calling this function with an argument that is not a NULL pointer or an
-** out to disk and so if any I/O errors occur, they will likely occur
+** open blob handle results in undefined behaviour. ^Calling this routine 
-** at the time when the BLOB is closed.  Any errors that occur during
+** with a null pointer (such as would be returned by a failed call to 
-** closing are reported as a non-zero return value.)^
+** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function
-**
+** is passed a valid open blob handle, the values returned by the 
-** ^(The BLOB is closed unconditionally.  Even if this routine returns
+** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning.
-** an error code, the BLOB is still closed.)^
-**
-** ^Calling this routine with a null pointer (such as would be returned
-** by a failed call to [sqlite3_blob_open()]) is a harmless no-op.
 */
 int sqlite3_blob_close(sqlite3_blob *);
 

test/e_blobclose.test

@@ -0,0 +1,171 @@
+# 2014 October 30
+#
+# The author disclaims copyright to this source code.  In place of
+# a legal notice, here is a blessing:
+#
+#    May you do good and not evil.
+#    May you find forgiveness for yourself and forgive others.
+#    May you share freely, never taking more than you give.
+#
+#***********************************************************************
+#
+
+set testdir [file dirname $argv0]
+source $testdir/tester.tcl
+set testprefix e_blobclose
+
+set dots [string repeat . 40]
+do_execsql_test 1.0 {
+  CREATE TABLE x1(a INTEGER PRIMARY KEY, b DOTS);
+  INSERT INTO x1 VALUES(-1, $dots);
+  INSERT INTO x1 VALUES(-10, $dots);
+  INSERT INTO x1 VALUES(-100, $dots);
+  INSERT INTO x1 VALUES(-1000, $dots);
+  INSERT INTO x1 VALUES(-10000, $dots);
+}
+
+# EVIDENCE-OF: R-03145-46390 This function closes an open BLOB handle.
+#
+#   It's not clear how to test that a blob handle really is closed.
+#   Attempting to use a closed blob handle will likely crash the process.
+#   Assume here that if the SHARED lock on the db file is released,
+#   the blob handle has been closed.
+#
+do_execsql_test 1.1 { PRAGMA lock_status } {main unlocked temp closed}
+sqlite3_blob_open db main x1 b -1 0 B
+do_execsql_test 1.2 { PRAGMA lock_status } {main shared temp closed}
+sqlite3_blob_close $B
+do_execsql_test 1.3 { PRAGMA lock_status } {main unlocked temp closed}
+
+
+# EVIDENCE-OF: R-34027-00617 If the blob handle being closed was opened
+# for read-write access, and if the database is in auto-commit mode and
+# there are no other open read-write blob handles or active write
+# statements, the current transaction is committed.
+#
+#   2.1.*: Transaction is not committed if there are other open 
+#          read-write blob handles.
+#
+#   2.2.*: Transaction is not committed if not in auto-commit mode.
+#
+#   2.3.*: Active write statements.
+#
+do_test 2.1.1 {
+  sqlite3_blob_open db main x1 b -100 1 B1
+  sqlite3_blob_open db main x1 b -1000 1 B2
+  sqlite3_blob_open db main x1 b -10000 1 B3
+  sqlite3_blob_open db main x1 b -10000 0 B4      ;# B4 is read-only!
+  execsql { PRAGMA lock_status }
+} {main reserved temp closed}
+do_test 2.1.2 {
+  sqlite3_blob_close $B1 
+  execsql { PRAGMA lock_status }
+} {main reserved temp closed}
+do_test 2.1.3 {
+  sqlite3_blob_close $B2 
+  execsql { PRAGMA lock_status }
+} {main reserved temp closed}
+do_test 2.1.4 {
+  sqlite3_blob_close $B3 
+  execsql { PRAGMA lock_status }
+} {main shared temp closed}
+do_test 2.1.5 {
+  sqlite3_blob_close $B4 
+  execsql { PRAGMA lock_status }
+} {main unlocked temp closed}
+
+do_test 2.2.1 {
+  sqlite3_blob_open db main x1 b -100 1 B1
+  execsql { PRAGMA lock_status }
+} {main reserved temp closed}
+do_test 2.2.2 {
+  execsql { BEGIN }
+  sqlite3_blob_close $B1 
+  execsql { PRAGMA lock_status }
+} {main reserved temp closed}
+do_test 2.2.3 {
+  execsql { COMMIT }
+  execsql { PRAGMA lock_status }
+} {main unlocked temp closed}
+
+proc val {} { 
+  sqlite3_blob_close $::B 
+  db eval { PRAGMA lock_status }
+}
+db func val val
+do_test 2.3.1 {
+  sqlite3_blob_open db main x1 b -100 1 B
+  execsql { PRAGMA lock_status }
+} {main reserved temp closed}
+do_test 2.3.2 {
+  execsql { INSERT INTO x1 VALUES(15, val()) }
+  execsql { PRAGMA lock_status }
+} {main unlocked temp closed}
+do_test 2.3.3 {
+  execsql { SELECT * FROM x1 WHERE a = 15 }
+} {15 {main reserved temp closed}}
+
+# A reader does not inhibit commit.
+do_test 2.3.4 {
+  sqlite3_blob_open db main x1 b -100 1 B
+  execsql { PRAGMA lock_status }
+} {main reserved temp closed}
+do_test 2.3.5 {
+  execsql { SELECT a, val() FROM x1 LIMIT 1 }
+} {-10000 {main shared temp closed}}
+
+
+do_test 3.1 {
+  sqlite3_blob_open db main x1 b -10 1 B
+  execsql {
+    INSERT INTO x1 VALUES(1, 'abc');
+    SELECT * FROM x1 WHERE a=1;
+  }
+} {1 abc}
+do_test 3.2 {
+  sqlite3_blob_write $B 0 "abcdefghij" 10
+  execsql { SELECT * FROM x1 WHERE a=-10 }
+} {-10 abcdefghij..............................}
+
+do_test 3.3 {
+  sqlite3 db2 test.db
+  execsql { BEGIN ; SELECT * FROM x1 } db2
+  sqlite3_blob_close $B 
+} {SQLITE_BUSY}
+
+# EVIDENCE-OF: R-41959-38737 Otherwise, if this function is passed a
+# valid open blob handle, the values returned by the sqlite3_errcode()
+# and sqlite3_errmsg() functions are set before returning.
+#
+do_test 3.4 {
+  list [sqlite3_errcode db] [sqlite3_errmsg db]
+} {SQLITE_BUSY {database is locked}}
+
+# EVIDENCE-OF: R-37801-37633 The BLOB handle is closed unconditionally.
+# Even if this routine returns an error code, the handle is still
+# closed.
+#
+#   Test that the lock has been released. Assume this means the handle
+#   is closed, even though blob_close() returned SQLITE_BUSY.
+#
+do_execsql_test 3.4 { PRAGMA lock_status } {main unlocked temp closed}
+
+# EVIDENCE-OF: R-35111-05628 If an error occurs while committing the
+# transaction, an error code is returned and the transaction rolled
+# back.
+#
+#   Row 1 is removed (it was inserted this transaction) and row -10
+#   is restored to its original state. Transaction has been rolled back.
+#
+do_execsql_test 3.5 {
+  SELECT * FROM x1 WHERE a IN (1, -10);
+} {-10 ........................................}
+
+# EVIDENCE-OF: R-25894-51060 Calling this routine with a null pointer
+# (such as would be returned by a failed call to sqlite3_blob_open()) is
+# a harmless no-op.
+#
+do_test 4.0 { sqlite3_blob_close 0 } {}
+
+finish_test
+