1 /* 2 ** 2001 September 15 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 ** This header file defines the interface that the sqlite B-Tree file 13 ** subsystem. See comments in the source code for a detailed description 14 ** of what each interface routine does. 15 */ 16 #ifndef SQLITE_BTREE_H 17 #define SQLITE_BTREE_H 18 19 /* TODO: This definition is just included so other modules compile. It 20 ** needs to be revisited. 21 */ 22 #define SQLITE_N_BTREE_META 16 23 24 /* 25 ** If defined as non-zero, auto-vacuum is enabled by default. Otherwise 26 ** it must be turned on for each database using "PRAGMA auto_vacuum = 1". 27 */ 28 #ifndef SQLITE_DEFAULT_AUTOVACUUM 29 #define SQLITE_DEFAULT_AUTOVACUUM 0 30 #endif 31 32 #define BTREE_AUTOVACUUM_NONE 0 /* Do not do auto-vacuum */ 33 #define BTREE_AUTOVACUUM_FULL 1 /* Do full auto-vacuum */ 34 #define BTREE_AUTOVACUUM_INCR 2 /* Incremental vacuum */ 35 36 /* 37 ** Forward declarations of structure 38 */ 39 typedef struct Btree Btree; 40 typedef struct BtCursor BtCursor; 41 typedef struct BtShared BtShared; 42 typedef struct BtreePayload BtreePayload; 43 44 45 int sqlite3BtreeOpen( 46 sqlite3_vfs *pVfs, /* VFS to use with this b-tree */ 47 const char *zFilename, /* Name of database file to open */ 48 sqlite3 *db, /* Associated database connection */ 49 Btree **ppBtree, /* Return open Btree* here */ 50 int flags, /* Flags */ 51 int vfsFlags /* Flags passed through to VFS open */ 52 ); 53 54 /* The flags parameter to sqlite3BtreeOpen can be the bitwise or of the 55 ** following values. 56 ** 57 ** NOTE: These values must match the corresponding PAGER_ values in 58 ** pager.h. 59 */ 60 #define BTREE_OMIT_JOURNAL 1 /* Do not create or use a rollback journal */ 61 #define BTREE_MEMORY 2 /* This is an in-memory DB */ 62 #define BTREE_SINGLE 4 /* The file contains at most 1 b-tree */ 63 #define BTREE_UNORDERED 8 /* Use of a hash implementation is OK */ 64 65 int sqlite3BtreeClose(Btree*); 66 int sqlite3BtreeSetCacheSize(Btree*,int); 67 int sqlite3BtreeSetSpillSize(Btree*,int); 68 #if SQLITE_MAX_MMAP_SIZE>0 69 int sqlite3BtreeSetMmapLimit(Btree*,sqlite3_int64); 70 #endif 71 int sqlite3BtreeSetPagerFlags(Btree*,unsigned); 72 int sqlite3BtreeSetPageSize(Btree *p, int nPagesize, int nReserve, int eFix); 73 int sqlite3BtreeGetPageSize(Btree*); 74 Pgno sqlite3BtreeMaxPageCount(Btree*,Pgno); 75 Pgno sqlite3BtreeLastPage(Btree*); 76 int sqlite3BtreeSecureDelete(Btree*,int); 77 int sqlite3BtreeGetRequestedReserve(Btree*); 78 int sqlite3BtreeGetReserveNoMutex(Btree *p); 79 int sqlite3BtreeSetAutoVacuum(Btree *, int); 80 int sqlite3BtreeGetAutoVacuum(Btree *); 81 int sqlite3BtreeBeginTrans(Btree*,int,int*); 82 int sqlite3BtreeCommitPhaseOne(Btree*, const char*); 83 int sqlite3BtreeCommitPhaseTwo(Btree*, int); 84 int sqlite3BtreeCommit(Btree*); 85 int sqlite3BtreeRollback(Btree*,int,int); 86 int sqlite3BtreeBeginStmt(Btree*,int); 87 int sqlite3BtreeCreateTable(Btree*, Pgno*, int flags); 88 int sqlite3BtreeTxnState(Btree*); 89 int sqlite3BtreeIsInBackup(Btree*); 90 91 void *sqlite3BtreeSchema(Btree *, int, void(*)(void *)); 92 int sqlite3BtreeSchemaLocked(Btree *pBtree); 93 #ifndef SQLITE_OMIT_SHARED_CACHE 94 int sqlite3BtreeLockTable(Btree *pBtree, int iTab, u8 isWriteLock); 95 #endif 96 97 /* Savepoints are named, nestable SQL transactions mostly implemented */ 98 /* in vdbe.c and pager.c See https://sqlite.org/lang_savepoint.html */ 99 int sqlite3BtreeSavepoint(Btree *, int, int); 100 101 /* "Checkpoint" only refers to WAL. See https://sqlite.org/wal.html#ckpt */ 102 #ifndef SQLITE_OMIT_WAL 103 int sqlite3BtreeCheckpoint(Btree*, int, int *, int *); 104 #endif 105 106 const char *sqlite3BtreeGetFilename(Btree *); 107 const char *sqlite3BtreeGetJournalname(Btree *); 108 int sqlite3BtreeCopyFile(Btree *, Btree *); 109 110 int sqlite3BtreeIncrVacuum(Btree *); 111 112 /* The flags parameter to sqlite3BtreeCreateTable can be the bitwise OR 113 ** of the flags shown below. 114 ** 115 ** Every SQLite table must have either BTREE_INTKEY or BTREE_BLOBKEY set. 116 ** With BTREE_INTKEY, the table key is a 64-bit integer and arbitrary data 117 ** is stored in the leaves. (BTREE_INTKEY is used for SQL tables.) With 118 ** BTREE_BLOBKEY, the key is an arbitrary BLOB and no content is stored 119 ** anywhere - the key is the content. (BTREE_BLOBKEY is used for SQL 120 ** indices.) 121 */ 122 #define BTREE_INTKEY 1 /* Table has only 64-bit signed integer keys */ 123 #define BTREE_BLOBKEY 2 /* Table has keys only - no data */ 124 125 int sqlite3BtreeDropTable(Btree*, int, int*); 126 int sqlite3BtreeClearTable(Btree*, int, int*); 127 int sqlite3BtreeClearTableOfCursor(BtCursor*); 128 int sqlite3BtreeTripAllCursors(Btree*, int, int); 129 130 void sqlite3BtreeGetMeta(Btree *pBtree, int idx, u32 *pValue); 131 int sqlite3BtreeUpdateMeta(Btree*, int idx, u32 value); 132 133 int sqlite3BtreeNewDb(Btree *p); 134 135 /* 136 ** The second parameter to sqlite3BtreeGetMeta or sqlite3BtreeUpdateMeta 137 ** should be one of the following values. The integer values are assigned 138 ** to constants so that the offset of the corresponding field in an 139 ** SQLite database header may be found using the following formula: 140 ** 141 ** offset = 36 + (idx * 4) 142 ** 143 ** For example, the free-page-count field is located at byte offset 36 of 144 ** the database file header. The incr-vacuum-flag field is located at 145 ** byte offset 64 (== 36+4*7). 146 ** 147 ** The BTREE_DATA_VERSION value is not really a value stored in the header. 148 ** It is a read-only number computed by the pager. But we merge it with 149 ** the header value access routines since its access pattern is the same. 150 ** Call it a "virtual meta value". 151 */ 152 #define BTREE_FREE_PAGE_COUNT 0 153 #define BTREE_SCHEMA_VERSION 1 154 #define BTREE_FILE_FORMAT 2 155 #define BTREE_DEFAULT_CACHE_SIZE 3 156 #define BTREE_LARGEST_ROOT_PAGE 4 157 #define BTREE_TEXT_ENCODING 5 158 #define BTREE_USER_VERSION 6 159 #define BTREE_INCR_VACUUM 7 160 #define BTREE_APPLICATION_ID 8 161 #define BTREE_DATA_VERSION 15 /* A virtual meta-value */ 162 163 /* 164 ** Kinds of hints that can be passed into the sqlite3BtreeCursorHint() 165 ** interface. 166 ** 167 ** BTREE_HINT_RANGE (arguments: Expr*, Mem*) 168 ** 169 ** The first argument is an Expr* (which is guaranteed to be constant for 170 ** the lifetime of the cursor) that defines constraints on which rows 171 ** might be fetched with this cursor. The Expr* tree may contain 172 ** TK_REGISTER nodes that refer to values stored in the array of registers 173 ** passed as the second parameter. In other words, if Expr.op==TK_REGISTER 174 ** then the value of the node is the value in Mem[pExpr.iTable]. Any 175 ** TK_COLUMN node in the expression tree refers to the Expr.iColumn-th 176 ** column of the b-tree of the cursor. The Expr tree will not contain 177 ** any function calls nor subqueries nor references to b-trees other than 178 ** the cursor being hinted. 179 ** 180 ** The design of the _RANGE hint is aid b-tree implementations that try 181 ** to prefetch content from remote machines - to provide those 182 ** implementations with limits on what needs to be prefetched and thereby 183 ** reduce network bandwidth. 184 ** 185 ** Note that BTREE_HINT_FLAGS with BTREE_BULKLOAD is the only hint used by 186 ** standard SQLite. The other hints are provided for extentions that use 187 ** the SQLite parser and code generator but substitute their own storage 188 ** engine. 189 */ 190 #define BTREE_HINT_RANGE 0 /* Range constraints on queries */ 191 192 /* 193 ** Values that may be OR'd together to form the argument to the 194 ** BTREE_HINT_FLAGS hint for sqlite3BtreeCursorHint(): 195 ** 196 ** The BTREE_BULKLOAD flag is set on index cursors when the index is going 197 ** to be filled with content that is already in sorted order. 198 ** 199 ** The BTREE_SEEK_EQ flag is set on cursors that will get OP_SeekGE or 200 ** OP_SeekLE opcodes for a range search, but where the range of entries 201 ** selected will all have the same key. In other words, the cursor will 202 ** be used only for equality key searches. 203 ** 204 */ 205 #define BTREE_BULKLOAD 0x00000001 /* Used to full index in sorted order */ 206 #define BTREE_SEEK_EQ 0x00000002 /* EQ seeks only - no range seeks */ 207 208 /* 209 ** Flags passed as the third argument to sqlite3BtreeCursor(). 210 ** 211 ** For read-only cursors the wrFlag argument is always zero. For read-write 212 ** cursors it may be set to either (BTREE_WRCSR|BTREE_FORDELETE) or just 213 ** (BTREE_WRCSR). If the BTREE_FORDELETE bit is set, then the cursor will 214 ** only be used by SQLite for the following: 215 ** 216 ** * to seek to and then delete specific entries, and/or 217 ** 218 ** * to read values that will be used to create keys that other 219 ** BTREE_FORDELETE cursors will seek to and delete. 220 ** 221 ** The BTREE_FORDELETE flag is an optimization hint. It is not used by 222 ** by this, the native b-tree engine of SQLite, but it is available to 223 ** alternative storage engines that might be substituted in place of this 224 ** b-tree system. For alternative storage engines in which a delete of 225 ** the main table row automatically deletes corresponding index rows, 226 ** the FORDELETE flag hint allows those alternative storage engines to 227 ** skip a lot of work. Namely: FORDELETE cursors may treat all SEEK 228 ** and DELETE operations as no-ops, and any READ operation against a 229 ** FORDELETE cursor may return a null row: 0x01 0x00. 230 */ 231 #define BTREE_WRCSR 0x00000004 /* read-write cursor */ 232 #define BTREE_FORDELETE 0x00000008 /* Cursor is for seek/delete only */ 233 234 int sqlite3BtreeCursor( 235 Btree*, /* BTree containing table to open */ 236 Pgno iTable, /* Index of root page */ 237 int wrFlag, /* 1 for writing. 0 for read-only */ 238 struct KeyInfo*, /* First argument to compare function */ 239 BtCursor *pCursor /* Space to write cursor structure */ 240 ); 241 BtCursor *sqlite3BtreeFakeValidCursor(void); 242 int sqlite3BtreeCursorSize(void); 243 void sqlite3BtreeCursorZero(BtCursor*); 244 void sqlite3BtreeCursorHintFlags(BtCursor*, unsigned); 245 #ifdef SQLITE_ENABLE_CURSOR_HINTS 246 void sqlite3BtreeCursorHint(BtCursor*, int, ...); 247 #endif 248 249 int sqlite3BtreeCloseCursor(BtCursor*); 250 int sqlite3BtreeMovetoUnpacked( 251 BtCursor*, 252 UnpackedRecord *pUnKey, 253 i64 intKey, 254 int bias, 255 int *pRes 256 ); 257 int sqlite3BtreeCursorHasMoved(BtCursor*); 258 int sqlite3BtreeCursorRestore(BtCursor*, int*); 259 int sqlite3BtreeDelete(BtCursor*, u8 flags); 260 261 /* Allowed flags for sqlite3BtreeDelete() and sqlite3BtreeInsert() */ 262 #define BTREE_SAVEPOSITION 0x02 /* Leave cursor pointing at NEXT or PREV */ 263 #define BTREE_AUXDELETE 0x04 /* not the primary delete operation */ 264 #define BTREE_APPEND 0x08 /* Insert is likely an append */ 265 #define BTREE_PREFORMAT 0x80 /* Inserted data is a preformated cell */ 266 267 /* An instance of the BtreePayload object describes the content of a single 268 ** entry in either an index or table btree. 269 ** 270 ** Index btrees (used for indexes and also WITHOUT ROWID tables) contain 271 ** an arbitrary key and no data. These btrees have pKey,nKey set to the 272 ** key and the pData,nData,nZero fields are uninitialized. The aMem,nMem 273 ** fields give an array of Mem objects that are a decomposition of the key. 274 ** The nMem field might be zero, indicating that no decomposition is available. 275 ** 276 ** Table btrees (used for rowid tables) contain an integer rowid used as 277 ** the key and passed in the nKey field. The pKey field is zero. 278 ** pData,nData hold the content of the new entry. nZero extra zero bytes 279 ** are appended to the end of the content when constructing the entry. 280 ** The aMem,nMem fields are uninitialized for table btrees. 281 ** 282 ** Field usage summary: 283 ** 284 ** Table BTrees Index Btrees 285 ** 286 ** pKey always NULL encoded key 287 ** nKey the ROWID length of pKey 288 ** pData data not used 289 ** aMem not used decomposed key value 290 ** nMem not used entries in aMem 291 ** nData length of pData not used 292 ** nZero extra zeros after pData not used 293 ** 294 ** This object is used to pass information into sqlite3BtreeInsert(). The 295 ** same information used to be passed as five separate parameters. But placing 296 ** the information into this object helps to keep the interface more 297 ** organized and understandable, and it also helps the resulting code to 298 ** run a little faster by using fewer registers for parameter passing. 299 */ 300 struct BtreePayload { 301 const void *pKey; /* Key content for indexes. NULL for tables */ 302 sqlite3_int64 nKey; /* Size of pKey for indexes. PRIMARY KEY for tabs */ 303 const void *pData; /* Data for tables. */ 304 sqlite3_value *aMem; /* First of nMem value in the unpacked pKey */ 305 u16 nMem; /* Number of aMem[] value. Might be zero */ 306 int nData; /* Size of pData. 0 if none. */ 307 int nZero; /* Extra zero data appended after pData,nData */ 308 }; 309 310 int sqlite3BtreeInsert(BtCursor*, const BtreePayload *pPayload, 311 int flags, int seekResult); 312 int sqlite3BtreeFirst(BtCursor*, int *pRes); 313 int sqlite3BtreeLast(BtCursor*, int *pRes); 314 int sqlite3BtreeNext(BtCursor*, int flags); 315 int sqlite3BtreeEof(BtCursor*); 316 int sqlite3BtreePrevious(BtCursor*, int flags); 317 i64 sqlite3BtreeIntegerKey(BtCursor*); 318 void sqlite3BtreeCursorPin(BtCursor*); 319 void sqlite3BtreeCursorUnpin(BtCursor*); 320 #ifdef SQLITE_ENABLE_OFFSET_SQL_FUNC 321 i64 sqlite3BtreeOffset(BtCursor*); 322 #endif 323 int sqlite3BtreePayload(BtCursor*, u32 offset, u32 amt, void*); 324 const void *sqlite3BtreePayloadFetch(BtCursor*, u32 *pAmt); 325 u32 sqlite3BtreePayloadSize(BtCursor*); 326 sqlite3_int64 sqlite3BtreeMaxRecordSize(BtCursor*); 327 328 char *sqlite3BtreeIntegrityCheck(sqlite3*,Btree*,Pgno*aRoot,int nRoot,int,int*); 329 struct Pager *sqlite3BtreePager(Btree*); 330 i64 sqlite3BtreeRowCountEst(BtCursor*); 331 332 #ifndef SQLITE_OMIT_INCRBLOB 333 int sqlite3BtreePayloadChecked(BtCursor*, u32 offset, u32 amt, void*); 334 int sqlite3BtreePutData(BtCursor*, u32 offset, u32 amt, void*); 335 void sqlite3BtreeIncrblobCursor(BtCursor *); 336 #endif 337 void sqlite3BtreeClearCursor(BtCursor *); 338 int sqlite3BtreeSetVersion(Btree *pBt, int iVersion); 339 int sqlite3BtreeCursorHasHint(BtCursor*, unsigned int mask); 340 int sqlite3BtreeIsReadonly(Btree *pBt); 341 int sqlite3HeaderSizeBtree(void); 342 343 #ifdef SQLITE_DEBUG 344 sqlite3_uint64 sqlite3BtreeSeekCount(Btree*); 345 #else 346 # define sqlite3BtreeSeekCount(X) 0 347 #endif 348 349 #ifndef NDEBUG 350 int sqlite3BtreeCursorIsValid(BtCursor*); 351 #endif 352 int sqlite3BtreeCursorIsValidNN(BtCursor*); 353 354 int sqlite3BtreeCount(sqlite3*, BtCursor*, i64*); 355 356 #ifdef SQLITE_TEST 357 int sqlite3BtreeCursorInfo(BtCursor*, int*, int); 358 void sqlite3BtreeCursorList(Btree*); 359 #endif 360 361 #ifndef SQLITE_OMIT_WAL 362 int sqlite3BtreeCheckpoint(Btree*, int, int *, int *); 363 #endif 364 365 int sqlite3BtreeTransferRow(BtCursor*, BtCursor*, i64); 366 367 /* 368 ** If we are not using shared cache, then there is no need to 369 ** use mutexes to access the BtShared structures. So make the 370 ** Enter and Leave procedures no-ops. 371 */ 372 #ifndef SQLITE_OMIT_SHARED_CACHE 373 void sqlite3BtreeEnter(Btree*); 374 void sqlite3BtreeEnterAll(sqlite3*); 375 int sqlite3BtreeSharable(Btree*); 376 void sqlite3BtreeEnterCursor(BtCursor*); 377 int sqlite3BtreeConnectionCount(Btree*); 378 #else 379 # define sqlite3BtreeEnter(X) 380 # define sqlite3BtreeEnterAll(X) 381 # define sqlite3BtreeSharable(X) 0 382 # define sqlite3BtreeEnterCursor(X) 383 # define sqlite3BtreeConnectionCount(X) 1 384 #endif 385 386 #if !defined(SQLITE_OMIT_SHARED_CACHE) && SQLITE_THREADSAFE 387 void sqlite3BtreeLeave(Btree*); 388 void sqlite3BtreeLeaveCursor(BtCursor*); 389 void sqlite3BtreeLeaveAll(sqlite3*); 390 #ifndef NDEBUG 391 /* These routines are used inside assert() statements only. */ 392 int sqlite3BtreeHoldsMutex(Btree*); 393 int sqlite3BtreeHoldsAllMutexes(sqlite3*); 394 int sqlite3SchemaMutexHeld(sqlite3*,int,Schema*); 395 #endif 396 #else 397 398 # define sqlite3BtreeLeave(X) 399 # define sqlite3BtreeLeaveCursor(X) 400 # define sqlite3BtreeLeaveAll(X) 401 402 # define sqlite3BtreeHoldsMutex(X) 1 403 # define sqlite3BtreeHoldsAllMutexes(X) 1 404 # define sqlite3SchemaMutexHeld(X,Y,Z) 1 405 #endif 406 407 408 #endif /* SQLITE_BTREE_H */ 409