Debian Codegraph @

ext/intck/sqlite3intck.h

raw
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 */