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 ** @(#) $Id: pager.h,v 1.101 2009/04/30 09:10:38 danielk1977 Exp $ 17 */ 18 19 #ifndef _PAGER_H_ 20 #define _PAGER_H_ 21 22 /* 23 ** Default maximum size for persistent journal files. A negative 24 ** value means no limit. This value may be overridden using the 25 ** sqlite3PagerJournalSizeLimit() API. See also "PRAGMA journal_size_limit". 26 */ 27 #ifndef SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT 28 #define SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT -1 29 #endif 30 31 /* 32 ** The type used to represent a page number. The first page in a file 33 ** is called page 1. 0 is used to represent "not a page". 34 */ 35 typedef u32 Pgno; 36 37 /* 38 ** Each open file is managed by a separate instance of the "Pager" structure. 39 */ 40 typedef struct Pager Pager; 41 42 /* 43 ** Handle type for pages. 44 */ 45 typedef struct PgHdr DbPage; 46 47 /* 48 ** Page number PAGER_MJ_PGNO is never used in an SQLite database (it is 49 ** reserved for working around a windows/posix incompatibility). It is 50 ** used in the journal to signify that the remainder of the journal file 51 ** is devoted to storing a master journal name - there are no more pages to 52 ** roll back. See comments for function writeMasterJournal() in pager.c 53 ** for details. 54 */ 55 #define PAGER_MJ_PGNO(x) ((Pgno)((PENDING_BYTE/((x)->pageSize))+1)) 56 57 /* 58 ** Allowed values for the flags parameter to sqlite3PagerOpen(). 59 ** 60 ** NOTE: These values must match the corresponding BTREE_ values in btree.h. 61 */ 62 #define PAGER_OMIT_JOURNAL 0x0001 /* Do not use a rollback journal */ 63 #define PAGER_NO_READLOCK 0x0002 /* Omit readlocks on readonly files */ 64 65 /* 66 ** Valid values for the second argument to sqlite3PagerLockingMode(). 67 */ 68 #define PAGER_LOCKINGMODE_QUERY -1 69 #define PAGER_LOCKINGMODE_NORMAL 0 70 #define PAGER_LOCKINGMODE_EXCLUSIVE 1 71 72 /* 73 ** Valid values for the second argument to sqlite3PagerJournalMode(). 74 */ 75 #define PAGER_JOURNALMODE_QUERY -1 76 #define PAGER_JOURNALMODE_DELETE 0 /* Commit by deleting journal file */ 77 #define PAGER_JOURNALMODE_PERSIST 1 /* Commit by zeroing journal header */ 78 #define PAGER_JOURNALMODE_OFF 2 /* Journal omitted. */ 79 #define PAGER_JOURNALMODE_TRUNCATE 3 /* Commit by truncating journal */ 80 #define PAGER_JOURNALMODE_MEMORY 4 /* In-memory journal file */ 81 82 /* 83 ** The remainder of this file contains the declarations of the functions 84 ** that make up the Pager sub-system API. See source code comments for 85 ** a detailed description of each routine. 86 */ 87 88 /* Open and close a Pager connection. */ 89 int sqlite3PagerOpen(sqlite3_vfs *, Pager **ppPager, const char*, int,int,int); 90 int sqlite3PagerClose(Pager *pPager); 91 int sqlite3PagerReadFileheader(Pager*, int, unsigned char*); 92 93 /* Functions used to configure a Pager object. */ 94 void sqlite3PagerSetBusyhandler(Pager*, int(*)(void *), void *); 95 void sqlite3PagerSetReiniter(Pager*, void(*)(DbPage*)); 96 int sqlite3PagerSetPagesize(Pager*, u16*); 97 int sqlite3PagerMaxPageCount(Pager*, int); 98 void sqlite3PagerSetCachesize(Pager*, int); 99 void sqlite3PagerSetSafetyLevel(Pager*,int,int); 100 int sqlite3PagerLockingMode(Pager *, int); 101 int sqlite3PagerJournalMode(Pager *, int); 102 i64 sqlite3PagerJournalSizeLimit(Pager *, i64); 103 sqlite3_backup **sqlite3PagerBackupPtr(Pager*); 104 105 /* Functions used to obtain and release page references. */ 106 int sqlite3PagerAcquire(Pager *pPager, Pgno pgno, DbPage **ppPage, int clrFlag); 107 #define sqlite3PagerGet(A,B,C) sqlite3PagerAcquire(A,B,C,0) 108 DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno); 109 void sqlite3PagerRef(DbPage*); 110 void sqlite3PagerUnref(DbPage*); 111 112 /* Operations on page references. */ 113 int sqlite3PagerWrite(DbPage*); 114 void sqlite3PagerDontWrite(DbPage*); 115 int sqlite3PagerMovepage(Pager*,DbPage*,Pgno,int); 116 int sqlite3PagerPageRefcount(DbPage*); 117 void *sqlite3PagerGetData(DbPage *); 118 void *sqlite3PagerGetExtra(DbPage *); 119 120 /* Functions used to manage pager transactions and savepoints. */ 121 int sqlite3PagerPagecount(Pager*, int*); 122 int sqlite3PagerBegin(Pager*, int exFlag, int); 123 int sqlite3PagerCommitPhaseOne(Pager*,const char *zMaster, int); 124 int sqlite3PagerSync(Pager *pPager); 125 int sqlite3PagerCommitPhaseTwo(Pager*); 126 int sqlite3PagerRollback(Pager*); 127 int sqlite3PagerOpenSavepoint(Pager *pPager, int n); 128 int sqlite3PagerSavepoint(Pager *pPager, int op, int iSavepoint); 129 130 /* Functions used to query pager state and configuration. */ 131 u8 sqlite3PagerIsreadonly(Pager*); 132 int sqlite3PagerRefcount(Pager*); 133 const char *sqlite3PagerFilename(Pager*); 134 const sqlite3_vfs *sqlite3PagerVfs(Pager*); 135 sqlite3_file *sqlite3PagerFile(Pager*); 136 const char *sqlite3PagerJournalname(Pager*); 137 int sqlite3PagerNosync(Pager*); 138 void *sqlite3PagerTempSpace(Pager*); 139 int sqlite3PagerIsMemdb(Pager*); 140 141 /* Functions used to truncate the database file. */ 142 void sqlite3PagerTruncateImage(Pager*,Pgno); 143 144 /* Used by encryption extensions. */ 145 #ifdef SQLITE_HAS_CODEC 146 void sqlite3PagerSetCodec(Pager*,void*(*)(void*,void*,Pgno,int),void*); 147 #endif 148 149 /* Functions to support testing and debugging. */ 150 #if !defined(NDEBUG) || defined(SQLITE_TEST) 151 Pgno sqlite3PagerPagenumber(DbPage*); 152 int sqlite3PagerIswriteable(DbPage*); 153 #endif 154 #ifdef SQLITE_TEST 155 int *sqlite3PagerStats(Pager*); 156 void sqlite3PagerRefdump(Pager*); 157 void disable_simulated_io_errors(void); 158 void enable_simulated_io_errors(void); 159 #else 160 # define disable_simulated_io_errors() 161 # define enable_simulated_io_errors() 162 #endif 163 164 #endif /* _PAGER_H_ */ 165