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 _PAGER_H_ 18 #define _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_MJ_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 master journal name - there are no more pages to 50 ** roll back. See comments for function writeMasterJournal() in pager.c 51 ** for details. 52 */ 53 #define PAGER_MJ_PGNO(x) ((Pgno)((PENDING_BYTE/((x)->pageSize))+1)) 54 55 /* 56 ** Allowed values for the flags parameter to sqlite3PagerOpen(). 57 ** 58 ** NOTE: These values must match the corresponding BTREE_ values in btree.h. 59 */ 60 #define PAGER_OMIT_JOURNAL 0x0001 /* Do not use a rollback journal */ 61 #define PAGER_MEMORY 0x0002 /* In-memory database */ 62 63 /* 64 ** Valid values for the second argument to sqlite3PagerLockingMode(). 65 */ 66 #define PAGER_LOCKINGMODE_QUERY -1 67 #define PAGER_LOCKINGMODE_NORMAL 0 68 #define PAGER_LOCKINGMODE_EXCLUSIVE 1 69 70 /* 71 ** Numeric constants that encode the journalmode. 72 */ 73 #define PAGER_JOURNALMODE_QUERY (-1) /* Query the value of journalmode */ 74 #define PAGER_JOURNALMODE_DELETE 0 /* Commit by deleting journal file */ 75 #define PAGER_JOURNALMODE_PERSIST 1 /* Commit by zeroing journal header */ 76 #define PAGER_JOURNALMODE_OFF 2 /* Journal omitted. */ 77 #define PAGER_JOURNALMODE_TRUNCATE 3 /* Commit by truncating journal */ 78 #define PAGER_JOURNALMODE_MEMORY 4 /* In-memory journal file */ 79 #define PAGER_JOURNALMODE_WAL 5 /* Use write-ahead logging */ 80 81 /* 82 ** The remainder of this file contains the declarations of the functions 83 ** that make up the Pager sub-system API. See source code comments for 84 ** a detailed description of each routine. 85 */ 86 87 /* Open and close a Pager connection. */ 88 int sqlite3PagerOpen( 89 sqlite3_vfs*, 90 Pager **ppPager, 91 const char*, 92 int, 93 int, 94 int, 95 void(*)(DbPage*) 96 ); 97 int sqlite3PagerClose(Pager *pPager); 98 int sqlite3PagerReadFileheader(Pager*, int, unsigned char*); 99 100 /* Functions used to configure a Pager object. */ 101 void sqlite3PagerSetBusyhandler(Pager*, int(*)(void *), void *); 102 int sqlite3PagerSetPagesize(Pager*, u32*, int); 103 int sqlite3PagerMaxPageCount(Pager*, int); 104 void sqlite3PagerSetCachesize(Pager*, int); 105 void sqlite3PagerShrink(Pager*); 106 void sqlite3PagerSetSafetyLevel(Pager*,int,int,int); 107 int sqlite3PagerLockingMode(Pager *, int); 108 int sqlite3PagerSetJournalMode(Pager *, int); 109 int sqlite3PagerGetJournalMode(Pager*); 110 int sqlite3PagerOkToChangeJournalMode(Pager*); 111 i64 sqlite3PagerJournalSizeLimit(Pager *, i64); 112 sqlite3_backup **sqlite3PagerBackupPtr(Pager*); 113 114 /* Functions used to obtain and release page references. */ 115 int sqlite3PagerAcquire(Pager *pPager, Pgno pgno, DbPage **ppPage, int clrFlag); 116 #define sqlite3PagerGet(A,B,C) sqlite3PagerAcquire(A,B,C,0) 117 DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno); 118 void sqlite3PagerRef(DbPage*); 119 void sqlite3PagerUnref(DbPage*); 120 121 /* Operations on page references. */ 122 int sqlite3PagerWrite(DbPage*); 123 void sqlite3PagerDontWrite(DbPage*); 124 int sqlite3PagerMovepage(Pager*,DbPage*,Pgno,int); 125 int sqlite3PagerPageRefcount(DbPage*); 126 void *sqlite3PagerGetData(DbPage *); 127 void *sqlite3PagerGetExtra(DbPage *); 128 129 /* Functions used to manage pager transactions and savepoints. */ 130 void sqlite3PagerPagecount(Pager*, int*); 131 int sqlite3PagerBegin(Pager*, int exFlag, int); 132 int sqlite3PagerCommitPhaseOne(Pager*,const char *zMaster, int); 133 int sqlite3PagerExclusiveLock(Pager*); 134 int sqlite3PagerSync(Pager *pPager); 135 int sqlite3PagerCommitPhaseTwo(Pager*); 136 int sqlite3PagerRollback(Pager*); 137 int sqlite3PagerOpenSavepoint(Pager *pPager, int n); 138 int sqlite3PagerSavepoint(Pager *pPager, int op, int iSavepoint); 139 int sqlite3PagerSharedLock(Pager *pPager); 140 141 int sqlite3PagerCheckpoint(Pager *pPager, int, int*, int*); 142 int sqlite3PagerWalSupported(Pager *pPager); 143 int sqlite3PagerWalCallback(Pager *pPager); 144 int sqlite3PagerOpenWal(Pager *pPager, int *pisOpen); 145 int sqlite3PagerCloseWal(Pager *pPager); 146 #ifdef SQLITE_ENABLE_ZIPVFS 147 int sqlite3PagerWalFramesize(Pager *pPager); 148 #endif 149 150 /* Functions used to query pager state and configuration. */ 151 u8 sqlite3PagerIsreadonly(Pager*); 152 int sqlite3PagerRefcount(Pager*); 153 int sqlite3PagerMemUsed(Pager*); 154 const char *sqlite3PagerFilename(Pager*, int); 155 const sqlite3_vfs *sqlite3PagerVfs(Pager*); 156 sqlite3_file *sqlite3PagerFile(Pager*); 157 const char *sqlite3PagerJournalname(Pager*); 158 int sqlite3PagerNosync(Pager*); 159 void *sqlite3PagerTempSpace(Pager*); 160 int sqlite3PagerIsMemdb(Pager*); 161 void sqlite3PagerCacheStat(Pager *, int, int, int *); 162 void sqlite3PagerClearCache(Pager *); 163 164 /* Functions used to truncate the database file. */ 165 void sqlite3PagerTruncateImage(Pager*,Pgno); 166 167 #if defined(SQLITE_HAS_CODEC) && !defined(SQLITE_OMIT_WAL) 168 void *sqlite3PagerCodec(DbPage *); 169 #endif 170 171 /* Functions to support testing and debugging. */ 172 #if !defined(NDEBUG) || defined(SQLITE_TEST) 173 Pgno sqlite3PagerPagenumber(DbPage*); 174 int sqlite3PagerIswriteable(DbPage*); 175 #endif 176 #ifdef SQLITE_TEST 177 int *sqlite3PagerStats(Pager*); 178 void sqlite3PagerRefdump(Pager*); 179 void disable_simulated_io_errors(void); 180 void enable_simulated_io_errors(void); 181 #else 182 # define disable_simulated_io_errors() 183 # define enable_simulated_io_errors() 184 #endif 185 186 #endif /* _PAGER_H_ */ 187