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*/
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_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_NO_READLOCK   0x0002    /* Omit readlocks on readonly files */
62#define PAGER_MEMORY        0x0004    /* 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#define PAGER_JOURNALMODE_QUERY     (-1)  /* Query the value of journalmode */
75#define PAGER_JOURNALMODE_DELETE      0   /* Commit by deleting journal file */
76#define PAGER_JOURNALMODE_PERSIST     1   /* Commit by zeroing journal header */
77#define PAGER_JOURNALMODE_OFF         2   /* Journal omitted.  */
78#define PAGER_JOURNALMODE_TRUNCATE    3   /* Commit by truncating journal */
79#define PAGER_JOURNALMODE_MEMORY      4   /* In-memory journal file */
80#define PAGER_JOURNALMODE_WAL         5   /* Use write-ahead logging */
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. */
89int sqlite3PagerOpen(
90  sqlite3_vfs*,
91  Pager **ppPager,
92  const char*,
93  int,
94  int,
95  int,
96  void(*)(DbPage*)
97);
98int sqlite3PagerClose(Pager *pPager);
99int sqlite3PagerReadFileheader(Pager*, int, unsigned char*);
100
101/* Functions used to configure a Pager object. */
102void sqlite3PagerSetBusyhandler(Pager*, int(*)(void *), void *);
103int sqlite3PagerSetPagesize(Pager*, u32*, int);
104int sqlite3PagerMaxPageCount(Pager*, int);
105void sqlite3PagerSetCachesize(Pager*, int);
106void sqlite3PagerSetSafetyLevel(Pager*,int,int,int);
107int sqlite3PagerLockingMode(Pager *, int);
108int sqlite3PagerSetJournalMode(Pager *, int);
109int sqlite3PagerGetJournalMode(Pager*);
110int sqlite3PagerOkToChangeJournalMode(Pager*);
111i64 sqlite3PagerJournalSizeLimit(Pager *, i64);
112sqlite3_backup **sqlite3PagerBackupPtr(Pager*);
113
114/* Functions used to obtain and release page references. */
115int sqlite3PagerAcquire(Pager *pPager, Pgno pgno, DbPage **ppPage, int clrFlag);
116#define sqlite3PagerGet(A,B,C) sqlite3PagerAcquire(A,B,C,0)
117DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno);
118void sqlite3PagerRef(DbPage*);
119void sqlite3PagerUnref(DbPage*);
120
121/* Operations on page references. */
122int sqlite3PagerWrite(DbPage*);
123void sqlite3PagerDontWrite(DbPage*);
124int sqlite3PagerMovepage(Pager*,DbPage*,Pgno,int);
125int sqlite3PagerPageRefcount(DbPage*);
126void *sqlite3PagerGetData(DbPage *);
127void *sqlite3PagerGetExtra(DbPage *);
128
129/* Functions used to manage pager transactions and savepoints. */
130void sqlite3PagerPagecount(Pager*, int*);
131int sqlite3PagerBegin(Pager*, int exFlag, int);
132int sqlite3PagerCommitPhaseOne(Pager*,const char *zMaster, int);
133int sqlite3PagerExclusiveLock(Pager*);
134int sqlite3PagerSync(Pager *pPager);
135int sqlite3PagerCommitPhaseTwo(Pager*);
136int sqlite3PagerRollback(Pager*);
137int sqlite3PagerOpenSavepoint(Pager *pPager, int n);
138int sqlite3PagerSavepoint(Pager *pPager, int op, int iSavepoint);
139int sqlite3PagerSharedLock(Pager *pPager);
140
141int sqlite3PagerCheckpoint(Pager *pPager, int, int*, int*);
142int sqlite3PagerWalSupported(Pager *pPager);
143int sqlite3PagerWalCallback(Pager *pPager);
144int sqlite3PagerOpenWal(Pager *pPager, int *pisOpen);
145int sqlite3PagerCloseWal(Pager *pPager);
146
147/* Functions used to query pager state and configuration. */
148u8 sqlite3PagerIsreadonly(Pager*);
149int sqlite3PagerRefcount(Pager*);
150int sqlite3PagerMemUsed(Pager*);
151const char *sqlite3PagerFilename(Pager*);
152const sqlite3_vfs *sqlite3PagerVfs(Pager*);
153sqlite3_file *sqlite3PagerFile(Pager*);
154const char *sqlite3PagerJournalname(Pager*);
155int sqlite3PagerNosync(Pager*);
156void *sqlite3PagerTempSpace(Pager*);
157int sqlite3PagerIsMemdb(Pager*);
158
159/* Functions used to truncate the database file. */
160void sqlite3PagerTruncateImage(Pager*,Pgno);
161
162#if defined(SQLITE_HAS_CODEC) && !defined(SQLITE_OMIT_WAL)
163void *sqlite3PagerCodec(DbPage *);
164#endif
165
166/* Functions to support testing and debugging. */
167#if !defined(NDEBUG) || defined(SQLITE_TEST)
168  Pgno sqlite3PagerPagenumber(DbPage*);
169  int sqlite3PagerIswriteable(DbPage*);
170#endif
171#ifdef SQLITE_TEST
172  int *sqlite3PagerStats(Pager*);
173  void sqlite3PagerRefdump(Pager*);
174  void disable_simulated_io_errors(void);
175  void enable_simulated_io_errors(void);
176#else
177# define disable_simulated_io_errors()
178# define enable_simulated_io_errors()
179#endif
180
181#endif /* _PAGER_H_ */
182