src/pager.h

   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 */
  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_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. */
 117 int sqlite3PagerOpen(
 118   sqlite3_vfs*,
 119   Pager **ppPager,
 120   const char*,
 121   int,
 122   int,
 123   int,
 124   void(*)(DbPage*)
 125 );
 126 int sqlite3PagerClose(Pager *pPager, sqlite3*);
 127 int sqlite3PagerReadFileheader(Pager*, int, unsigned char*);
 128
 129 /* Functions used to configure a Pager object. */
 130 void sqlite3PagerSetBusyHandler(Pager*, int(*)(void *), void *);
 131 int sqlite3PagerSetPagesize(Pager*, u32*, int);
 132 /* BEGIN SQLCIPHER */
 133 #ifdef SQLITE_HAS_CODEC
 134 void sqlite3PagerAlignReserve(Pager*,Pager*);
 135 #endif
 136 /* END SQLCIPHER */
 137 Pgno sqlite3PagerMaxPageCount(Pager*, Pgno);
 138 void sqlite3PagerSetCachesize(Pager*, int);
 139 int sqlite3PagerSetSpillsize(Pager*, int);
 140 void sqlite3PagerSetMmapLimit(Pager *, sqlite3_int64);
 141 void sqlite3PagerShrink(Pager*);
 142 void sqlite3PagerSetFlags(Pager*,unsigned);
 143 int sqlite3PagerLockingMode(Pager *, int);
 144 int sqlite3PagerSetJournalMode(Pager *, int);
 145 int sqlite3PagerGetJournalMode(Pager*);
 146 int sqlite3PagerOkToChangeJournalMode(Pager*);
 147 i64 sqlite3PagerJournalSizeLimit(Pager *, i64);
 148 sqlite3_backup **sqlite3PagerBackupPtr(Pager*);
 149 int sqlite3PagerFlush(Pager*);
 150
 151 /* Functions used to obtain and release page references. */
 152 int sqlite3PagerGet(Pager *pPager, Pgno pgno, DbPage **ppPage, int clrFlag);
 153 DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno);
 154 void sqlite3PagerRef(DbPage*);
 155 void sqlite3PagerUnref(DbPage*);
 156 void sqlite3PagerUnrefNotNull(DbPage*);
 157 void sqlite3PagerUnrefPageOne(DbPage*);
 158
 159 /* Operations on page references. */
 160 int sqlite3PagerWrite(DbPage*);
 161 void sqlite3PagerDontWrite(DbPage*);
 162 int sqlite3PagerMovepage(Pager*,DbPage*,Pgno,int);
 163 int sqlite3PagerPageRefcount(DbPage*);
 164 void *sqlite3PagerGetData(DbPage *);
 165 void *sqlite3PagerGetExtra(DbPage *);
 166
 167 /* Functions used to manage pager transactions and savepoints. */
 168 void sqlite3PagerPagecount(Pager*, int*);
 169 int sqlite3PagerBegin(Pager*, int exFlag, int);
 170 int sqlite3PagerCommitPhaseOne(Pager*,const char *zSuper, int);
 171 int sqlite3PagerExclusiveLock(Pager*);
 172 int sqlite3PagerSync(Pager *pPager, const char *zSuper);
 173 int sqlite3PagerCommitPhaseTwo(Pager*);
 174 int sqlite3PagerRollback(Pager*);
 175 int sqlite3PagerOpenSavepoint(Pager *pPager, int n);
 176 int sqlite3PagerSavepoint(Pager *pPager, int op, int iSavepoint);
 177 int sqlite3PagerSharedLock(Pager *pPager);
 178
 179 #ifndef SQLITE_OMIT_WAL
 180   int sqlite3PagerCheckpoint(Pager *pPager, sqlite3*, int, int*, int*);
 181   int sqlite3PagerWalSupported(Pager *pPager);
 182   int sqlite3PagerWalCallback(Pager *pPager);
 183   int sqlite3PagerOpenWal(Pager *pPager, int *pisOpen);
 184   int sqlite3PagerCloseWal(Pager *pPager, sqlite3*);
 185 # ifdef SQLITE_ENABLE_SNAPSHOT
 186   int sqlite3PagerSnapshotGet(Pager*, sqlite3_snapshot **ppSnapshot);
 187   int sqlite3PagerSnapshotOpen(Pager*, sqlite3_snapshot *pSnapshot);
 188   int sqlite3PagerSnapshotRecover(Pager *pPager);
 189   int sqlite3PagerSnapshotCheck(Pager *pPager, sqlite3_snapshot *pSnapshot);
 190   void sqlite3PagerSnapshotUnlock(Pager *pPager);
 191 # endif
 192 #endif
 193
 194 #if !defined(SQLITE_OMIT_WAL) && defined(SQLITE_ENABLE_SETLK_TIMEOUT)
 195   int sqlite3PagerWalWriteLock(Pager*, int);
 196   void sqlite3PagerWalDb(Pager*, sqlite3*);
 197 #else
 198 # define sqlite3PagerWalWriteLock(y,z) SQLITE_OK
 199 # define sqlite3PagerWalDb(x,y)
 200 #endif
 201
 202 #ifdef SQLITE_DIRECT_OVERFLOW_READ
 203   int sqlite3PagerDirectReadOk(Pager *pPager, Pgno pgno);
 204 #endif
 205
 206 #ifdef SQLITE_ENABLE_ZIPVFS
 207   int sqlite3PagerWalFramesize(Pager *pPager);
 208 #endif
 209
 210 /* Functions used to query pager state and configuration. */
 211 u8 sqlite3PagerIsreadonly(Pager*);
 212 u32 sqlite3PagerDataVersion(Pager*);
 213 #ifdef SQLITE_DEBUG
 214   int sqlite3PagerRefcount(Pager*);
 215 #endif
 216 int sqlite3PagerMemUsed(Pager*);
 217 const char *sqlite3PagerFilename(const Pager*, int);
 218 sqlite3_vfs *sqlite3PagerVfs(Pager*);
 219 sqlite3_file *sqlite3PagerFile(Pager*);
 220 sqlite3_file *sqlite3PagerJrnlFile(Pager*);
 221 const char *sqlite3PagerJournalname(Pager*);
 222 void *sqlite3PagerTempSpace(Pager*);
 223 int sqlite3PagerIsMemdb(Pager*);
 224 void sqlite3PagerCacheStat(Pager *, int, int, int *);
 225 void sqlite3PagerClearCache(Pager*);
 226 int sqlite3SectorSize(sqlite3_file *);
 227
 228 /* Functions used to truncate the database file. */
 229 void sqlite3PagerTruncateImage(Pager*,Pgno);
 230
 231 void sqlite3PagerRekey(DbPage*, Pgno, u16);
 232
 233 /* BEGIN SQLCIPHER */
 234 #if defined(SQLITE_HAS_CODEC) && !defined(SQLITE_OMIT_WAL)
 235 void *sqlcipherPagerCodec(DbPage *);
 236 #endif
 237 /* END SQLCIPHER */
 238
 239 /* Functions to support testing and debugging. */
 240 #if !defined(NDEBUG) || defined(SQLITE_TEST)
 241   Pgno sqlite3PagerPagenumber(DbPage*);
 242   int sqlite3PagerIswriteable(DbPage*);
 243 #endif
 244 #ifdef SQLITE_TEST
 245   int *sqlite3PagerStats(Pager*);
 246   void sqlite3PagerRefdump(Pager*);
 247   void disable_simulated_io_errors(void);
 248   void enable_simulated_io_errors(void);
 249 #else
 250 # define disable_simulated_io_errors()
 251 # define enable_simulated_io_errors()
 252 #endif
 253
 254 #if defined(SQLITE_USE_SEH) && !defined(SQLITE_OMIT_WAL)
 255 int sqlite3PagerWalSystemErrno(Pager*);
 256 #endif
 257
 258 #endif /* SQLITE_PAGER_H */