From: drh <drh@noemail.net>
Date: Thu, 26 Jun 2008 15:04:57 +0000 (+0000)
Subject: Document the rules for when an sqlite3_blob object expires. (CVS 5313)
X-Git-Tag: version-3.6.10~864
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=9de1b351891628d56e180625394ec8821b05ac94;p=thirdparty%2Fsqlite.git

Document the rules for when an sqlite3_blob object expires. (CVS 5313)

FossilOrigin-Name: e1de2287fd9b067f687cb8b427786b878af6c5b7
---

diff --git a/manifest b/manifest
index b127b2b707..769a500573 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Change\sthe\sTEMP_STORE\spreprocessor\ssymbol\sto\sSQLITE_TEMP_STORE.\s(CVS\s5312)
-D 2008-06-26T10:54:12
+C Document\sthe\srules\sfor\swhen\san\ssqlite3_blob\sobject\sexpires.\s(CVS\s5313)
+D 2008-06-26T15:04:58
 F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0
 F Makefile.in 325dfac0a0dd1cb4d975f1ace6453157892e6042
 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
@@ -142,7 +142,7 @@ F src/printf.c 8b063da9dcde26b7c500a01444b718d86f21bc6e
 F src/random.c 5c754319d38abdd6acd74601ee0105504adc508a
 F src/select.c 79f60dc4a7e90bb907c7a2cca42f45276d1ead99
 F src/shell.c 479807b87f0409289eec4a776cd6ae56d30544b1
-F src/sqlite.h.in 0dfa5d11d2c063ef551cbc9f3933295857e420fc
+F src/sqlite.h.in 2b9e8de3378101ad8ec8de98e3679ad5c2f39427
 F src/sqlite3ext.h f162a72daef5ebf8b211fe8c0ec96e85d22fbf9b
 F src/sqliteInt.h 5ed69fd1affa577a47ce01baa42ee94f22f45ed7
 F src/sqliteLimit.h f435e728c6b620ef7312814d660a81f9356eb5c8
@@ -594,7 +594,7 @@ F tool/speedtest16.c c8a9c793df96db7e4933f0852abb7a03d48f2e81
 F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
 F tool/speedtest8.c 1dbced29de5f59ba2ebf877edcadf171540374d1
 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
-P cdd4cf4ce2ab363ddc3f27c5e44896e17269a161
-R 4b084b9e9669e70ff412e4ed6bcd00b8
-U danielk1977
-Z 57e6cb4b6ed478ad88e2ade57e93f2ba
+P 1e3b8308021107d983d2152663f62b369cca091d
+R 5972f13e602e13f1fa109add837cf301
+U drh
+Z 6e75d867f7857f56f8d906b33d9926f0
diff --git a/manifest.uuid b/manifest.uuid
index 4d972150b6..b2d89f7a25 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-1e3b8308021107d983d2152663f62b369cca091d
\ No newline at end of file
+e1de2287fd9b067f687cb8b427786b878af6c5b7
\ No newline at end of file
diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 0e2793fb4c..38c78076ac 100644
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -30,7 +30,7 @@
 ** the version number) and changes its name to "sqlite3.h" as
 ** part of the build process.
 **
-** @(#) $Id: sqlite.h.in,v 1.358 2008/06/26 02:53:02 drh Exp $
+** @(#) $Id: sqlite.h.in,v 1.359 2008/06/26 15:04:58 drh Exp $
 */
 #ifndef _SQLITE3_H_
 #define _SQLITE3_H_
@@ -5445,26 +5445,44 @@ typedef struct sqlite3_blob sqlite3_blob;
 ** This function sets the [database connection] error code and message
 ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
 **
+** If the row that a BLOB handle points to is modified by an
+** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
+** then the BLOB handle is marked as "expired".
+** This is true if any column of the row is changed, even a column
+** other than the one the BLOB handle is open on.
+** Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
+** a expired BLOB handle fail with an return code of [SQLITE_ABORT].
+** Changes written into a BLOB prior to the BLOB expiring are not
+** rollback by the expiration of the BLOB.  Such changes will eventually
+** commit if the transaction continues to completion.
+**
 ** INVARIANTS:
 **
 ** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)]
-**          interface opens an [sqlite3_blob] object P on the BLOB in column C
-**          of the table T in the database B on the [database connection] D.
+**          interface shall open an [sqlite3_blob] object P on the BLOB
+**          in column C of the table T in the database B on
+**          the [database connection] D.
 **
-** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] starts
+** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] shall start
 **          a new transaction on the [database connection] D if that
 **          connection is not already in a transaction.
 **
-** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface opens the BLOB for
-**          read and write access if and only if the F parameter is non-zero.
+** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface shall open
+**          the BLOB for read and write access if and only if the F
+**          parameter is non-zero.
 **
-** {F17819} The [sqlite3_blob_open()] interface returns [SQLITE_OK] on
+** {F17819} The [sqlite3_blob_open()] interface shall return [SQLITE_OK] on
 **          success and an appropriate [error code] on failure.
 **
 ** {F17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)]
 **          then subsequent calls to [sqlite3_errcode(D)],
-**          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
+**          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
 **          information appropriate for that error.
+**
+** {F17824} If any column in the row that a [sqlite3_blob] has open is
+**          changed by a separate [UPDATE] or [DELETE] statement or by
+**          an [ON CONFLICT] side effect, then the [sqlite3_blob] shall
+**          be marked as invalid.
 */
 int sqlite3_blob_open(
   sqlite3*,
@@ -5506,7 +5524,7 @@ int sqlite3_blob_open(
 **          or [prepared statements] on the same [database connection] and
 **          the database connection is in [autocommit mode].
 **
-** {F17839} The [sqlite3_blob_close(P)] interfaces closes the
+** {F17839} The [sqlite3_blob_close(P)] interfaces shall close the
 **          [sqlite3_blob] object P unconditionally, even if
 **          [sqlite3_blob_close(P)] returns something other than [SQLITE_OK].
 */
@@ -5537,33 +5555,41 @@ int sqlite3_blob_bytes(sqlite3_blob *);
 ** [SQLITE_ERROR] is returned and no data is read.  If N or iOffset is
 ** less than zero, [SQLITE_ERROR] is returned and no data is read.
 **
+** An attempt to read from an expired [BLOB handle] fails with an
+** error code of [SQLITE_ABORT].
+**
 ** On success, SQLITE_OK is returned.
 ** Otherwise, an [error code] or an [extended error code] is returned.
 **
 ** INVARIANTS:
 **
-** {F17853} The [sqlite3_blob_read(P,Z,N,X)] interface reads N bytes beginning
-**          at offset X from the BLOB that [sqlite3_blob] object P refers to
-**          and writes those N bytes into buffer Z.
+** {F17853} A successful invocation of [sqlite3_blob_read(P,Z,N,X)] 
+**          shall reads N bytes of data out of the BLOB referenced by
+**          [BLOB handle] P beginning at offset X and store those bytes
+**          into buffer Z.
 **
 ** {F17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the BLOB
-**          is less than N+X bytes, then the function returns [SQLITE_ERROR]
-**          and nothing is read from the BLOB.
+**          is less than N+X bytes, then the function shall leave the
+**          Z buffer unchanged and return [SQLITE_ERROR].
 **
 ** {F17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero
-**          then the function returns [SQLITE_ERROR]
-**          and nothing is read from the BLOB.
+**          then the function shall leave the Z buffer unchanged
+**          and return [SQLITE_ERROR].
 **
-** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface returns [SQLITE_OK]
-**          if N bytes where successfully read into buffer Z.
+** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface shall return [SQLITE_OK]
+**          if N bytes are successfully read into buffer Z.
+**
+** {F17863} If the [BLOB handle] P is expired and X and N are within bounds
+**          then [sqlite3_blob_read(P,Z,N,X)] shall leave the Z buffer
+**          unchanged and return [SQLITE_ABORT].
 **
 ** {F17865} If the requested read could not be completed,
-**          the [sqlite3_blob_read(P,Z,N,X)] interface returns an
+**          the [sqlite3_blob_read(P,Z,N,X)] interface shall return an
 **          appropriate [error code] or [extended error code].
 **
 ** {F17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)]
 **          then subsequent calls to [sqlite3_errcode(D)],
-**          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
+**          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
 **          information appropriate for that error, where D is the
 **          [database connection] that was used to open the [BLOB handle] P.
 */
@@ -5586,37 +5612,53 @@ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
 ** [SQLITE_ERROR] is returned and no data is written.  If N is
 ** less than zero [SQLITE_ERROR] is returned and no data is written.
 **
+** An attempt to write to an expired [BLOB handle] fails with an
+** error code of [SQLITE_ABORT].  Writes to the BLOB that occurred
+** before the [BLOB handle] expired are not rolled back by the
+** expiration of the handle, though of course those changes might
+** have been overwritten by the statement that expired the BLOB handle
+** or by other independent statements.
+**
 ** On success, SQLITE_OK is returned.
 ** Otherwise, an  [error code] or an [extended error code] is returned.
 **
 ** INVARIANTS:
 **
-** {F17873} The [sqlite3_blob_write(P,Z,N,X)] interface writes N bytes
-**          from buffer Z into the BLOB that [sqlite3_blob] object P
-**          refers to beginning at an offset of X into the BLOB.
+** {F17873} A successful invocation of [sqlite3_blob_write(P,Z,N,X)]
+**          shall write N bytes of data from buffer Z into the BLOB 
+**          referenced by [BLOB handle] P beginning at offset X into
+**          the BLOB.
+**
+** {F17874} In the absence of other overridding changes, the changes
+**          written to a BLOB by [sqlite3_blob_write()] shall
+**          remain in effect after the associated [BLOB handle] expires.
+**
+** {F17875} If the [BLOB handle] P was opened for reading only then
+**          an invocation of [sqlite3_blob_write(P,Z,N,X)] shall leave
+**          the referenced BLOB unchanged and return [SQLITE_READONLY].
 **
-** {F17875} The [sqlite3_blob_write(P,Z,N,X)] interface returns
-**          [SQLITE_READONLY] if the [sqlite3_blob] object P was
-**          [sqlite3_blob_open | opened] for reading only.
+** {F17876} If the size of the BLOB referenced by [BLOB handle] P is
+**          less than N+X bytes then [sqlite3_blob_write(P,Z,N,X)] shall
+**          leave the BLOB unchanged and return [SQLITE_ERROR].
 **
-** {F17876} In [sqlite3_blob_write(P,Z,N,X)] if the size of the BLOB
-**          is less than N+X bytes, then the function returns [SQLITE_ERROR]
-**          and nothing is written into the BLOB.
+** {F17877} If the [BLOB handle] P is expired and X and N are within bounds
+**          then [sqlite3_blob_read(P,Z,N,X)] shall leave the BLOB
+**          unchanged and return [SQLITE_ABORT].
 **
-** {F17879} In [sqlite3_blob_write(P,Z,N,X)] if X or N is less than zero
-**          then the function returns [SQLITE_ERROR]
-**          and nothing is written into the BLOB.
+** {F17879} If X or N are less than zero then [sqlite3_blob_write(P,Z,N,X)]
+**          shall leave the BLOB referenced by [BLOB handle] P unchanged
+**          and return [SQLITE_ERROR].
 **
-** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface returns [SQLITE_OK]
-**          if N bytes where successfully written into the BLOB.
+** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface shall return
+**          [SQLITE_OK] if N bytes where successfully written into the BLOB.
 **
 ** {F17885} If the requested write could not be completed,
-**          the [sqlite3_blob_write(P,Z,N,X)] interface returns an
+**          the [sqlite3_blob_write(P,Z,N,X)] interface shall return an
 **          appropriate [error code] or [extended error code].
 **
 ** {F17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)]
 **          then subsequent calls to [sqlite3_errcode(D)],
-**          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
+**          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
 **          information appropriate for that error.
 */
 int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);