Prettify btree.h headings. Close branch.

FossilOrigin-Name: ee9689ad2fadb3b9c11235312bfc32a1db294485b4503a07692bbdbce71e021d

manifest

@@ -1,5 +1,5 @@
-C Always\screate\sa\sstatement\sjournal\swhen\susing\sthe\sOP_ParseSchema\sopcode,\nas\syou\snever\sknow\swhen\sit\smight\sfail.\s\sSee\sthe\sdiscussion\son\n[forum:/forumpost/daa2c728cc|forum\spost\sdaa2c728cc].
-D 2020-10-26T18:14:12.864
+C Prettify\sbtree.h\sheadings.\sClose\sbranch.
+D 2020-10-27T11:58:37.756
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -478,8 +478,8 @@ F src/auth.c a3d5bfdba83d25abed1013a8c7a5f204e2e29b0c25242a56bc02bb0c07bf1e06
 F src/backup.c 3014889fa06e20e6adfa0d07b60097eec1f6e5b06671625f476a714d2356513d
 F src/bitvec.c 17ea48eff8ba979f1f5b04cc484c7bb2be632f33
 F src/btmutex.c 8acc2f464ee76324bf13310df5692a262b801808984c1b79defb2503bbafadb6
-F src/btree.c c678de5bf6f57933e0ad40578fbdb0fc8113b414bf517e0a2525cb319c379874
-F src/btree.h dcdff4037d75b3f032a5de0d922fcfaf35d48589417f634fa8627362709315f9
+F src/btree.c ad0a38e4d4a0b6b3e003b5478556dbe890c0d58c7a95362e02d1fa539631af19
+F src/btree.h c16c855f7e2ef5bfe8fb119a20339fb8e24a3efe6edce17be4df66bce4e20241
 F src/btreeInt.h ffd66480520d9d70222171b3a026d78b80833b5cea49c89867949f3e023d5f43
 F src/build.c f6449d4e85e998e14d3f537e8ea898dca2fcb83c277db3e60945af9b9177db81
 F src/callback.c d0b853dd413255d2e337b34545e54d888ea02f20da5ad0e63585b389624c4a6c
@@ -542,7 +542,7 @@ F src/shell.c.in b317d851046496c92e28529eb96f9d2ec1ad480590b1676e0362865f5466f88
 F src/sqlite.h.in ff32663b457306eb88c3039868280aa39da31162ed69c4e71fa8e028684e7277
 F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
 F src/sqlite3ext.h 2d1af80082edffd71c6f96f70ad1ce6a4fb46615ad10291fc77fe0dea9ff0197
-F src/sqliteInt.h c01115c8dd967f7d334a98ba37ac821eafb04144c8085a795daaf2185743d27a
+F src/sqliteInt.h c6c4c310b699364eff6457f05beb47fd30943687d511bf99b6f722af236377fb
 F src/sqliteLimit.h d7323ffea5208c6af2734574bae933ca8ed2ab728083caa117c9738581a31657
 F src/status.c 4b8bc2a6905163a38b739854a35b826c737333fab5b1f8e03fa7eb9a4799c4c1
 F src/table.c 0f141b58a16de7e2fbe81c308379e7279f4c6b50eb08efeec5892794a0ba30d1
@@ -1883,7 +1883,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 80eba105d6d1b49ba8ca2ad4e14ddec2de0bdc2f6686c2f8a1c1d24fc1fe846f
-R eea974520c1d74de24586e181010f011
-U drh
-Z c0d2472c8013bdcee23ed82f2bfd8f37
+P eb6e5fc1891be52acf378269405a99bab92b9bf501b7eba04eae07c851ed3027
+R 4d578fe854f29eb4522630d2ff1014ab
+T +closed *
+U shearer
+Z 451aeadec2dd7d0cf13fe0ace3038992

manifest.uuid

@@ -1 +1 @@
-aa512f72cf5adfece6299db17bd122aeff0cdee2a25f83f60e2ebb05e99c9591
+ee9689ad2fadb3b9c11235312bfc32a1db294485b4503a07692bbdbce71e021d

src/btree.c

@@ -10542,7 +10542,7 @@ int sqlite3BtreeSetVersion(Btree *pBtree, int iVersion){
 
 /*
 ** Return true if the cursor has a hint specified.  This routine is
-** only used from within assert() statements
+** only used from within or around assert() statements
 */
 int sqlite3BtreeCursorHasHint(BtCursor *pCsr, unsigned int mask){
   return (pCsr->hints & mask)!=0;

src/btree.h

@@ -9,17 +9,99 @@
 **    May you share freely, never taking more than you give.
 **
 *************************************************************************
-** This header file defines the interface that the sqlite B-Tree file
-** subsystem.  See comments in the source code for a detailed description
-** of what each interface routine does.
+** This header file defines the interface to the sqlite B-Tree storage
+** subsystem. All SQLite database operations become calls to the B-Tree 
+** storage layer. The B-Tree layer requires a key-value store underneath 
+** that is capable of MVCC - that is, transaction commit and rollback, 
+** locking and concurrent access. See comments in btree.c for a detailed 
+** description of each interface routine.
+**
+** The btree module organises an SQL database of tables and rows into 
+** multiple key-value pair stores, which in turn are represented as 
+** fixed-size pages in the memory-based page cache. The BTree functions 
+** operate on pages in the page cache. A separate B-tree is used for each 
+** table and each index in the database. Databases are stored in an on-disk 
+** Database Image, which the B-Tree module knows nothing about except for 
+** opening and closing.
+**
+** The architecture is described at https://www.sqlite.org/arch.html .
+**
+** A Btree record is also called a payload in SQLite source. A Btree
+** record for table data contains only two fields: the unique key value
+** ROWID, and the table row data. A Btree record for an index btree or 
+** a WITHOUT ROWID table contain an arbitary key and no (uninitialised) data.
+** Btree pages are a fixed size. There will usually be multiple payloads 
+** per page, but large payloads (eg BLOB data) may spill over to multiple
+** pages.
+**
+** Functions in this header file are grouped according to their logical task:
+**
+**      Opening and Closing Database Connections
+**
+**      Database Image Configuration and Querying
+**
+**      Btree Connection Configuration and Querying
+**
+**      Mutex Function Wrappers
+**
+**      Transaction and Savepoint Functions
+**
+**      Cursors and Cursor Functions
+**
+**      Record and Payload Handling Functions
+**
+**      Table Functions
+**
+**      Reading and Writing Metadata
+**
 */
+
 #ifndef SQLITE_BTREE_H
 #define SQLITE_BTREE_H
 
-/* TODO: This definition is just included so other modules compile. It
-** needs to be revisited.
+/*
+** Forward declarations of structure
+*/
+typedef struct Btree Btree;
+typedef struct BtCursor BtCursor;
+typedef struct BtShared BtShared;
+typedef struct BtreePayload BtreePayload;
+
+/*
+********************************************
+*   Opening and Closing Database Connections
+********************************************
+*/
+
+int sqlite3BtreeOpen(
+  sqlite3_vfs *pVfs,       /* VFS to use with this b-tree */
+  const char *zFilename,   /* Name of database file to open */
+  sqlite3 *db,             /* Associated database connection */
+  Btree **ppBtree,         /* Return open Btree* here */
+  int flags,               /* Flags */
+  int vfsFlags             /* Flags passed through to VFS open */
+);
+
+/* The flags parameter to sqlite3BtreeOpen can be the bitwise OR of the
+** following values.
+**
+** NOTE:  These values must match the corresponding PAGER_ values in
+** pager.h.
+*/
+
+#define BTREE_OMIT_JOURNAL  1  /* No create/use journal in temp databases */
+#define BTREE_MEMORY        2  /* This is an in-memory DB */
+#define BTREE_SINGLE        4  /* The file contains at most 1 b-tree */
+#define BTREE_UNORDERED     8  /* Use of a hash implementation is OK */
+                               /* Only a BTREE_SINGLE can be BTREE_UNORDERED */
+
+int sqlite3BtreeClose(Btree*);
+
+/* 
+**********************************************
+**   Database Image Configuration and Querying
+**********************************************
 */
-#define SQLITE_N_BTREE_META 16
 
 /*
 ** If defined as non-zero, auto-vacuum is enabled by default. Otherwise
@@ -33,132 +115,148 @@
 #define BTREE_AUTOVACUUM_FULL 1        /* Do full auto-vacuum */
 #define BTREE_AUTOVACUUM_INCR 2        /* Incremental vacuum */
 
-/*
-** Forward declarations of structure
-*/
-typedef struct Btree Btree;
-typedef struct BtCursor BtCursor;
-typedef struct BtShared BtShared;
-typedef struct BtreePayload BtreePayload;
+int sqlite3BtreeSetPageSize(Btree *p, int nPagesize, int nReserve, int eFix);
+int sqlite3BtreeGetPageSize(Btree*);
 
+int sqlite3BtreeSetAutoVacuum(Btree *, int);
+int sqlite3BtreeGetAutoVacuum(Btree *);
 
-int sqlite3BtreeOpen(
-  sqlite3_vfs *pVfs,       /* VFS to use with this b-tree */
-  const char *zFilename,   /* Name of database file to open */
-  sqlite3 *db,             /* Associated database connection */
-  Btree **ppBtree,         /* Return open Btree* here */
-  int flags,               /* Flags */
-  int vfsFlags             /* Flags passed through to VFS open */
-);
-
-/* The flags parameter to sqlite3BtreeOpen can be the bitwise or of the
-** following values.
-**
-** NOTE:  These values must match the corresponding PAGER_ values in
-** pager.h.
-*/
-#define BTREE_OMIT_JOURNAL  1  /* Do not create or use a rollback journal */
-#define BTREE_MEMORY        2  /* This is an in-memory DB */
-#define BTREE_SINGLE        4  /* The file contains at most 1 b-tree */
-#define BTREE_UNORDERED     8  /* Use of a hash implementation is OK */
-
-int sqlite3BtreeClose(Btree*);
-int sqlite3BtreeSetCacheSize(Btree*,int);
 int sqlite3BtreeSetSpillSize(Btree*,int);
 #if SQLITE_MAX_MMAP_SIZE>0
   int sqlite3BtreeSetMmapLimit(Btree*,sqlite3_int64);
 #endif
 int sqlite3BtreeSetPagerFlags(Btree*,unsigned);
-int sqlite3BtreeSetPageSize(Btree *p, int nPagesize, int nReserve, int eFix);
-int sqlite3BtreeGetPageSize(Btree*);
-Pgno sqlite3BtreeMaxPageCount(Btree*,Pgno);
-Pgno sqlite3BtreeLastPage(Btree*);
 int sqlite3BtreeSecureDelete(Btree*,int);
 int sqlite3BtreeGetRequestedReserve(Btree*);
 int sqlite3BtreeGetReserveNoMutex(Btree *p);
-int sqlite3BtreeSetAutoVacuum(Btree *, int);
-int sqlite3BtreeGetAutoVacuum(Btree *);
+
+/* Implements PRAGMA integrity_check on a Btree and its associated file.
+ * Only called from vdbe.c/OP_IntegrityCk */
+char *sqlite3BtreeIntegrityCheck(sqlite3*,Btree*,Pgno*aRoot,int nRoot,int,int*);
+
+/* A single step of an incremental vacuum. For PRAGMA incremental_vacuum(N) */
+/* Neither autovacuum mode nor the VACUUM SQLite command use this function. */
+int sqlite3BtreeIncrVacuum(Btree *);
+
+/* Copy a complete Btree into another Btree, ie from one file into another */
+/* Used only in the case of a backup and vacuum operations */
+int sqlite3BtreeCopyFile(Btree *, Btree *);
+
+
+/*
+************************************************
+**   Btree Connection Configuration and Querying
+************************************************
+*/
+
+
+int sqlite3BtreeSetCacheSize(Btree*,int);
+Pgno sqlite3BtreeMaxPageCount(Btree*,Pgno);
+Pgno sqlite3BtreeLastPage(Btree*);
+const char *sqlite3BtreeGetFilename(Btree *);
+const char *sqlite3BtreeGetJournalname(Btree *);
+
+int sqlite3BtreeIsReadonly(Btree *pBt);
+
+/* Estimate number of rows in table
+ * called only by OP IsSmaller, from PRAGMA optimize
+*/
+i64 sqlite3BtreeRowCountEst(BtCursor*);  
+
+/* Return the pager associated with a BTree */
+struct Pager *sqlite3BtreePager(Btree*);
+
+
+/*
+****************************
+**   Mutex Function Wrappers 
+****************************
+**
+** Every lock applies to an entire BTree. These functions are
+** wrappers for the sqlite3_mutex* functions, which are called  
+** outside btree.c
+*/
+
+/*
+** If we are not using shared cache, then there is no need to
+** use mutexes to access the BtShared structures.  So make the
+** Enter and Leave procedures no-ops.
+*/
+#ifndef SQLITE_OMIT_SHARED_CACHE
+  void sqlite3BtreeEnter(Btree*);
+  void sqlite3BtreeEnterAll(sqlite3*);
+  int sqlite3BtreeSharable(Btree*);
+  void sqlite3BtreeEnterCursor(BtCursor*);
+  int sqlite3BtreeConnectionCount(Btree*);
+#else
+# define sqlite3BtreeEnter(X) 
+# define sqlite3BtreeEnterAll(X)
+# define sqlite3BtreeSharable(X) 0
+# define sqlite3BtreeEnterCursor(X)
+# define sqlite3BtreeConnectionCount(X) 1
+#endif
+
+#if !defined(SQLITE_OMIT_SHARED_CACHE) && SQLITE_THREADSAFE
+  void sqlite3BtreeLeave(Btree*);
+  void sqlite3BtreeLeaveCursor(BtCursor*);
+  void sqlite3BtreeLeaveAll(sqlite3*);
+#ifndef NDEBUG
+  /* These routines are used inside assert() statements only. */
+  int sqlite3BtreeHoldsMutex(Btree*);
+  int sqlite3BtreeHoldsAllMutexes(sqlite3*);
+  int sqlite3SchemaMutexHeld(sqlite3*,int,Schema*);
+#endif
+#else
+
+# define sqlite3BtreeLeave(X)
+# define sqlite3BtreeLeaveCursor(X)
+# define sqlite3BtreeLeaveAll(X)
+
+# define sqlite3BtreeHoldsMutex(X) 1
+# define sqlite3BtreeHoldsAllMutexes(X) 1
+# define sqlite3SchemaMutexHeld(X,Y,Z) 1
+#endif
+
+
+/*
+****************************************
+**   Transaction and SavePoint Functions
+****************************************
+*/
+
 int sqlite3BtreeBeginTrans(Btree*,int,int*);
-int sqlite3BtreeCommitPhaseOne(Btree*, const char*);
+int sqlite3BtreeCommitPhaseOne(Btree*, const char *zMaster);
 int sqlite3BtreeCommitPhaseTwo(Btree*, int);
 int sqlite3BtreeCommit(Btree*);
 int sqlite3BtreeRollback(Btree*,int,int);
-int sqlite3BtreeBeginStmt(Btree*,int);
 int sqlite3BtreeCreateTable(Btree*, Pgno*, int flags);
 int sqlite3BtreeTxnState(Btree*);
 int sqlite3BtreeIsInBackup(Btree*);
 
-void *sqlite3BtreeSchema(Btree *, int, void(*)(void *));
-int sqlite3BtreeSchemaLocked(Btree *pBtree);
-#ifndef SQLITE_OMIT_SHARED_CACHE
-int sqlite3BtreeLockTable(Btree *pBtree, int iTab, u8 isWriteLock);
-#endif
-
-/* Savepoints are named, nestable SQL transactions mostly implemented */ 
+/* Savepoints are named, nestable SQL transactions mostly implemented */
 /* in vdbe.c and pager.c See https://sqlite.org/lang_savepoint.html */
 int sqlite3BtreeSavepoint(Btree *, int, int);
 
-/* "Checkpoint" only refers to WAL. See https://sqlite.org/wal.html#ckpt */
+/* A statement sub-transaction is an internal-only transaction used */
+/* only by OP_Transaction, see comments in vdbe.c. A statement */
+/* sub-transaction is implemented as an anonymous savepoint. */
+int sqlite3BtreeBeginStmt(Btree*,int);
+
+/* A checkpoint refers to only to WAL. See https://sqlite.org/wal.html#ckpt */
 #ifndef SQLITE_OMIT_WAL
   int sqlite3BtreeCheckpoint(Btree*, int, int *, int *);  
 #endif
 
-const char *sqlite3BtreeGetFilename(Btree *);
-const char *sqlite3BtreeGetJournalname(Btree *);
-int sqlite3BtreeCopyFile(Btree *, Btree *);
-
-int sqlite3BtreeIncrVacuum(Btree *);
-
-/* The flags parameter to sqlite3BtreeCreateTable can be the bitwise OR
-** of the flags shown below.
-**
-** Every SQLite table must have either BTREE_INTKEY or BTREE_BLOBKEY set.
-** With BTREE_INTKEY, the table key is a 64-bit integer and arbitrary data
-** is stored in the leaves.  (BTREE_INTKEY is used for SQL tables.)  With
-** BTREE_BLOBKEY, the key is an arbitrary BLOB and no content is stored
-** anywhere - the key is the content.  (BTREE_BLOBKEY is used for SQL
-** indices.)
-*/
-#define BTREE_INTKEY     1    /* Table has only 64-bit signed integer keys */
-#define BTREE_BLOBKEY    2    /* Table has keys only - no data */
-
-int sqlite3BtreeDropTable(Btree*, int, int*);
-int sqlite3BtreeClearTable(Btree*, int, int*);
-int sqlite3BtreeClearTableOfCursor(BtCursor*);
+/* Set all relevant cursors to error state on transaction rollback */
 int sqlite3BtreeTripAllCursors(Btree*, int, int);
 
-void sqlite3BtreeGetMeta(Btree *pBtree, int idx, u32 *pValue);
-int sqlite3BtreeUpdateMeta(Btree*, int idx, u32 value);
-
-int sqlite3BtreeNewDb(Btree *p);
 
 /*
-** The second parameter to sqlite3BtreeGetMeta or sqlite3BtreeUpdateMeta
-** should be one of the following values. The integer values are assigned 
-** to constants so that the offset of the corresponding field in an
-** SQLite database header may be found using the following formula:
+*********************************
+**   Cursors and Cursor functions
+*********************************
 **
-**   offset = 36 + (idx * 4)
-**
-** For example, the free-page-count field is located at byte offset 36 of
-** the database file header. The incr-vacuum-flag field is located at
-** byte offset 64 (== 36+4*7).
-**
-** The BTREE_DATA_VERSION value is not really a value stored in the header.
-** It is a read-only number computed by the pager.  But we merge it with
-** the header value access routines since its access pattern is the same.
-** Call it a "virtual meta value".
 */
-#define BTREE_FREE_PAGE_COUNT     0
-#define BTREE_SCHEMA_VERSION      1
-#define BTREE_FILE_FORMAT         2
-#define BTREE_DEFAULT_CACHE_SIZE  3
-#define BTREE_LARGEST_ROOT_PAGE   4
-#define BTREE_TEXT_ENCODING       5
-#define BTREE_USER_VERSION        6
-#define BTREE_INCR_VACUUM         7
-#define BTREE_APPLICATION_ID      8
-#define BTREE_DATA_VERSION        15  /* A virtual meta-value */
 
 /*
 ** Kinds of hints that can be passed into the sqlite3BtreeCursorHint()
@@ -233,12 +331,28 @@ int sqlite3BtreeNewDb(Btree *p);
 
 int sqlite3BtreeCursor(
   Btree*,                              /* BTree containing table to open */
-  Pgno iTable,                         /* Index of root page */
+  Pgno iTable,                          /* Index of root page */
   int wrFlag,                          /* 1 for writing.  0 for read-only */
   struct KeyInfo*,                     /* First argument to compare function */
   BtCursor *pCursor                    /* Space to write cursor structure */
 );
+
+/* True if hint specified, used in or around assert statements only */
+int sqlite3BtreeCursorHasHint(BtCursor*, unsigned int mask); 
+
 BtCursor *sqlite3BtreeFakeValidCursor(void);
+
+#ifdef SQLITE_DEBUG
+sqlite3_uint64 sqlite3BtreeSeekCount(Btree*);
+#else
+# define sqlite3BtreeSeekCount(X) 0
+#endif
+
+#ifndef NDEBUG
+int sqlite3BtreeCursorIsValid(BtCursor*); 
+#endif
+int sqlite3BtreeCursorIsValidNN(BtCursor*);
+
 int sqlite3BtreeCursorSize(void);
 void sqlite3BtreeCursorZero(BtCursor*);
 void sqlite3BtreeCursorHintFlags(BtCursor*, unsigned);
@@ -246,7 +360,10 @@ void sqlite3BtreeCursorHintFlags(BtCursor*, unsigned);
 void sqlite3BtreeCursorHint(BtCursor*, int, ...);
 #endif
 
+void sqlite3BtreeClearCursor(BtCursor *);
 int sqlite3BtreeCloseCursor(BtCursor*);
+
+/* Cursor seek to a specified rowid in the Btree */
 int sqlite3BtreeMovetoUnpacked(
   BtCursor*,
   UnpackedRecord *pUnKey,
@@ -254,9 +371,42 @@ int sqlite3BtreeMovetoUnpacked(
   int bias,
   int *pRes
 );
-int sqlite3BtreeCursorHasMoved(BtCursor*);
-int sqlite3BtreeCursorRestore(BtCursor*, int*);
-int sqlite3BtreeDelete(BtCursor*, u8 flags);
+
+int sqlite3BtreeFirst(BtCursor*, int *pRes);
+int sqlite3BtreeLast(BtCursor*, int *pRes);
+int sqlite3BtreeNext(BtCursor*, int flags);
+int sqlite3BtreeEof(BtCursor*);
+int sqlite3BtreePrevious(BtCursor*, int flags);
+i64 sqlite3BtreeIntegerKey(BtCursor*); 
+
+int sqlite3BtreeCount(sqlite3*, BtCursor*, i64*);
+
+
+void *sqlite3BtreeSchema(Btree *, int, void(*)(void *));
+int sqlite3BtreeSchemaLocked(Btree *pBtree);
+#ifndef SQLITE_OMIT_SHARED_CACHE
+int sqlite3BtreeLockTable(Btree *pBtree, int iTab, u8 isWriteLock);
+#endif
+void sqlite3BtreeCursorPin(BtCursor*);  
+void sqlite3BtreeCursorUnpin(BtCursor*); 
+
+int sqlite3BtreeCursorHasMoved(BtCursor*);  
+int sqlite3BtreeCursorRestore(BtCursor*, int*); 
+
+#ifdef SQLITE_TEST
+int sqlite3BtreeCursorInfo(BtCursor*, int*, int);  
+void sqlite3BtreeCursorList(Btree*);
+#endif
+
+/*
+******************************************
+**   Record and Payload handling functions
+******************************************
+**
+** A Btree record is a key-value pair consisting of a rowid key, and arbitary 
+** data value. The record is also called a payload.
+**
+*/
 
 /* Allowed flags for sqlite3BtreeDelete() and sqlite3BtreeInsert() */
 #define BTREE_SAVEPOSITION 0x02  /* Leave cursor pointing at NEXT or PREV */
@@ -308,98 +458,114 @@ struct BtreePayload {
 
 int sqlite3BtreeInsert(BtCursor*, const BtreePayload *pPayload,
                        int flags, int seekResult);
-int sqlite3BtreeFirst(BtCursor*, int *pRes);
-int sqlite3BtreeLast(BtCursor*, int *pRes);
-int sqlite3BtreeNext(BtCursor*, int flags);
-int sqlite3BtreeEof(BtCursor*);
-int sqlite3BtreePrevious(BtCursor*, int flags);
-i64 sqlite3BtreeIntegerKey(BtCursor*);
-void sqlite3BtreeCursorPin(BtCursor*);
-void sqlite3BtreeCursorUnpin(BtCursor*);
+
+int sqlite3BtreeDelete(BtCursor*, u8 flags);
+
 #ifdef SQLITE_ENABLE_OFFSET_SQL_FUNC
 i64 sqlite3BtreeOffset(BtCursor*);
 #endif
 int sqlite3BtreePayload(BtCursor*, u32 offset, u32 amt, void*);
 const void *sqlite3BtreePayloadFetch(BtCursor*, u32 *pAmt);
 u32 sqlite3BtreePayloadSize(BtCursor*);
-sqlite3_int64 sqlite3BtreeMaxRecordSize(BtCursor*);
-
-char *sqlite3BtreeIntegrityCheck(sqlite3*,Btree*,Pgno*aRoot,int nRoot,int,int*);
-struct Pager *sqlite3BtreePager(Btree*);
-i64 sqlite3BtreeRowCountEst(BtCursor*);
 
+/* These functions deal with arbitary-sized binary blobs in a Btree */
 #ifndef SQLITE_OMIT_INCRBLOB
 int sqlite3BtreePayloadChecked(BtCursor*, u32 offset, u32 amt, void*);
 int sqlite3BtreePutData(BtCursor*, u32 offset, u32 amt, void*);
 void sqlite3BtreeIncrblobCursor(BtCursor *);
 #endif
-void sqlite3BtreeClearCursor(BtCursor *);
-int sqlite3BtreeSetVersion(Btree *pBt, int iVersion);
-int sqlite3BtreeCursorHasHint(BtCursor*, unsigned int mask);
-int sqlite3BtreeIsReadonly(Btree *pBt);
-int sqlite3HeaderSizeBtree(void);
 
-#ifdef SQLITE_DEBUG
-sqlite3_uint64 sqlite3BtreeSeekCount(Btree*);
-#else
-# define sqlite3BtreeSeekCount(X) 0
-#endif
 
-#ifndef NDEBUG
-int sqlite3BtreeCursorIsValid(BtCursor*);
-#endif
-int sqlite3BtreeCursorIsValidNN(BtCursor*);
-
-int sqlite3BtreeCount(sqlite3*, BtCursor*, i64*);
-
-#ifdef SQLITE_TEST
-int sqlite3BtreeCursorInfo(BtCursor*, int*, int);
-void sqlite3BtreeCursorList(Btree*);
-#endif
-
-#ifndef SQLITE_OMIT_WAL
-  int sqlite3BtreeCheckpoint(Btree*, int, int *, int *);
-#endif
 
 /*
-** If we are not using shared cache, then there is no need to
-** use mutexes to access the BtShared structures.  So make the
-** Enter and Leave procedures no-ops.
+********************
+**   Table functions
+********************
+**
 */
-#ifndef SQLITE_OMIT_SHARED_CACHE
-  void sqlite3BtreeEnter(Btree*);
-  void sqlite3BtreeEnterAll(sqlite3*);
-  int sqlite3BtreeSharable(Btree*);
-  void sqlite3BtreeEnterCursor(BtCursor*);
-  int sqlite3BtreeConnectionCount(Btree*);
-#else
-# define sqlite3BtreeEnter(X) 
-# define sqlite3BtreeEnterAll(X)
-# define sqlite3BtreeSharable(X) 0
-# define sqlite3BtreeEnterCursor(X)
-# define sqlite3BtreeConnectionCount(X) 1
-#endif
 
-#if !defined(SQLITE_OMIT_SHARED_CACHE) && SQLITE_THREADSAFE
-  void sqlite3BtreeLeave(Btree*);
-  void sqlite3BtreeLeaveCursor(BtCursor*);
-  void sqlite3BtreeLeaveAll(sqlite3*);
-#ifndef NDEBUG
-  /* These routines are used inside assert() statements only. */
-  int sqlite3BtreeHoldsMutex(Btree*);
-  int sqlite3BtreeHoldsAllMutexes(sqlite3*);
-  int sqlite3SchemaMutexHeld(sqlite3*,int,Schema*);
-#endif
-#else
+/* The flags parameter to sqlite3BtreeCreateTable can be the bitwise OR
+** of the flags shown below.
+**
+** Every SQLite table must have either BTREE_INTKEY or BTREE_BLOBKEY set.
+** With BTREE_INTKEY, the table key is a 64-bit integer and arbitrary data
+** is stored in the leaves.  (BTREE_INTKEY is used for SQL tables.)  With
+** BTREE_BLOBKEY, the key is an arbitrary BLOB and no content is stored
+** anywhere - the key is the content.  (BTREE_BLOBKEY is used for SQL
+** indices.)
+*/
 
-# define sqlite3BtreeLeave(X)
-# define sqlite3BtreeLeaveCursor(X)
-# define sqlite3BtreeLeaveAll(X)
+#define BTREE_INTKEY     1    /* Table has only 64-bit signed integer keys */
+#define BTREE_BLOBKEY    2    /* Table has keys only - no data */
 
-# define sqlite3BtreeHoldsMutex(X) 1
-# define sqlite3BtreeHoldsAllMutexes(X) 1
-# define sqlite3SchemaMutexHeld(X,Y,Z) 1
-#endif
+int sqlite3BtreeDropTable(Btree*, int, int*);
+int sqlite3BtreeClearTable(Btree*, int, int*);
+int sqlite3BtreeClearTableOfCursor(BtCursor*);
+
+
+/*
+*********************************
+**   Reading and Writing Metadata
+*********************************
+**
+** Note there is metadata which is not in the first database page
+** including (as below) some visible via the os.h API
+*/
+
+
+/*
+** The second parameter to sqlite3BtreeGetMeta or sqlite3BtreeUpdateMeta
+** should be one of the following values. The integer values are assigned 
+** to constants so that the offset of the corresponding field in an
+** SQLite database header may be found using the following formula:
+**
+**   offset = 36 + (idx * 4)
+**
+** For example, the free-page-count field is located at byte offset 36 of
+** the database file header. The incr-vacuum-flag field is located at
+** byte offset 64 (== 36+4*7).
+**
+** The BTREE_DATA_VERSION value is not really a value stored in the header.
+** It is a read-only number computed by the pager.  But we merge it with
+** the header value access routines since its access pattern is the same.
+** Call it a "virtual meta value".
+*/
+#define BTREE_FREE_PAGE_COUNT     0
+#define BTREE_SCHEMA_VERSION      1
+#define BTREE_FILE_FORMAT         2
+#define BTREE_DEFAULT_CACHE_SIZE  3
+#define BTREE_LARGEST_ROOT_PAGE   4
+#define BTREE_TEXT_ENCODING       5
+#define BTREE_USER_VERSION        6
+#define BTREE_INCR_VACUUM         7
+#define BTREE_APPLICATION_ID      8
+#define BTREE_DATA_VERSION        15  /* A virtual meta-value */
+
+
+/* Refers to the size of the per-page header, not per-database header */
+/* Used for configuring the size of the pages in the page cache */
+int sqlite3HeaderSizeBtree(void);
+
+/* TODO: This definition is only used in asserts to determine whether 
+ * the metadata index (second parameter of Get/UpdateMeta functions) 
+ * is out of range. It is only included here so other modules compile. It
+ * ** needs to be revisited.
+ * */
+#define SQLITE_N_BTREE_META 16
+
+void sqlite3BtreeGetMeta(Btree *pBtree, int idx, u32 *pValue);
+int sqlite3BtreeUpdateMeta(Btree*, int idx, u32 value);
+
+/* This returns the size of the current database file, ie the same */
+/* result as sqlite3OsFileSize in os.h . */
+sqlite3_int64 sqlite3BtreeMaxRecordSize(BtCursor*);
+
+/* Version number of the file format must be either 1 or 2 */
+/* 1=legacy, 2=WAL . Read and write versions set to same value */
+int sqlite3BtreeSetVersion(Btree *pBt, int iVersion); 
+
+/* Initialize the first page of the database file and return */
+int sqlite3BtreeNewDb(Btree *p);
 
 
 #endif /* SQLITE_BTREE_H */

src/sqliteInt.h

@@ -17,15 +17,16 @@
 
 /* Special Comments:
 **
-** Some comments have special meaning to the tools that measure test
-** coverage:
+** Some comments have special meaning to the external tools that measure test
+** coverage of conditional brances (MC/DC testing, described in
+** https://en.wikipedia.org/wiki/Modified_condition/decision_coverage ).
 **
 **    NO_TEST                     - The branches on this line are not
 **                                  measured by branch coverage.  This is
 **                                  used on lines of code that actually
 **                                  implement parts of coverage testing.
 **
-**    OPTIMIZATION-IF-TRUE        - This branch is allowed to alway be false
+**    OPTIMIZATION-IF-TRUE        - This branch is allowed to always be false
 **                                  and the correct answer is still obtained,
 **                                  though perhaps more slowly.
 **
@@ -35,7 +36,11 @@
 **
 **    PREVENTS-HARMLESS-OVERREAD  - This branch prevents a buffer overread
 **                                  that would be harmless and undetectable
-**                                  if it did occur.  
+**                                  if it did occur.
+**
+** The OPTIMIZATION-* comments above are for mutation testing as described in
+** https://en.wikipedia.org/wiki/Mutation_testing and
+** https://www.sqlite.org/testing.html#mutationtests .
 **
 ** In all cases, the special comment must be enclosed in the usual
 ** slash-asterisk...asterisk-slash comment marks, with no spaces between the