Add documentation to ext/intck/sqlite3intck.h.

FossilOrigin-Name: 4cc19bd74f05fe92658cc392a1d1afa173d93181a77303af6bc5684436ae832e

diff --git a/ext/intck/intck_common.tcl b/ext/intck/intck_common.tcl
index f00a465b3c8cb7559daa7d35e76ff85f1fe7b137..cea1a247a38c15ba5e437ba1e5912c3b62edef3c 100644 (file)
--- a/ext/intck/intck_common.tcl
+++ b/ext/intck/intck_common.tcl
@@ -24,7 +24,7 @@ proc do_intck {db {bSuspend 0}} {
     if {$msg!=""} {
       lappend ret $msg
     }
-    if {$bSuspend} { $ic suspend }
+    if {$bSuspend} { $ic unlock }
   }
 
   set err [$ic error]

diff --git a/ext/intck/sqlite3intck.c b/ext/intck/sqlite3intck.c
index f23dbbd1d7f484c965f87aec790906503db2f6a0..d00b5ef529900118f729f183fc649a9566476cd8 100644 (file)
--- a/ext/intck/sqlite3intck.c
+++ b/ext/intck/sqlite3intck.c
@@ -18,7 +18,7 @@
 
 /*
 ** apKeyVal:
-**   If sqlite3_intck_suspend() is called when there is a running pCheck
+**   If sqlite3_intck_unlock() is called when there is a running pCheck
 **   statement, this array is allocated and populated with the key values 
 **   required to restart the check. If the intck object has not been
 **   suspended, this is set to NULL.
@@ -845,7 +845,7 @@ const char *sqlite3_intck_message(sqlite3_intck *p){
 }
 
 int sqlite3_intck_error(sqlite3_intck *p, const char **pzErr){
-  *pzErr = p->zErr;
+  if( pzErr ) *pzErr = p->zErr;
   return (p->rc==SQLITE_DONE ? SQLITE_OK : p->rc);
 }
 
@@ -861,7 +861,7 @@ static sqlite3_value *intckValueDup(sqlite3_intck *p, sqlite3_value *pIn){
   return pRet;
 }
 
-int sqlite3_intck_suspend(sqlite3_intck *p){
+int sqlite3_intck_unlock(sqlite3_intck *p){
   if( p->pCheck && p->rc==SQLITE_OK ){
     const int nByte = sizeof(sqlite3_value*) * p->nKeyVal;
     int ii;

diff --git a/ext/intck/sqlite3intck.h b/ext/intck/sqlite3intck.h
index e39825fc7ea2836913264767578182962b7596f7..e08a86f289e3fab83f9e3ab97b17ffc1305b1222 100644 (file)
--- a/ext/intck/sqlite3intck.h
+++ b/ext/intck/sqlite3intck.h
@@ -11,6 +11,50 @@
 *************************************************************************
 */
 
+/*
+** Incremental Integrity-Check Extension
+** -------------------------------------
+**
+** This module contains code to check whether or not an SQLite database
+** is well-formed or corrupt. This is the same task as performed by SQLite's
+** built-in "PRAGMA integrity_check" command. This module differs from
+** "PRAGMA integrity_check" in that:
+**
+**   +  It is less thorough - this module does not detect certain types
+**      of corruption that are detected by the PRAGMA command. However,
+**      it does detect all kinds of corruption that are likely to cause
+**      errors in SQLite applications.
+**
+**   +  It is slower. Sometimes up to three times slower.
+**
+**   +  It allows integrity-check operations to be split into multiple
+**      transactions, so that the database does not need to be read-locked
+**      for the duration of the integrity-check.
+**
+** One way to use the API to run integrity-check on the "main" database
+** of handle db is:
+**
+**   int rc = SQLITE_OK;
+**   sqlite3_intck *p = 0;
+**
+**   sqlite3_intck_open(db, "main", &p);
+**   while( SQLITE_OK==sqlite3_intck_step(p) ){
+**     const char *zMsg = sqlite3_intck_message(p);
+**     if( zMsg ) printf("corruption: %s\n", zMsg);
+**   }
+**   rc = sqlite3_intck_error(p, &zErr);
+**   if( rc!=SQLITE_OK ){
+**     printf("error occured (rc=%d), (errmsg=%s)\n", rc, zErr);
+**   }
+**   sqlite3_intck_close(p);
+**
+** Usually, the sqlite3_intck object opens a read transaction within the
+** first call to sqlite3_intck_step() and holds it open until the 
+** integrity-check is complete. However, if sqlite3_intck_unlock() is
+** called, the read transaction is ended and a new read transaction opened
+** by the subsequent call to sqlite3_intck_step().
+*/
+
 #ifndef _SQLITE_INTCK_H
 #define _SQLITE_INTCK_H
 
@@ -20,23 +64,96 @@
 extern "C" {
 #endif
 
+/*
+** An ongoing incremental integrity-check operation is represented by an
+** opaque pointer of the following type.
+*/
 typedef struct sqlite3_intck sqlite3_intck;
 
+/*
+** Open a new incremental integrity-check object. If successful, populate
+** output variable (*ppOut) with the new object handle and return SQLITE_OK.
+** Or, if an error occurs, set (*ppOut) to NULL and return an SQLite error
+** code (e.g. SQLITE_NOMEM).
+**
+** The integrity-check will be conducted on database zDb (which must be "main",
+** "temp", or the name of an attached database) of database handle db. Once
+** this function has been called successfully, the caller should not use 
+** database handle db until the integrity-check object has been destroyed
+** using sqlite3_intck_close().
+*/
 int sqlite3_intck_open(
-  sqlite3 *db, 
-  const char *zDb, 
-  sqlite3_intck **ppOut
+  sqlite3 *db,                    /* Database handle */
+  const char *zDb,                /* Database name ("main", "temp" etc.) */
+  sqlite3_intck **ppOut           /* OUT: New sqlite3_intck handle */
 );
 
-void sqlite3_intck_close(sqlite3_intck*);
+/*
+** Close and release all resources associated with a handle opened by an
+** earlier call to sqlite3_intck_open(). The results of using an
+** integrity-check handle after it has been passed to this function are
+** undefined.
+*/
+void sqlite3_intck_close(sqlite3_intck *pCk);
 
+/*
+** Do the next step of the integrity-check operation specified by the handle
+** passed as the only argument. This function returns SQLITE_DONE if the 
+** integrity-check operation is finished, or an SQLite error code if
+** an error occurs, or SQLITE_OK if no error occurs but the integrity-check
+** is not finished. It is not considered an error if database corruption
+** is encountered.
+**
+** Following a successful call to sqlite3_intck_step() (one that returns
+** SQLITE_OK), sqlite3_intck_message() returns a non-NULL value if 
+** corruption was detected in the db.
+**
+** If an error occurs and a value other than SQLITE_OK or SQLITE_DONE is
+** returned, then the integrity-check handle is placed in an error state.
+** In this state all subsequent calls to sqlite3_intck_step() or 
+** sqlite3_intck_unlock() will immediately return the same error. The 
+** sqlite3_intck_error() method may be used to obtain an English language 
+** error message in this case.
+*/
 int sqlite3_intck_step(sqlite3_intck *pCk);
 
+/*
+** If the previous call to sqlite3_intck_step() encountered corruption 
+** within the database, then this function returns a pointer to a buffer
+** containing a nul-terminated string describing the corruption in 
+** English. If the previous call to sqlite3_intck_step() did not encounter
+** corruption, or if there was no previous call, this function returns 
+** NULL.
+*/
 const char *sqlite3_intck_message(sqlite3_intck *pCk);
 
-int sqlite3_intck_error(sqlite3_intck *pCk, const char **pzErr);
+/*
+** Close any read-transaction opened by an earlier call to 
+** sqlite3_intck_step(). Any subsequent call to sqlite3_intck_step() will
+** open a new transaction. Return SQLITE_OK if successful, or an SQLite error
+** code otherwise.
+**
+** If an error occurs, then the integrity-check handle is placed in an error
+** state. In this state all subsequent calls to sqlite3_intck_step() or 
+** sqlite3_intck_unlock() will immediately return the same error. The 
+** sqlite3_intck_error() method may be used to obtain an English language 
+** error message in this case.
+*/
+int sqlite3_intck_unlock(sqlite3_intck *pCk);
 
-int sqlite3_intck_suspend(sqlite3_intck *pCk);
+/*
+** If an error has occurred in an earlier call to sqlite3_intck_step()
+** or sqlite3_intck_unlock(), then this method returns the associated 
+** SQLite error code. Additionally, if pzErr is not NULL, then (*pzErr)
+** may be set to point to a nul-terminated string containing an English
+** language error message. Or, if no error message is available, to
+** NULL.
+**
+** If no error has occurred within sqlite3_intck_step() or
+** sqlite_intck_unlock() calls on the handle passed as the first argument, 
+** then SQLITE_OK is returned and (*pzErr) set to NULL.
+*/
+int sqlite3_intck_error(sqlite3_intck *pCk, const char **pzErr);
 
 /*
 ** This API is used for testing only. It returns the full-text of an SQL

diff --git a/ext/intck/test_intck.c b/ext/intck/test_intck.c
index 0e2aebf056b490c95f86b594c3cde2f849b0e58d..4c34e2fd262f158204a7bdead8d4a95cfb8da882 100644 (file)
--- a/ext/intck/test_intck.c
+++ b/ext/intck/test_intck.c
@@ -49,7 +49,7 @@ static int testIntckCmd(
     {"step", 0, ""},         /* 1 */
     {"message", 0, ""},      /* 2 */
     {"error", 0, ""},        /* 3 */
-    {"suspend", 0, ""},      /* 4 */
+    {"unlock", 0, ""},      /* 4 */
     {"test_sql", 1, ""},     /* 5 */
     {0 , 0}
   };
@@ -105,8 +105,8 @@ static int testIntckCmd(
       break;
     }
 
-    case 4: assert( 0==strcmp("suspend", aCmd[iIdx].zName) ); {
-      int rc = sqlite3_intck_suspend(p->intck);
+    case 4: assert( 0==strcmp("unlock", aCmd[iIdx].zName) ); {
+      int rc = sqlite3_intck_unlock(p->intck);
       Tcl_SetObjResult(interp, Tcl_NewStringObj(sqlite3ErrName(rc), -1));
       break;
     }
@@ -146,7 +146,6 @@ static int test_sqlite3_intck(
   TestIntck *p = 0;
   sqlite3 *db = 0;
   const char *zDb = 0;
-  const char *zFile = 0;
   int rc = SQLITE_OK;
 
   if( objc!=3 ){

diff --git a/manifest b/manifest
index 43263453a2f98b15117f34022b2f333458a45b70..32648946aa75d430f59a18ccc88555144c0e1d1c 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Ensure\sintck\stests\sare\srun\sby\stestrunner.tcl.
-D 2024-02-21T16:15:50.181
+C Add\sdocumentation\sto\sext/intck/sqlite3intck.h.
+D 2024-02-21T19:17:45.632
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -250,11 +250,11 @@ F ext/icu/icu.c c074519b46baa484bb5396c7e01e051034da8884bad1a1cb7f09bbe6be3f0282
 F ext/icu/sqliteicu.h fa373836ed5a1ee7478bdf8a1650689294e41d0c89c1daab26e9ae78a32075a8
 F ext/intck/intck1.test 15e94ee868e939c6d3aef6884c5652d969b28d3eac940a15585511cf8aec71ad
 F ext/intck/intck2.test b65d7f627342f767e1d2c447d25619666cec36f516786dd56568bd741e5d7e67
-F ext/intck/intck_common.tcl 6e5df126e55d6a0d7e3be9757400d5fb87bd291726d01b72a9fe77a7201967e4
+F ext/intck/intck_common.tcl b8a63ae820dbcdf50ddaba474f130b43c26ba81f4b7720ff1d8b9a6592bdd420
 F ext/intck/intckcorrupt.test 3211ef68ac53e83951b6c8f6a8d2396506d123fe5898f97f848a25837744ec56
-F ext/intck/sqlite3intck.c 0f9674952f84084741eb4e945d7532b02996ba8ea938b060228d7874f15557f9
-F ext/intck/sqlite3intck.h dec4a37584024154ad5734cf6ee98dc484ce25c26af88652a096be402fe51833
-F ext/intck/test_intck.c eb84e825a3a0fd43ae1e4280305280a19c9ef42c2bdef3110b282b115de60463
+F ext/intck/sqlite3intck.c edc93065be0e16394891bb6ad7d279cb54220db65cc66228ac6d6e0bc3919a63
+F ext/intck/sqlite3intck.h 2b40c38e7063ab822c974c0bd4aed97dabb579ccfe2e180a4639bb3bbef0f1c9
+F ext/intck/test_intck.c dec07fc82e2626a1450e58be474e351643627b04ee08ce8fae6495a533b87e85
 F ext/jni/GNUmakefile 59eb05f2a363bdfac8d15d66bed624bfe1ff289229184f3861b95f98a19cf4b2
 F ext/jni/README.md d899789a9082a07b99bf30b1bbb6204ae57c060efcaa634536fa669323918f42
 F ext/jni/jar-dist.make 030aaa4ae71dd86e4ec5e7c1e6cd86f9dfa47c4592c070d2e35157e42498e1fa
@@ -2169,8 +2169,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 63e8846ac1dc1cf1f7071c4634ccbfec3c13560db6afec376cd91515b62430d3
-R f5edb7901b3b1288ef6973d26c0dbe97
+P 11d6816c060b6edb9cd61f29297ab95e75e2b46f29c0a796820d94fc13586f6d
+R f33ba3131334feff25011177f18e259c
 U dan
-Z 5466cb7224bcaecbaa43fd497cf85347
+Z fc231a0a5c69f02b295f0b4d4c9d9f6a
 # Remove this line to create a well-formed Fossil manifest.

diff --git a/manifest.uuid b/manifest.uuid
index 1a133ba48fc146250b18b577dfc578f088ee016f..12f0b62ab84b46c467838b659252600d090aa492 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-11d6816c060b6edb9cd61f29297ab95e75e2b46f29c0a796820d94fc13586f6d
\ No newline at end of file
+4cc19bd74f05fe92658cc392a1d1afa173d93181a77303af6bc5684436ae832e
\ No newline at end of file