4 ** The author disclaims copyright to this source code. In place of
5 ** a legal notice, here is a blessing:
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.
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.
17 #ifndef SQLITE_PAGER_H
18 #define SQLITE_PAGER_H
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".
25 #ifndef SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT
26 #define SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT -1
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".
36 ** Each open file is managed by a separate instance of the "Pager" structure.
38 typedef struct Pager Pager
;
41 ** Handle type for pages.
43 typedef struct PgHdr DbPage
;
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
53 #define PAGER_MJ_PGNO(x) ((Pgno)((PENDING_BYTE/((x)->pageSize))+1))
56 ** Allowed values for the flags parameter to sqlite3PagerOpen().
58 ** NOTE: These values must match the corresponding BTREE_ values in btree.h.
60 #define PAGER_OMIT_JOURNAL 0x0001 /* Do not use a rollback journal */
61 #define PAGER_MEMORY 0x0002 /* In-memory database */
64 ** Valid values for the second argument to sqlite3PagerLockingMode().
66 #define PAGER_LOCKINGMODE_QUERY -1
67 #define PAGER_LOCKINGMODE_NORMAL 0
68 #define PAGER_LOCKINGMODE_EXCLUSIVE 1
71 ** Numeric constants that encode the journalmode.
73 ** The numeric values encoded here (other than PAGER_JOURNALMODE_QUERY)
74 ** are exposed in the API via the "PRAGMA journal_mode" command and
75 ** therefore cannot be changed without a compatibility break.
77 #define PAGER_JOURNALMODE_QUERY (-1) /* Query the value of journalmode */
78 #define PAGER_JOURNALMODE_DELETE 0 /* Commit by deleting journal file */
79 #define PAGER_JOURNALMODE_PERSIST 1 /* Commit by zeroing journal header */
80 #define PAGER_JOURNALMODE_OFF 2 /* Journal omitted. */
81 #define PAGER_JOURNALMODE_TRUNCATE 3 /* Commit by truncating journal */
82 #define PAGER_JOURNALMODE_MEMORY 4 /* In-memory journal file */
83 #define PAGER_JOURNALMODE_WAL 5 /* Use write-ahead logging */
86 ** Flags that make up the mask passed to sqlite3PagerGet().
88 #define PAGER_GET_NOCONTENT 0x01 /* Do not load data from disk */
89 #define PAGER_GET_READONLY 0x02 /* Read-only page is acceptable */
92 ** Flags for sqlite3PagerSetFlags()
94 ** Value constraints (enforced via assert()):
95 ** PAGER_FULLFSYNC == SQLITE_FullFSync
96 ** PAGER_CKPT_FULLFSYNC == SQLITE_CkptFullFSync
97 ** PAGER_CACHE_SPILL == SQLITE_CacheSpill
99 #define PAGER_SYNCHRONOUS_OFF 0x01 /* PRAGMA synchronous=OFF */
100 #define PAGER_SYNCHRONOUS_NORMAL 0x02 /* PRAGMA synchronous=NORMAL */
101 #define PAGER_SYNCHRONOUS_FULL 0x03 /* PRAGMA synchronous=FULL */
102 #define PAGER_SYNCHRONOUS_EXTRA 0x04 /* PRAGMA synchronous=EXTRA */
103 #define PAGER_SYNCHRONOUS_MASK 0x07 /* Mask for four values above */
104 #define PAGER_FULLFSYNC 0x08 /* PRAGMA fullfsync=ON */
105 #define PAGER_CKPT_FULLFSYNC 0x10 /* PRAGMA checkpoint_fullfsync=ON */
106 #define PAGER_CACHESPILL 0x20 /* PRAGMA cache_spill=ON */
107 #define PAGER_FLAGS_MASK 0x38 /* All above except SYNCHRONOUS */
110 ** The remainder of this file contains the declarations of the functions
111 ** that make up the Pager sub-system API. See source code comments for
112 ** a detailed description of each routine.
115 /* Open and close a Pager connection. */
116 int sqlite3PagerOpen(
125 int sqlite3PagerClose(Pager
*pPager
);
126 int sqlite3PagerReadFileheader(Pager
*, int, unsigned char*);
128 /* Functions used to configure a Pager object. */
129 void sqlite3PagerSetBusyhandler(Pager
*, int(*)(void *), void *);
130 int sqlite3PagerSetPagesize(Pager
*, u32
*, int);
131 #ifdef SQLITE_HAS_CODEC
132 void sqlite3PagerAlignReserve(Pager
*,Pager
*);
134 int sqlite3PagerMaxPageCount(Pager
*, int);
135 void sqlite3PagerSetCachesize(Pager
*, int);
136 int sqlite3PagerSetSpillsize(Pager
*, int);
137 void sqlite3PagerSetMmapLimit(Pager
*, sqlite3_int64
);
138 void sqlite3PagerShrink(Pager
*);
139 void sqlite3PagerSetFlags(Pager
*,unsigned);
140 int sqlite3PagerLockingMode(Pager
*, int);
141 int sqlite3PagerSetJournalMode(Pager
*, int);
142 int sqlite3PagerGetJournalMode(Pager
*);
143 int sqlite3PagerOkToChangeJournalMode(Pager
*);
144 i64
sqlite3PagerJournalSizeLimit(Pager
*, i64
);
145 sqlite3_backup
**sqlite3PagerBackupPtr(Pager
*);
146 int sqlite3PagerFlush(Pager
*);
148 /* Functions used to obtain and release page references. */
149 int sqlite3PagerGet(Pager
*pPager
, Pgno pgno
, DbPage
**ppPage
, int clrFlag
);
150 DbPage
*sqlite3PagerLookup(Pager
*pPager
, Pgno pgno
);
151 void sqlite3PagerRef(DbPage
*);
152 void sqlite3PagerUnref(DbPage
*);
153 void sqlite3PagerUnrefNotNull(DbPage
*);
155 /* Operations on page references. */
156 int sqlite3PagerWrite(DbPage
*);
157 void sqlite3PagerDontWrite(DbPage
*);
158 int sqlite3PagerMovepage(Pager
*,DbPage
*,Pgno
,int);
159 int sqlite3PagerPageRefcount(DbPage
*);
160 void *sqlite3PagerGetData(DbPage
*);
161 void *sqlite3PagerGetExtra(DbPage
*);
163 /* Functions used to manage pager transactions and savepoints. */
164 void sqlite3PagerPagecount(Pager
*, int*);
165 int sqlite3PagerBegin(Pager
*, int exFlag
, int);
166 int sqlite3PagerCommitPhaseOne(Pager
*,const char *zMaster
, int);
167 int sqlite3PagerExclusiveLock(Pager
*);
168 int sqlite3PagerSync(Pager
*pPager
, const char *zMaster
);
169 int sqlite3PagerCommitPhaseTwo(Pager
*);
170 int sqlite3PagerRollback(Pager
*);
171 int sqlite3PagerOpenSavepoint(Pager
*pPager
, int n
);
172 int sqlite3PagerSavepoint(Pager
*pPager
, int op
, int iSavepoint
);
173 int sqlite3PagerSharedLock(Pager
*pPager
);
175 #ifndef SQLITE_OMIT_WAL
176 int sqlite3PagerCheckpoint(Pager
*pPager
, int, int*, int*);
177 int sqlite3PagerWalSupported(Pager
*pPager
);
178 int sqlite3PagerWalCallback(Pager
*pPager
);
179 int sqlite3PagerOpenWal(Pager
*pPager
, int *pisOpen
);
180 int sqlite3PagerCloseWal(Pager
*pPager
);
181 # ifdef SQLITE_ENABLE_SNAPSHOT
182 int sqlite3PagerSnapshotGet(Pager
*pPager
, sqlite3_snapshot
**ppSnapshot
);
183 int sqlite3PagerSnapshotOpen(Pager
*pPager
, sqlite3_snapshot
*pSnapshot
);
187 #ifdef SQLITE_ENABLE_ZIPVFS
188 int sqlite3PagerWalFramesize(Pager
*pPager
);
191 /* Functions used to query pager state and configuration. */
192 u8
sqlite3PagerIsreadonly(Pager
*);
193 u32
sqlite3PagerDataVersion(Pager
*);
195 int sqlite3PagerRefcount(Pager
*);
197 int sqlite3PagerMemUsed(Pager
*);
198 const char *sqlite3PagerFilename(Pager
*, int);
199 sqlite3_vfs
*sqlite3PagerVfs(Pager
*);
200 sqlite3_file
*sqlite3PagerFile(Pager
*);
201 sqlite3_file
*sqlite3PagerJrnlFile(Pager
*);
202 const char *sqlite3PagerJournalname(Pager
*);
203 void *sqlite3PagerTempSpace(Pager
*);
204 int sqlite3PagerIsMemdb(Pager
*);
205 void sqlite3PagerCacheStat(Pager
*, int, int, int *);
206 int sqlite3SectorSize(sqlite3_file
*);
208 /* Functions used to truncate the database file. */
209 void sqlite3PagerTruncateImage(Pager
*,Pgno
);
211 void sqlite3PagerRekey(DbPage
*, Pgno
, u16
);
213 #if defined(SQLITE_HAS_CODEC) && !defined(SQLITE_OMIT_WAL)
214 void *sqlite3PagerCodec(DbPage
*);
217 /* Functions to support testing and debugging. */
218 #if !defined(NDEBUG) || defined(SQLITE_TEST)
219 Pgno
sqlite3PagerPagenumber(DbPage
*);
220 int sqlite3PagerIswriteable(DbPage
*);
223 int *sqlite3PagerStats(Pager
*);
224 void sqlite3PagerRefdump(Pager
*);
225 void disable_simulated_io_errors(void);
226 void enable_simulated_io_errors(void);
228 # define disable_simulated_io_errors()
229 # define enable_simulated_io_errors()
232 #endif /* SQLITE_PAGER_H */