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 page cache 13 ** subsystem. The page cache subsystem reads and writes a file a page 14 ** at a time and provides a journal for rollback. 15 */ 16 17 #ifndef SQLITE_PAGER_H 18 #define SQLITE_PAGER_H 19 20 /* 21 ** Default maximum size for persistent journal files. A negative 22 ** value means no limit. This value may be overridden using the 23 ** sqlite3PagerJournalSizeLimit() API. See also "PRAGMA journal_size_limit". 24 */ 25 #ifndef SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT 26 #define SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT -1 27 #endif 28 29 /* 30 ** The type used to represent a page number. The first page in a file 31 ** is called page 1. 0 is used to represent "not a page". 32 */ 33 typedef u32 Pgno; 34 35 /* 36 ** Each open file is managed by a separate instance of the "Pager" structure. 37 */ 38 typedef struct Pager Pager; 39 40 /* 41 ** Handle type for pages. 42 */ 43 typedef struct PgHdr DbPage; 44 45 /* 46 ** Page number PAGER_SJ_PGNO is never used in an SQLite database (it is 47 ** reserved for working around a windows/posix incompatibility). It is 48 ** used in the journal to signify that the remainder of the journal file 49 ** is devoted to storing a super-journal name - there are no more pages to 50 ** roll back. See comments for function writeSuperJournal() in pager.c 51 ** for details. 52 */ 53 #define PAGER_SJ_PGNO_COMPUTED(x) ((Pgno)((PENDING_BYTE/((x)->pageSize))+1)) 54 #define PAGER_SJ_PGNO(x) ((x)->lckPgno) 55 56 /* 57 ** Allowed values for the flags parameter to sqlite3PagerOpen(). 58 ** 59 ** NOTE: These values must match the corresponding BTREE_ values in btree.h. 60 */ 61 #define PAGER_OMIT_JOURNAL 0x0001 /* Do not use a rollback journal */ 62 #define PAGER_MEMORY 0x0002 /* In-memory database */ 63 64 /* 65 ** Valid values for the second argument to sqlite3PagerLockingMode(). 66 */ 67 #define PAGER_LOCKINGMODE_QUERY -1 68 #define PAGER_LOCKINGMODE_NORMAL 0 69 #define PAGER_LOCKINGMODE_EXCLUSIVE 1 70 71 /* 72 ** Numeric constants that encode the journalmode. 73 ** 74 ** The numeric values encoded here (other than PAGER_JOURNALMODE_QUERY) 75 ** are exposed in the API via the "PRAGMA journal_mode" command and 76 ** therefore cannot be changed without a compatibility break. 77 */ 78 #define PAGER_JOURNALMODE_QUERY (-1) /* Query the value of journalmode */ 79 #define PAGER_JOURNALMODE_DELETE 0 /* Commit by deleting journal file */ 80 #define PAGER_JOURNALMODE_PERSIST 1 /* Commit by zeroing journal header */ 81 #define PAGER_JOURNALMODE_OFF 2 /* Journal omitted. */ 82 #define PAGER_JOURNALMODE_TRUNCATE 3 /* Commit by truncating journal */ 83 #define PAGER_JOURNALMODE_MEMORY 4 /* In-memory journal file */ 84 #define PAGER_JOURNALMODE_WAL 5 /* Use write-ahead logging */ 85 86 /* 87 ** Flags that make up the mask passed to sqlite3PagerGet(). 88 */ 89 #define PAGER_GET_NOCONTENT 0x01 /* Do not load data from disk */ 90 #define PAGER_GET_READONLY 0x02 /* Read-only page is acceptable */ 91 92 /* 93 ** Flags for sqlite3PagerSetFlags() 94 ** 95 ** Value constraints (enforced via assert()): 96 ** PAGER_FULLFSYNC == SQLITE_FullFSync 97 ** PAGER_CKPT_FULLFSYNC == SQLITE_CkptFullFSync 98 ** PAGER_CACHE_SPILL == SQLITE_CacheSpill 99 */ 100 #define PAGER_SYNCHRONOUS_OFF 0x01 /* PRAGMA synchronous=OFF */ 101 #define PAGER_SYNCHRONOUS_NORMAL 0x02 /* PRAGMA synchronous=NORMAL */ 102 #define PAGER_SYNCHRONOUS_FULL 0x03 /* PRAGMA synchronous=FULL */ 103 #define PAGER_SYNCHRONOUS_EXTRA 0x04 /* PRAGMA synchronous=EXTRA */ 104 #define PAGER_SYNCHRONOUS_MASK 0x07 /* Mask for four values above */ 105 #define PAGER_FULLFSYNC 0x08 /* PRAGMA fullfsync=ON */ 106 #define PAGER_CKPT_FULLFSYNC 0x10 /* PRAGMA checkpoint_fullfsync=ON */ 107 #define PAGER_CACHESPILL 0x20 /* PRAGMA cache_spill=ON */ 108 #define PAGER_FLAGS_MASK 0x38 /* All above except SYNCHRONOUS */ 109 110 /* 111 ** The remainder of this file contains the declarations of the functions 112 ** that make up the Pager sub-system API. See source code comments for 113 ** a detailed description of each routine. 114 */ 115 116 /* Open and close a Pager connection. */ 117 int sqlite3PagerOpen( 118 sqlite3_vfs*, 119 Pager **ppPager, 120 const char*, 121 int, 122 int, 123 int, 124 void(*)(DbPage*) 125 ); 126 int sqlite3PagerClose(Pager *pPager, sqlite3*); 127 int sqlite3PagerReadFileheader(Pager*, int, unsigned char*); 128 129 /* Functions used to configure a Pager object. */ 130 void sqlite3PagerSetBusyHandler(Pager*, int(*)(void *), void *); 131 int sqlite3PagerSetPagesize(Pager*, u32*, int); 132 Pgno sqlite3PagerMaxPageCount(Pager*, Pgno); 133 void sqlite3PagerSetCachesize(Pager*, int); 134 int sqlite3PagerSetSpillsize(Pager*, int); 135 void sqlite3PagerSetMmapLimit(Pager *, sqlite3_int64); 136 void sqlite3PagerShrink(Pager*); 137 void sqlite3PagerSetFlags(Pager*,unsigned); 138 int sqlite3PagerLockingMode(Pager *, int); 139 int sqlite3PagerSetJournalMode(Pager *, int); 140 int sqlite3PagerGetJournalMode(Pager*); 141 int sqlite3PagerOkToChangeJournalMode(Pager*); 142 i64 sqlite3PagerJournalSizeLimit(Pager *, i64); 143 sqlite3_backup **sqlite3PagerBackupPtr(Pager*); 144 int sqlite3PagerFlush(Pager*); 145 146 /* Functions used to obtain and release page references. */ 147 int sqlite3PagerGet(Pager *pPager, Pgno pgno, DbPage **ppPage, int clrFlag); 148 DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno); 149 void sqlite3PagerRef(DbPage*); 150 void sqlite3PagerUnref(DbPage*); 151 void sqlite3PagerUnrefNotNull(DbPage*); 152 void sqlite3PagerUnrefPageOne(DbPage*); 153 154 /* Operations on page references. */ 155 int sqlite3PagerWrite(DbPage*); 156 void sqlite3PagerDontWrite(DbPage*); 157 int sqlite3PagerMovepage(Pager*,DbPage*,Pgno,int); 158 int sqlite3PagerPageRefcount(DbPage*); 159 void *sqlite3PagerGetData(DbPage *); 160 void *sqlite3PagerGetExtra(DbPage *); 161 162 /* Functions used to manage pager transactions and savepoints. */ 163 void sqlite3PagerPagecount(Pager*, int*); 164 int sqlite3PagerBegin(Pager*, int exFlag, int); 165 int sqlite3PagerCommitPhaseOne(Pager*,const char *zSuper, int); 166 int sqlite3PagerExclusiveLock(Pager*); 167 int sqlite3PagerSync(Pager *pPager, const char *zSuper); 168 int sqlite3PagerCommitPhaseTwo(Pager*); 169 int sqlite3PagerRollback(Pager*); 170 int sqlite3PagerOpenSavepoint(Pager *pPager, int n); 171 int sqlite3PagerSavepoint(Pager *pPager, int op, int iSavepoint); 172 int sqlite3PagerSharedLock(Pager *pPager); 173 174 #ifndef SQLITE_OMIT_WAL 175 int sqlite3PagerCheckpoint(Pager *pPager, sqlite3*, int, int*, int*); 176 int sqlite3PagerWalSupported(Pager *pPager); 177 int sqlite3PagerWalCallback(Pager *pPager); 178 int sqlite3PagerOpenWal(Pager *pPager, int *pisOpen); 179 int sqlite3PagerCloseWal(Pager *pPager, sqlite3*); 180 # ifdef SQLITE_ENABLE_SNAPSHOT 181 int sqlite3PagerSnapshotGet(Pager*, sqlite3_snapshot **ppSnapshot); 182 int sqlite3PagerSnapshotOpen(Pager*, sqlite3_snapshot *pSnapshot); 183 int sqlite3PagerSnapshotRecover(Pager *pPager); 184 int sqlite3PagerSnapshotCheck(Pager *pPager, sqlite3_snapshot *pSnapshot); 185 void sqlite3PagerSnapshotUnlock(Pager *pPager); 186 # endif 187 #endif 188 189 #if !defined(SQLITE_OMIT_WAL) && defined(SQLITE_ENABLE_SETLK_TIMEOUT) 190 int sqlite3PagerWalWriteLock(Pager*, int); 191 void sqlite3PagerWalDb(Pager*, sqlite3*); 192 #else 193 # define sqlite3PagerWalWriteLock(y,z) SQLITE_OK 194 # define sqlite3PagerWalDb(x,y) 195 #endif 196 197 #ifdef SQLITE_DIRECT_OVERFLOW_READ 198 int sqlite3PagerDirectReadOk(Pager *pPager, Pgno pgno); 199 #endif 200 201 #ifdef SQLITE_ENABLE_ZIPVFS 202 int sqlite3PagerWalFramesize(Pager *pPager); 203 #endif 204 205 /* Functions used to query pager state and configuration. */ 206 u8 sqlite3PagerIsreadonly(Pager*); 207 u32 sqlite3PagerDataVersion(Pager*); 208 #ifdef SQLITE_DEBUG 209 int sqlite3PagerRefcount(Pager*); 210 #endif 211 int sqlite3PagerMemUsed(Pager*); 212 const char *sqlite3PagerFilename(const Pager*, int); 213 sqlite3_vfs *sqlite3PagerVfs(Pager*); 214 sqlite3_file *sqlite3PagerFile(Pager*); 215 sqlite3_file *sqlite3PagerJrnlFile(Pager*); 216 const char *sqlite3PagerJournalname(Pager*); 217 void *sqlite3PagerTempSpace(Pager*); 218 int sqlite3PagerIsMemdb(Pager*); 219 void sqlite3PagerCacheStat(Pager *, int, int, int *); 220 void sqlite3PagerClearCache(Pager*); 221 int sqlite3SectorSize(sqlite3_file *); 222 223 /* Functions used to truncate the database file. */ 224 void sqlite3PagerTruncateImage(Pager*,Pgno); 225 226 void sqlite3PagerRekey(DbPage*, Pgno, u16); 227 228 /* Functions to support testing and debugging. */ 229 #if !defined(NDEBUG) || defined(SQLITE_TEST) 230 Pgno sqlite3PagerPagenumber(DbPage*); 231 int sqlite3PagerIswriteable(DbPage*); 232 #endif 233 #ifdef SQLITE_TEST 234 int *sqlite3PagerStats(Pager*); 235 void sqlite3PagerRefdump(Pager*); 236 void disable_simulated_io_errors(void); 237 void enable_simulated_io_errors(void); 238 #else 239 # define disable_simulated_io_errors() 240 # define enable_simulated_io_errors() 241 #endif 242 243 #endif /* SQLITE_PAGER_H */ 244