Updates to sqlite3_finalize() documentation.

FossilOrigin-Name: 8c5994cf8e5ae0c1cb8f655ac83e52e668e75c86

manifest

@@ -1,8 +1,8 @@
 -----BEGIN PGP SIGNED MESSAGE-----
 Hash: SHA1
 
-C Simplify\sthe\stest\sthat\sdetermines\sif\sthe\sname\sof\sa\snew\stable\scollides\swith\na\sprior\sindex\sname.
-D 2010-09-28T20:26:44
+C Updates\sto\ssqlite3_finalize()\sdocumentation.
+D 2010-09-29T01:54:01
 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f
 F Makefile.in c599a15d268b1db2aeadea19df2adc3bf2eb6bee
 F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23
@@ -178,7 +178,7 @@ F src/resolve.c 1c0f32b64f8e3f555fe1f732f9d6f501a7f05706
 F src/rowset.c 69afa95a97c524ba6faf3805e717b5b7ae85a697
 F src/select.c cf3013b1953348c7c6ff9636342e87b9fda68466
 F src/shell.c 8517fc1f9c59ae4007e6cc8b9af91ab231ea2056
-F src/sqlite.h.in 4d59b9292a52d5601a050e29a3508e5c0a2821fa
+F src/sqlite.h.in a5b50e1bc4d4d9a3cc95386747220a839d0c40f7
 F src/sqlite3ext.h 69dfb8116af51b84a029cddb3b35062354270c89
 F src/sqliteInt.h ea31c7867d910c1da9b20adb6614e474011fbae0
 F src/sqliteLimit.h a17dcd3fb775d63b64a43a55c54cb282f9726f44
@@ -231,7 +231,7 @@ F src/vacuum.c 924bd1bcee2dfb05376f79845bd3b4cec7b54b2f
 F src/vdbe.c 69812aabf486a2d6a5b0960ffd9a47d141442735
 F src/vdbe.h 4de0efb4b0fdaaa900cf419b35c458933ef1c6d2
 F src/vdbeInt.h 7f4cf1b2b69bef3a432b1f23dfebef57275436b4
-F src/vdbeapi.c 14040ffad59a9961468a457754d30266e71ebb2d
+F src/vdbeapi.c 03cddfa4f85cadf608c0d28ff6b622b7da432446
 F src/vdbeaux.c de0b06b11a25293e820a49159eca9f1c51a64716
 F src/vdbeblob.c 258a6010ba7a82b72b327fb24c55790655689256
 F src/vdbemem.c 8ff4f80a35d51f3690c191ec44778ef4bf949ac0
@@ -872,14 +872,14 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
 F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224
 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
 F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f
-P 655991ec8a781d67d69fc353853403b9a811acf2
-R 3ebe614f99889b0121e3dcd673c123b6
+P 3f30f00a384d23582f3fe5e68add7fb7d7834926
+R b0980111e3e0b2d0ef05c30ea2a11545
 U drh
-Z c1fbe6db9cf459e94c2fe99b3554c8bf
+Z 077dc8851dd441abeb5ea23f673b000f
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.6 (GNU/Linux)
 
-iD8DBQFMok+HoxKgR168RlERApXZAJ4mdLGLMy3sXIbrGw+WhaboRRTHtQCfX1yP
-5sAeF2PvuF+fHt0Vxh8vt0g=
-=ut/t
+iD8DBQFMopw8oxKgR168RlERAscVAJ9rRCu1ZaOtDkJQt3k0WWkFfgmYaQCfU+t0
+nRPk3cMqqgV9u8P4XFWBmsc=
+=z7xR
 -----END PGP SIGNATURE-----

manifest.uuid

@@ -1 +1 @@
-3f30f00a384d23582f3fe5e68add7fb7d7834926
+8c5994cf8e5ae0c1cb8f655ac83e52e668e75c86

src/sqlite.h.in

@@ -3260,17 +3260,26 @@ sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
 ** CAPI3REF: Destroy A Prepared Statement Object
 **
 ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
-** ^If the statement was executed successfully or not executed at all, then
-** SQLITE_OK is returned. ^If execution of the statement failed then an
-** [error code] or [extended error code] is returned.
+** ^If the most recent evaluation of the statement encountered no errors or
+** or if the statement is never been evaluated, then sqlite3_finalize() returns
+** SQLITE_OK.  ^If the most recent evaluation of statement S failed, then
+** sqlite3_finalize(S) returns the appropriate [error code] or
+** [extended error code].
 **
-** ^This routine can be called at any point during the execution of the
-** [prepared statement].  ^If the virtual machine has not
-** completed execution when this routine is called, that is like
-** encountering an error or an [sqlite3_interrupt | interrupt].
-** ^Incomplete updates may be rolled back and transactions canceled,
-** depending on the circumstances, and the
-** [error code] returned will be [SQLITE_ABORT].
+** ^The sqlite3_finalize(S) routine can be called at any point during
+** the life cycle of [prepared statement] S:
+** before statement S is ever evaluated, after
+** one or more calls to [sqlite3_reset()], or after any call
+** to [sqlite3_step()] regardless of whether or not the statement has
+** completed execution.
+**
+** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
+**
+** The application must finalize every [prepared statement] in order to avoid
+** resource leaks.  It is a grievous error for the application to try to use
+** a prepared statement after it has been finalized.  Any use of a prepared
+** statement after it has been finalized can result in undefined and
+** undesirable behavior such as segfaults and heap corruption.
 */
 int sqlite3_finalize(sqlite3_stmt *pStmt);
 

src/vdbeapi.c

@@ -65,6 +65,8 @@ static int vdbeSafetyNotNull(Vdbe *p){
 int sqlite3_finalize(sqlite3_stmt *pStmt){
   int rc;
   if( pStmt==0 ){
+    /* IMPLEMENTATION-OF: R-57228-12904 Invoking sqlite3_finalize() on a NULL
+    ** pointer is a harmless no-op. */
     rc = SQLITE_OK;
   }else{
     Vdbe *v = (Vdbe*)pStmt;