AryaWu/sqlite

1/*2** 2001 September 153**4** The author disclaims copyright to this source code.  In place of5** 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 cache13** subsystem.  The page cache subsystem reads and writes a file a page14** at a time and provides a journal for rollback.15*/16 17#ifndef SQLITE_PAGER_H18#define SQLITE_PAGER_H19 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_LIMIT26  #define SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT -127#endif28 29/*30** The type used to represent a page number.  The first page in a file31** 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 is47** reserved for working around a windows/posix incompatibility). It is48** 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 to50** 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      -168#define PAGER_LOCKINGMODE_NORMAL      069#define PAGER_LOCKINGMODE_EXCLUSIVE   170 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 and76** 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#define isWalMode(x) ((x)==PAGER_JOURNALMODE_WAL)87 88/*89** The argument to this macro is a file descriptor (type sqlite3_file*).90** Return 0 if it is not open, or non-zero (but not 1) if it is.91**92** This is so that expressions can be written as:93**94**   if( isOpen(pPager->jfd) ){ ...95**96** instead of97**98**   if( pPager->jfd->pMethods ){ ...99*/100#define isOpen(pFd) ((pFd)->pMethods!=0)101 102/*103** Flags that make up the mask passed to sqlite3PagerGet().104*/105#define PAGER_GET_NOCONTENT     0x01  /* Do not load data from disk */106#define PAGER_GET_READONLY      0x02  /* Read-only page is acceptable */107 108/*109** Flags for sqlite3PagerSetFlags()110**111** Value constraints (enforced via assert()):112**    PAGER_FULLFSYNC      == SQLITE_FullFSync113**    PAGER_CKPT_FULLFSYNC == SQLITE_CkptFullFSync114**    PAGER_CACHE_SPILL    == SQLITE_CacheSpill115*/116#define PAGER_SYNCHRONOUS_OFF       0x01  /* PRAGMA synchronous=OFF */117#define PAGER_SYNCHRONOUS_NORMAL    0x02  /* PRAGMA synchronous=NORMAL */118#define PAGER_SYNCHRONOUS_FULL      0x03  /* PRAGMA synchronous=FULL */119#define PAGER_SYNCHRONOUS_EXTRA     0x04  /* PRAGMA synchronous=EXTRA */120#define PAGER_SYNCHRONOUS_MASK      0x07  /* Mask for four values above */121#define PAGER_FULLFSYNC             0x08  /* PRAGMA fullfsync=ON */122#define PAGER_CKPT_FULLFSYNC        0x10  /* PRAGMA checkpoint_fullfsync=ON */123#define PAGER_CACHESPILL            0x20  /* PRAGMA cache_spill=ON */124#define PAGER_FLAGS_MASK            0x38  /* All above except SYNCHRONOUS */125 126/*127** The remainder of this file contains the declarations of the functions128** that make up the Pager sub-system API. See source code comments for 129** a detailed description of each routine.130*/131 132/* Open and close a Pager connection. */ 133int sqlite3PagerOpen(134  sqlite3_vfs*,135  Pager **ppPager,136  const char*,137  int,138  int,139  int,140  void(*)(DbPage*)141);142int sqlite3PagerClose(Pager *pPager, sqlite3*);143int sqlite3PagerReadFileheader(Pager*, int, unsigned char*);144 145/* Functions used to configure a Pager object. */146void sqlite3PagerSetBusyHandler(Pager*, int(*)(void *), void *);147int sqlite3PagerSetPagesize(Pager*, u32*, int);148Pgno sqlite3PagerMaxPageCount(Pager*, Pgno);149void sqlite3PagerSetCachesize(Pager*, int);150int sqlite3PagerSetSpillsize(Pager*, int);151void sqlite3PagerSetMmapLimit(Pager *, sqlite3_int64);152void sqlite3PagerShrink(Pager*);153void sqlite3PagerSetFlags(Pager*,unsigned);154int sqlite3PagerLockingMode(Pager *, int);155int sqlite3PagerSetJournalMode(Pager *, int);156int sqlite3PagerGetJournalMode(Pager*);157int sqlite3PagerOkToChangeJournalMode(Pager*);158i64 sqlite3PagerJournalSizeLimit(Pager *, i64);159sqlite3_backup **sqlite3PagerBackupPtr(Pager*);160int sqlite3PagerFlush(Pager*);161 162/* Functions used to obtain and release page references. */ 163int sqlite3PagerGet(Pager *pPager, Pgno pgno, DbPage **ppPage, int clrFlag);164DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno);165void sqlite3PagerRef(DbPage*);166void sqlite3PagerUnref(DbPage*);167void sqlite3PagerUnrefNotNull(DbPage*);168void sqlite3PagerUnrefPageOne(DbPage*);169 170/* Operations on page references. */171int sqlite3PagerWrite(DbPage*);172void sqlite3PagerDontWrite(DbPage*);173int sqlite3PagerMovepage(Pager*,DbPage*,Pgno,int);174int sqlite3PagerPageRefcount(DbPage*);175void *sqlite3PagerGetData(DbPage *); 176void *sqlite3PagerGetExtra(DbPage *); 177 178/* Functions used to manage pager transactions and savepoints. */179void sqlite3PagerPagecount(Pager*, int*);180int sqlite3PagerBegin(Pager*, int exFlag, int);181int sqlite3PagerCommitPhaseOne(Pager*,const char *zSuper, int);182int sqlite3PagerExclusiveLock(Pager*);183int sqlite3PagerSync(Pager *pPager, const char *zSuper);184int sqlite3PagerCommitPhaseTwo(Pager*);185int sqlite3PagerRollback(Pager*);186int sqlite3PagerOpenSavepoint(Pager *pPager, int n);187int sqlite3PagerSavepoint(Pager *pPager, int op, int iSavepoint);188int sqlite3PagerSharedLock(Pager *pPager);189 190#ifndef SQLITE_OMIT_WAL191  int sqlite3PagerCheckpoint(Pager *pPager, sqlite3*, int, int*, int*);192  int sqlite3PagerWalSupported(Pager *pPager);193  int sqlite3PagerWalCallback(Pager *pPager);194  int sqlite3PagerOpenWal(Pager *pPager, int *pisOpen);195  int sqlite3PagerCloseWal(Pager *pPager, sqlite3*);196# ifdef SQLITE_ENABLE_SNAPSHOT197  int sqlite3PagerSnapshotGet(Pager*, sqlite3_snapshot **ppSnapshot);198  int sqlite3PagerSnapshotOpen(Pager*, sqlite3_snapshot *pSnapshot);199  int sqlite3PagerSnapshotRecover(Pager *pPager);200  int sqlite3PagerSnapshotCheck(Pager *pPager, sqlite3_snapshot *pSnapshot);201  void sqlite3PagerSnapshotUnlock(Pager *pPager);202# endif203#endif204 205#if !defined(SQLITE_OMIT_WAL) && defined(SQLITE_ENABLE_SETLK_TIMEOUT)206  int sqlite3PagerWalWriteLock(Pager*, int);207  void sqlite3PagerWalDb(Pager*, sqlite3*);208#else209# define sqlite3PagerWalWriteLock(y,z) SQLITE_OK210# define sqlite3PagerWalDb(x,y)211#endif212 213#ifdef SQLITE_DIRECT_OVERFLOW_READ214  int sqlite3PagerDirectReadOk(Pager *pPager, Pgno pgno);215#endif216 217#ifdef SQLITE_ENABLE_ZIPVFS218  int sqlite3PagerWalFramesize(Pager *pPager);219#endif220 221/* Functions used to query pager state and configuration. */222u8 sqlite3PagerIsreadonly(Pager*);223u32 sqlite3PagerDataVersion(Pager*);224#ifdef SQLITE_DEBUG225  int sqlite3PagerRefcount(Pager*);226#endif227int sqlite3PagerMemUsed(Pager*);228const char *sqlite3PagerFilename(const Pager*, int);229sqlite3_vfs *sqlite3PagerVfs(Pager*);230sqlite3_file *sqlite3PagerFile(Pager*);231sqlite3_file *sqlite3PagerJrnlFile(Pager*);232const char *sqlite3PagerJournalname(Pager*);233void *sqlite3PagerTempSpace(Pager*);234int sqlite3PagerIsMemdb(Pager*);235void sqlite3PagerCacheStat(Pager *, int, int, u64*);236void sqlite3PagerClearCache(Pager*);237int sqlite3SectorSize(sqlite3_file *);238 239/* Functions used to truncate the database file. */240void sqlite3PagerTruncateImage(Pager*,Pgno);241 242void sqlite3PagerRekey(DbPage*, Pgno, u16);243 244/* Functions to support testing and debugging. */245#if !defined(NDEBUG) || defined(SQLITE_TEST)246  Pgno sqlite3PagerPagenumber(DbPage*);247  int sqlite3PagerIswriteable(DbPage*);248#endif249#ifdef SQLITE_TEST250  int *sqlite3PagerStats(Pager*);251  void sqlite3PagerRefdump(Pager*);252  void disable_simulated_io_errors(void);253  void enable_simulated_io_errors(void);254#else255# define disable_simulated_io_errors()256# define enable_simulated_io_errors()257#endif258 259#if defined(SQLITE_USE_SEH) && !defined(SQLITE_OMIT_WAL)260int sqlite3PagerWalSystemErrno(Pager*);261#endif262 263#endif /* SQLITE_PAGER_H */264