From: dan Date: Wed, 21 Feb 2024 19:17:45 +0000 (+0000) Subject: Add documentation to ext/intck/sqlite3intck.h. X-Git-Tag: version-3.46.0~193^2~9 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=b783f56c587304d57702580ec8aff11d8d67641f;p=thirdparty%2Fsqlite.git 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 f00a465b3c..cea1a247a3 100644 --- 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 f23dbbd1d7..d00b5ef529 100644 --- 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 e39825fc7e..e08a86f289 100644 --- 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 0e2aebf056..4c34e2fd26 100644 --- 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 43263453a2..32648946aa 100644 --- 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 1a133ba48f..12f0b62ab8 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -11d6816c060b6edb9cd61f29297ab95e75e2b46f29c0a796820d94fc13586f6d \ No newline at end of file +4cc19bd74f05fe92658cc392a1d1afa173d93181a77303af6bc5684436ae832e \ No newline at end of file