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 _BTREE_H_ 17 #define _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 43 44 int sqlite3BtreeOpen( 45 sqlite3_vfs *pVfs, /* VFS to use with this b-tree */ 46 const char *zFilename, /* Name of database file to open */ 47 sqlite3 *db, /* Associated database connection */ 48 Btree **ppBtree, /* Return open Btree* here */ 49 int flags, /* Flags */ 50 int vfsFlags /* Flags passed through to VFS open */ 51 ); 52 53 /* The flags parameter to sqlite3BtreeOpen can be the bitwise or of the 54 ** following values. 55 ** 56 ** NOTE: These values must match the corresponding PAGER_ values in 57 ** pager.h. 58 */ 59 #define BTREE_OMIT_JOURNAL 1 /* Do not create or use a rollback journal */ 60 #define BTREE_MEMORY 2 /* This is an in-memory DB */ 61 #define BTREE_SINGLE 4 /* The file contains at most 1 b-tree */ 62 #define BTREE_UNORDERED 8 /* Use of a hash implementation is OK */ 63 64 int sqlite3BtreeClose(Btree*); 65 int sqlite3BtreeSetCacheSize(Btree*,int); 66 int sqlite3BtreeSetSpillSize(Btree*,int); 67 #if SQLITE_MAX_MMAP_SIZE>0 68 int sqlite3BtreeSetMmapLimit(Btree*,sqlite3_int64); 69 #endif 70 int sqlite3BtreeSetPagerFlags(Btree*,unsigned); 71 int sqlite3BtreeSetPageSize(Btree *p, int nPagesize, int nReserve, int eFix); 72 int sqlite3BtreeGetPageSize(Btree*); 73 int sqlite3BtreeMaxPageCount(Btree*,int); 74 u32 sqlite3BtreeLastPage(Btree*); 75 int sqlite3BtreeSecureDelete(Btree*,int); 76 int sqlite3BtreeGetOptimalReserve(Btree*); 77 int sqlite3BtreeGetReserveNoMutex(Btree *p); 78 int sqlite3BtreeSetAutoVacuum(Btree *, int); 79 int sqlite3BtreeGetAutoVacuum(Btree *); 80 int sqlite3BtreeBeginTrans(Btree*,int); 81 int sqlite3BtreeCommitPhaseOne(Btree*, const char *zMaster); 82 int sqlite3BtreeCommitPhaseTwo(Btree*, int); 83 int sqlite3BtreeCommit(Btree*); 84 int sqlite3BtreeRollback(Btree*,int,int); 85 int sqlite3BtreeBeginStmt(Btree*,int); 86 int sqlite3BtreeCreateTable(Btree*, int*, int flags); 87 int sqlite3BtreeIsInTrans(Btree*); 88 int sqlite3BtreeIsInReadTrans(Btree*); 89 int sqlite3BtreeIsInBackup(Btree*); 90 void *sqlite3BtreeSchema(Btree *, int, void(*)(void *)); 91 int sqlite3BtreeSchemaLocked(Btree *pBtree); 92 int sqlite3BtreeLockTable(Btree *pBtree, int iTab, u8 isWriteLock); 93 int sqlite3BtreeSavepoint(Btree *, int, int); 94 95 const char *sqlite3BtreeGetFilename(Btree *); 96 const char *sqlite3BtreeGetJournalname(Btree *); 97 int sqlite3BtreeCopyFile(Btree *, Btree *); 98 99 int sqlite3BtreeIncrVacuum(Btree *); 100 101 /* The flags parameter to sqlite3BtreeCreateTable can be the bitwise OR 102 ** of the flags shown below. 103 ** 104 ** Every SQLite table must have either BTREE_INTKEY or BTREE_BLOBKEY set. 105 ** With BTREE_INTKEY, the table key is a 64-bit integer and arbitrary data 106 ** is stored in the leaves. (BTREE_INTKEY is used for SQL tables.) With 107 ** BTREE_BLOBKEY, the key is an arbitrary BLOB and no content is stored 108 ** anywhere - the key is the content. (BTREE_BLOBKEY is used for SQL 109 ** indices.) 110 */ 111 #define BTREE_INTKEY 1 /* Table has only 64-bit signed integer keys */ 112 #define BTREE_BLOBKEY 2 /* Table has keys only - no data */ 113 114 int sqlite3BtreeDropTable(Btree*, int, int*); 115 int sqlite3BtreeClearTable(Btree*, int, int*); 116 int sqlite3BtreeClearTableOfCursor(BtCursor*); 117 int sqlite3BtreeTripAllCursors(Btree*, int, int); 118 119 void sqlite3BtreeGetMeta(Btree *pBtree, int idx, u32 *pValue); 120 int sqlite3BtreeUpdateMeta(Btree*, int idx, u32 value); 121 122 int sqlite3BtreeNewDb(Btree *p); 123 124 /* 125 ** The second parameter to sqlite3BtreeGetMeta or sqlite3BtreeUpdateMeta 126 ** should be one of the following values. The integer values are assigned 127 ** to constants so that the offset of the corresponding field in an 128 ** SQLite database header may be found using the following formula: 129 ** 130 ** offset = 36 + (idx * 4) 131 ** 132 ** For example, the free-page-count field is located at byte offset 36 of 133 ** the database file header. The incr-vacuum-flag field is located at 134 ** byte offset 64 (== 36+4*7). 135 ** 136 ** The BTREE_DATA_VERSION value is not really a value stored in the header. 137 ** It is a read-only number computed by the pager. But we merge it with 138 ** the header value access routines since its access pattern is the same. 139 ** Call it a "virtual meta value". 140 */ 141 #define BTREE_FREE_PAGE_COUNT 0 142 #define BTREE_SCHEMA_VERSION 1 143 #define BTREE_FILE_FORMAT 2 144 #define BTREE_DEFAULT_CACHE_SIZE 3 145 #define BTREE_LARGEST_ROOT_PAGE 4 146 #define BTREE_TEXT_ENCODING 5 147 #define BTREE_USER_VERSION 6 148 #define BTREE_INCR_VACUUM 7 149 #define BTREE_APPLICATION_ID 8 150 #define BTREE_DATA_VERSION 15 /* A virtual meta-value */ 151 152 /* 153 ** Kinds of hints that can be passed into the sqlite3BtreeCursorHint() 154 ** interface. 155 ** 156 ** BTREE_HINT_RANGE (arguments: Expr*, Mem*) 157 ** 158 ** The first argument is an Expr* (which is guaranteed to be constant for 159 ** the lifetime of the cursor) that defines constraints on which rows 160 ** might be fetched with this cursor. The Expr* tree may contain 161 ** TK_REGISTER nodes that refer to values stored in the array of registers 162 ** passed as the second parameter. In other words, if Expr.op==TK_REGISTER 163 ** then the value of the node is the value in Mem[pExpr.iTable]. Any 164 ** TK_COLUMN node in the expression tree refers to the Expr.iColumn-th 165 ** column of the b-tree of the cursor. The Expr tree will not contain 166 ** any function calls nor subqueries nor references to b-trees other than 167 ** the cursor being hinted. 168 ** 169 ** The design of the _RANGE hint is aid b-tree implementations that try 170 ** to prefetch content from remote machines - to provide those 171 ** implementations with limits on what needs to be prefetched and thereby 172 ** reduce network bandwidth. 173 ** 174 ** Note that BTREE_HINT_FLAGS with BTREE_BULKLOAD is the only hint used by 175 ** standard SQLite. The other hints are provided for extentions that use 176 ** the SQLite parser and code generator but substitute their own storage 177 ** engine. 178 */ 179 #define BTREE_HINT_RANGE 0 /* Range constraints on queries */ 180 181 /* 182 ** Values that may be OR'd together to form the argument to the 183 ** BTREE_HINT_FLAGS hint for sqlite3BtreeCursorHint(): 184 ** 185 ** The BTREE_BULKLOAD flag is set on index cursors when the index is going 186 ** to be filled with content that is already in sorted order. 187 ** 188 ** The BTREE_SEEK_EQ flag is set on cursors that will get OP_SeekGE or 189 ** OP_SeekLE opcodes for a range search, but where the range of entries 190 ** selected will all have the same key. In other words, the cursor will 191 ** be used only for equality key searches. 192 ** 193 */ 194 #define BTREE_BULKLOAD 0x00000001 /* Used to full index in sorted order */ 195 #define BTREE_SEEK_EQ 0x00000002 /* EQ seeks only - no range seeks */ 196 197 /* 198 ** Flags passed as the third argument to sqlite3BtreeCursor(). 199 ** 200 ** For read-only cursors the wrFlag argument is always zero. For read-write 201 ** cursors it may be set to either (BTREE_WRCSR|BTREE_FORDELETE) or just 202 ** (BTREE_WRCSR). If the BTREE_FORDELETE bit is set, then the cursor will 203 ** only be used by SQLite for the following: 204 ** 205 ** * to seek to and then delete specific entries, and/or 206 ** 207 ** * to read values that will be used to create keys that other 208 ** BTREE_FORDELETE cursors will seek to and delete. 209 ** 210 ** The BTREE_FORDELETE flag is an optimization hint. It is not used by 211 ** by this, the native b-tree engine of SQLite, but it is available to 212 ** alternative storage engines that might be substituted in place of this 213 ** b-tree system. For alternative storage engines in which a delete of 214 ** the main table row automatically deletes corresponding index rows, 215 ** the FORDELETE flag hint allows those alternative storage engines to 216 ** skip a lot of work. Namely: FORDELETE cursors may treat all SEEK 217 ** and DELETE operations as no-ops, and any READ operation against a 218 ** FORDELETE cursor may return a null row: 0x01 0x00. 219 */ 220 #define BTREE_WRCSR 0x00000004 /* read-write cursor */ 221 #define BTREE_FORDELETE 0x00000008 /* Cursor is for seek/delete only */ 222 223 int sqlite3BtreeCursor( 224 Btree*, /* BTree containing table to open */ 225 int iTable, /* Index of root page */ 226 int wrFlag, /* 1 for writing. 0 for read-only */ 227 struct KeyInfo*, /* First argument to compare function */ 228 BtCursor *pCursor /* Space to write cursor structure */ 229 ); 230 int sqlite3BtreeCursorSize(void); 231 void sqlite3BtreeCursorZero(BtCursor*); 232 void sqlite3BtreeCursorHintFlags(BtCursor*, unsigned); 233 #ifdef SQLITE_ENABLE_CURSOR_HINTS 234 void sqlite3BtreeCursorHint(BtCursor*, int, ...); 235 #endif 236 237 int sqlite3BtreeCloseCursor(BtCursor*); 238 int sqlite3BtreeMovetoUnpacked( 239 BtCursor*, 240 UnpackedRecord *pUnKey, 241 i64 intKey, 242 int bias, 243 int *pRes 244 ); 245 int sqlite3BtreeCursorHasMoved(BtCursor*); 246 int sqlite3BtreeCursorRestore(BtCursor*, int*); 247 int sqlite3BtreeDelete(BtCursor*, u8 flags); 248 249 /* Allowed flags for the 2nd argument to sqlite3BtreeDelete() */ 250 #define BTREE_SAVEPOSITION 0x02 /* Leave cursor pointing at NEXT or PREV */ 251 #define BTREE_AUXDELETE 0x04 /* not the primary delete operation */ 252 253 int sqlite3BtreeInsert(BtCursor*, const void *pKey, i64 nKey, 254 const void *pData, int nData, 255 int nZero, int bias, int seekResult); 256 int sqlite3BtreeFirst(BtCursor*, int *pRes); 257 int sqlite3BtreeLast(BtCursor*, int *pRes); 258 int sqlite3BtreeNext(BtCursor*, int *pRes); 259 int sqlite3BtreeEof(BtCursor*); 260 int sqlite3BtreePrevious(BtCursor*, int *pRes); 261 int sqlite3BtreeKeySize(BtCursor*, i64 *pSize); 262 int sqlite3BtreeKey(BtCursor*, u32 offset, u32 amt, void*); 263 const void *sqlite3BtreeKeyFetch(BtCursor*, u32 *pAmt); 264 const void *sqlite3BtreeDataFetch(BtCursor*, u32 *pAmt); 265 int sqlite3BtreeDataSize(BtCursor*, u32 *pSize); 266 int sqlite3BtreeData(BtCursor*, u32 offset, u32 amt, void*); 267 268 char *sqlite3BtreeIntegrityCheck(Btree*, int *aRoot, int nRoot, int, int*); 269 struct Pager *sqlite3BtreePager(Btree*); 270 271 int sqlite3BtreePutData(BtCursor*, u32 offset, u32 amt, void*); 272 void sqlite3BtreeIncrblobCursor(BtCursor *); 273 void sqlite3BtreeClearCursor(BtCursor *); 274 int sqlite3BtreeSetVersion(Btree *pBt, int iVersion); 275 int sqlite3BtreeCursorHasHint(BtCursor*, unsigned int mask); 276 int sqlite3BtreeIsReadonly(Btree *pBt); 277 int sqlite3HeaderSizeBtree(void); 278 279 #ifndef NDEBUG 280 int sqlite3BtreeCursorIsValid(BtCursor*); 281 #endif 282 283 #ifndef SQLITE_OMIT_BTREECOUNT 284 int sqlite3BtreeCount(BtCursor *, i64 *); 285 #endif 286 287 #ifdef SQLITE_TEST 288 int sqlite3BtreeCursorInfo(BtCursor*, int*, int); 289 void sqlite3BtreeCursorList(Btree*); 290 #endif 291 292 #ifndef SQLITE_OMIT_WAL 293 int sqlite3BtreeCheckpoint(Btree*, int, int *, int *); 294 #endif 295 296 /* 297 ** If we are not using shared cache, then there is no need to 298 ** use mutexes to access the BtShared structures. So make the 299 ** Enter and Leave procedures no-ops. 300 */ 301 #ifndef SQLITE_OMIT_SHARED_CACHE 302 void sqlite3BtreeEnter(Btree*); 303 void sqlite3BtreeEnterAll(sqlite3*); 304 int sqlite3BtreeSharable(Btree*); 305 void sqlite3BtreeEnterCursor(BtCursor*); 306 #else 307 # define sqlite3BtreeEnter(X) 308 # define sqlite3BtreeEnterAll(X) 309 # define sqlite3BtreeSharable(X) 0 310 # define sqlite3BtreeEnterCursor(X) 311 #endif 312 313 #if !defined(SQLITE_OMIT_SHARED_CACHE) && SQLITE_THREADSAFE 314 void sqlite3BtreeLeave(Btree*); 315 void sqlite3BtreeLeaveCursor(BtCursor*); 316 void sqlite3BtreeLeaveAll(sqlite3*); 317 #ifndef NDEBUG 318 /* These routines are used inside assert() statements only. */ 319 int sqlite3BtreeHoldsMutex(Btree*); 320 int sqlite3BtreeHoldsAllMutexes(sqlite3*); 321 int sqlite3SchemaMutexHeld(sqlite3*,int,Schema*); 322 #endif 323 #else 324 325 # define sqlite3BtreeLeave(X) 326 # define sqlite3BtreeLeaveCursor(X) 327 # define sqlite3BtreeLeaveAll(X) 328 329 # define sqlite3BtreeHoldsMutex(X) 1 330 # define sqlite3BtreeHoldsAllMutexes(X) 1 331 # define sqlite3SchemaMutexHeld(X,Y,Z) 1 332 #endif 333 334 335 #endif /* _BTREE_H_ */ 336