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*/
39typedef struct Btree Btree;
40typedef struct BtCursor BtCursor;
41typedef struct BtShared BtShared;
42typedef struct BtreePayload BtreePayload;
43
44
45int 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
65int sqlite3BtreeClose(Btree*);
66int sqlite3BtreeSetCacheSize(Btree*,int);
67int sqlite3BtreeSetSpillSize(Btree*,int);
68#if SQLITE_MAX_MMAP_SIZE>0
69 int sqlite3BtreeSetMmapLimit(Btree*,sqlite3_int64);
70#endif
71int sqlite3BtreeSetPagerFlags(Btree*,unsigned);
72int sqlite3BtreeSetPageSize(Btree *p, int nPagesize, int nReserve, int eFix);
73int sqlite3BtreeGetPageSize(Btree*);
74Pgno sqlite3BtreeMaxPageCount(Btree*,Pgno);
75Pgno sqlite3BtreeLastPage(Btree*);
76int sqlite3BtreeSecureDelete(Btree*,int);
77int sqlite3BtreeGetRequestedReserve(Btree*);
78int sqlite3BtreeGetReserveNoMutex(Btree *p);
79int sqlite3BtreeSetAutoVacuum(Btree *, int);
80int sqlite3BtreeGetAutoVacuum(Btree *);
81int sqlite3BtreeBeginTrans(Btree*,int,int*);
82int sqlite3BtreeCommitPhaseOne(Btree*, const char*);
83int sqlite3BtreeCommitPhaseTwo(Btree*, int);
84int sqlite3BtreeCommit(Btree*);
85int sqlite3BtreeRollback(Btree*,int,int);
86int sqlite3BtreeBeginStmt(Btree*,int);
87int sqlite3BtreeCreateTable(Btree*, Pgno*, int flags);
88int sqlite3BtreeTxnState(Btree*);
89int sqlite3BtreeIsInBackup(Btree*);
90
91void *sqlite3BtreeSchema(Btree *, int, void(*)(void *));
92int sqlite3BtreeSchemaLocked(Btree *pBtree);
93#ifndef SQLITE_OMIT_SHARED_CACHE
94int 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 */
99int 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
106const char *sqlite3BtreeGetFilename(Btree *);
107const char *sqlite3BtreeGetJournalname(Btree *);
108int sqlite3BtreeCopyFile(Btree *, Btree *);
109
110int 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
125int sqlite3BtreeDropTable(Btree*, int, int*);
126int sqlite3BtreeClearTable(Btree*, int, i64*);
127int sqlite3BtreeClearTableOfCursor(BtCursor*);
128int sqlite3BtreeTripAllCursors(Btree*, int, int);
129
130void sqlite3BtreeGetMeta(Btree *pBtree, int idx, u32 *pValue);
131int sqlite3BtreeUpdateMeta(Btree*, int idx, u32 value);
132
133int 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
234int 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);
241BtCursor *sqlite3BtreeFakeValidCursor(void);
242int sqlite3BtreeCursorSize(void);
243void sqlite3BtreeCursorZero(BtCursor*);
244void sqlite3BtreeCursorHintFlags(BtCursor*, unsigned);
245#ifdef SQLITE_ENABLE_CURSOR_HINTS
246void sqlite3BtreeCursorHint(BtCursor*, int, ...);
247#endif
248
249int sqlite3BtreeCloseCursor(BtCursor*);
250int sqlite3BtreeTableMoveto(
251 BtCursor*,
252 i64 intKey,
253 int bias,
254 int *pRes
255);
256int sqlite3BtreeIndexMoveto(
257 BtCursor*,
258 UnpackedRecord *pUnKey,
259 int *pRes
260);
261int sqlite3BtreeCursorHasMoved(BtCursor*);
262int sqlite3BtreeCursorRestore(BtCursor*, int*);
263int sqlite3BtreeDelete(BtCursor*, u8 flags);
264
265/* Allowed flags for sqlite3BtreeDelete() and sqlite3BtreeInsert() */
266#define BTREE_SAVEPOSITION 0x02 /* Leave cursor pointing at NEXT or PREV */
267#define BTREE_AUXDELETE 0x04 /* not the primary delete operation */
268#define BTREE_APPEND 0x08 /* Insert is likely an append */
269#define BTREE_PREFORMAT 0x80 /* Inserted data is a preformated cell */
270
271/* An instance of the BtreePayload object describes the content of a single
272** entry in either an index or table btree.
273**
274** Index btrees (used for indexes and also WITHOUT ROWID tables) contain
275** an arbitrary key and no data. These btrees have pKey,nKey set to the
276** key and the pData,nData,nZero fields are uninitialized. The aMem,nMem
277** fields give an array of Mem objects that are a decomposition of the key.
278** The nMem field might be zero, indicating that no decomposition is available.
279**
280** Table btrees (used for rowid tables) contain an integer rowid used as
281** the key and passed in the nKey field. The pKey field is zero.
282** pData,nData hold the content of the new entry. nZero extra zero bytes
283** are appended to the end of the content when constructing the entry.
284** The aMem,nMem fields are uninitialized for table btrees.
285**
286** Field usage summary:
287**
288** Table BTrees Index Btrees
289**
290** pKey always NULL encoded key
291** nKey the ROWID length of pKey
292** pData data not used
293** aMem not used decomposed key value
294** nMem not used entries in aMem
295** nData length of pData not used
296** nZero extra zeros after pData not used
297**
298** This object is used to pass information into sqlite3BtreeInsert(). The
299** same information used to be passed as five separate parameters. But placing
300** the information into this object helps to keep the interface more
301** organized and understandable, and it also helps the resulting code to
302** run a little faster by using fewer registers for parameter passing.
303*/
304struct BtreePayload {
305 const void *pKey; /* Key content for indexes. NULL for tables */
306 sqlite3_int64 nKey; /* Size of pKey for indexes. PRIMARY KEY for tabs */
307 const void *pData; /* Data for tables. */
308 sqlite3_value *aMem; /* First of nMem value in the unpacked pKey */
309 u16 nMem; /* Number of aMem[] value. Might be zero */
310 int nData; /* Size of pData. 0 if none. */
311 int nZero; /* Extra zero data appended after pData,nData */
312};
313
314int sqlite3BtreeInsert(BtCursor*, const BtreePayload *pPayload,
315 int flags, int seekResult);
316int sqlite3BtreeFirst(BtCursor*, int *pRes);
317int sqlite3BtreeLast(BtCursor*, int *pRes);
318int sqlite3BtreeNext(BtCursor*, int flags);
319int sqlite3BtreeEof(BtCursor*);
320int sqlite3BtreePrevious(BtCursor*, int flags);
321i64 sqlite3BtreeIntegerKey(BtCursor*);
322void sqlite3BtreeCursorPin(BtCursor*);
323void sqlite3BtreeCursorUnpin(BtCursor*);
324#ifdef SQLITE_ENABLE_OFFSET_SQL_FUNC
325i64 sqlite3BtreeOffset(BtCursor*);
326#endif
327int sqlite3BtreePayload(BtCursor*, u32 offset, u32 amt, void*);
328const void *sqlite3BtreePayloadFetch(BtCursor*, u32 *pAmt);
329u32 sqlite3BtreePayloadSize(BtCursor*);
330sqlite3_int64 sqlite3BtreeMaxRecordSize(BtCursor*);
331
332char *sqlite3BtreeIntegrityCheck(sqlite3*,Btree*,Pgno*aRoot,int nRoot,int,int*);
333struct Pager *sqlite3BtreePager(Btree*);
334i64 sqlite3BtreeRowCountEst(BtCursor*);
335
336#ifndef SQLITE_OMIT_INCRBLOB
337int sqlite3BtreePayloadChecked(BtCursor*, u32 offset, u32 amt, void*);
338int sqlite3BtreePutData(BtCursor*, u32 offset, u32 amt, void*);
339void sqlite3BtreeIncrblobCursor(BtCursor *);
340#endif
341void sqlite3BtreeClearCursor(BtCursor *);
342int sqlite3BtreeSetVersion(Btree *pBt, int iVersion);
343int sqlite3BtreeCursorHasHint(BtCursor*, unsigned int mask);
344int sqlite3BtreeIsReadonly(Btree *pBt);
345int sqlite3HeaderSizeBtree(void);
346
347#ifdef SQLITE_DEBUG
348sqlite3_uint64 sqlite3BtreeSeekCount(Btree*);
349#else
350# define sqlite3BtreeSeekCount(X) 0
351#endif
352
353#ifndef NDEBUG
354int sqlite3BtreeCursorIsValid(BtCursor*);
355#endif
356int sqlite3BtreeCursorIsValidNN(BtCursor*);
357
358int sqlite3BtreeCount(sqlite3*, BtCursor*, i64*);
359
360#ifdef SQLITE_TEST
361int sqlite3BtreeCursorInfo(BtCursor*, int*, int);
362void sqlite3BtreeCursorList(Btree*);
363#endif
364
365#ifndef SQLITE_OMIT_WAL
366 int sqlite3BtreeCheckpoint(Btree*, int, int *, int *);
367#endif
368
369int sqlite3BtreeTransferRow(BtCursor*, BtCursor*, i64);
370
371void sqlite3BtreeClearCache(Btree*);
372
373/*
374** If we are not using shared cache, then there is no need to
375** use mutexes to access the BtShared structures. So make the
376** Enter and Leave procedures no-ops.
377*/
378#ifndef SQLITE_OMIT_SHARED_CACHE
379 void sqlite3BtreeEnter(Btree*);
380 void sqlite3BtreeEnterAll(sqlite3*);
381 int sqlite3BtreeSharable(Btree*);
382 void sqlite3BtreeEnterCursor(BtCursor*);
383 int sqlite3BtreeConnectionCount(Btree*);
384#else
385# define sqlite3BtreeEnter(X)
386# define sqlite3BtreeEnterAll(X)
387# define sqlite3BtreeSharable(X) 0
388# define sqlite3BtreeEnterCursor(X)
389# define sqlite3BtreeConnectionCount(X) 1
390#endif
391
392#if !defined(SQLITE_OMIT_SHARED_CACHE) && SQLITE_THREADSAFE
393 void sqlite3BtreeLeave(Btree*);
394 void sqlite3BtreeLeaveCursor(BtCursor*);
395 void sqlite3BtreeLeaveAll(sqlite3*);
396#ifndef NDEBUG
397 /* These routines are used inside assert() statements only. */
398 int sqlite3BtreeHoldsMutex(Btree*);
399 int sqlite3BtreeHoldsAllMutexes(sqlite3*);
400 int sqlite3SchemaMutexHeld(sqlite3*,int,Schema*);
401#endif
402#else
403
404# define sqlite3BtreeLeave(X)
405# define sqlite3BtreeLeaveCursor(X)
406# define sqlite3BtreeLeaveAll(X)
407
408# define sqlite3BtreeHoldsMutex(X) 1
409# define sqlite3BtreeHoldsAllMutexes(X) 1
410# define sqlite3SchemaMutexHeld(X,Y,Z) 1
411#endif
412
413
414#endif /* SQLITE_BTREE_H */
415