From: dan Date: Thu, 8 Sep 2022 21:43:18 +0000 (+0000) Subject: Update comments in sqlite3recover.h. X-Git-Tag: version-3.40.0~91^2~33 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=46d439844043cef65b11e32317d54caf798cc7dd;p=thirdparty%2Fsqlite.git Update comments in sqlite3recover.h. FossilOrigin-Name: 14164047c43e3ca43aa010c77ea00dfa85400e15645ee0f5b90a677898b6a836 --- diff --git a/ext/recover/sqlite3recover.c b/ext/recover/sqlite3recover.c index cef2fb9da7..3e797e4bb3 100644 --- a/ext/recover/sqlite3recover.c +++ b/ext/recover/sqlite3recover.c @@ -1395,7 +1395,7 @@ static void recoverStep(sqlite3_recover *p){ p->pGetPage = 0; } -int sqlite3_recover_step(sqlite3_recover *p){ +int sqlite3_recover_run(sqlite3_recover *p){ if( p && p->errCode==SQLITE_OK ){ recoverStep(p); } diff --git a/ext/recover/sqlite3recover.h b/ext/recover/sqlite3recover.h index 1ef707e13c..ffe016b4f3 100644 --- a/ext/recover/sqlite3recover.h +++ b/ext/recover/sqlite3recover.h @@ -10,6 +10,31 @@ ** ************************************************************************* ** +** This file contains the public interface to the "recover" extension - +** an SQLite extension designed to recover data from corrupted database +** files. +*/ + +/* +** OVERVIEW: +** +** To use the API to recover data from a corrupted database, an +** application: +** +** 1) Creates an sqlite3_recover handle by calling either +** sqlite3_recover_init() or sqlite3_recover_init_sql(). +** +** 2) Configures the new handle using one or more calls to +** sqlite3_recover_config(). +** +** 3) Executes the recovery by calling sqlite3_recover_run() on the handle. +** +** 4) Retrieves any error code and English language error message using the +** sqlite3_recover_errcode() and sqlite3_recover_errmsg() APIs, +** respectively. +** +** 5) Destroys the sqlite3_recover handle and frees all resources +** using sqlite3_recover_finish(). */ @@ -22,20 +47,46 @@ extern "C" { #endif +/* +** Opaque handle type. +*/ typedef struct sqlite3_recover sqlite3_recover; /* -** Create an object to recover data from database zDb (e.g. "main") -** opened by handle db. Data will be recovered into the database -** identified by parameter zUri. Database zUri is clobbered if it -** already exists. +** These two APIs attempt to create and return a new sqlite3_recover object. +** In both cases the first two arguments identify the (possibly +** corrupt) database to recover data from. The first argument is an open +** database handle and the second the name of a database attached to that +** handle (i.e. "main", "temp" or the name of an attached database). +** +** If sqlite3_recover_init() is used to create the new sqlite3_recover +** handle, then data is recovered into a new database, identified by +** string parameter zUri. zUri may be an absolute or relative file path, +** or may be an SQLite URI. If the identified database file already exists, +** it is overwritten. +** +** If sqlite3_recover_init_sql() is invoked, then any recovered data will +** be returned to the user as a series of SQL statements. Executing these +** SQL statements results in the same database as would have been created +** had sqlite3_recover_init() been used. For each SQL statement in the +** output, the callback function passed as the third argument (xSql) is +** invoked once. The first parameter is a passed a copy of the fourth argument +** to this function (pCtx) as its first parameter, and a pointer to a +** nul-terminated buffer containing the SQL statement formated as UTF-8 as +** the second. If the xSql callback returns any value other than SQLITE_OK, +** then processing is immediately abandoned and the value returned used as +** the recover handle error code (see below). +** +** If an out-of-memory error occurs, NULL may be returned instead of +** a valid handle. In all other cases, it is the responsibility of the +** application to avoid resource leaks by ensuring that +** sqlite3_recover_finish() is called on all allocated handles. */ sqlite3_recover *sqlite3_recover_init( sqlite3* db, const char *zDb, const char *zUri ); - sqlite3_recover *sqlite3_recover_init_sql( sqlite3* db, const char *zDb, @@ -43,7 +94,9 @@ sqlite3_recover *sqlite3_recover_init_sql( void *pCtx ); -/* Details TBD. */ +/* +** +*/ int sqlite3_recover_config(sqlite3_recover*, int op, void *pArg); /* @@ -76,21 +129,31 @@ int sqlite3_recover_config(sqlite3_recover*, int op, void *pArg); #define SQLITE_RECOVER_FREELIST_CORRUPT 791 #define SQLITE_RECOVER_ROWIDS 792 -/* Step the recovery object. Return SQLITE_DONE if recovery is complete, -** SQLITE_OK if recovery is not complete but no error has occurred, or -** an SQLite error code if an error has occurred. +/* +** Run the recovery. Return an SQLite error code if an error occurs, or +** SQLITE_OK otherwise. */ -int sqlite3_recover_step(sqlite3_recover*); +int sqlite3_recover_run(sqlite3_recover*); +/* +** Return a pointer to a buffer containing the English language error +** message stored in the sqlite3_recover handle. If no error message +** is available (including in the case where no error has occurred), +** NULL is returned. +*/ const char *sqlite3_recover_errmsg(sqlite3_recover*); +/* +** Return the recover handle error code. SQLITE_OK is returned if no error +** has occurred. +*/ int sqlite3_recover_errcode(sqlite3_recover*); -/* Clean up a recovery object created by a call to sqlite3_recover_init(). -** This function returns SQLITE_DONE if the new database was created, -** SQLITE_OK if it processing was abandoned before it as finished or -** an SQLite error code (e.g. SQLITE_IOERR, SQLITE_NOMEM etc.) if an -** error occurred. */ +/* +** Clean up a recovery object created by a call to sqlite3_recover_init(). +** This function returns SQLITE_OK if no error occurred, or else a copy +** of the recover handle error code. +*/ int sqlite3_recover_finish(sqlite3_recover*); diff --git a/ext/recover/test_recover.c b/ext/recover/test_recover.c index 83166e994c..e7fef42fd7 100644 --- a/ext/recover/test_recover.c +++ b/ext/recover/test_recover.c @@ -146,7 +146,7 @@ static int testRecoverCmd( break; } case 1: assert( sqlite3_stricmp("step", aSub[iSub].zSub)==0 ); { - int res = sqlite3_recover_step(pTest->p); + int res = sqlite3_recover_run(pTest->p); Tcl_SetObjResult(interp, Tcl_NewIntObj(res)); break; } diff --git a/manifest b/manifest index 013ce9cd0f..f0dfaa0cd4 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Update\sthe\sshell\sto\suse\sthe\srecover\sextension\sfor\sthe\s.recover\scommand. -D 2022-09-08T19:22:29.395 +C Update\scomments\sin\ssqlite3recover.h. +D 2022-09-08T21:43:18.230 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724 @@ -392,9 +392,9 @@ F ext/recover/recover_common.tcl 6679af7dffc858e345053a91c9b0a897595b4a13007acef F ext/recover/recoverclobber.test e6537ebf99f57bfff6cca59550b5f4278319b57a89865abb98d755a8fd561d84 F ext/recover/recoverold.test f368a6ae2db12b6017257b332a19ab5df527f4061e43f12f5c85d8e2b236f074 F ext/recover/recoverrowid.test ec4436cd69e6cdacb48dd2963ff6dd9dbd5fe648376de5e7c0c2f4f6cbacb417 -F ext/recover/sqlite3recover.c b44241ca3b0cca2b50cfa7f715f79f4eddbe87d56e3baadd4e7bafe4c5872550 -F ext/recover/sqlite3recover.h 218cd9ba8c5c66c3841ca5014910982dc956cba5274257a0ecefb889db879133 -F ext/recover/test_recover.c 68b095ad396d8b1d9242ea663a4be1ad7585a46b1fc03483e9a692c8a87d2674 +F ext/recover/sqlite3recover.c aaab721cf1ade0703162e95f1d154b811eef962be42a861b59ef015514bc3b65 +F ext/recover/sqlite3recover.h 73648878cea3492427b9a8facebdad0464ed15b161ed1cd70f349a02456e8879 +F ext/recover/test_recover.c b973526785e145e7d9d7920ccde72112025ee5204e22b332db9d86796be73f00 F ext/repair/README.md 92f5e8aae749a4dae14f02eea8e1bb42d4db2b6ce5e83dbcdd6b1446997e0c15 F ext/repair/checkfreelist.c e21f06995ff4efdc1622dcceaea4dcba2caa83ca2f31a1607b98a8509168a996 F ext/repair/checkindex.c 4383e4469c21e5b9ae321d0d63cec53e981af9d7a6564be6374f0eeb93dfc890 @@ -597,7 +597,7 @@ F src/random.c 546d6feb15ec69c1aafe9bb351a277cbb498fd5410e646add673acb805714960 F src/resolve.c efea4e5fbecfd6d0a9071b0be0d952620991673391b6ffaaf4c277b0bb674633 F src/rowset.c ba9515a922af32abe1f7d39406b9d35730ed65efab9443dc5702693b60854c92 F src/select.c ccce37e7fbe71089cf6aec91e7134c9c0c1d4840cff9f02587bbc71240d914a5 -F src/shell.c.in b36581c005ebaa59b1eeb143bd3ad5a4b273bf15380ccac63ac8cdf4f0c4d3c9 +F src/shell.c.in a805e05f3ed90e0236eb4eb5bdec327bf735d12e754b83ac037cbc22e45ecc09 F src/sqlite.h.in b9b7fd73239d94db20332bb6e504688001e5564b655e1318a4427a1caef4b99e F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8 F src/sqlite3ext.h a988810c9b21c0dc36dc7a62735012339dc76fc7ab448fb0792721d30eacb69d @@ -2007,8 +2007,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 356d2209ea5f6b69ce15b62027c63419c2d039e52f01c74a3810a6317abf4fb0 -R 9479c02b6838b39b62d6729211ce276e +P ae832e77084eddd696c80cb926d070a5db9d45dce34156a02522b3140e8f5e8b +R 260b6b87f29011e60d0280e7bdf9107f U dan -Z df9c400431a19b9f6f7750b759f567b5 +Z c0005f6f4d932e314a4bcb73861ec3e0 # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index 8cbff6b606..e003488dbc 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -ae832e77084eddd696c80cb926d070a5db9d45dce34156a02522b3140e8f5e8b \ No newline at end of file +14164047c43e3ca43aa010c77ea00dfa85400e15645ee0f5b90a677898b6a836 \ No newline at end of file diff --git a/src/shell.c.in b/src/shell.c.in index 2a2aa81463..632d9633fd 100644 --- a/src/shell.c.in +++ b/src/shell.c.in @@ -7314,7 +7314,7 @@ static int recoverDatabaseCmd(ShellState *pState, int nArg, char **azArg){ sqlite3_recover_config(p, SQLITE_RECOVER_ROWIDS, (void*)&bRowids); sqlite3_recover_config(p, SQLITE_RECOVER_FREELIST_CORRUPT,(void*)&bFreelist); - sqlite3_recover_step(p); + sqlite3_recover_run(p); if( sqlite3_recover_errcode(p)!=SQLITE_OK ){ const char *zErr = sqlite3_recover_errmsg(p); int errCode = sqlite3_recover_errcode(p);