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 _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 */
  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_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_MEMORY        0x0002    /* In-memory database */
  62
  63 /*
  64 ** Valid values for the second argument to sqlite3PagerLockingMode().
  65 */
  66 #define PAGER_LOCKINGMODE_QUERY      -1
  67 #define PAGER_LOCKINGMODE_NORMAL      0
  68 #define PAGER_LOCKINGMODE_EXCLUSIVE   1
  69
  70 /*
  71 ** Numeric constants that encode the journalmode.
  72 */
  73 #define PAGER_JOURNALMODE_QUERY     (-1)  /* Query the value of journalmode */
  74 #define PAGER_JOURNALMODE_DELETE      0   /* Commit by deleting journal file */
  75 #define PAGER_JOURNALMODE_PERSIST     1   /* Commit by zeroing journal header */
  76 #define PAGER_JOURNALMODE_OFF         2   /* Journal omitted.  */
  77 #define PAGER_JOURNALMODE_TRUNCATE    3   /* Commit by truncating journal */
  78 #define PAGER_JOURNALMODE_MEMORY      4   /* In-memory journal file */
  79 #define PAGER_JOURNALMODE_WAL         5   /* Use write-ahead logging */
  80
  81 /*
  82 ** The remainder of this file contains the declarations of the functions
  83 ** that make up the Pager sub-system API. See source code comments for
  84 ** a detailed description of each routine.
  85 */
  86
  87 /* Open and close a Pager connection. */
  88 int sqlite3PagerOpen(
  89   sqlite3_vfs*,
  90   Pager **ppPager,
  91   const char*,
  92   int,
  93   int,
  94   int,
  95   void(*)(DbPage*)
  96 );
  97 int sqlite3PagerClose(Pager *pPager);
  98 int sqlite3PagerReadFileheader(Pager*, int, unsigned char*);
  99
 100 /* Functions used to configure a Pager object. */
 101 void sqlite3PagerSetBusyhandler(Pager*, int(*)(void *), void *);
 102 int sqlite3PagerSetPagesize(Pager*, u32*, int);
 103 int sqlite3PagerMaxPageCount(Pager*, int);
 104 void sqlite3PagerSetCachesize(Pager*, int);
 105 void sqlite3PagerShrink(Pager*);
 106 void sqlite3PagerSetSafetyLevel(Pager*,int,int,int);
 107 int sqlite3PagerLockingMode(Pager *, int);
 108 int sqlite3PagerSetJournalMode(Pager *, int);
 109 int sqlite3PagerGetJournalMode(Pager*);
 110 int sqlite3PagerOkToChangeJournalMode(Pager*);
 111 i64 sqlite3PagerJournalSizeLimit(Pager *, i64);
 112 sqlite3_backup **sqlite3PagerBackupPtr(Pager*);
 113
 114 /* Functions used to obtain and release page references. */
 115 int sqlite3PagerAcquire(Pager *pPager, Pgno pgno, DbPage **ppPage, int clrFlag);
 116 #define sqlite3PagerGet(A,B,C) sqlite3PagerAcquire(A,B,C,0)
 117 DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno);
 118 void sqlite3PagerRef(DbPage*);
 119 void sqlite3PagerUnref(DbPage*);
 120
 121 /* Operations on page references. */
 122 int sqlite3PagerWrite(DbPage*);
 123 void sqlite3PagerDontWrite(DbPage*);
 124 int sqlite3PagerMovepage(Pager*,DbPage*,Pgno,int);
 125 int sqlite3PagerPageRefcount(DbPage*);
 126 void *sqlite3PagerGetData(DbPage *);
 127 void *sqlite3PagerGetExtra(DbPage *);
 128
 129 /* Functions used to manage pager transactions and savepoints. */
 130 void sqlite3PagerPagecount(Pager*, int*);
 131 int sqlite3PagerBegin(Pager*, int exFlag, int);
 132 int sqlite3PagerCommitPhaseOne(Pager*,const char *zMaster, int);
 133 int sqlite3PagerExclusiveLock(Pager*);
 134 int sqlite3PagerSync(Pager *pPager);
 135 int sqlite3PagerCommitPhaseTwo(Pager*);
 136 int sqlite3PagerRollback(Pager*);
 137 int sqlite3PagerOpenSavepoint(Pager *pPager, int n);
 138 int sqlite3PagerSavepoint(Pager *pPager, int op, int iSavepoint);
 139 int sqlite3PagerSharedLock(Pager *pPager);
 140
 141 int sqlite3PagerCheckpoint(Pager *pPager, int, int*, int*);
 142 int sqlite3PagerWalSupported(Pager *pPager);
 143 int sqlite3PagerWalCallback(Pager *pPager);
 144 int sqlite3PagerOpenWal(Pager *pPager, int *pisOpen);
 145 int sqlite3PagerCloseWal(Pager *pPager);
 146 #ifdef SQLITE_ENABLE_ZIPVFS
 147   int sqlite3PagerWalFramesize(Pager *pPager);
 148 #endif
 149
 150 /* Functions used to query pager state and configuration. */
 151 u8 sqlite3PagerIsreadonly(Pager*);
 152 int sqlite3PagerRefcount(Pager*);
 153 int sqlite3PagerMemUsed(Pager*);
 154 const char *sqlite3PagerFilename(Pager*);
 155 const sqlite3_vfs *sqlite3PagerVfs(Pager*);
 156 sqlite3_file *sqlite3PagerFile(Pager*);
 157 const char *sqlite3PagerJournalname(Pager*);
 158 int sqlite3PagerNosync(Pager*);
 159 void *sqlite3PagerTempSpace(Pager*);
 160 int sqlite3PagerIsMemdb(Pager*);
 161 void sqlite3PagerCacheStat(Pager *, int, int, int *);
 162 void sqlite3PagerClearCache(Pager *);
 163
 164 /* Functions used to truncate the database file. */
 165 void sqlite3PagerTruncateImage(Pager*,Pgno);
 166
 167 #if defined(SQLITE_HAS_CODEC) && !defined(SQLITE_OMIT_WAL)
 168 void *sqlite3PagerCodec(DbPage *);
 169 #endif
 170
 171 /* Functions to support testing and debugging. */
 172 #if !defined(NDEBUG) || defined(SQLITE_TEST)
 173   Pgno sqlite3PagerPagenumber(DbPage*);
 174   int sqlite3PagerIswriteable(DbPage*);
 175 #endif
 176 #ifdef SQLITE_TEST
 177   int *sqlite3PagerStats(Pager*);
 178   void sqlite3PagerRefdump(Pager*);
 179   void disable_simulated_io_errors(void);
 180   void enable_simulated_io_errors(void);
 181 #else
 182 # define disable_simulated_io_errors()
 183 # define enable_simulated_io_errors()
 184 #endif
 185
 186 #endif /* _PAGER_H_ */