Add documentation to ext/intck/sqlite3intck.h.

FossilOrigin-Name: 4cc19bd74f05fe92658cc392a1d1afa173d93181a77303af6bc5684436ae832e
This commit is contained in:
dan
2024-02-21 19:17:45 +00:00
parent b2897c221d
commit b783f56c58
6 changed files with 140 additions and 24 deletions
+1 -1
View File
@@ -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]
+3 -3
View File
@@ -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;
+123 -6
View File
@@ -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
+3 -4
View File
@@ -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 ){
+9 -9
View File
@@ -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.
+1 -1
View File
@@ -1 +1 @@
11d6816c060b6edb9cd61f29297ab95e75e2b46f29c0a796820d94fc13586f6d
4cc19bd74f05fe92658cc392a1d1afa173d93181a77303af6bc5684436ae832e