| 1 |
/* |
| 2 |
** 2024-02-08 |
| 3 |
** |
| 4 |
** The author disclaims copyright to this source code. In place of |
| 5 |
** a legal notice, here is a blessing: |
| 6 |
** |
| 7 |
** May you do good and not evil. |
| 8 |
** May you find forgiveness for yourself and forgive others. |
| 9 |
** May you share freely, never taking more than you give. |
| 10 |
** |
| 11 |
************************************************************************* |
| 12 |
*/ |
| 13 |
|
| 14 |
/* |
| 15 |
** Incremental Integrity-Check Extension |
| 16 |
** ------------------------------------- |
| 17 |
** |
| 18 |
** This module contains code to check whether or not an SQLite database |
| 19 |
** is well-formed or corrupt. This is the same task as performed by SQLite's |
| 20 |
** built-in "PRAGMA integrity_check" command. This module differs from |
| 21 |
** "PRAGMA integrity_check" in that: |
| 22 |
** |
| 23 |
** + It is less thorough - this module does not detect certain types |
| 24 |
** of corruption that are detected by the PRAGMA command. However, |
| 25 |
** it does detect all kinds of corruption that are likely to cause |
| 26 |
** errors in SQLite applications. |
| 27 |
** |
| 28 |
** + It is slower. Sometimes up to three times slower. |
| 29 |
** |
| 30 |
** + It allows integrity-check operations to be split into multiple |
| 31 |
** transactions, so that the database does not need to be read-locked |
| 32 |
** for the duration of the integrity-check. |
| 33 |
** |
| 34 |
** One way to use the API to run integrity-check on the "main" database |
| 35 |
** of handle db is: |
| 36 |
** |
| 37 |
** int rc = SQLITE_OK; |
| 38 |
** sqlite3_intck *p = 0; |
| 39 |
** |
| 40 |
** sqlite3_intck_open(db, "main", &p); |
| 41 |
** while( SQLITE_OK==sqlite3_intck_step(p) ){ |
| 42 |
** const char *zMsg = sqlite3_intck_message(p); |
| 43 |
** if( zMsg ) printf("corruption: %s\n", zMsg); |
| 44 |
** } |
| 45 |
** rc = sqlite3_intck_error(p, &zErr); |
| 46 |
** if( rc!=SQLITE_OK ){ |
| 47 |
** printf("error occured (rc=%d), (errmsg=%s)\n", rc, zErr); |
| 48 |
** } |
| 49 |
** sqlite3_intck_close(p); |
| 50 |
** |
| 51 |
** Usually, the sqlite3_intck object opens a read transaction within the |
| 52 |
** first call to sqlite3_intck_step() and holds it open until the |
| 53 |
** integrity-check is complete. However, if sqlite3_intck_unlock() is |
| 54 |
** called, the read transaction is ended and a new read transaction opened |
| 55 |
** by the subsequent call to sqlite3_intck_step(). |
| 56 |
*/ |
| 57 |
|
| 58 |
#ifndef _SQLITE_INTCK_H |
| 59 |
#define _SQLITE_INTCK_H |
| 60 |
|
| 61 |
#include "sqlite3.h" |
| 62 |
|
| 63 |
#ifdef __cplusplus |
| 64 |
extern "C" { |
| 65 |
#endif |
| 66 |
|
| 67 |
/* |
| 68 |
** An ongoing incremental integrity-check operation is represented by an |
| 69 |
** opaque pointer of the following type. |
| 70 |
*/ |
| 71 |
typedef struct sqlite3_intck sqlite3_intck; |
| 72 |
|
| 73 |
/* |
| 74 |
** Open a new incremental integrity-check object. If successful, populate |
| 75 |
** output variable (*ppOut) with the new object handle and return SQLITE_OK. |
| 76 |
** Or, if an error occurs, set (*ppOut) to NULL and return an SQLite error |
| 77 |
** code (e.g. SQLITE_NOMEM). |
| 78 |
** |
| 79 |
** The integrity-check will be conducted on database zDb (which must be "main", |
| 80 |
** "temp", or the name of an attached database) of database handle db. Once |
| 81 |
** this function has been called successfully, the caller should not use |
| 82 |
** database handle db until the integrity-check object has been destroyed |
| 83 |
** using sqlite3_intck_close(). |
| 84 |
*/ |
| 85 |
int sqlite3_intck_open( |
| 86 |
sqlite3 *db, /* Database handle */ |
| 87 |
const char *zDb, /* Database name ("main", "temp" etc.) */ |
| 88 |
sqlite3_intck **ppOut /* OUT: New sqlite3_intck handle */ |
| 89 |
); |
| 90 |
|
| 91 |
/* |
| 92 |
** Close and release all resources associated with a handle opened by an |
| 93 |
** earlier call to sqlite3_intck_open(). The results of using an |
| 94 |
** integrity-check handle after it has been passed to this function are |
| 95 |
** undefined. |
| 96 |
*/ |
| 97 |
void sqlite3_intck_close(sqlite3_intck *pCk); |
| 98 |
|
| 99 |
/* |
| 100 |
** Do the next step of the integrity-check operation specified by the handle |
| 101 |
** passed as the only argument. This function returns SQLITE_DONE if the |
| 102 |
** integrity-check operation is finished, or an SQLite error code if |
| 103 |
** an error occurs, or SQLITE_OK if no error occurs but the integrity-check |
| 104 |
** is not finished. It is not considered an error if database corruption |
| 105 |
** is encountered. |
| 106 |
** |
| 107 |
** Following a successful call to sqlite3_intck_step() (one that returns |
| 108 |
** SQLITE_OK), sqlite3_intck_message() returns a non-NULL value if |
| 109 |
** corruption was detected in the db. |
| 110 |
** |
| 111 |
** If an error occurs and a value other than SQLITE_OK or SQLITE_DONE is |
| 112 |
** returned, then the integrity-check handle is placed in an error state. |
| 113 |
** In this state all subsequent calls to sqlite3_intck_step() or |
| 114 |
** sqlite3_intck_unlock() will immediately return the same error. The |
| 115 |
** sqlite3_intck_error() method may be used to obtain an English language |
| 116 |
** error message in this case. |
| 117 |
*/ |
| 118 |
int sqlite3_intck_step(sqlite3_intck *pCk); |
| 119 |
|
| 120 |
/* |
| 121 |
** If the previous call to sqlite3_intck_step() encountered corruption |
| 122 |
** within the database, then this function returns a pointer to a buffer |
| 123 |
** containing a nul-terminated string describing the corruption in |
| 124 |
** English. If the previous call to sqlite3_intck_step() did not encounter |
| 125 |
** corruption, or if there was no previous call, this function returns |
| 126 |
** NULL. |
| 127 |
*/ |
| 128 |
const char *sqlite3_intck_message(sqlite3_intck *pCk); |
| 129 |
|
| 130 |
/* |
| 131 |
** Close any read-transaction opened by an earlier call to |
| 132 |
** sqlite3_intck_step(). Any subsequent call to sqlite3_intck_step() will |
| 133 |
** open a new transaction. Return SQLITE_OK if successful, or an SQLite error |
| 134 |
** code otherwise. |
| 135 |
** |
| 136 |
** If an error occurs, then the integrity-check handle is placed in an error |
| 137 |
** state. In this state all subsequent calls to sqlite3_intck_step() or |
| 138 |
** sqlite3_intck_unlock() will immediately return the same error. The |
| 139 |
** sqlite3_intck_error() method may be used to obtain an English language |
| 140 |
** error message in this case. |
| 141 |
*/ |
| 142 |
int sqlite3_intck_unlock(sqlite3_intck *pCk); |
| 143 |
|
| 144 |
/* |
| 145 |
** If an error has occurred in an earlier call to sqlite3_intck_step() |
| 146 |
** or sqlite3_intck_unlock(), then this method returns the associated |
| 147 |
** SQLite error code. Additionally, if pzErr is not NULL, then (*pzErr) |
| 148 |
** may be set to point to a nul-terminated string containing an English |
| 149 |
** language error message. Or, if no error message is available, to |
| 150 |
** NULL. |
| 151 |
** |
| 152 |
** If no error has occurred within sqlite3_intck_step() or |
| 153 |
** sqlite_intck_unlock() calls on the handle passed as the first argument, |
| 154 |
** then SQLITE_OK is returned and (*pzErr) set to NULL. |
| 155 |
*/ |
| 156 |
int sqlite3_intck_error(sqlite3_intck *pCk, const char **pzErr); |
| 157 |
|
| 158 |
/* |
| 159 |
** This API is used for testing only. It returns the full-text of an SQL |
| 160 |
** statement used to test object zObj, which may be a table or index. |
| 161 |
** The returned buffer is valid until the next call to either this function |
| 162 |
** or sqlite3_intck_close() on the same sqlite3_intck handle. |
| 163 |
*/ |
| 164 |
const char *sqlite3_intck_test_sql(sqlite3_intck *pCk, const char *zObj); |
| 165 |
|
| 166 |
|
| 167 |
#ifdef __cplusplus |
| 168 |
} /* end of the 'extern "C"' block */ |
| 169 |
#endif |
| 170 |
|
| 171 |
#endif /* ifndef _SQLITE_INTCK_H */ |