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*/
33typedef u32 Pgno;
34
35/*
36** Each open file is managed by a separate instance of the "Pager" structure.
37*/
38typedef struct Pager Pager;
39
40/*
41** Handle type for pages.
42*/
43typedef 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. */
117int sqlite3PagerOpen(
118 sqlite3_vfs*,
119 Pager **ppPager,
120 const char*,
121 int,
122 int,
123 int,
124 void(*)(DbPage*)
125);
126int sqlite3PagerClose(Pager *pPager, sqlite3*);
127int sqlite3PagerReadFileheader(Pager*, int, unsigned char*);
128
129/* Functions used to configure a Pager object. */
130void sqlite3PagerSetBusyHandler(Pager*, int(*)(void *), void *);
131int sqlite3PagerSetPagesize(Pager*, u32*, int);
132Pgno sqlite3PagerMaxPageCount(Pager*, Pgno);
133void sqlite3PagerSetCachesize(Pager*, int);
134int sqlite3PagerSetSpillsize(Pager*, int);
135void sqlite3PagerSetMmapLimit(Pager *, sqlite3_int64);
136void sqlite3PagerShrink(Pager*);
137void sqlite3PagerSetFlags(Pager*,unsigned);
138int sqlite3PagerLockingMode(Pager *, int);
139int sqlite3PagerSetJournalMode(Pager *, int);
140int sqlite3PagerGetJournalMode(Pager*);
141int sqlite3PagerOkToChangeJournalMode(Pager*);
142i64 sqlite3PagerJournalSizeLimit(Pager *, i64);
143sqlite3_backup **sqlite3PagerBackupPtr(Pager*);
144int sqlite3PagerFlush(Pager*);
145
146/* Functions used to obtain and release page references. */
147int sqlite3PagerGet(Pager *pPager, Pgno pgno, DbPage **ppPage, int clrFlag);
148DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno);
149void sqlite3PagerRef(DbPage*);
150void sqlite3PagerUnref(DbPage*);
151void sqlite3PagerUnrefNotNull(DbPage*);
152void sqlite3PagerUnrefPageOne(DbPage*);
153
154/* Operations on page references. */
155int sqlite3PagerWrite(DbPage*);
156void sqlite3PagerDontWrite(DbPage*);
157int sqlite3PagerMovepage(Pager*,DbPage*,Pgno,int);
158int sqlite3PagerPageRefcount(DbPage*);
159void *sqlite3PagerGetData(DbPage *);
160void *sqlite3PagerGetExtra(DbPage *);
161
162/* Functions used to manage pager transactions and savepoints. */
163void sqlite3PagerPagecount(Pager*, int*);
164int sqlite3PagerBegin(Pager*, int exFlag, int);
165int sqlite3PagerCommitPhaseOne(Pager*,const char *zSuper, int);
166int sqlite3PagerExclusiveLock(Pager*);
167int sqlite3PagerSync(Pager *pPager, const char *zSuper);
168int sqlite3PagerCommitPhaseTwo(Pager*);
169int sqlite3PagerRollback(Pager*);
170int sqlite3PagerOpenSavepoint(Pager *pPager, int n);
171int sqlite3PagerSavepoint(Pager *pPager, int op, int iSavepoint);
172int 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. */
206u8 sqlite3PagerIsreadonly(Pager*);
207u32 sqlite3PagerDataVersion(Pager*);
208#ifdef SQLITE_DEBUG
209 int sqlite3PagerRefcount(Pager*);
210#endif
211int sqlite3PagerMemUsed(Pager*);
212const char *sqlite3PagerFilename(const Pager*, int);
213sqlite3_vfs *sqlite3PagerVfs(Pager*);
214sqlite3_file *sqlite3PagerFile(Pager*);
215sqlite3_file *sqlite3PagerJrnlFile(Pager*);
216const char *sqlite3PagerJournalname(Pager*);
217void *sqlite3PagerTempSpace(Pager*);
218int sqlite3PagerIsMemdb(Pager*);
219void sqlite3PagerCacheStat(Pager *, int, int, int *);
220void sqlite3PagerClearCache(Pager*);
221int sqlite3SectorSize(sqlite3_file *);
222
223/* Functions used to truncate the database file. */
224void sqlite3PagerTruncateImage(Pager*,Pgno);
225
226void 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