/ Artifact Content
Login

Artifact b1e79698f3903e64d7a8ab5f4b3163aa39ed25686289a68de20b6b5734de70e6:


     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 is the implementation of the page cache subsystem or "pager".
    13  ** 
    14  ** The pager is used to access a database disk file.  It implements
    15  ** atomic commit and rollback through the use of a journal file that
    16  ** is separate from the database file.  The pager also implements file
    17  ** locking to prevent two processes from writing the same database
    18  ** file simultaneously, or one process from reading the database while
    19  ** another is writing.
    20  */
    21  #ifndef SQLITE_OMIT_DISKIO
    22  #include "sqliteInt.h"
    23  #include "wal.h"
    24  
    25  
    26  /******************* NOTES ON THE DESIGN OF THE PAGER ************************
    27  **
    28  ** This comment block describes invariants that hold when using a rollback
    29  ** journal.  These invariants do not apply for journal_mode=WAL,
    30  ** journal_mode=MEMORY, or journal_mode=OFF.
    31  **
    32  ** Within this comment block, a page is deemed to have been synced
    33  ** automatically as soon as it is written when PRAGMA synchronous=OFF.
    34  ** Otherwise, the page is not synced until the xSync method of the VFS
    35  ** is called successfully on the file containing the page.
    36  **
    37  ** Definition:  A page of the database file is said to be "overwriteable" if
    38  ** one or more of the following are true about the page:
    39  ** 
    40  **     (a)  The original content of the page as it was at the beginning of
    41  **          the transaction has been written into the rollback journal and
    42  **          synced.
    43  ** 
    44  **     (b)  The page was a freelist leaf page at the start of the transaction.
    45  ** 
    46  **     (c)  The page number is greater than the largest page that existed in
    47  **          the database file at the start of the transaction.
    48  ** 
    49  ** (1) A page of the database file is never overwritten unless one of the
    50  **     following are true:
    51  ** 
    52  **     (a) The page and all other pages on the same sector are overwriteable.
    53  ** 
    54  **     (b) The atomic page write optimization is enabled, and the entire
    55  **         transaction other than the update of the transaction sequence
    56  **         number consists of a single page change.
    57  ** 
    58  ** (2) The content of a page written into the rollback journal exactly matches
    59  **     both the content in the database when the rollback journal was written
    60  **     and the content in the database at the beginning of the current
    61  **     transaction.
    62  ** 
    63  ** (3) Writes to the database file are an integer multiple of the page size
    64  **     in length and are aligned on a page boundary.
    65  ** 
    66  ** (4) Reads from the database file are either aligned on a page boundary and
    67  **     an integer multiple of the page size in length or are taken from the
    68  **     first 100 bytes of the database file.
    69  ** 
    70  ** (5) All writes to the database file are synced prior to the rollback journal
    71  **     being deleted, truncated, or zeroed.
    72  ** 
    73  ** (6) If a master journal file is used, then all writes to the database file
    74  **     are synced prior to the master journal being deleted.
    75  ** 
    76  ** Definition: Two databases (or the same database at two points it time)
    77  ** are said to be "logically equivalent" if they give the same answer to
    78  ** all queries.  Note in particular the content of freelist leaf
    79  ** pages can be changed arbitrarily without affecting the logical equivalence
    80  ** of the database.
    81  ** 
    82  ** (7) At any time, if any subset, including the empty set and the total set,
    83  **     of the unsynced changes to a rollback journal are removed and the 
    84  **     journal is rolled back, the resulting database file will be logically
    85  **     equivalent to the database file at the beginning of the transaction.
    86  ** 
    87  ** (8) When a transaction is rolled back, the xTruncate method of the VFS
    88  **     is called to restore the database file to the same size it was at
    89  **     the beginning of the transaction.  (In some VFSes, the xTruncate
    90  **     method is a no-op, but that does not change the fact the SQLite will
    91  **     invoke it.)
    92  ** 
    93  ** (9) Whenever the database file is modified, at least one bit in the range
    94  **     of bytes from 24 through 39 inclusive will be changed prior to releasing
    95  **     the EXCLUSIVE lock, thus signaling other connections on the same
    96  **     database to flush their caches.
    97  **
    98  ** (10) The pattern of bits in bytes 24 through 39 shall not repeat in less
    99  **      than one billion transactions.
   100  **
   101  ** (11) A database file is well-formed at the beginning and at the conclusion
   102  **      of every transaction.
   103  **
   104  ** (12) An EXCLUSIVE lock is held on the database file when writing to
   105  **      the database file.
   106  **
   107  ** (13) A SHARED lock is held on the database file while reading any
   108  **      content out of the database file.
   109  **
   110  ******************************************************************************/
   111  
   112  /*
   113  ** Macros for troubleshooting.  Normally turned off
   114  */
   115  #if 0
   116  int sqlite3PagerTrace=1;  /* True to enable tracing */
   117  #define sqlite3DebugPrintf printf
   118  #define PAGERTRACE(X)     if( sqlite3PagerTrace ){ sqlite3DebugPrintf X; }
   119  #else
   120  #define PAGERTRACE(X)
   121  #endif
   122  
   123  /*
   124  ** The following two macros are used within the PAGERTRACE() macros above
   125  ** to print out file-descriptors. 
   126  **
   127  ** PAGERID() takes a pointer to a Pager struct as its argument. The
   128  ** associated file-descriptor is returned. FILEHANDLEID() takes an sqlite3_file
   129  ** struct as its argument.
   130  */
   131  #define PAGERID(p) (SQLITE_PTR_TO_INT(p->fd))
   132  #define FILEHANDLEID(fd) (SQLITE_PTR_TO_INT(fd))
   133  
   134  /*
   135  ** The Pager.eState variable stores the current 'state' of a pager. A
   136  ** pager may be in any one of the seven states shown in the following
   137  ** state diagram.
   138  **
   139  **                            OPEN <------+------+
   140  **                              |         |      |
   141  **                              V         |      |
   142  **               +---------> READER-------+      |
   143  **               |              |                |
   144  **               |              V                |
   145  **               |<-------WRITER_LOCKED------> ERROR
   146  **               |              |                ^  
   147  **               |              V                |
   148  **               |<------WRITER_CACHEMOD-------->|
   149  **               |              |                |
   150  **               |              V                |
   151  **               |<-------WRITER_DBMOD---------->|
   152  **               |              |                |
   153  **               |              V                |
   154  **               +<------WRITER_FINISHED-------->+
   155  **
   156  **
   157  ** List of state transitions and the C [function] that performs each:
   158  ** 
   159  **   OPEN              -> READER              [sqlite3PagerSharedLock]
   160  **   READER            -> OPEN                [pager_unlock]
   161  **
   162  **   READER            -> WRITER_LOCKED       [sqlite3PagerBegin]
   163  **   WRITER_LOCKED     -> WRITER_CACHEMOD     [pager_open_journal]
   164  **   WRITER_CACHEMOD   -> WRITER_DBMOD        [syncJournal]
   165  **   WRITER_DBMOD      -> WRITER_FINISHED     [sqlite3PagerCommitPhaseOne]
   166  **   WRITER_***        -> READER              [pager_end_transaction]
   167  **
   168  **   WRITER_***        -> ERROR               [pager_error]
   169  **   ERROR             -> OPEN                [pager_unlock]
   170  ** 
   171  **
   172  **  OPEN:
   173  **
   174  **    The pager starts up in this state. Nothing is guaranteed in this
   175  **    state - the file may or may not be locked and the database size is
   176  **    unknown. The database may not be read or written.
   177  **
   178  **    * No read or write transaction is active.
   179  **    * Any lock, or no lock at all, may be held on the database file.
   180  **    * The dbSize, dbOrigSize and dbFileSize variables may not be trusted.
   181  **
   182  **  READER:
   183  **
   184  **    In this state all the requirements for reading the database in 
   185  **    rollback (non-WAL) mode are met. Unless the pager is (or recently
   186  **    was) in exclusive-locking mode, a user-level read transaction is 
   187  **    open. The database size is known in this state.
   188  **
   189  **    A connection running with locking_mode=normal enters this state when
   190  **    it opens a read-transaction on the database and returns to state
   191  **    OPEN after the read-transaction is completed. However a connection
   192  **    running in locking_mode=exclusive (including temp databases) remains in
   193  **    this state even after the read-transaction is closed. The only way
   194  **    a locking_mode=exclusive connection can transition from READER to OPEN
   195  **    is via the ERROR state (see below).
   196  ** 
   197  **    * A read transaction may be active (but a write-transaction cannot).
   198  **    * A SHARED or greater lock is held on the database file.
   199  **    * The dbSize variable may be trusted (even if a user-level read 
   200  **      transaction is not active). The dbOrigSize and dbFileSize variables
   201  **      may not be trusted at this point.
   202  **    * If the database is a WAL database, then the WAL connection is open.
   203  **    * Even if a read-transaction is not open, it is guaranteed that 
   204  **      there is no hot-journal in the file-system.
   205  **
   206  **  WRITER_LOCKED:
   207  **
   208  **    The pager moves to this state from READER when a write-transaction
   209  **    is first opened on the database. In WRITER_LOCKED state, all locks 
   210  **    required to start a write-transaction are held, but no actual 
   211  **    modifications to the cache or database have taken place.
   212  **
   213  **    In rollback mode, a RESERVED or (if the transaction was opened with 
   214  **    BEGIN EXCLUSIVE) EXCLUSIVE lock is obtained on the database file when
   215  **    moving to this state, but the journal file is not written to or opened 
   216  **    to in this state. If the transaction is committed or rolled back while 
   217  **    in WRITER_LOCKED state, all that is required is to unlock the database 
   218  **    file.
   219  **
   220  **    IN WAL mode, WalBeginWriteTransaction() is called to lock the log file.
   221  **    If the connection is running with locking_mode=exclusive, an attempt
   222  **    is made to obtain an EXCLUSIVE lock on the database file.
   223  **
   224  **    * A write transaction is active.
   225  **    * If the connection is open in rollback-mode, a RESERVED or greater 
   226  **      lock is held on the database file.
   227  **    * If the connection is open in WAL-mode, a WAL write transaction
   228  **      is open (i.e. sqlite3WalBeginWriteTransaction() has been successfully
   229  **      called).
   230  **    * The dbSize, dbOrigSize and dbFileSize variables are all valid.
   231  **    * The contents of the pager cache have not been modified.
   232  **    * The journal file may or may not be open.
   233  **    * Nothing (not even the first header) has been written to the journal.
   234  **
   235  **  WRITER_CACHEMOD:
   236  **
   237  **    A pager moves from WRITER_LOCKED state to this state when a page is
   238  **    first modified by the upper layer. In rollback mode the journal file
   239  **    is opened (if it is not already open) and a header written to the
   240  **    start of it. The database file on disk has not been modified.
   241  **
   242  **    * A write transaction is active.
   243  **    * A RESERVED or greater lock is held on the database file.
   244  **    * The journal file is open and the first header has been written 
   245  **      to it, but the header has not been synced to disk.
   246  **    * The contents of the page cache have been modified.
   247  **
   248  **  WRITER_DBMOD:
   249  **
   250  **    The pager transitions from WRITER_CACHEMOD into WRITER_DBMOD state
   251  **    when it modifies the contents of the database file. WAL connections
   252  **    never enter this state (since they do not modify the database file,
   253  **    just the log file).
   254  **
   255  **    * A write transaction is active.
   256  **    * An EXCLUSIVE or greater lock is held on the database file.
   257  **    * The journal file is open and the first header has been written 
   258  **      and synced to disk.
   259  **    * The contents of the page cache have been modified (and possibly
   260  **      written to disk).
   261  **
   262  **  WRITER_FINISHED:
   263  **
   264  **    It is not possible for a WAL connection to enter this state.
   265  **
   266  **    A rollback-mode pager changes to WRITER_FINISHED state from WRITER_DBMOD
   267  **    state after the entire transaction has been successfully written into the
   268  **    database file. In this state the transaction may be committed simply
   269  **    by finalizing the journal file. Once in WRITER_FINISHED state, it is 
   270  **    not possible to modify the database further. At this point, the upper 
   271  **    layer must either commit or rollback the transaction.
   272  **
   273  **    * A write transaction is active.
   274  **    * An EXCLUSIVE or greater lock is held on the database file.
   275  **    * All writing and syncing of journal and database data has finished.
   276  **      If no error occurred, all that remains is to finalize the journal to
   277  **      commit the transaction. If an error did occur, the caller will need
   278  **      to rollback the transaction. 
   279  **
   280  **  ERROR:
   281  **
   282  **    The ERROR state is entered when an IO or disk-full error (including
   283  **    SQLITE_IOERR_NOMEM) occurs at a point in the code that makes it 
   284  **    difficult to be sure that the in-memory pager state (cache contents, 
   285  **    db size etc.) are consistent with the contents of the file-system.
   286  **
   287  **    Temporary pager files may enter the ERROR state, but in-memory pagers
   288  **    cannot.
   289  **
   290  **    For example, if an IO error occurs while performing a rollback, 
   291  **    the contents of the page-cache may be left in an inconsistent state.
   292  **    At this point it would be dangerous to change back to READER state
   293  **    (as usually happens after a rollback). Any subsequent readers might
   294  **    report database corruption (due to the inconsistent cache), and if
   295  **    they upgrade to writers, they may inadvertently corrupt the database
   296  **    file. To avoid this hazard, the pager switches into the ERROR state
   297  **    instead of READER following such an error.
   298  **
   299  **    Once it has entered the ERROR state, any attempt to use the pager
   300  **    to read or write data returns an error. Eventually, once all 
   301  **    outstanding transactions have been abandoned, the pager is able to
   302  **    transition back to OPEN state, discarding the contents of the 
   303  **    page-cache and any other in-memory state at the same time. Everything
   304  **    is reloaded from disk (and, if necessary, hot-journal rollback peformed)
   305  **    when a read-transaction is next opened on the pager (transitioning
   306  **    the pager into READER state). At that point the system has recovered 
   307  **    from the error.
   308  **
   309  **    Specifically, the pager jumps into the ERROR state if:
   310  **
   311  **      1. An error occurs while attempting a rollback. This happens in
   312  **         function sqlite3PagerRollback().
   313  **
   314  **      2. An error occurs while attempting to finalize a journal file
   315  **         following a commit in function sqlite3PagerCommitPhaseTwo().
   316  **
   317  **      3. An error occurs while attempting to write to the journal or
   318  **         database file in function pagerStress() in order to free up
   319  **         memory.
   320  **
   321  **    In other cases, the error is returned to the b-tree layer. The b-tree
   322  **    layer then attempts a rollback operation. If the error condition 
   323  **    persists, the pager enters the ERROR state via condition (1) above.
   324  **
   325  **    Condition (3) is necessary because it can be triggered by a read-only
   326  **    statement executed within a transaction. In this case, if the error
   327  **    code were simply returned to the user, the b-tree layer would not
   328  **    automatically attempt a rollback, as it assumes that an error in a
   329  **    read-only statement cannot leave the pager in an internally inconsistent 
   330  **    state.
   331  **
   332  **    * The Pager.errCode variable is set to something other than SQLITE_OK.
   333  **    * There are one or more outstanding references to pages (after the
   334  **      last reference is dropped the pager should move back to OPEN state).
   335  **    * The pager is not an in-memory pager.
   336  **    
   337  **
   338  ** Notes:
   339  **
   340  **   * A pager is never in WRITER_DBMOD or WRITER_FINISHED state if the
   341  **     connection is open in WAL mode. A WAL connection is always in one
   342  **     of the first four states.
   343  **
   344  **   * Normally, a connection open in exclusive mode is never in PAGER_OPEN
   345  **     state. There are two exceptions: immediately after exclusive-mode has
   346  **     been turned on (and before any read or write transactions are 
   347  **     executed), and when the pager is leaving the "error state".
   348  **
   349  **   * See also: assert_pager_state().
   350  */
   351  #define PAGER_OPEN                  0
   352  #define PAGER_READER                1
   353  #define PAGER_WRITER_LOCKED         2
   354  #define PAGER_WRITER_CACHEMOD       3
   355  #define PAGER_WRITER_DBMOD          4
   356  #define PAGER_WRITER_FINISHED       5
   357  #define PAGER_ERROR                 6
   358  
   359  /*
   360  ** The Pager.eLock variable is almost always set to one of the 
   361  ** following locking-states, according to the lock currently held on
   362  ** the database file: NO_LOCK, SHARED_LOCK, RESERVED_LOCK or EXCLUSIVE_LOCK.
   363  ** This variable is kept up to date as locks are taken and released by
   364  ** the pagerLockDb() and pagerUnlockDb() wrappers.
   365  **
   366  ** If the VFS xLock() or xUnlock() returns an error other than SQLITE_BUSY
   367  ** (i.e. one of the SQLITE_IOERR subtypes), it is not clear whether or not
   368  ** the operation was successful. In these circumstances pagerLockDb() and
   369  ** pagerUnlockDb() take a conservative approach - eLock is always updated
   370  ** when unlocking the file, and only updated when locking the file if the
   371  ** VFS call is successful. This way, the Pager.eLock variable may be set
   372  ** to a less exclusive (lower) value than the lock that is actually held
   373  ** at the system level, but it is never set to a more exclusive value.
   374  **
   375  ** This is usually safe. If an xUnlock fails or appears to fail, there may 
   376  ** be a few redundant xLock() calls or a lock may be held for longer than
   377  ** required, but nothing really goes wrong.
   378  **
   379  ** The exception is when the database file is unlocked as the pager moves
   380  ** from ERROR to OPEN state. At this point there may be a hot-journal file 
   381  ** in the file-system that needs to be rolled back (as part of an OPEN->SHARED
   382  ** transition, by the same pager or any other). If the call to xUnlock()
   383  ** fails at this point and the pager is left holding an EXCLUSIVE lock, this
   384  ** can confuse the call to xCheckReservedLock() call made later as part
   385  ** of hot-journal detection.
   386  **
   387  ** xCheckReservedLock() is defined as returning true "if there is a RESERVED 
   388  ** lock held by this process or any others". So xCheckReservedLock may 
   389  ** return true because the caller itself is holding an EXCLUSIVE lock (but
   390  ** doesn't know it because of a previous error in xUnlock). If this happens
   391  ** a hot-journal may be mistaken for a journal being created by an active
   392  ** transaction in another process, causing SQLite to read from the database
   393  ** without rolling it back.
   394  **
   395  ** To work around this, if a call to xUnlock() fails when unlocking the
   396  ** database in the ERROR state, Pager.eLock is set to UNKNOWN_LOCK. It
   397  ** is only changed back to a real locking state after a successful call
   398  ** to xLock(EXCLUSIVE). Also, the code to do the OPEN->SHARED state transition
   399  ** omits the check for a hot-journal if Pager.eLock is set to UNKNOWN_LOCK 
   400  ** lock. Instead, it assumes a hot-journal exists and obtains an EXCLUSIVE
   401  ** lock on the database file before attempting to roll it back. See function
   402  ** PagerSharedLock() for more detail.
   403  **
   404  ** Pager.eLock may only be set to UNKNOWN_LOCK when the pager is in 
   405  ** PAGER_OPEN state.
   406  */
   407  #define UNKNOWN_LOCK                (EXCLUSIVE_LOCK+1)
   408  
   409  /*
   410  ** The maximum allowed sector size. 64KiB. If the xSectorsize() method 
   411  ** returns a value larger than this, then MAX_SECTOR_SIZE is used instead.
   412  ** This could conceivably cause corruption following a power failure on
   413  ** such a system. This is currently an undocumented limit.
   414  */
   415  #define MAX_SECTOR_SIZE 0x10000
   416  
   417  
   418  /*
   419  ** An instance of the following structure is allocated for each active
   420  ** savepoint and statement transaction in the system. All such structures
   421  ** are stored in the Pager.aSavepoint[] array, which is allocated and
   422  ** resized using sqlite3Realloc().
   423  **
   424  ** When a savepoint is created, the PagerSavepoint.iHdrOffset field is
   425  ** set to 0. If a journal-header is written into the main journal while
   426  ** the savepoint is active, then iHdrOffset is set to the byte offset 
   427  ** immediately following the last journal record written into the main
   428  ** journal before the journal-header. This is required during savepoint
   429  ** rollback (see pagerPlaybackSavepoint()).
   430  */
   431  typedef struct PagerSavepoint PagerSavepoint;
   432  struct PagerSavepoint {
   433    i64 iOffset;                 /* Starting offset in main journal */
   434    i64 iHdrOffset;              /* See above */
   435    Bitvec *pInSavepoint;        /* Set of pages in this savepoint */
   436    Pgno nOrig;                  /* Original number of pages in file */
   437    Pgno iSubRec;                /* Index of first record in sub-journal */
   438  #ifndef SQLITE_OMIT_WAL
   439    u32 aWalData[WAL_SAVEPOINT_NDATA];        /* WAL savepoint context */
   440  #endif
   441  };
   442  
   443  /*
   444  ** Bits of the Pager.doNotSpill flag.  See further description below.
   445  */
   446  #define SPILLFLAG_OFF         0x01 /* Never spill cache.  Set via pragma */
   447  #define SPILLFLAG_ROLLBACK    0x02 /* Current rolling back, so do not spill */
   448  #define SPILLFLAG_NOSYNC      0x04 /* Spill is ok, but do not sync */
   449  
   450  /*
   451  ** An open page cache is an instance of struct Pager. A description of
   452  ** some of the more important member variables follows:
   453  **
   454  ** eState
   455  **
   456  **   The current 'state' of the pager object. See the comment and state
   457  **   diagram above for a description of the pager state.
   458  **
   459  ** eLock
   460  **
   461  **   For a real on-disk database, the current lock held on the database file -
   462  **   NO_LOCK, SHARED_LOCK, RESERVED_LOCK or EXCLUSIVE_LOCK.
   463  **
   464  **   For a temporary or in-memory database (neither of which require any
   465  **   locks), this variable is always set to EXCLUSIVE_LOCK. Since such
   466  **   databases always have Pager.exclusiveMode==1, this tricks the pager
   467  **   logic into thinking that it already has all the locks it will ever
   468  **   need (and no reason to release them).
   469  **
   470  **   In some (obscure) circumstances, this variable may also be set to
   471  **   UNKNOWN_LOCK. See the comment above the #define of UNKNOWN_LOCK for
   472  **   details.
   473  **
   474  ** changeCountDone
   475  **
   476  **   This boolean variable is used to make sure that the change-counter 
   477  **   (the 4-byte header field at byte offset 24 of the database file) is 
   478  **   not updated more often than necessary. 
   479  **
   480  **   It is set to true when the change-counter field is updated, which 
   481  **   can only happen if an exclusive lock is held on the database file.
   482  **   It is cleared (set to false) whenever an exclusive lock is 
   483  **   relinquished on the database file. Each time a transaction is committed,
   484  **   The changeCountDone flag is inspected. If it is true, the work of
   485  **   updating the change-counter is omitted for the current transaction.
   486  **
   487  **   This mechanism means that when running in exclusive mode, a connection 
   488  **   need only update the change-counter once, for the first transaction
   489  **   committed.
   490  **
   491  ** setMaster
   492  **
   493  **   When PagerCommitPhaseOne() is called to commit a transaction, it may
   494  **   (or may not) specify a master-journal name to be written into the 
   495  **   journal file before it is synced to disk.
   496  **
   497  **   Whether or not a journal file contains a master-journal pointer affects 
   498  **   the way in which the journal file is finalized after the transaction is 
   499  **   committed or rolled back when running in "journal_mode=PERSIST" mode.
   500  **   If a journal file does not contain a master-journal pointer, it is
   501  **   finalized by overwriting the first journal header with zeroes. If
   502  **   it does contain a master-journal pointer the journal file is finalized 
   503  **   by truncating it to zero bytes, just as if the connection were 
   504  **   running in "journal_mode=truncate" mode.
   505  **
   506  **   Journal files that contain master journal pointers cannot be finalized
   507  **   simply by overwriting the first journal-header with zeroes, as the
   508  **   master journal pointer could interfere with hot-journal rollback of any
   509  **   subsequently interrupted transaction that reuses the journal file.
   510  **
   511  **   The flag is cleared as soon as the journal file is finalized (either
   512  **   by PagerCommitPhaseTwo or PagerRollback). If an IO error prevents the
   513  **   journal file from being successfully finalized, the setMaster flag
   514  **   is cleared anyway (and the pager will move to ERROR state).
   515  **
   516  ** doNotSpill
   517  **
   518  **   This variables control the behavior of cache-spills  (calls made by
   519  **   the pcache module to the pagerStress() routine to write cached data
   520  **   to the file-system in order to free up memory).
   521  **
   522  **   When bits SPILLFLAG_OFF or SPILLFLAG_ROLLBACK of doNotSpill are set,
   523  **   writing to the database from pagerStress() is disabled altogether.
   524  **   The SPILLFLAG_ROLLBACK case is done in a very obscure case that
   525  **   comes up during savepoint rollback that requires the pcache module
   526  **   to allocate a new page to prevent the journal file from being written
   527  **   while it is being traversed by code in pager_playback().  The SPILLFLAG_OFF
   528  **   case is a user preference.
   529  ** 
   530  **   If the SPILLFLAG_NOSYNC bit is set, writing to the database from
   531  **   pagerStress() is permitted, but syncing the journal file is not.
   532  **   This flag is set by sqlite3PagerWrite() when the file-system sector-size
   533  **   is larger than the database page-size in order to prevent a journal sync
   534  **   from happening in between the journalling of two pages on the same sector. 
   535  **
   536  ** subjInMemory
   537  **
   538  **   This is a boolean variable. If true, then any required sub-journal
   539  **   is opened as an in-memory journal file. If false, then in-memory
   540  **   sub-journals are only used for in-memory pager files.
   541  **
   542  **   This variable is updated by the upper layer each time a new 
   543  **   write-transaction is opened.
   544  **
   545  ** dbSize, dbOrigSize, dbFileSize
   546  **
   547  **   Variable dbSize is set to the number of pages in the database file.
   548  **   It is valid in PAGER_READER and higher states (all states except for
   549  **   OPEN and ERROR). 
   550  **
   551  **   dbSize is set based on the size of the database file, which may be 
   552  **   larger than the size of the database (the value stored at offset
   553  **   28 of the database header by the btree). If the size of the file
   554  **   is not an integer multiple of the page-size, the value stored in
   555  **   dbSize is rounded down (i.e. a 5KB file with 2K page-size has dbSize==2).
   556  **   Except, any file that is greater than 0 bytes in size is considered
   557  **   to have at least one page. (i.e. a 1KB file with 2K page-size leads
   558  **   to dbSize==1).
   559  **
   560  **   During a write-transaction, if pages with page-numbers greater than
   561  **   dbSize are modified in the cache, dbSize is updated accordingly.
   562  **   Similarly, if the database is truncated using PagerTruncateImage(), 
   563  **   dbSize is updated.
   564  **
   565  **   Variables dbOrigSize and dbFileSize are valid in states 
   566  **   PAGER_WRITER_LOCKED and higher. dbOrigSize is a copy of the dbSize
   567  **   variable at the start of the transaction. It is used during rollback,
   568  **   and to determine whether or not pages need to be journalled before
   569  **   being modified.
   570  **
   571  **   Throughout a write-transaction, dbFileSize contains the size of
   572  **   the file on disk in pages. It is set to a copy of dbSize when the
   573  **   write-transaction is first opened, and updated when VFS calls are made
   574  **   to write or truncate the database file on disk. 
   575  **
   576  **   The only reason the dbFileSize variable is required is to suppress 
   577  **   unnecessary calls to xTruncate() after committing a transaction. If, 
   578  **   when a transaction is committed, the dbFileSize variable indicates 
   579  **   that the database file is larger than the database image (Pager.dbSize), 
   580  **   pager_truncate() is called. The pager_truncate() call uses xFilesize()
   581  **   to measure the database file on disk, and then truncates it if required.
   582  **   dbFileSize is not used when rolling back a transaction. In this case
   583  **   pager_truncate() is called unconditionally (which means there may be
   584  **   a call to xFilesize() that is not strictly required). In either case,
   585  **   pager_truncate() may cause the file to become smaller or larger.
   586  **
   587  ** dbHintSize
   588  **
   589  **   The dbHintSize variable is used to limit the number of calls made to
   590  **   the VFS xFileControl(FCNTL_SIZE_HINT) method. 
   591  **
   592  **   dbHintSize is set to a copy of the dbSize variable when a
   593  **   write-transaction is opened (at the same time as dbFileSize and
   594  **   dbOrigSize). If the xFileControl(FCNTL_SIZE_HINT) method is called,
   595  **   dbHintSize is increased to the number of pages that correspond to the
   596  **   size-hint passed to the method call. See pager_write_pagelist() for 
   597  **   details.
   598  **
   599  ** errCode
   600  **
   601  **   The Pager.errCode variable is only ever used in PAGER_ERROR state. It
   602  **   is set to zero in all other states. In PAGER_ERROR state, Pager.errCode 
   603  **   is always set to SQLITE_FULL, SQLITE_IOERR or one of the SQLITE_IOERR_XXX 
   604  **   sub-codes.
   605  **
   606  ** syncFlags, walSyncFlags
   607  **
   608  **   syncFlags is either SQLITE_SYNC_NORMAL (0x02) or SQLITE_SYNC_FULL (0x03).
   609  **   syncFlags is used for rollback mode.  walSyncFlags is used for WAL mode
   610  **   and contains the flags used to sync the checkpoint operations in the
   611  **   lower two bits, and sync flags used for transaction commits in the WAL
   612  **   file in bits 0x04 and 0x08.  In other words, to get the correct sync flags
   613  **   for checkpoint operations, use (walSyncFlags&0x03) and to get the correct
   614  **   sync flags for transaction commit, use ((walSyncFlags>>2)&0x03).  Note
   615  **   that with synchronous=NORMAL in WAL mode, transaction commit is not synced
   616  **   meaning that the 0x04 and 0x08 bits are both zero.
   617  */
   618  struct Pager {
   619    sqlite3_vfs *pVfs;          /* OS functions to use for IO */
   620    u8 exclusiveMode;           /* Boolean. True if locking_mode==EXCLUSIVE */
   621    u8 journalMode;             /* One of the PAGER_JOURNALMODE_* values */
   622    u8 useJournal;              /* Use a rollback journal on this file */
   623    u8 noSync;                  /* Do not sync the journal if true */
   624    u8 fullSync;                /* Do extra syncs of the journal for robustness */
   625    u8 extraSync;               /* sync directory after journal delete */
   626    u8 syncFlags;               /* SYNC_NORMAL or SYNC_FULL otherwise */
   627    u8 walSyncFlags;            /* See description above */
   628    u8 tempFile;                /* zFilename is a temporary or immutable file */
   629    u8 noLock;                  /* Do not lock (except in WAL mode) */
   630    u8 readOnly;                /* True for a read-only database */
   631    u8 memDb;                   /* True to inhibit all file I/O */
   632  
   633    /**************************************************************************
   634    ** The following block contains those class members that change during
   635    ** routine operation.  Class members not in this block are either fixed
   636    ** when the pager is first created or else only change when there is a
   637    ** significant mode change (such as changing the page_size, locking_mode,
   638    ** or the journal_mode).  From another view, these class members describe
   639    ** the "state" of the pager, while other class members describe the
   640    ** "configuration" of the pager.
   641    */
   642    u8 eState;                  /* Pager state (OPEN, READER, WRITER_LOCKED..) */
   643    u8 eLock;                   /* Current lock held on database file */
   644    u8 changeCountDone;         /* Set after incrementing the change-counter */
   645    u8 setMaster;               /* True if a m-j name has been written to jrnl */
   646    u8 doNotSpill;              /* Do not spill the cache when non-zero */
   647    u8 subjInMemory;            /* True to use in-memory sub-journals */
   648    u8 bUseFetch;               /* True to use xFetch() */
   649    u8 hasHeldSharedLock;       /* True if a shared lock has ever been held */
   650    Pgno dbSize;                /* Number of pages in the database */
   651    Pgno dbOrigSize;            /* dbSize before the current transaction */
   652    Pgno dbFileSize;            /* Number of pages in the database file */
   653    Pgno dbHintSize;            /* Value passed to FCNTL_SIZE_HINT call */
   654    int errCode;                /* One of several kinds of errors */
   655    int nRec;                   /* Pages journalled since last j-header written */
   656    u32 cksumInit;              /* Quasi-random value added to every checksum */
   657    u32 nSubRec;                /* Number of records written to sub-journal */
   658    Bitvec *pInJournal;         /* One bit for each page in the database file */
   659    sqlite3_file *fd;           /* File descriptor for database */
   660    sqlite3_file *jfd;          /* File descriptor for main journal */
   661    sqlite3_file *sjfd;         /* File descriptor for sub-journal */
   662    i64 journalOff;             /* Current write offset in the journal file */
   663    i64 journalHdr;             /* Byte offset to previous journal header */
   664    sqlite3_backup *pBackup;    /* Pointer to list of ongoing backup processes */
   665    PagerSavepoint *aSavepoint; /* Array of active savepoints */
   666    int nSavepoint;             /* Number of elements in aSavepoint[] */
   667    u32 iDataVersion;           /* Changes whenever database content changes */
   668    char dbFileVers[16];        /* Changes whenever database file changes */
   669  
   670    int nMmapOut;               /* Number of mmap pages currently outstanding */
   671    sqlite3_int64 szMmap;       /* Desired maximum mmap size */
   672    PgHdr *pMmapFreelist;       /* List of free mmap page headers (pDirty) */
   673    /*
   674    ** End of the routinely-changing class members
   675    ***************************************************************************/
   676  
   677    u16 nExtra;                 /* Add this many bytes to each in-memory page */
   678    i16 nReserve;               /* Number of unused bytes at end of each page */
   679    u32 vfsFlags;               /* Flags for sqlite3_vfs.xOpen() */
   680    u32 sectorSize;             /* Assumed sector size during rollback */
   681    int pageSize;               /* Number of bytes in a page */
   682    Pgno mxPgno;                /* Maximum allowed size of the database */
   683    i64 journalSizeLimit;       /* Size limit for persistent journal files */
   684    char *zFilename;            /* Name of the database file */
   685    char *zJournal;             /* Name of the journal file */
   686    int (*xBusyHandler)(void*); /* Function to call when busy */
   687    void *pBusyHandlerArg;      /* Context argument for xBusyHandler */
   688    int aStat[4];               /* Total cache hits, misses, writes, spills */
   689  #ifdef SQLITE_TEST
   690    int nRead;                  /* Database pages read */
   691  #endif
   692    void (*xReiniter)(DbPage*); /* Call this routine when reloading pages */
   693    int (*xGet)(Pager*,Pgno,DbPage**,int); /* Routine to fetch a patch */
   694    char *pTmpSpace;            /* Pager.pageSize bytes of space for tmp use */
   695    PCache *pPCache;            /* Pointer to page cache object */
   696  #ifndef SQLITE_OMIT_WAL
   697    Wal *pWal;                  /* Write-ahead log used by "journal_mode=wal" */
   698    char *zWal;                 /* File name for write-ahead log */
   699  #endif
   700  };
   701  
   702  /*
   703  ** Indexes for use with Pager.aStat[]. The Pager.aStat[] array contains
   704  ** the values accessed by passing SQLITE_DBSTATUS_CACHE_HIT, CACHE_MISS 
   705  ** or CACHE_WRITE to sqlite3_db_status().
   706  */
   707  #define PAGER_STAT_HIT   0
   708  #define PAGER_STAT_MISS  1
   709  #define PAGER_STAT_WRITE 2
   710  #define PAGER_STAT_SPILL 3
   711  
   712  /*
   713  ** The following global variables hold counters used for
   714  ** testing purposes only.  These variables do not exist in
   715  ** a non-testing build.  These variables are not thread-safe.
   716  */
   717  #ifdef SQLITE_TEST
   718  int sqlite3_pager_readdb_count = 0;    /* Number of full pages read from DB */
   719  int sqlite3_pager_writedb_count = 0;   /* Number of full pages written to DB */
   720  int sqlite3_pager_writej_count = 0;    /* Number of pages written to journal */
   721  # define PAGER_INCR(v)  v++
   722  #else
   723  # define PAGER_INCR(v)
   724  #endif
   725  
   726  
   727  
   728  /*
   729  ** Journal files begin with the following magic string.  The data
   730  ** was obtained from /dev/random.  It is used only as a sanity check.
   731  **
   732  ** Since version 2.8.0, the journal format contains additional sanity
   733  ** checking information.  If the power fails while the journal is being
   734  ** written, semi-random garbage data might appear in the journal
   735  ** file after power is restored.  If an attempt is then made
   736  ** to roll the journal back, the database could be corrupted.  The additional
   737  ** sanity checking data is an attempt to discover the garbage in the
   738  ** journal and ignore it.
   739  **
   740  ** The sanity checking information for the new journal format consists
   741  ** of a 32-bit checksum on each page of data.  The checksum covers both
   742  ** the page number and the pPager->pageSize bytes of data for the page.
   743  ** This cksum is initialized to a 32-bit random value that appears in the
   744  ** journal file right after the header.  The random initializer is important,
   745  ** because garbage data that appears at the end of a journal is likely
   746  ** data that was once in other files that have now been deleted.  If the
   747  ** garbage data came from an obsolete journal file, the checksums might
   748  ** be correct.  But by initializing the checksum to random value which
   749  ** is different for every journal, we minimize that risk.
   750  */
   751  static const unsigned char aJournalMagic[] = {
   752    0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, 0xd7,
   753  };
   754  
   755  /*
   756  ** The size of the of each page record in the journal is given by
   757  ** the following macro.
   758  */
   759  #define JOURNAL_PG_SZ(pPager)  ((pPager->pageSize) + 8)
   760  
   761  /*
   762  ** The journal header size for this pager. This is usually the same 
   763  ** size as a single disk sector. See also setSectorSize().
   764  */
   765  #define JOURNAL_HDR_SZ(pPager) (pPager->sectorSize)
   766  
   767  /*
   768  ** The macro MEMDB is true if we are dealing with an in-memory database.
   769  ** We do this as a macro so that if the SQLITE_OMIT_MEMORYDB macro is set,
   770  ** the value of MEMDB will be a constant and the compiler will optimize
   771  ** out code that would never execute.
   772  */
   773  #ifdef SQLITE_OMIT_MEMORYDB
   774  # define MEMDB 0
   775  #else
   776  # define MEMDB pPager->memDb
   777  #endif
   778  
   779  /*
   780  ** The macro USEFETCH is true if we are allowed to use the xFetch and xUnfetch
   781  ** interfaces to access the database using memory-mapped I/O.
   782  */
   783  #if SQLITE_MAX_MMAP_SIZE>0
   784  # define USEFETCH(x) ((x)->bUseFetch)
   785  #else
   786  # define USEFETCH(x) 0
   787  #endif
   788  
   789  /*
   790  ** The maximum legal page number is (2^31 - 1).
   791  */
   792  #define PAGER_MAX_PGNO 2147483647
   793  
   794  /*
   795  ** The argument to this macro is a file descriptor (type sqlite3_file*).
   796  ** Return 0 if it is not open, or non-zero (but not 1) if it is.
   797  **
   798  ** This is so that expressions can be written as:
   799  **
   800  **   if( isOpen(pPager->jfd) ){ ...
   801  **
   802  ** instead of
   803  **
   804  **   if( pPager->jfd->pMethods ){ ...
   805  */
   806  #define isOpen(pFd) ((pFd)->pMethods!=0)
   807  
   808  #ifdef SQLITE_DIRECT_OVERFLOW_READ
   809  /*
   810  ** Return true if page pgno can be read directly from the database file
   811  ** by the b-tree layer. This is the case if:
   812  **
   813  **   * the database file is open,
   814  **   * there are no dirty pages in the cache, and
   815  **   * the desired page is not currently in the wal file.
   816  */
   817  int sqlite3PagerDirectReadOk(Pager *pPager, Pgno pgno){
   818    if( pPager->fd->pMethods==0 ) return 0;
   819    if( sqlite3PCacheIsDirty(pPager->pPCache) ) return 0;
   820  #ifndef SQLITE_OMIT_WAL
   821    if( pPager->pWal ){
   822      u32 iRead = 0;
   823      int rc;
   824      rc = sqlite3WalFindFrame(pPager->pWal, pgno, &iRead);
   825      return (rc==SQLITE_OK && iRead==0);
   826    }
   827  #endif
   828    return 1;
   829  }
   830  #endif
   831  
   832  #ifndef SQLITE_OMIT_WAL
   833  # define pagerUseWal(x) ((x)->pWal!=0)
   834  #else
   835  # define pagerUseWal(x) 0
   836  # define pagerRollbackWal(x) 0
   837  # define pagerWalFrames(v,w,x,y) 0
   838  # define pagerOpenWalIfPresent(z) SQLITE_OK
   839  # define pagerBeginReadTransaction(z) SQLITE_OK
   840  #endif
   841  
   842  #ifndef NDEBUG 
   843  /*
   844  ** Usage:
   845  **
   846  **   assert( assert_pager_state(pPager) );
   847  **
   848  ** This function runs many asserts to try to find inconsistencies in
   849  ** the internal state of the Pager object.
   850  */
   851  static int assert_pager_state(Pager *p){
   852    Pager *pPager = p;
   853  
   854    /* State must be valid. */
   855    assert( p->eState==PAGER_OPEN
   856         || p->eState==PAGER_READER
   857         || p->eState==PAGER_WRITER_LOCKED
   858         || p->eState==PAGER_WRITER_CACHEMOD
   859         || p->eState==PAGER_WRITER_DBMOD
   860         || p->eState==PAGER_WRITER_FINISHED
   861         || p->eState==PAGER_ERROR
   862    );
   863  
   864    /* Regardless of the current state, a temp-file connection always behaves
   865    ** as if it has an exclusive lock on the database file. It never updates
   866    ** the change-counter field, so the changeCountDone flag is always set.
   867    */
   868    assert( p->tempFile==0 || p->eLock==EXCLUSIVE_LOCK );
   869    assert( p->tempFile==0 || pPager->changeCountDone );
   870  
   871    /* If the useJournal flag is clear, the journal-mode must be "OFF". 
   872    ** And if the journal-mode is "OFF", the journal file must not be open.
   873    */
   874    assert( p->journalMode==PAGER_JOURNALMODE_OFF || p->useJournal );
   875    assert( p->journalMode!=PAGER_JOURNALMODE_OFF || !isOpen(p->jfd) );
   876  
   877    /* Check that MEMDB implies noSync. And an in-memory journal. Since 
   878    ** this means an in-memory pager performs no IO at all, it cannot encounter 
   879    ** either SQLITE_IOERR or SQLITE_FULL during rollback or while finalizing 
   880    ** a journal file. (although the in-memory journal implementation may 
   881    ** return SQLITE_IOERR_NOMEM while the journal file is being written). It 
   882    ** is therefore not possible for an in-memory pager to enter the ERROR 
   883    ** state.
   884    */
   885    if( MEMDB ){
   886      assert( !isOpen(p->fd) );
   887      assert( p->noSync );
   888      assert( p->journalMode==PAGER_JOURNALMODE_OFF 
   889           || p->journalMode==PAGER_JOURNALMODE_MEMORY 
   890      );
   891      assert( p->eState!=PAGER_ERROR && p->eState!=PAGER_OPEN );
   892      assert( pagerUseWal(p)==0 );
   893    }
   894  
   895    /* If changeCountDone is set, a RESERVED lock or greater must be held
   896    ** on the file.
   897    */
   898    assert( pPager->changeCountDone==0 || pPager->eLock>=RESERVED_LOCK );
   899    assert( p->eLock!=PENDING_LOCK );
   900  
   901    switch( p->eState ){
   902      case PAGER_OPEN:
   903        assert( !MEMDB );
   904        assert( pPager->errCode==SQLITE_OK );
   905        assert( sqlite3PcacheRefCount(pPager->pPCache)==0 || pPager->tempFile );
   906        break;
   907  
   908      case PAGER_READER:
   909        assert( pPager->errCode==SQLITE_OK );
   910        assert( p->eLock!=UNKNOWN_LOCK );
   911        assert( p->eLock>=SHARED_LOCK );
   912        break;
   913  
   914      case PAGER_WRITER_LOCKED:
   915        assert( p->eLock!=UNKNOWN_LOCK );
   916        assert( pPager->errCode==SQLITE_OK );
   917        if( !pagerUseWal(pPager) ){
   918          assert( p->eLock>=RESERVED_LOCK );
   919        }
   920        assert( pPager->dbSize==pPager->dbOrigSize );
   921        assert( pPager->dbOrigSize==pPager->dbFileSize );
   922        assert( pPager->dbOrigSize==pPager->dbHintSize );
   923        assert( pPager->setMaster==0 );
   924        break;
   925  
   926      case PAGER_WRITER_CACHEMOD:
   927        assert( p->eLock!=UNKNOWN_LOCK );
   928        assert( pPager->errCode==SQLITE_OK );
   929        if( !pagerUseWal(pPager) ){
   930          /* It is possible that if journal_mode=wal here that neither the
   931          ** journal file nor the WAL file are open. This happens during
   932          ** a rollback transaction that switches from journal_mode=off
   933          ** to journal_mode=wal.
   934          */
   935          assert( p->eLock>=RESERVED_LOCK );
   936          assert( isOpen(p->jfd) 
   937               || p->journalMode==PAGER_JOURNALMODE_OFF 
   938               || p->journalMode==PAGER_JOURNALMODE_WAL 
   939          );
   940        }
   941        assert( pPager->dbOrigSize==pPager->dbFileSize );
   942        assert( pPager->dbOrigSize==pPager->dbHintSize );
   943        break;
   944  
   945      case PAGER_WRITER_DBMOD:
   946        assert( p->eLock==EXCLUSIVE_LOCK );
   947        assert( pPager->errCode==SQLITE_OK );
   948        assert( !pagerUseWal(pPager) );
   949        assert( p->eLock>=EXCLUSIVE_LOCK );
   950        assert( isOpen(p->jfd) 
   951             || p->journalMode==PAGER_JOURNALMODE_OFF 
   952             || p->journalMode==PAGER_JOURNALMODE_WAL 
   953             || (sqlite3OsDeviceCharacteristics(p->fd)&SQLITE_IOCAP_BATCH_ATOMIC)
   954        );
   955        assert( pPager->dbOrigSize<=pPager->dbHintSize );
   956        break;
   957  
   958      case PAGER_WRITER_FINISHED:
   959        assert( p->eLock==EXCLUSIVE_LOCK );
   960        assert( pPager->errCode==SQLITE_OK );
   961        assert( !pagerUseWal(pPager) );
   962        assert( isOpen(p->jfd) 
   963             || p->journalMode==PAGER_JOURNALMODE_OFF 
   964             || p->journalMode==PAGER_JOURNALMODE_WAL 
   965             || (sqlite3OsDeviceCharacteristics(p->fd)&SQLITE_IOCAP_BATCH_ATOMIC)
   966        );
   967        break;
   968  
   969      case PAGER_ERROR:
   970        /* There must be at least one outstanding reference to the pager if
   971        ** in ERROR state. Otherwise the pager should have already dropped
   972        ** back to OPEN state.
   973        */
   974        assert( pPager->errCode!=SQLITE_OK );
   975        assert( sqlite3PcacheRefCount(pPager->pPCache)>0 || pPager->tempFile );
   976        break;
   977    }
   978  
   979    return 1;
   980  }
   981  #endif /* ifndef NDEBUG */
   982  
   983  #ifdef SQLITE_DEBUG 
   984  /*
   985  ** Return a pointer to a human readable string in a static buffer
   986  ** containing the state of the Pager object passed as an argument. This
   987  ** is intended to be used within debuggers. For example, as an alternative
   988  ** to "print *pPager" in gdb:
   989  **
   990  ** (gdb) printf "%s", print_pager_state(pPager)
   991  **
   992  ** This routine has external linkage in order to suppress compiler warnings
   993  ** about an unused function.  It is enclosed within SQLITE_DEBUG and so does
   994  ** not appear in normal builds.
   995  */
   996  char *print_pager_state(Pager *p){
   997    static char zRet[1024];
   998  
   999    sqlite3_snprintf(1024, zRet,
  1000        "Filename:      %s\n"
  1001        "State:         %s errCode=%d\n"
  1002        "Lock:          %s\n"
  1003        "Locking mode:  locking_mode=%s\n"
  1004        "Journal mode:  journal_mode=%s\n"
  1005        "Backing store: tempFile=%d memDb=%d useJournal=%d\n"
  1006        "Journal:       journalOff=%lld journalHdr=%lld\n"
  1007        "Size:          dbsize=%d dbOrigSize=%d dbFileSize=%d\n"
  1008        , p->zFilename
  1009        , p->eState==PAGER_OPEN            ? "OPEN" :
  1010          p->eState==PAGER_READER          ? "READER" :
  1011          p->eState==PAGER_WRITER_LOCKED   ? "WRITER_LOCKED" :
  1012          p->eState==PAGER_WRITER_CACHEMOD ? "WRITER_CACHEMOD" :
  1013          p->eState==PAGER_WRITER_DBMOD    ? "WRITER_DBMOD" :
  1014          p->eState==PAGER_WRITER_FINISHED ? "WRITER_FINISHED" :
  1015          p->eState==PAGER_ERROR           ? "ERROR" : "?error?"
  1016        , (int)p->errCode
  1017        , p->eLock==NO_LOCK         ? "NO_LOCK" :
  1018          p->eLock==RESERVED_LOCK   ? "RESERVED" :
  1019          p->eLock==EXCLUSIVE_LOCK  ? "EXCLUSIVE" :
  1020          p->eLock==SHARED_LOCK     ? "SHARED" :
  1021          p->eLock==UNKNOWN_LOCK    ? "UNKNOWN" : "?error?"
  1022        , p->exclusiveMode ? "exclusive" : "normal"
  1023        , p->journalMode==PAGER_JOURNALMODE_MEMORY   ? "memory" :
  1024          p->journalMode==PAGER_JOURNALMODE_OFF      ? "off" :
  1025          p->journalMode==PAGER_JOURNALMODE_DELETE   ? "delete" :
  1026          p->journalMode==PAGER_JOURNALMODE_PERSIST  ? "persist" :
  1027          p->journalMode==PAGER_JOURNALMODE_TRUNCATE ? "truncate" :
  1028          p->journalMode==PAGER_JOURNALMODE_WAL      ? "wal" : "?error?"
  1029        , (int)p->tempFile, (int)p->memDb, (int)p->useJournal
  1030        , p->journalOff, p->journalHdr
  1031        , (int)p->dbSize, (int)p->dbOrigSize, (int)p->dbFileSize
  1032    );
  1033  
  1034    return zRet;
  1035  }
  1036  #endif
  1037  
  1038  /* Forward references to the various page getters */
  1039  static int getPageNormal(Pager*,Pgno,DbPage**,int);
  1040  static int getPageError(Pager*,Pgno,DbPage**,int);
  1041  #if SQLITE_MAX_MMAP_SIZE>0
  1042  static int getPageMMap(Pager*,Pgno,DbPage**,int);
  1043  #endif
  1044  
  1045  /*
  1046  ** Set the Pager.xGet method for the appropriate routine used to fetch
  1047  ** content from the pager.
  1048  */
  1049  static void setGetterMethod(Pager *pPager){
  1050    if( pPager->errCode ){
  1051      pPager->xGet = getPageError;
  1052  #if SQLITE_MAX_MMAP_SIZE>0
  1053    }else if( USEFETCH(pPager) ){
  1054      pPager->xGet = getPageMMap;
  1055  #endif /* SQLITE_MAX_MMAP_SIZE>0 */
  1056    }else{
  1057      pPager->xGet = getPageNormal;
  1058    }
  1059  }
  1060  
  1061  /*
  1062  ** Return true if it is necessary to write page *pPg into the sub-journal.
  1063  ** A page needs to be written into the sub-journal if there exists one
  1064  ** or more open savepoints for which:
  1065  **
  1066  **   * The page-number is less than or equal to PagerSavepoint.nOrig, and
  1067  **   * The bit corresponding to the page-number is not set in
  1068  **     PagerSavepoint.pInSavepoint.
  1069  */
  1070  static int subjRequiresPage(PgHdr *pPg){
  1071    Pager *pPager = pPg->pPager;
  1072    PagerSavepoint *p;
  1073    Pgno pgno = pPg->pgno;
  1074    int i;
  1075    for(i=0; i<pPager->nSavepoint; i++){
  1076      p = &pPager->aSavepoint[i];
  1077      if( p->nOrig>=pgno && 0==sqlite3BitvecTestNotNull(p->pInSavepoint, pgno) ){
  1078        return 1;
  1079      }
  1080    }
  1081    return 0;
  1082  }
  1083  
  1084  #ifdef SQLITE_DEBUG
  1085  /*
  1086  ** Return true if the page is already in the journal file.
  1087  */
  1088  static int pageInJournal(Pager *pPager, PgHdr *pPg){
  1089    return sqlite3BitvecTest(pPager->pInJournal, pPg->pgno);
  1090  }
  1091  #endif
  1092  
  1093  /*
  1094  ** Read a 32-bit integer from the given file descriptor.  Store the integer
  1095  ** that is read in *pRes.  Return SQLITE_OK if everything worked, or an
  1096  ** error code is something goes wrong.
  1097  **
  1098  ** All values are stored on disk as big-endian.
  1099  */
  1100  static int read32bits(sqlite3_file *fd, i64 offset, u32 *pRes){
  1101    unsigned char ac[4];
  1102    int rc = sqlite3OsRead(fd, ac, sizeof(ac), offset);
  1103    if( rc==SQLITE_OK ){
  1104      *pRes = sqlite3Get4byte(ac);
  1105    }
  1106    return rc;
  1107  }
  1108  
  1109  /*
  1110  ** Write a 32-bit integer into a string buffer in big-endian byte order.
  1111  */
  1112  #define put32bits(A,B)  sqlite3Put4byte((u8*)A,B)
  1113  
  1114  
  1115  /*
  1116  ** Write a 32-bit integer into the given file descriptor.  Return SQLITE_OK
  1117  ** on success or an error code is something goes wrong.
  1118  */
  1119  static int write32bits(sqlite3_file *fd, i64 offset, u32 val){
  1120    char ac[4];
  1121    put32bits(ac, val);
  1122    return sqlite3OsWrite(fd, ac, 4, offset);
  1123  }
  1124  
  1125  /*
  1126  ** Unlock the database file to level eLock, which must be either NO_LOCK
  1127  ** or SHARED_LOCK. Regardless of whether or not the call to xUnlock()
  1128  ** succeeds, set the Pager.eLock variable to match the (attempted) new lock.
  1129  **
  1130  ** Except, if Pager.eLock is set to UNKNOWN_LOCK when this function is
  1131  ** called, do not modify it. See the comment above the #define of 
  1132  ** UNKNOWN_LOCK for an explanation of this.
  1133  */
  1134  static int pagerUnlockDb(Pager *pPager, int eLock){
  1135    int rc = SQLITE_OK;
  1136  
  1137    assert( !pPager->exclusiveMode || pPager->eLock==eLock );
  1138    assert( eLock==NO_LOCK || eLock==SHARED_LOCK );
  1139    assert( eLock!=NO_LOCK || pagerUseWal(pPager)==0 );
  1140    if( isOpen(pPager->fd) ){
  1141      assert( pPager->eLock>=eLock );
  1142      rc = pPager->noLock ? SQLITE_OK : sqlite3OsUnlock(pPager->fd, eLock);
  1143      if( pPager->eLock!=UNKNOWN_LOCK ){
  1144        pPager->eLock = (u8)eLock;
  1145      }
  1146      IOTRACE(("UNLOCK %p %d\n", pPager, eLock))
  1147    }
  1148    pPager->changeCountDone = pPager->tempFile; /* ticket fb3b3024ea238d5c */
  1149    return rc;
  1150  }
  1151  
  1152  /*
  1153  ** Lock the database file to level eLock, which must be either SHARED_LOCK,
  1154  ** RESERVED_LOCK or EXCLUSIVE_LOCK. If the caller is successful, set the
  1155  ** Pager.eLock variable to the new locking state. 
  1156  **
  1157  ** Except, if Pager.eLock is set to UNKNOWN_LOCK when this function is 
  1158  ** called, do not modify it unless the new locking state is EXCLUSIVE_LOCK. 
  1159  ** See the comment above the #define of UNKNOWN_LOCK for an explanation 
  1160  ** of this.
  1161  */
  1162  static int pagerLockDb(Pager *pPager, int eLock){
  1163    int rc = SQLITE_OK;
  1164  
  1165    assert( eLock==SHARED_LOCK || eLock==RESERVED_LOCK || eLock==EXCLUSIVE_LOCK );
  1166    if( pPager->eLock<eLock || pPager->eLock==UNKNOWN_LOCK ){
  1167      rc = pPager->noLock ? SQLITE_OK : sqlite3OsLock(pPager->fd, eLock);
  1168      if( rc==SQLITE_OK && (pPager->eLock!=UNKNOWN_LOCK||eLock==EXCLUSIVE_LOCK) ){
  1169        pPager->eLock = (u8)eLock;
  1170        IOTRACE(("LOCK %p %d\n", pPager, eLock))
  1171      }
  1172    }
  1173    return rc;
  1174  }
  1175  
  1176  /*
  1177  ** This function determines whether or not the atomic-write or
  1178  ** atomic-batch-write optimizations can be used with this pager. The
  1179  ** atomic-write optimization can be used if:
  1180  **
  1181  **  (a) the value returned by OsDeviceCharacteristics() indicates that
  1182  **      a database page may be written atomically, and
  1183  **  (b) the value returned by OsSectorSize() is less than or equal
  1184  **      to the page size.
  1185  **
  1186  ** If it can be used, then the value returned is the size of the journal 
  1187  ** file when it contains rollback data for exactly one page.
  1188  **
  1189  ** The atomic-batch-write optimization can be used if OsDeviceCharacteristics()
  1190  ** returns a value with the SQLITE_IOCAP_BATCH_ATOMIC bit set. -1 is
  1191  ** returned in this case.
  1192  **
  1193  ** If neither optimization can be used, 0 is returned.
  1194  */
  1195  static int jrnlBufferSize(Pager *pPager){
  1196    assert( !MEMDB );
  1197  
  1198  #if defined(SQLITE_ENABLE_ATOMIC_WRITE) \
  1199   || defined(SQLITE_ENABLE_BATCH_ATOMIC_WRITE)
  1200    int dc;                           /* Device characteristics */
  1201  
  1202    assert( isOpen(pPager->fd) );
  1203    dc = sqlite3OsDeviceCharacteristics(pPager->fd);
  1204  #else
  1205    UNUSED_PARAMETER(pPager);
  1206  #endif
  1207  
  1208  #ifdef SQLITE_ENABLE_BATCH_ATOMIC_WRITE
  1209    if( pPager->dbSize>0 && (dc&SQLITE_IOCAP_BATCH_ATOMIC) ){
  1210      return -1;
  1211    }
  1212  #endif
  1213  
  1214  #ifdef SQLITE_ENABLE_ATOMIC_WRITE
  1215    {
  1216      int nSector = pPager->sectorSize;
  1217      int szPage = pPager->pageSize;
  1218  
  1219      assert(SQLITE_IOCAP_ATOMIC512==(512>>8));
  1220      assert(SQLITE_IOCAP_ATOMIC64K==(65536>>8));
  1221      if( 0==(dc&(SQLITE_IOCAP_ATOMIC|(szPage>>8)) || nSector>szPage) ){
  1222        return 0;
  1223      }
  1224    }
  1225  
  1226    return JOURNAL_HDR_SZ(pPager) + JOURNAL_PG_SZ(pPager);
  1227  #endif
  1228  
  1229    return 0;
  1230  }
  1231  
  1232  /*
  1233  ** If SQLITE_CHECK_PAGES is defined then we do some sanity checking
  1234  ** on the cache using a hash function.  This is used for testing
  1235  ** and debugging only.
  1236  */
  1237  #ifdef SQLITE_CHECK_PAGES
  1238  /*
  1239  ** Return a 32-bit hash of the page data for pPage.
  1240  */
  1241  static u32 pager_datahash(int nByte, unsigned char *pData){
  1242    u32 hash = 0;
  1243    int i;
  1244    for(i=0; i<nByte; i++){
  1245      hash = (hash*1039) + pData[i];
  1246    }
  1247    return hash;
  1248  }
  1249  static u32 pager_pagehash(PgHdr *pPage){
  1250    return pager_datahash(pPage->pPager->pageSize, (unsigned char *)pPage->pData);
  1251  }
  1252  static void pager_set_pagehash(PgHdr *pPage){
  1253    pPage->pageHash = pager_pagehash(pPage);
  1254  }
  1255  
  1256  /*
  1257  ** The CHECK_PAGE macro takes a PgHdr* as an argument. If SQLITE_CHECK_PAGES
  1258  ** is defined, and NDEBUG is not defined, an assert() statement checks
  1259  ** that the page is either dirty or still matches the calculated page-hash.
  1260  */
  1261  #define CHECK_PAGE(x) checkPage(x)
  1262  static void checkPage(PgHdr *pPg){
  1263    Pager *pPager = pPg->pPager;
  1264    assert( pPager->eState!=PAGER_ERROR );
  1265    assert( (pPg->flags&PGHDR_DIRTY) || pPg->pageHash==pager_pagehash(pPg) );
  1266  }
  1267  
  1268  #else
  1269  #define pager_datahash(X,Y)  0
  1270  #define pager_pagehash(X)  0
  1271  #define pager_set_pagehash(X)
  1272  #define CHECK_PAGE(x)
  1273  #endif  /* SQLITE_CHECK_PAGES */
  1274  
  1275  /*
  1276  ** When this is called the journal file for pager pPager must be open.
  1277  ** This function attempts to read a master journal file name from the 
  1278  ** end of the file and, if successful, copies it into memory supplied 
  1279  ** by the caller. See comments above writeMasterJournal() for the format
  1280  ** used to store a master journal file name at the end of a journal file.
  1281  **
  1282  ** zMaster must point to a buffer of at least nMaster bytes allocated by
  1283  ** the caller. This should be sqlite3_vfs.mxPathname+1 (to ensure there is
  1284  ** enough space to write the master journal name). If the master journal
  1285  ** name in the journal is longer than nMaster bytes (including a
  1286  ** nul-terminator), then this is handled as if no master journal name
  1287  ** were present in the journal.
  1288  **
  1289  ** If a master journal file name is present at the end of the journal
  1290  ** file, then it is copied into the buffer pointed to by zMaster. A
  1291  ** nul-terminator byte is appended to the buffer following the master
  1292  ** journal file name.
  1293  **
  1294  ** If it is determined that no master journal file name is present 
  1295  ** zMaster[0] is set to 0 and SQLITE_OK returned.
  1296  **
  1297  ** If an error occurs while reading from the journal file, an SQLite
  1298  ** error code is returned.
  1299  */
  1300  static int readMasterJournal(sqlite3_file *pJrnl, char *zMaster, u32 nMaster){
  1301    int rc;                    /* Return code */
  1302    u32 len;                   /* Length in bytes of master journal name */
  1303    i64 szJ;                   /* Total size in bytes of journal file pJrnl */
  1304    u32 cksum;                 /* MJ checksum value read from journal */
  1305    u32 u;                     /* Unsigned loop counter */
  1306    unsigned char aMagic[8];   /* A buffer to hold the magic header */
  1307    zMaster[0] = '\0';
  1308  
  1309    if( SQLITE_OK!=(rc = sqlite3OsFileSize(pJrnl, &szJ))
  1310     || szJ<16
  1311     || SQLITE_OK!=(rc = read32bits(pJrnl, szJ-16, &len))
  1312     || len>=nMaster 
  1313     || len>szJ-16
  1314     || len==0 
  1315     || SQLITE_OK!=(rc = read32bits(pJrnl, szJ-12, &cksum))
  1316     || SQLITE_OK!=(rc = sqlite3OsRead(pJrnl, aMagic, 8, szJ-8))
  1317     || memcmp(aMagic, aJournalMagic, 8)
  1318     || SQLITE_OK!=(rc = sqlite3OsRead(pJrnl, zMaster, len, szJ-16-len))
  1319    ){
  1320      return rc;
  1321    }
  1322  
  1323    /* See if the checksum matches the master journal name */
  1324    for(u=0; u<len; u++){
  1325      cksum -= zMaster[u];
  1326    }
  1327    if( cksum ){
  1328      /* If the checksum doesn't add up, then one or more of the disk sectors
  1329      ** containing the master journal filename is corrupted. This means
  1330      ** definitely roll back, so just return SQLITE_OK and report a (nul)
  1331      ** master-journal filename.
  1332      */
  1333      len = 0;
  1334    }
  1335    zMaster[len] = '\0';
  1336    zMaster[len+1] = '\0';
  1337     
  1338    return SQLITE_OK;
  1339  }
  1340  
  1341  /*
  1342  ** Return the offset of the sector boundary at or immediately 
  1343  ** following the value in pPager->journalOff, assuming a sector 
  1344  ** size of pPager->sectorSize bytes.
  1345  **
  1346  ** i.e for a sector size of 512:
  1347  **
  1348  **   Pager.journalOff          Return value
  1349  **   ---------------------------------------
  1350  **   0                         0
  1351  **   512                       512
  1352  **   100                       512
  1353  **   2000                      2048
  1354  ** 
  1355  */
  1356  static i64 journalHdrOffset(Pager *pPager){
  1357    i64 offset = 0;
  1358    i64 c = pPager->journalOff;
  1359    if( c ){
  1360      offset = ((c-1)/JOURNAL_HDR_SZ(pPager) + 1) * JOURNAL_HDR_SZ(pPager);
  1361    }
  1362    assert( offset%JOURNAL_HDR_SZ(pPager)==0 );
  1363    assert( offset>=c );
  1364    assert( (offset-c)<JOURNAL_HDR_SZ(pPager) );
  1365    return offset;
  1366  }
  1367  
  1368  /*
  1369  ** The journal file must be open when this function is called.
  1370  **
  1371  ** This function is a no-op if the journal file has not been written to
  1372  ** within the current transaction (i.e. if Pager.journalOff==0).
  1373  **
  1374  ** If doTruncate is non-zero or the Pager.journalSizeLimit variable is
  1375  ** set to 0, then truncate the journal file to zero bytes in size. Otherwise,
  1376  ** zero the 28-byte header at the start of the journal file. In either case, 
  1377  ** if the pager is not in no-sync mode, sync the journal file immediately 
  1378  ** after writing or truncating it.
  1379  **
  1380  ** If Pager.journalSizeLimit is set to a positive, non-zero value, and
  1381  ** following the truncation or zeroing described above the size of the 
  1382  ** journal file in bytes is larger than this value, then truncate the
  1383  ** journal file to Pager.journalSizeLimit bytes. The journal file does
  1384  ** not need to be synced following this operation.
  1385  **
  1386  ** If an IO error occurs, abandon processing and return the IO error code.
  1387  ** Otherwise, return SQLITE_OK.
  1388  */
  1389  static int zeroJournalHdr(Pager *pPager, int doTruncate){
  1390    int rc = SQLITE_OK;                               /* Return code */
  1391    assert( isOpen(pPager->jfd) );
  1392    assert( !sqlite3JournalIsInMemory(pPager->jfd) );
  1393    if( pPager->journalOff ){
  1394      const i64 iLimit = pPager->journalSizeLimit;    /* Local cache of jsl */
  1395  
  1396      IOTRACE(("JZEROHDR %p\n", pPager))
  1397      if( doTruncate || iLimit==0 ){
  1398        rc = sqlite3OsTruncate(pPager->jfd, 0);
  1399      }else{
  1400        static const char zeroHdr[28] = {0};
  1401        rc = sqlite3OsWrite(pPager->jfd, zeroHdr, sizeof(zeroHdr), 0);
  1402      }
  1403      if( rc==SQLITE_OK && !pPager->noSync ){
  1404        rc = sqlite3OsSync(pPager->jfd, SQLITE_SYNC_DATAONLY|pPager->syncFlags);
  1405      }
  1406  
  1407      /* At this point the transaction is committed but the write lock 
  1408      ** is still held on the file. If there is a size limit configured for 
  1409      ** the persistent journal and the journal file currently consumes more
  1410      ** space than that limit allows for, truncate it now. There is no need
  1411      ** to sync the file following this operation.
  1412      */
  1413      if( rc==SQLITE_OK && iLimit>0 ){
  1414        i64 sz;
  1415        rc = sqlite3OsFileSize(pPager->jfd, &sz);
  1416        if( rc==SQLITE_OK && sz>iLimit ){
  1417          rc = sqlite3OsTruncate(pPager->jfd, iLimit);
  1418        }
  1419      }
  1420    }
  1421    return rc;
  1422  }
  1423  
  1424  /*
  1425  ** The journal file must be open when this routine is called. A journal
  1426  ** header (JOURNAL_HDR_SZ bytes) is written into the journal file at the
  1427  ** current location.
  1428  **
  1429  ** The format for the journal header is as follows:
  1430  ** - 8 bytes: Magic identifying journal format.
  1431  ** - 4 bytes: Number of records in journal, or -1 no-sync mode is on.
  1432  ** - 4 bytes: Random number used for page hash.
  1433  ** - 4 bytes: Initial database page count.
  1434  ** - 4 bytes: Sector size used by the process that wrote this journal.
  1435  ** - 4 bytes: Database page size.
  1436  ** 
  1437  ** Followed by (JOURNAL_HDR_SZ - 28) bytes of unused space.
  1438  */
  1439  static int writeJournalHdr(Pager *pPager){
  1440    int rc = SQLITE_OK;                 /* Return code */
  1441    char *zHeader = pPager->pTmpSpace;  /* Temporary space used to build header */
  1442    u32 nHeader = (u32)pPager->pageSize;/* Size of buffer pointed to by zHeader */
  1443    u32 nWrite;                         /* Bytes of header sector written */
  1444    int ii;                             /* Loop counter */
  1445  
  1446    assert( isOpen(pPager->jfd) );      /* Journal file must be open. */
  1447  
  1448    if( nHeader>JOURNAL_HDR_SZ(pPager) ){
  1449      nHeader = JOURNAL_HDR_SZ(pPager);
  1450    }
  1451  
  1452    /* If there are active savepoints and any of them were created 
  1453    ** since the most recent journal header was written, update the 
  1454    ** PagerSavepoint.iHdrOffset fields now.
  1455    */
  1456    for(ii=0; ii<pPager->nSavepoint; ii++){
  1457      if( pPager->aSavepoint[ii].iHdrOffset==0 ){
  1458        pPager->aSavepoint[ii].iHdrOffset = pPager->journalOff;
  1459      }
  1460    }
  1461  
  1462    pPager->journalHdr = pPager->journalOff = journalHdrOffset(pPager);
  1463  
  1464    /* 
  1465    ** Write the nRec Field - the number of page records that follow this
  1466    ** journal header. Normally, zero is written to this value at this time.
  1467    ** After the records are added to the journal (and the journal synced, 
  1468    ** if in full-sync mode), the zero is overwritten with the true number
  1469    ** of records (see syncJournal()).
  1470    **
  1471    ** A faster alternative is to write 0xFFFFFFFF to the nRec field. When
  1472    ** reading the journal this value tells SQLite to assume that the
  1473    ** rest of the journal file contains valid page records. This assumption
  1474    ** is dangerous, as if a failure occurred whilst writing to the journal
  1475    ** file it may contain some garbage data. There are two scenarios
  1476    ** where this risk can be ignored:
  1477    **
  1478    **   * When the pager is in no-sync mode. Corruption can follow a
  1479    **     power failure in this case anyway.
  1480    **
  1481    **   * When the SQLITE_IOCAP_SAFE_APPEND flag is set. This guarantees
  1482    **     that garbage data is never appended to the journal file.
  1483    */
  1484    assert( isOpen(pPager->fd) || pPager->noSync );
  1485    if( pPager->noSync || (pPager->journalMode==PAGER_JOURNALMODE_MEMORY)
  1486     || (sqlite3OsDeviceCharacteristics(pPager->fd)&SQLITE_IOCAP_SAFE_APPEND) 
  1487    ){
  1488      memcpy(zHeader, aJournalMagic, sizeof(aJournalMagic));
  1489      put32bits(&zHeader[sizeof(aJournalMagic)], 0xffffffff);
  1490    }else{
  1491      memset(zHeader, 0, sizeof(aJournalMagic)+4);
  1492    }
  1493  
  1494    /* The random check-hash initializer */ 
  1495    sqlite3_randomness(sizeof(pPager->cksumInit), &pPager->cksumInit);
  1496    put32bits(&zHeader[sizeof(aJournalMagic)+4], pPager->cksumInit);
  1497    /* The initial database size */
  1498    put32bits(&zHeader[sizeof(aJournalMagic)+8], pPager->dbOrigSize);
  1499    /* The assumed sector size for this process */
  1500    put32bits(&zHeader[sizeof(aJournalMagic)+12], pPager->sectorSize);
  1501  
  1502    /* The page size */
  1503    put32bits(&zHeader[sizeof(aJournalMagic)+16], pPager->pageSize);
  1504  
  1505    /* Initializing the tail of the buffer is not necessary.  Everything
  1506    ** works find if the following memset() is omitted.  But initializing
  1507    ** the memory prevents valgrind from complaining, so we are willing to
  1508    ** take the performance hit.
  1509    */
  1510    memset(&zHeader[sizeof(aJournalMagic)+20], 0,
  1511           nHeader-(sizeof(aJournalMagic)+20));
  1512  
  1513    /* In theory, it is only necessary to write the 28 bytes that the 
  1514    ** journal header consumes to the journal file here. Then increment the 
  1515    ** Pager.journalOff variable by JOURNAL_HDR_SZ so that the next 
  1516    ** record is written to the following sector (leaving a gap in the file
  1517    ** that will be implicitly filled in by the OS).
  1518    **
  1519    ** However it has been discovered that on some systems this pattern can 
  1520    ** be significantly slower than contiguously writing data to the file,
  1521    ** even if that means explicitly writing data to the block of 
  1522    ** (JOURNAL_HDR_SZ - 28) bytes that will not be used. So that is what
  1523    ** is done. 
  1524    **
  1525    ** The loop is required here in case the sector-size is larger than the 
  1526    ** database page size. Since the zHeader buffer is only Pager.pageSize
  1527    ** bytes in size, more than one call to sqlite3OsWrite() may be required
  1528    ** to populate the entire journal header sector.
  1529    */ 
  1530    for(nWrite=0; rc==SQLITE_OK&&nWrite<JOURNAL_HDR_SZ(pPager); nWrite+=nHeader){
  1531      IOTRACE(("JHDR %p %lld %d\n", pPager, pPager->journalHdr, nHeader))
  1532      rc = sqlite3OsWrite(pPager->jfd, zHeader, nHeader, pPager->journalOff);
  1533      assert( pPager->journalHdr <= pPager->journalOff );
  1534      pPager->journalOff += nHeader;
  1535    }
  1536  
  1537    return rc;
  1538  }
  1539  
  1540  /*
  1541  ** The journal file must be open when this is called. A journal header file
  1542  ** (JOURNAL_HDR_SZ bytes) is read from the current location in the journal
  1543  ** file. The current location in the journal file is given by
  1544  ** pPager->journalOff. See comments above function writeJournalHdr() for
  1545  ** a description of the journal header format.
  1546  **
  1547  ** If the header is read successfully, *pNRec is set to the number of
  1548  ** page records following this header and *pDbSize is set to the size of the
  1549  ** database before the transaction began, in pages. Also, pPager->cksumInit
  1550  ** is set to the value read from the journal header. SQLITE_OK is returned
  1551  ** in this case.
  1552  **
  1553  ** If the journal header file appears to be corrupted, SQLITE_DONE is
  1554  ** returned and *pNRec and *PDbSize are undefined.  If JOURNAL_HDR_SZ bytes
  1555  ** cannot be read from the journal file an error code is returned.
  1556  */
  1557  static int readJournalHdr(
  1558    Pager *pPager,               /* Pager object */
  1559    int isHot,
  1560    i64 journalSize,             /* Size of the open journal file in bytes */
  1561    u32 *pNRec,                  /* OUT: Value read from the nRec field */
  1562    u32 *pDbSize                 /* OUT: Value of original database size field */
  1563  ){
  1564    int rc;                      /* Return code */
  1565    unsigned char aMagic[8];     /* A buffer to hold the magic header */
  1566    i64 iHdrOff;                 /* Offset of journal header being read */
  1567  
  1568    assert( isOpen(pPager->jfd) );      /* Journal file must be open. */
  1569  
  1570    /* Advance Pager.journalOff to the start of the next sector. If the
  1571    ** journal file is too small for there to be a header stored at this
  1572    ** point, return SQLITE_DONE.
  1573    */
  1574    pPager->journalOff = journalHdrOffset(pPager);
  1575    if( pPager->journalOff+JOURNAL_HDR_SZ(pPager) > journalSize ){
  1576      return SQLITE_DONE;
  1577    }
  1578    iHdrOff = pPager->journalOff;
  1579  
  1580    /* Read in the first 8 bytes of the journal header. If they do not match
  1581    ** the  magic string found at the start of each journal header, return
  1582    ** SQLITE_DONE. If an IO error occurs, return an error code. Otherwise,
  1583    ** proceed.
  1584    */
  1585    if( isHot || iHdrOff!=pPager->journalHdr ){
  1586      rc = sqlite3OsRead(pPager->jfd, aMagic, sizeof(aMagic), iHdrOff);
  1587      if( rc ){
  1588        return rc;
  1589      }
  1590      if( memcmp(aMagic, aJournalMagic, sizeof(aMagic))!=0 ){
  1591        return SQLITE_DONE;
  1592      }
  1593    }
  1594  
  1595    /* Read the first three 32-bit fields of the journal header: The nRec
  1596    ** field, the checksum-initializer and the database size at the start
  1597    ** of the transaction. Return an error code if anything goes wrong.
  1598    */
  1599    if( SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+8, pNRec))
  1600     || SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+12, &pPager->cksumInit))
  1601     || SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+16, pDbSize))
  1602    ){
  1603      return rc;
  1604    }
  1605  
  1606    if( pPager->journalOff==0 ){
  1607      u32 iPageSize;               /* Page-size field of journal header */
  1608      u32 iSectorSize;             /* Sector-size field of journal header */
  1609  
  1610      /* Read the page-size and sector-size journal header fields. */
  1611      if( SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+20, &iSectorSize))
  1612       || SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+24, &iPageSize))
  1613      ){
  1614        return rc;
  1615      }
  1616  
  1617      /* Versions of SQLite prior to 3.5.8 set the page-size field of the
  1618      ** journal header to zero. In this case, assume that the Pager.pageSize
  1619      ** variable is already set to the correct page size.
  1620      */
  1621      if( iPageSize==0 ){
  1622        iPageSize = pPager->pageSize;
  1623      }
  1624  
  1625      /* Check that the values read from the page-size and sector-size fields
  1626      ** are within range. To be 'in range', both values need to be a power
  1627      ** of two greater than or equal to 512 or 32, and not greater than their 
  1628      ** respective compile time maximum limits.
  1629      */
  1630      if( iPageSize<512                  || iSectorSize<32
  1631       || iPageSize>SQLITE_MAX_PAGE_SIZE || iSectorSize>MAX_SECTOR_SIZE
  1632       || ((iPageSize-1)&iPageSize)!=0   || ((iSectorSize-1)&iSectorSize)!=0 
  1633      ){
  1634        /* If the either the page-size or sector-size in the journal-header is 
  1635        ** invalid, then the process that wrote the journal-header must have 
  1636        ** crashed before the header was synced. In this case stop reading 
  1637        ** the journal file here.
  1638        */
  1639        return SQLITE_DONE;
  1640      }
  1641  
  1642      /* Update the page-size to match the value read from the journal. 
  1643      ** Use a testcase() macro to make sure that malloc failure within 
  1644      ** PagerSetPagesize() is tested.
  1645      */
  1646      rc = sqlite3PagerSetPagesize(pPager, &iPageSize, -1);
  1647      testcase( rc!=SQLITE_OK );
  1648  
  1649      /* Update the assumed sector-size to match the value used by 
  1650      ** the process that created this journal. If this journal was
  1651      ** created by a process other than this one, then this routine
  1652      ** is being called from within pager_playback(). The local value
  1653      ** of Pager.sectorSize is restored at the end of that routine.
  1654      */
  1655      pPager->sectorSize = iSectorSize;
  1656    }
  1657  
  1658    pPager->journalOff += JOURNAL_HDR_SZ(pPager);
  1659    return rc;
  1660  }
  1661  
  1662  
  1663  /*
  1664  ** Write the supplied master journal name into the journal file for pager
  1665  ** pPager at the current location. The master journal name must be the last
  1666  ** thing written to a journal file. If the pager is in full-sync mode, the
  1667  ** journal file descriptor is advanced to the next sector boundary before
  1668  ** anything is written. The format is:
  1669  **
  1670  **   + 4 bytes: PAGER_MJ_PGNO.
  1671  **   + N bytes: Master journal filename in utf-8.
  1672  **   + 4 bytes: N (length of master journal name in bytes, no nul-terminator).
  1673  **   + 4 bytes: Master journal name checksum.
  1674  **   + 8 bytes: aJournalMagic[].
  1675  **
  1676  ** The master journal page checksum is the sum of the bytes in the master
  1677  ** journal name, where each byte is interpreted as a signed 8-bit integer.
  1678  **
  1679  ** If zMaster is a NULL pointer (occurs for a single database transaction), 
  1680  ** this call is a no-op.
  1681  */
  1682  static int writeMasterJournal(Pager *pPager, const char *zMaster){
  1683    int rc;                          /* Return code */
  1684    int nMaster;                     /* Length of string zMaster */
  1685    i64 iHdrOff;                     /* Offset of header in journal file */
  1686    i64 jrnlSize;                    /* Size of journal file on disk */
  1687    u32 cksum = 0;                   /* Checksum of string zMaster */
  1688  
  1689    assert( pPager->setMaster==0 );
  1690    assert( !pagerUseWal(pPager) );
  1691  
  1692    if( !zMaster 
  1693     || pPager->journalMode==PAGER_JOURNALMODE_MEMORY 
  1694     || !isOpen(pPager->jfd)
  1695    ){
  1696      return SQLITE_OK;
  1697    }
  1698    pPager->setMaster = 1;
  1699    assert( pPager->journalHdr <= pPager->journalOff );
  1700  
  1701    /* Calculate the length in bytes and the checksum of zMaster */
  1702    for(nMaster=0; zMaster[nMaster]; nMaster++){
  1703      cksum += zMaster[nMaster];
  1704    }
  1705  
  1706    /* If in full-sync mode, advance to the next disk sector before writing
  1707    ** the master journal name. This is in case the previous page written to
  1708    ** the journal has already been synced.
  1709    */
  1710    if( pPager->fullSync ){
  1711      pPager->journalOff = journalHdrOffset(pPager);
  1712    }
  1713    iHdrOff = pPager->journalOff;
  1714  
  1715    /* Write the master journal data to the end of the journal file. If
  1716    ** an error occurs, return the error code to the caller.
  1717    */
  1718    if( (0 != (rc = write32bits(pPager->jfd, iHdrOff, PAGER_MJ_PGNO(pPager))))
  1719     || (0 != (rc = sqlite3OsWrite(pPager->jfd, zMaster, nMaster, iHdrOff+4)))
  1720     || (0 != (rc = write32bits(pPager->jfd, iHdrOff+4+nMaster, nMaster)))
  1721     || (0 != (rc = write32bits(pPager->jfd, iHdrOff+4+nMaster+4, cksum)))
  1722     || (0 != (rc = sqlite3OsWrite(pPager->jfd, aJournalMagic, 8,
  1723                                   iHdrOff+4+nMaster+8)))
  1724    ){
  1725      return rc;
  1726    }
  1727    pPager->journalOff += (nMaster+20);
  1728  
  1729    /* If the pager is in peristent-journal mode, then the physical 
  1730    ** journal-file may extend past the end of the master-journal name
  1731    ** and 8 bytes of magic data just written to the file. This is 
  1732    ** dangerous because the code to rollback a hot-journal file
  1733    ** will not be able to find the master-journal name to determine 
  1734    ** whether or not the journal is hot. 
  1735    **
  1736    ** Easiest thing to do in this scenario is to truncate the journal 
  1737    ** file to the required size.
  1738    */ 
  1739    if( SQLITE_OK==(rc = sqlite3OsFileSize(pPager->jfd, &jrnlSize))
  1740     && jrnlSize>pPager->journalOff
  1741    ){
  1742      rc = sqlite3OsTruncate(pPager->jfd, pPager->journalOff);
  1743    }
  1744    return rc;
  1745  }
  1746  
  1747  /*
  1748  ** Discard the entire contents of the in-memory page-cache.
  1749  */
  1750  static void pager_reset(Pager *pPager){
  1751    pPager->iDataVersion++;
  1752    sqlite3BackupRestart(pPager->pBackup);
  1753    sqlite3PcacheClear(pPager->pPCache);
  1754  }
  1755  
  1756  /*
  1757  ** Return the pPager->iDataVersion value
  1758  */
  1759  u32 sqlite3PagerDataVersion(Pager *pPager){
  1760    return pPager->iDataVersion;
  1761  }
  1762  
  1763  /*
  1764  ** Free all structures in the Pager.aSavepoint[] array and set both
  1765  ** Pager.aSavepoint and Pager.nSavepoint to zero. Close the sub-journal
  1766  ** if it is open and the pager is not in exclusive mode.
  1767  */
  1768  static void releaseAllSavepoints(Pager *pPager){
  1769    int ii;               /* Iterator for looping through Pager.aSavepoint */
  1770    for(ii=0; ii<pPager->nSavepoint; ii++){
  1771      sqlite3BitvecDestroy(pPager->aSavepoint[ii].pInSavepoint);
  1772    }
  1773    if( !pPager->exclusiveMode || sqlite3JournalIsInMemory(pPager->sjfd) ){
  1774      sqlite3OsClose(pPager->sjfd);
  1775    }
  1776    sqlite3_free(pPager->aSavepoint);
  1777    pPager->aSavepoint = 0;
  1778    pPager->nSavepoint = 0;
  1779    pPager->nSubRec = 0;
  1780  }
  1781  
  1782  /*
  1783  ** Set the bit number pgno in the PagerSavepoint.pInSavepoint 
  1784  ** bitvecs of all open savepoints. Return SQLITE_OK if successful
  1785  ** or SQLITE_NOMEM if a malloc failure occurs.
  1786  */
  1787  static int addToSavepointBitvecs(Pager *pPager, Pgno pgno){
  1788    int ii;                   /* Loop counter */
  1789    int rc = SQLITE_OK;       /* Result code */
  1790  
  1791    for(ii=0; ii<pPager->nSavepoint; ii++){
  1792      PagerSavepoint *p = &pPager->aSavepoint[ii];
  1793      if( pgno<=p->nOrig ){
  1794        rc |= sqlite3BitvecSet(p->pInSavepoint, pgno);
  1795        testcase( rc==SQLITE_NOMEM );
  1796        assert( rc==SQLITE_OK || rc==SQLITE_NOMEM );
  1797      }
  1798    }
  1799    return rc;
  1800  }
  1801  
  1802  /*
  1803  ** This function is a no-op if the pager is in exclusive mode and not
  1804  ** in the ERROR state. Otherwise, it switches the pager to PAGER_OPEN
  1805  ** state.
  1806  **
  1807  ** If the pager is not in exclusive-access mode, the database file is
  1808  ** completely unlocked. If the file is unlocked and the file-system does
  1809  ** not exhibit the UNDELETABLE_WHEN_OPEN property, the journal file is
  1810  ** closed (if it is open).
  1811  **
  1812  ** If the pager is in ERROR state when this function is called, the 
  1813  ** contents of the pager cache are discarded before switching back to 
  1814  ** the OPEN state. Regardless of whether the pager is in exclusive-mode
  1815  ** or not, any journal file left in the file-system will be treated
  1816  ** as a hot-journal and rolled back the next time a read-transaction
  1817  ** is opened (by this or by any other connection).
  1818  */
  1819  static void pager_unlock(Pager *pPager){
  1820  
  1821    assert( pPager->eState==PAGER_READER 
  1822         || pPager->eState==PAGER_OPEN 
  1823         || pPager->eState==PAGER_ERROR 
  1824    );
  1825  
  1826    sqlite3BitvecDestroy(pPager->pInJournal);
  1827    pPager->pInJournal = 0;
  1828    releaseAllSavepoints(pPager);
  1829  
  1830    if( pagerUseWal(pPager) ){
  1831      assert( !isOpen(pPager->jfd) );
  1832      sqlite3WalEndReadTransaction(pPager->pWal);
  1833      pPager->eState = PAGER_OPEN;
  1834    }else if( !pPager->exclusiveMode ){
  1835      int rc;                       /* Error code returned by pagerUnlockDb() */
  1836      int iDc = isOpen(pPager->fd)?sqlite3OsDeviceCharacteristics(pPager->fd):0;
  1837  
  1838      /* If the operating system support deletion of open files, then
  1839      ** close the journal file when dropping the database lock.  Otherwise
  1840      ** another connection with journal_mode=delete might delete the file
  1841      ** out from under us.
  1842      */
  1843      assert( (PAGER_JOURNALMODE_MEMORY   & 5)!=1 );
  1844      assert( (PAGER_JOURNALMODE_OFF      & 5)!=1 );
  1845      assert( (PAGER_JOURNALMODE_WAL      & 5)!=1 );
  1846      assert( (PAGER_JOURNALMODE_DELETE   & 5)!=1 );
  1847      assert( (PAGER_JOURNALMODE_TRUNCATE & 5)==1 );
  1848      assert( (PAGER_JOURNALMODE_PERSIST  & 5)==1 );
  1849      if( 0==(iDc & SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN)
  1850       || 1!=(pPager->journalMode & 5)
  1851      ){
  1852        sqlite3OsClose(pPager->jfd);
  1853      }
  1854  
  1855      /* If the pager is in the ERROR state and the call to unlock the database
  1856      ** file fails, set the current lock to UNKNOWN_LOCK. See the comment
  1857      ** above the #define for UNKNOWN_LOCK for an explanation of why this
  1858      ** is necessary.
  1859      */
  1860      rc = pagerUnlockDb(pPager, NO_LOCK);
  1861      if( rc!=SQLITE_OK && pPager->eState==PAGER_ERROR ){
  1862        pPager->eLock = UNKNOWN_LOCK;
  1863      }
  1864  
  1865      /* The pager state may be changed from PAGER_ERROR to PAGER_OPEN here
  1866      ** without clearing the error code. This is intentional - the error
  1867      ** code is cleared and the cache reset in the block below.
  1868      */
  1869      assert( pPager->errCode || pPager->eState!=PAGER_ERROR );
  1870      pPager->eState = PAGER_OPEN;
  1871    }
  1872  
  1873    /* If Pager.errCode is set, the contents of the pager cache cannot be
  1874    ** trusted. Now that there are no outstanding references to the pager,
  1875    ** it can safely move back to PAGER_OPEN state. This happens in both
  1876    ** normal and exclusive-locking mode.
  1877    */
  1878    assert( pPager->errCode==SQLITE_OK || !MEMDB );
  1879    if( pPager->errCode ){
  1880      if( pPager->tempFile==0 ){
  1881        pager_reset(pPager);
  1882        pPager->changeCountDone = 0;
  1883        pPager->eState = PAGER_OPEN;
  1884      }else{
  1885        pPager->eState = (isOpen(pPager->jfd) ? PAGER_OPEN : PAGER_READER);
  1886      }
  1887      if( USEFETCH(pPager) ) sqlite3OsUnfetch(pPager->fd, 0, 0);
  1888      pPager->errCode = SQLITE_OK;
  1889      setGetterMethod(pPager);
  1890    }
  1891  
  1892    pPager->journalOff = 0;
  1893    pPager->journalHdr = 0;
  1894    pPager->setMaster = 0;
  1895  }
  1896  
  1897  /*
  1898  ** This function is called whenever an IOERR or FULL error that requires
  1899  ** the pager to transition into the ERROR state may ahve occurred.
  1900  ** The first argument is a pointer to the pager structure, the second 
  1901  ** the error-code about to be returned by a pager API function. The 
  1902  ** value returned is a copy of the second argument to this function. 
  1903  **
  1904  ** If the second argument is SQLITE_FULL, SQLITE_IOERR or one of the
  1905  ** IOERR sub-codes, the pager enters the ERROR state and the error code
  1906  ** is stored in Pager.errCode. While the pager remains in the ERROR state,
  1907  ** all major API calls on the Pager will immediately return Pager.errCode.
  1908  **
  1909  ** The ERROR state indicates that the contents of the pager-cache 
  1910  ** cannot be trusted. This state can be cleared by completely discarding 
  1911  ** the contents of the pager-cache. If a transaction was active when
  1912  ** the persistent error occurred, then the rollback journal may need
  1913  ** to be replayed to restore the contents of the database file (as if
  1914  ** it were a hot-journal).
  1915  */
  1916  static int pager_error(Pager *pPager, int rc){
  1917    int rc2 = rc & 0xff;
  1918    assert( rc==SQLITE_OK || !MEMDB );
  1919    assert(
  1920         pPager->errCode==SQLITE_FULL ||
  1921         pPager->errCode==SQLITE_OK ||
  1922         (pPager->errCode & 0xff)==SQLITE_IOERR
  1923    );
  1924    if( rc2==SQLITE_FULL || rc2==SQLITE_IOERR ){
  1925      pPager->errCode = rc;
  1926      pPager->eState = PAGER_ERROR;
  1927      setGetterMethod(pPager);
  1928    }
  1929    return rc;
  1930  }
  1931  
  1932  static int pager_truncate(Pager *pPager, Pgno nPage);
  1933  
  1934  /*
  1935  ** The write transaction open on pPager is being committed (bCommit==1)
  1936  ** or rolled back (bCommit==0).
  1937  **
  1938  ** Return TRUE if and only if all dirty pages should be flushed to disk.
  1939  **
  1940  ** Rules:
  1941  **
  1942  **   *  For non-TEMP databases, always sync to disk.  This is necessary
  1943  **      for transactions to be durable.
  1944  **
  1945  **   *  Sync TEMP database only on a COMMIT (not a ROLLBACK) when the backing
  1946  **      file has been created already (via a spill on pagerStress()) and
  1947  **      when the number of dirty pages in memory exceeds 25% of the total
  1948  **      cache size.
  1949  */
  1950  static int pagerFlushOnCommit(Pager *pPager, int bCommit){
  1951    if( pPager->tempFile==0 ) return 1;
  1952    if( !bCommit ) return 0;
  1953    if( !isOpen(pPager->fd) ) return 0;
  1954    return (sqlite3PCachePercentDirty(pPager->pPCache)>=25);
  1955  }
  1956  
  1957  /*
  1958  ** This routine ends a transaction. A transaction is usually ended by 
  1959  ** either a COMMIT or a ROLLBACK operation. This routine may be called 
  1960  ** after rollback of a hot-journal, or if an error occurs while opening
  1961  ** the journal file or writing the very first journal-header of a
  1962  ** database transaction.
  1963  ** 
  1964  ** This routine is never called in PAGER_ERROR state. If it is called
  1965  ** in PAGER_NONE or PAGER_SHARED state and the lock held is less
  1966  ** exclusive than a RESERVED lock, it is a no-op.
  1967  **
  1968  ** Otherwise, any active savepoints are released.
  1969  **
  1970  ** If the journal file is open, then it is "finalized". Once a journal 
  1971  ** file has been finalized it is not possible to use it to roll back a 
  1972  ** transaction. Nor will it be considered to be a hot-journal by this
  1973  ** or any other database connection. Exactly how a journal is finalized
  1974  ** depends on whether or not the pager is running in exclusive mode and
  1975  ** the current journal-mode (Pager.journalMode value), as follows:
  1976  **
  1977  **   journalMode==MEMORY
  1978  **     Journal file descriptor is simply closed. This destroys an 
  1979  **     in-memory journal.
  1980  **
  1981  **   journalMode==TRUNCATE
  1982  **     Journal file is truncated to zero bytes in size.
  1983  **
  1984  **   journalMode==PERSIST
  1985  **     The first 28 bytes of the journal file are zeroed. This invalidates
  1986  **     the first journal header in the file, and hence the entire journal
  1987  **     file. An invalid journal file cannot be rolled back.
  1988  **
  1989  **   journalMode==DELETE
  1990  **     The journal file is closed and deleted using sqlite3OsDelete().
  1991  **
  1992  **     If the pager is running in exclusive mode, this method of finalizing
  1993  **     the journal file is never used. Instead, if the journalMode is
  1994  **     DELETE and the pager is in exclusive mode, the method described under
  1995  **     journalMode==PERSIST is used instead.
  1996  **
  1997  ** After the journal is finalized, the pager moves to PAGER_READER state.
  1998  ** If running in non-exclusive rollback mode, the lock on the file is 
  1999  ** downgraded to a SHARED_LOCK.
  2000  **
  2001  ** SQLITE_OK is returned if no error occurs. If an error occurs during
  2002  ** any of the IO operations to finalize the journal file or unlock the
  2003  ** database then the IO error code is returned to the user. If the 
  2004  ** operation to finalize the journal file fails, then the code still
  2005  ** tries to unlock the database file if not in exclusive mode. If the
  2006  ** unlock operation fails as well, then the first error code related
  2007  ** to the first error encountered (the journal finalization one) is
  2008  ** returned.
  2009  */
  2010  static int pager_end_transaction(Pager *pPager, int hasMaster, int bCommit){
  2011    int rc = SQLITE_OK;      /* Error code from journal finalization operation */
  2012    int rc2 = SQLITE_OK;     /* Error code from db file unlock operation */
  2013  
  2014    /* Do nothing if the pager does not have an open write transaction
  2015    ** or at least a RESERVED lock. This function may be called when there
  2016    ** is no write-transaction active but a RESERVED or greater lock is
  2017    ** held under two circumstances:
  2018    **
  2019    **   1. After a successful hot-journal rollback, it is called with
  2020    **      eState==PAGER_NONE and eLock==EXCLUSIVE_LOCK.
  2021    **
  2022    **   2. If a connection with locking_mode=exclusive holding an EXCLUSIVE 
  2023    **      lock switches back to locking_mode=normal and then executes a
  2024    **      read-transaction, this function is called with eState==PAGER_READER 
  2025    **      and eLock==EXCLUSIVE_LOCK when the read-transaction is closed.
  2026    */
  2027    assert( assert_pager_state(pPager) );
  2028    assert( pPager->eState!=PAGER_ERROR );
  2029    if( pPager->eState<PAGER_WRITER_LOCKED && pPager->eLock<RESERVED_LOCK ){
  2030      return SQLITE_OK;
  2031    }
  2032  
  2033    releaseAllSavepoints(pPager);
  2034    assert( isOpen(pPager->jfd) || pPager->pInJournal==0 
  2035        || (sqlite3OsDeviceCharacteristics(pPager->fd)&SQLITE_IOCAP_BATCH_ATOMIC)
  2036    );
  2037    if( isOpen(pPager->jfd) ){
  2038      assert( !pagerUseWal(pPager) );
  2039  
  2040      /* Finalize the journal file. */
  2041      if( sqlite3JournalIsInMemory(pPager->jfd) ){
  2042        /* assert( pPager->journalMode==PAGER_JOURNALMODE_MEMORY ); */
  2043        sqlite3OsClose(pPager->jfd);
  2044      }else if( pPager->journalMode==PAGER_JOURNALMODE_TRUNCATE ){
  2045        if( pPager->journalOff==0 ){
  2046          rc = SQLITE_OK;
  2047        }else{
  2048          rc = sqlite3OsTruncate(pPager->jfd, 0);
  2049          if( rc==SQLITE_OK && pPager->fullSync ){
  2050            /* Make sure the new file size is written into the inode right away.
  2051            ** Otherwise the journal might resurrect following a power loss and
  2052            ** cause the last transaction to roll back.  See
  2053            ** https://bugzilla.mozilla.org/show_bug.cgi?id=1072773
  2054            */
  2055            rc = sqlite3OsSync(pPager->jfd, pPager->syncFlags);
  2056          }
  2057        }
  2058        pPager->journalOff = 0;
  2059      }else if( pPager->journalMode==PAGER_JOURNALMODE_PERSIST
  2060        || (pPager->exclusiveMode && pPager->journalMode!=PAGER_JOURNALMODE_WAL)
  2061      ){
  2062        rc = zeroJournalHdr(pPager, hasMaster||pPager->tempFile);
  2063        pPager->journalOff = 0;
  2064      }else{
  2065        /* This branch may be executed with Pager.journalMode==MEMORY if
  2066        ** a hot-journal was just rolled back. In this case the journal
  2067        ** file should be closed and deleted. If this connection writes to
  2068        ** the database file, it will do so using an in-memory journal.
  2069        */
  2070        int bDelete = !pPager->tempFile;
  2071        assert( sqlite3JournalIsInMemory(pPager->jfd)==0 );
  2072        assert( pPager->journalMode==PAGER_JOURNALMODE_DELETE 
  2073             || pPager->journalMode==PAGER_JOURNALMODE_MEMORY 
  2074             || pPager->journalMode==PAGER_JOURNALMODE_WAL 
  2075        );
  2076        sqlite3OsClose(pPager->jfd);
  2077        if( bDelete ){
  2078          rc = sqlite3OsDelete(pPager->pVfs, pPager->zJournal, pPager->extraSync);
  2079        }
  2080      }
  2081    }
  2082  
  2083  #ifdef SQLITE_CHECK_PAGES
  2084    sqlite3PcacheIterateDirty(pPager->pPCache, pager_set_pagehash);
  2085    if( pPager->dbSize==0 && sqlite3PcacheRefCount(pPager->pPCache)>0 ){
  2086      PgHdr *p = sqlite3PagerLookup(pPager, 1);
  2087      if( p ){
  2088        p->pageHash = 0;
  2089        sqlite3PagerUnrefNotNull(p);
  2090      }
  2091    }
  2092  #endif
  2093  
  2094    sqlite3BitvecDestroy(pPager->pInJournal);
  2095    pPager->pInJournal = 0;
  2096    pPager->nRec = 0;
  2097    if( rc==SQLITE_OK ){
  2098      if( MEMDB || pagerFlushOnCommit(pPager, bCommit) ){
  2099        sqlite3PcacheCleanAll(pPager->pPCache);
  2100      }else{
  2101        sqlite3PcacheClearWritable(pPager->pPCache);
  2102      }
  2103      sqlite3PcacheTruncate(pPager->pPCache, pPager->dbSize);
  2104    }
  2105  
  2106    if( pagerUseWal(pPager) ){
  2107      /* Drop the WAL write-lock, if any. Also, if the connection was in 
  2108      ** locking_mode=exclusive mode but is no longer, drop the EXCLUSIVE 
  2109      ** lock held on the database file.
  2110      */
  2111      rc2 = sqlite3WalEndWriteTransaction(pPager->pWal);
  2112      assert( rc2==SQLITE_OK );
  2113    }else if( rc==SQLITE_OK && bCommit && pPager->dbFileSize>pPager->dbSize ){
  2114      /* This branch is taken when committing a transaction in rollback-journal
  2115      ** mode if the database file on disk is larger than the database image.
  2116      ** At this point the journal has been finalized and the transaction 
  2117      ** successfully committed, but the EXCLUSIVE lock is still held on the
  2118      ** file. So it is safe to truncate the database file to its minimum
  2119      ** required size.  */
  2120      assert( pPager->eLock==EXCLUSIVE_LOCK );
  2121      rc = pager_truncate(pPager, pPager->dbSize);
  2122    }
  2123  
  2124    if( rc==SQLITE_OK && bCommit ){
  2125      rc = sqlite3OsFileControl(pPager->fd, SQLITE_FCNTL_COMMIT_PHASETWO, 0);
  2126      if( rc==SQLITE_NOTFOUND ) rc = SQLITE_OK;
  2127    }
  2128  
  2129    if( !pPager->exclusiveMode 
  2130     && (!pagerUseWal(pPager) || sqlite3WalExclusiveMode(pPager->pWal, 0))
  2131    ){
  2132      rc2 = pagerUnlockDb(pPager, SHARED_LOCK);
  2133    }
  2134    pPager->eState = PAGER_READER;
  2135    pPager->setMaster = 0;
  2136  
  2137    return (rc==SQLITE_OK?rc2:rc);
  2138  }
  2139  
  2140  /*
  2141  ** Execute a rollback if a transaction is active and unlock the 
  2142  ** database file. 
  2143  **
  2144  ** If the pager has already entered the ERROR state, do not attempt 
  2145  ** the rollback at this time. Instead, pager_unlock() is called. The
  2146  ** call to pager_unlock() will discard all in-memory pages, unlock
  2147  ** the database file and move the pager back to OPEN state. If this 
  2148  ** means that there is a hot-journal left in the file-system, the next 
  2149  ** connection to obtain a shared lock on the pager (which may be this one) 
  2150  ** will roll it back.
  2151  **
  2152  ** If the pager has not already entered the ERROR state, but an IO or
  2153  ** malloc error occurs during a rollback, then this will itself cause 
  2154  ** the pager to enter the ERROR state. Which will be cleared by the
  2155  ** call to pager_unlock(), as described above.
  2156  */
  2157  static void pagerUnlockAndRollback(Pager *pPager){
  2158    if( pPager->eState!=PAGER_ERROR && pPager->eState!=PAGER_OPEN ){
  2159      assert( assert_pager_state(pPager) );
  2160      if( pPager->eState>=PAGER_WRITER_LOCKED ){
  2161        sqlite3BeginBenignMalloc();
  2162        sqlite3PagerRollback(pPager);
  2163        sqlite3EndBenignMalloc();
  2164      }else if( !pPager->exclusiveMode ){
  2165        assert( pPager->eState==PAGER_READER );
  2166        pager_end_transaction(pPager, 0, 0);
  2167      }
  2168    }
  2169    pager_unlock(pPager);
  2170  }
  2171  
  2172  /*
  2173  ** Parameter aData must point to a buffer of pPager->pageSize bytes
  2174  ** of data. Compute and return a checksum based ont the contents of the 
  2175  ** page of data and the current value of pPager->cksumInit.
  2176  **
  2177  ** This is not a real checksum. It is really just the sum of the 
  2178  ** random initial value (pPager->cksumInit) and every 200th byte
  2179  ** of the page data, starting with byte offset (pPager->pageSize%200).
  2180  ** Each byte is interpreted as an 8-bit unsigned integer.
  2181  **
  2182  ** Changing the formula used to compute this checksum results in an
  2183  ** incompatible journal file format.
  2184  **
  2185  ** If journal corruption occurs due to a power failure, the most likely 
  2186  ** scenario is that one end or the other of the record will be changed. 
  2187  ** It is much less likely that the two ends of the journal record will be
  2188  ** correct and the middle be corrupt.  Thus, this "checksum" scheme,
  2189  ** though fast and simple, catches the mostly likely kind of corruption.
  2190  */
  2191  static u32 pager_cksum(Pager *pPager, const u8 *aData){
  2192    u32 cksum = pPager->cksumInit;         /* Checksum value to return */
  2193    int i = pPager->pageSize-200;          /* Loop counter */
  2194    while( i>0 ){
  2195      cksum += aData[i];
  2196      i -= 200;
  2197    }
  2198    return cksum;
  2199  }
  2200  
  2201  /*
  2202  ** Read a single page from either the journal file (if isMainJrnl==1) or
  2203  ** from the sub-journal (if isMainJrnl==0) and playback that page.
  2204  ** The page begins at offset *pOffset into the file. The *pOffset
  2205  ** value is increased to the start of the next page in the journal.
  2206  **
  2207  ** The main rollback journal uses checksums - the statement journal does 
  2208  ** not.
  2209  **
  2210  ** If the page number of the page record read from the (sub-)journal file
  2211  ** is greater than the current value of Pager.dbSize, then playback is
  2212  ** skipped and SQLITE_OK is returned.
  2213  **
  2214  ** If pDone is not NULL, then it is a record of pages that have already
  2215  ** been played back.  If the page at *pOffset has already been played back
  2216  ** (if the corresponding pDone bit is set) then skip the playback.
  2217  ** Make sure the pDone bit corresponding to the *pOffset page is set
  2218  ** prior to returning.
  2219  **
  2220  ** If the page record is successfully read from the (sub-)journal file
  2221  ** and played back, then SQLITE_OK is returned. If an IO error occurs
  2222  ** while reading the record from the (sub-)journal file or while writing
  2223  ** to the database file, then the IO error code is returned. If data
  2224  ** is successfully read from the (sub-)journal file but appears to be
  2225  ** corrupted, SQLITE_DONE is returned. Data is considered corrupted in
  2226  ** two circumstances:
  2227  ** 
  2228  **   * If the record page-number is illegal (0 or PAGER_MJ_PGNO), or
  2229  **   * If the record is being rolled back from the main journal file
  2230  **     and the checksum field does not match the record content.
  2231  **
  2232  ** Neither of these two scenarios are possible during a savepoint rollback.
  2233  **
  2234  ** If this is a savepoint rollback, then memory may have to be dynamically
  2235  ** allocated by this function. If this is the case and an allocation fails,
  2236  ** SQLITE_NOMEM is returned.
  2237  */
  2238  static int pager_playback_one_page(
  2239    Pager *pPager,                /* The pager being played back */
  2240    i64 *pOffset,                 /* Offset of record to playback */
  2241    Bitvec *pDone,                /* Bitvec of pages already played back */
  2242    int isMainJrnl,               /* 1 -> main journal. 0 -> sub-journal. */
  2243    int isSavepnt                 /* True for a savepoint rollback */
  2244  ){
  2245    int rc;
  2246    PgHdr *pPg;                   /* An existing page in the cache */
  2247    Pgno pgno;                    /* The page number of a page in journal */
  2248    u32 cksum;                    /* Checksum used for sanity checking */
  2249    char *aData;                  /* Temporary storage for the page */
  2250    sqlite3_file *jfd;            /* The file descriptor for the journal file */
  2251    int isSynced;                 /* True if journal page is synced */
  2252  
  2253    assert( (isMainJrnl&~1)==0 );      /* isMainJrnl is 0 or 1 */
  2254    assert( (isSavepnt&~1)==0 );       /* isSavepnt is 0 or 1 */
  2255    assert( isMainJrnl || pDone );     /* pDone always used on sub-journals */
  2256    assert( isSavepnt || pDone==0 );   /* pDone never used on non-savepoint */
  2257  
  2258    aData = pPager->pTmpSpace;
  2259    assert( aData );         /* Temp storage must have already been allocated */
  2260    assert( pagerUseWal(pPager)==0 || (!isMainJrnl && isSavepnt) );
  2261  
  2262    /* Either the state is greater than PAGER_WRITER_CACHEMOD (a transaction 
  2263    ** or savepoint rollback done at the request of the caller) or this is
  2264    ** a hot-journal rollback. If it is a hot-journal rollback, the pager
  2265    ** is in state OPEN and holds an EXCLUSIVE lock. Hot-journal rollback
  2266    ** only reads from the main journal, not the sub-journal.
  2267    */
  2268    assert( pPager->eState>=PAGER_WRITER_CACHEMOD
  2269         || (pPager->eState==PAGER_OPEN && pPager->eLock==EXCLUSIVE_LOCK)
  2270    );
  2271    assert( pPager->eState>=PAGER_WRITER_CACHEMOD || isMainJrnl );
  2272  
  2273    /* Read the page number and page data from the journal or sub-journal
  2274    ** file. Return an error code to the caller if an IO error occurs.
  2275    */
  2276    jfd = isMainJrnl ? pPager->jfd : pPager->sjfd;
  2277    rc = read32bits(jfd, *pOffset, &pgno);
  2278    if( rc!=SQLITE_OK ) return rc;
  2279    rc = sqlite3OsRead(jfd, (u8*)aData, pPager->pageSize, (*pOffset)+4);
  2280    if( rc!=SQLITE_OK ) return rc;
  2281    *pOffset += pPager->pageSize + 4 + isMainJrnl*4;
  2282  
  2283    /* Sanity checking on the page.  This is more important that I originally
  2284    ** thought.  If a power failure occurs while the journal is being written,
  2285    ** it could cause invalid data to be written into the journal.  We need to
  2286    ** detect this invalid data (with high probability) and ignore it.
  2287    */
  2288    if( pgno==0 || pgno==PAGER_MJ_PGNO(pPager) ){
  2289      assert( !isSavepnt );
  2290      return SQLITE_DONE;
  2291    }
  2292    if( pgno>(Pgno)pPager->dbSize || sqlite3BitvecTest(pDone, pgno) ){
  2293      return SQLITE_OK;
  2294    }
  2295    if( isMainJrnl ){
  2296      rc = read32bits(jfd, (*pOffset)-4, &cksum);
  2297      if( rc ) return rc;
  2298      if( !isSavepnt && pager_cksum(pPager, (u8*)aData)!=cksum ){
  2299        return SQLITE_DONE;
  2300      }
  2301    }
  2302  
  2303    /* If this page has already been played back before during the current
  2304    ** rollback, then don't bother to play it back again.
  2305    */
  2306    if( pDone && (rc = sqlite3BitvecSet(pDone, pgno))!=SQLITE_OK ){
  2307      return rc;
  2308    }
  2309  
  2310    /* When playing back page 1, restore the nReserve setting
  2311    */
  2312    if( pgno==1 && pPager->nReserve!=((u8*)aData)[20] ){
  2313      pPager->nReserve = ((u8*)aData)[20];
  2314    }
  2315  
  2316    /* If the pager is in CACHEMOD state, then there must be a copy of this
  2317    ** page in the pager cache. In this case just update the pager cache,
  2318    ** not the database file. The page is left marked dirty in this case.
  2319    **
  2320    ** An exception to the above rule: If the database is in no-sync mode
  2321    ** and a page is moved during an incremental vacuum then the page may
  2322    ** not be in the pager cache. Later: if a malloc() or IO error occurs
  2323    ** during a Movepage() call, then the page may not be in the cache
  2324    ** either. So the condition described in the above paragraph is not
  2325    ** assert()able.
  2326    **
  2327    ** If in WRITER_DBMOD, WRITER_FINISHED or OPEN state, then we update the
  2328    ** pager cache if it exists and the main file. The page is then marked 
  2329    ** not dirty. Since this code is only executed in PAGER_OPEN state for
  2330    ** a hot-journal rollback, it is guaranteed that the page-cache is empty
  2331    ** if the pager is in OPEN state.
  2332    **
  2333    ** Ticket #1171:  The statement journal might contain page content that is
  2334    ** different from the page content at the start of the transaction.
  2335    ** This occurs when a page is changed prior to the start of a statement
  2336    ** then changed again within the statement.  When rolling back such a
  2337    ** statement we must not write to the original database unless we know
  2338    ** for certain that original page contents are synced into the main rollback
  2339    ** journal.  Otherwise, a power loss might leave modified data in the
  2340    ** database file without an entry in the rollback journal that can
  2341    ** restore the database to its original form.  Two conditions must be
  2342    ** met before writing to the database files. (1) the database must be
  2343    ** locked.  (2) we know that the original page content is fully synced
  2344    ** in the main journal either because the page is not in cache or else
  2345    ** the page is marked as needSync==0.
  2346    **
  2347    ** 2008-04-14:  When attempting to vacuum a corrupt database file, it
  2348    ** is possible to fail a statement on a database that does not yet exist.
  2349    ** Do not attempt to write if database file has never been opened.
  2350    */
  2351    if( pagerUseWal(pPager) ){
  2352      pPg = 0;
  2353    }else{
  2354      pPg = sqlite3PagerLookup(pPager, pgno);
  2355    }
  2356    assert( pPg || !MEMDB );
  2357    assert( pPager->eState!=PAGER_OPEN || pPg==0 || pPager->tempFile );
  2358    PAGERTRACE(("PLAYBACK %d page %d hash(%08x) %s\n",
  2359             PAGERID(pPager), pgno, pager_datahash(pPager->pageSize, (u8*)aData),
  2360             (isMainJrnl?"main-journal":"sub-journal")
  2361    ));
  2362    if( isMainJrnl ){
  2363      isSynced = pPager->noSync || (*pOffset <= pPager->journalHdr);
  2364    }else{
  2365      isSynced = (pPg==0 || 0==(pPg->flags & PGHDR_NEED_SYNC));
  2366    }
  2367    if( isOpen(pPager->fd)
  2368     && (pPager->eState>=PAGER_WRITER_DBMOD || pPager->eState==PAGER_OPEN)
  2369     && isSynced
  2370    ){
  2371      i64 ofst = (pgno-1)*(i64)pPager->pageSize;
  2372      testcase( !isSavepnt && pPg!=0 && (pPg->flags&PGHDR_NEED_SYNC)!=0 );
  2373      assert( !pagerUseWal(pPager) );
  2374  
  2375      /* Write the data read from the journal back into the database file.
  2376      ** This is usually safe even for an encrypted database - as the data
  2377      ** was encrypted before it was written to the journal file. The exception
  2378      ** is if the data was just read from an in-memory sub-journal. In that
  2379      ** case it must be encrypted here before it is copied into the database
  2380      ** file.  */
  2381      rc = sqlite3OsWrite(pPager->fd, (u8 *)aData, pPager->pageSize, ofst);
  2382  
  2383      if( pgno>pPager->dbFileSize ){
  2384        pPager->dbFileSize = pgno;
  2385      }
  2386      if( pPager->pBackup ){
  2387        sqlite3BackupUpdate(pPager->pBackup, pgno, (u8*)aData);
  2388      }
  2389    }else if( !isMainJrnl && pPg==0 ){
  2390      /* If this is a rollback of a savepoint and data was not written to
  2391      ** the database and the page is not in-memory, there is a potential
  2392      ** problem. When the page is next fetched by the b-tree layer, it 
  2393      ** will be read from the database file, which may or may not be 
  2394      ** current. 
  2395      **
  2396      ** There are a couple of different ways this can happen. All are quite
  2397      ** obscure. When running in synchronous mode, this can only happen 
  2398      ** if the page is on the free-list at the start of the transaction, then
  2399      ** populated, then moved using sqlite3PagerMovepage().
  2400      **
  2401      ** The solution is to add an in-memory page to the cache containing
  2402      ** the data just read from the sub-journal. Mark the page as dirty 
  2403      ** and if the pager requires a journal-sync, then mark the page as 
  2404      ** requiring a journal-sync before it is written.
  2405      */
  2406      assert( isSavepnt );
  2407      assert( (pPager->doNotSpill & SPILLFLAG_ROLLBACK)==0 );
  2408      pPager->doNotSpill |= SPILLFLAG_ROLLBACK;
  2409      rc = sqlite3PagerGet(pPager, pgno, &pPg, 1);
  2410      assert( (pPager->doNotSpill & SPILLFLAG_ROLLBACK)!=0 );
  2411      pPager->doNotSpill &= ~SPILLFLAG_ROLLBACK;
  2412      if( rc!=SQLITE_OK ) return rc;
  2413      sqlite3PcacheMakeDirty(pPg);
  2414    }
  2415    if( pPg ){
  2416      /* No page should ever be explicitly rolled back that is in use, except
  2417      ** for page 1 which is held in use in order to keep the lock on the
  2418      ** database active. However such a page may be rolled back as a result
  2419      ** of an internal error resulting in an automatic call to
  2420      ** sqlite3PagerRollback().
  2421      */
  2422      void *pData;
  2423      pData = pPg->pData;
  2424      memcpy(pData, (u8*)aData, pPager->pageSize);
  2425      pPager->xReiniter(pPg);
  2426      /* It used to be that sqlite3PcacheMakeClean(pPg) was called here.  But
  2427      ** that call was dangerous and had no detectable benefit since the cache
  2428      ** is normally cleaned by sqlite3PcacheCleanAll() after rollback and so
  2429      ** has been removed. */
  2430      pager_set_pagehash(pPg);
  2431  
  2432      /* If this was page 1, then restore the value of Pager.dbFileVers.
  2433      ** Do this before any decoding. */
  2434      if( pgno==1 ){
  2435        memcpy(&pPager->dbFileVers, &((u8*)pData)[24],sizeof(pPager->dbFileVers));
  2436      }
  2437      sqlite3PcacheRelease(pPg);
  2438    }
  2439    return rc;
  2440  }
  2441  
  2442  /*
  2443  ** Parameter zMaster is the name of a master journal file. A single journal
  2444  ** file that referred to the master journal file has just been rolled back.
  2445  ** This routine checks if it is possible to delete the master journal file,
  2446  ** and does so if it is.
  2447  **
  2448  ** Argument zMaster may point to Pager.pTmpSpace. So that buffer is not 
  2449  ** available for use within this function.
  2450  **
  2451  ** When a master journal file is created, it is populated with the names 
  2452  ** of all of its child journals, one after another, formatted as utf-8 
  2453  ** encoded text. The end of each child journal file is marked with a 
  2454  ** nul-terminator byte (0x00). i.e. the entire contents of a master journal
  2455  ** file for a transaction involving two databases might be:
  2456  **
  2457  **   "/home/bill/a.db-journal\x00/home/bill/b.db-journal\x00"
  2458  **
  2459  ** A master journal file may only be deleted once all of its child 
  2460  ** journals have been rolled back.
  2461  **
  2462  ** This function reads the contents of the master-journal file into 
  2463  ** memory and loops through each of the child journal names. For
  2464  ** each child journal, it checks if:
  2465  **
  2466  **   * if the child journal exists, and if so
  2467  **   * if the child journal contains a reference to master journal 
  2468  **     file zMaster
  2469  **
  2470  ** If a child journal can be found that matches both of the criteria
  2471  ** above, this function returns without doing anything. Otherwise, if
  2472  ** no such child journal can be found, file zMaster is deleted from
  2473  ** the file-system using sqlite3OsDelete().
  2474  **
  2475  ** If an IO error within this function, an error code is returned. This
  2476  ** function allocates memory by calling sqlite3Malloc(). If an allocation
  2477  ** fails, SQLITE_NOMEM is returned. Otherwise, if no IO or malloc errors 
  2478  ** occur, SQLITE_OK is returned.
  2479  **
  2480  ** TODO: This function allocates a single block of memory to load
  2481  ** the entire contents of the master journal file. This could be
  2482  ** a couple of kilobytes or so - potentially larger than the page 
  2483  ** size.
  2484  */
  2485  static int pager_delmaster(Pager *pPager, const char *zMaster){
  2486    sqlite3_vfs *pVfs = pPager->pVfs;
  2487    int rc;                   /* Return code */
  2488    sqlite3_file *pMaster;    /* Malloc'd master-journal file descriptor */
  2489    sqlite3_file *pJournal;   /* Malloc'd child-journal file descriptor */
  2490    char *zMasterJournal = 0; /* Contents of master journal file */
  2491    i64 nMasterJournal;       /* Size of master journal file */
  2492    char *zJournal;           /* Pointer to one journal within MJ file */
  2493    char *zMasterPtr;         /* Space to hold MJ filename from a journal file */
  2494    int nMasterPtr;           /* Amount of space allocated to zMasterPtr[] */
  2495  
  2496    /* Allocate space for both the pJournal and pMaster file descriptors.
  2497    ** If successful, open the master journal file for reading.
  2498    */
  2499    pMaster = (sqlite3_file *)sqlite3MallocZero(pVfs->szOsFile * 2);
  2500    pJournal = (sqlite3_file *)(((u8 *)pMaster) + pVfs->szOsFile);
  2501    if( !pMaster ){
  2502      rc = SQLITE_NOMEM_BKPT;
  2503    }else{
  2504      const int flags = (SQLITE_OPEN_READONLY|SQLITE_OPEN_MASTER_JOURNAL);
  2505      rc = sqlite3OsOpen(pVfs, zMaster, pMaster, flags, 0);
  2506    }
  2507    if( rc!=SQLITE_OK ) goto delmaster_out;
  2508  
  2509    /* Load the entire master journal file into space obtained from
  2510    ** sqlite3_malloc() and pointed to by zMasterJournal.   Also obtain
  2511    ** sufficient space (in zMasterPtr) to hold the names of master
  2512    ** journal files extracted from regular rollback-journals.
  2513    */
  2514    rc = sqlite3OsFileSize(pMaster, &nMasterJournal);
  2515    if( rc!=SQLITE_OK ) goto delmaster_out;
  2516    nMasterPtr = pVfs->mxPathname+1;
  2517    zMasterJournal = sqlite3Malloc(nMasterJournal + nMasterPtr + 2);
  2518    if( !zMasterJournal ){
  2519      rc = SQLITE_NOMEM_BKPT;
  2520      goto delmaster_out;
  2521    }
  2522    zMasterPtr = &zMasterJournal[nMasterJournal+2];
  2523    rc = sqlite3OsRead(pMaster, zMasterJournal, (int)nMasterJournal, 0);
  2524    if( rc!=SQLITE_OK ) goto delmaster_out;
  2525    zMasterJournal[nMasterJournal] = 0;
  2526    zMasterJournal[nMasterJournal+1] = 0;
  2527  
  2528    zJournal = zMasterJournal;
  2529    while( (zJournal-zMasterJournal)<nMasterJournal ){
  2530      int exists;
  2531      rc = sqlite3OsAccess(pVfs, zJournal, SQLITE_ACCESS_EXISTS, &exists);
  2532      if( rc!=SQLITE_OK ){
  2533        goto delmaster_out;
  2534      }
  2535      if( exists ){
  2536        /* One of the journals pointed to by the master journal exists.
  2537        ** Open it and check if it points at the master journal. If
  2538        ** so, return without deleting the master journal file.
  2539        */
  2540        int c;
  2541        int flags = (SQLITE_OPEN_READONLY|SQLITE_OPEN_MAIN_JOURNAL);
  2542        rc = sqlite3OsOpen(pVfs, zJournal, pJournal, flags, 0);
  2543        if( rc!=SQLITE_OK ){
  2544          goto delmaster_out;
  2545        }
  2546  
  2547        rc = readMasterJournal(pJournal, zMasterPtr, nMasterPtr);
  2548        sqlite3OsClose(pJournal);
  2549        if( rc!=SQLITE_OK ){
  2550          goto delmaster_out;
  2551        }
  2552  
  2553        c = zMasterPtr[0]!=0 && strcmp(zMasterPtr, zMaster)==0;
  2554        if( c ){
  2555          /* We have a match. Do not delete the master journal file. */
  2556          goto delmaster_out;
  2557        }
  2558      }
  2559      zJournal += (sqlite3Strlen30(zJournal)+1);
  2560    }
  2561   
  2562    sqlite3OsClose(pMaster);
  2563    rc = sqlite3OsDelete(pVfs, zMaster, 0);
  2564  
  2565  delmaster_out:
  2566    sqlite3_free(zMasterJournal);
  2567    if( pMaster ){
  2568      sqlite3OsClose(pMaster);
  2569      assert( !isOpen(pJournal) );
  2570      sqlite3_free(pMaster);
  2571    }
  2572    return rc;
  2573  }
  2574  
  2575  
  2576  /*
  2577  ** This function is used to change the actual size of the database 
  2578  ** file in the file-system. This only happens when committing a transaction,
  2579  ** or rolling back a transaction (including rolling back a hot-journal).
  2580  **
  2581  ** If the main database file is not open, or the pager is not in either
  2582  ** DBMOD or OPEN state, this function is a no-op. Otherwise, the size 
  2583  ** of the file is changed to nPage pages (nPage*pPager->pageSize bytes). 
  2584  ** If the file on disk is currently larger than nPage pages, then use the VFS
  2585  ** xTruncate() method to truncate it.
  2586  **
  2587  ** Or, it might be the case that the file on disk is smaller than 
  2588  ** nPage pages. Some operating system implementations can get confused if 
  2589  ** you try to truncate a file to some size that is larger than it 
  2590  ** currently is, so detect this case and write a single zero byte to 
  2591  ** the end of the new file instead.
  2592  **
  2593  ** If successful, return SQLITE_OK. If an IO error occurs while modifying
  2594  ** the database file, return the error code to the caller.
  2595  */
  2596  static int pager_truncate(Pager *pPager, Pgno nPage){
  2597    int rc = SQLITE_OK;
  2598    assert( pPager->eState!=PAGER_ERROR );
  2599    assert( pPager->eState!=PAGER_READER );
  2600    
  2601    if( isOpen(pPager->fd) 
  2602     && (pPager->eState>=PAGER_WRITER_DBMOD || pPager->eState==PAGER_OPEN) 
  2603    ){
  2604      i64 currentSize, newSize;
  2605      int szPage = pPager->pageSize;
  2606      assert( pPager->eLock==EXCLUSIVE_LOCK );
  2607      /* TODO: Is it safe to use Pager.dbFileSize here? */
  2608      rc = sqlite3OsFileSize(pPager->fd, &currentSize);
  2609      newSize = szPage*(i64)nPage;
  2610      if( rc==SQLITE_OK && currentSize!=newSize ){
  2611        if( currentSize>newSize ){
  2612          rc = sqlite3OsTruncate(pPager->fd, newSize);
  2613        }else if( (currentSize+szPage)<=newSize ){
  2614          char *pTmp = pPager->pTmpSpace;
  2615          memset(pTmp, 0, szPage);
  2616          testcase( (newSize-szPage) == currentSize );
  2617          testcase( (newSize-szPage) >  currentSize );
  2618          rc = sqlite3OsWrite(pPager->fd, pTmp, szPage, newSize-szPage);
  2619        }
  2620        if( rc==SQLITE_OK ){
  2621          pPager->dbFileSize = nPage;
  2622        }
  2623      }
  2624    }
  2625    return rc;
  2626  }
  2627  
  2628  /*
  2629  ** Return a sanitized version of the sector-size of OS file pFile. The
  2630  ** return value is guaranteed to lie between 32 and MAX_SECTOR_SIZE.
  2631  */
  2632  int sqlite3SectorSize(sqlite3_file *pFile){
  2633    int iRet = sqlite3OsSectorSize(pFile);
  2634    if( iRet<32 ){
  2635      iRet = 512;
  2636    }else if( iRet>MAX_SECTOR_SIZE ){
  2637      assert( MAX_SECTOR_SIZE>=512 );
  2638      iRet = MAX_SECTOR_SIZE;
  2639    }
  2640    return iRet;
  2641  }
  2642  
  2643  /*
  2644  ** Set the value of the Pager.sectorSize variable for the given
  2645  ** pager based on the value returned by the xSectorSize method
  2646  ** of the open database file. The sector size will be used 
  2647  ** to determine the size and alignment of journal header and 
  2648  ** master journal pointers within created journal files.
  2649  **
  2650  ** For temporary files the effective sector size is always 512 bytes.
  2651  **
  2652  ** Otherwise, for non-temporary files, the effective sector size is
  2653  ** the value returned by the xSectorSize() method rounded up to 32 if
  2654  ** it is less than 32, or rounded down to MAX_SECTOR_SIZE if it
  2655  ** is greater than MAX_SECTOR_SIZE.
  2656  **
  2657  ** If the file has the SQLITE_IOCAP_POWERSAFE_OVERWRITE property, then set
  2658  ** the effective sector size to its minimum value (512).  The purpose of
  2659  ** pPager->sectorSize is to define the "blast radius" of bytes that
  2660  ** might change if a crash occurs while writing to a single byte in
  2661  ** that range.  But with POWERSAFE_OVERWRITE, the blast radius is zero
  2662  ** (that is what POWERSAFE_OVERWRITE means), so we minimize the sector
  2663  ** size.  For backwards compatibility of the rollback journal file format,
  2664  ** we cannot reduce the effective sector size below 512.
  2665  */
  2666  static void setSectorSize(Pager *pPager){
  2667    assert( isOpen(pPager->fd) || pPager->tempFile );
  2668  
  2669    if( pPager->tempFile
  2670     || (sqlite3OsDeviceCharacteristics(pPager->fd) & 
  2671                SQLITE_IOCAP_POWERSAFE_OVERWRITE)!=0
  2672    ){
  2673      /* Sector size doesn't matter for temporary files. Also, the file
  2674      ** may not have been opened yet, in which case the OsSectorSize()
  2675      ** call will segfault. */
  2676      pPager->sectorSize = 512;
  2677    }else{
  2678      pPager->sectorSize = sqlite3SectorSize(pPager->fd);
  2679    }
  2680  }
  2681  
  2682  /*
  2683  ** Playback the journal and thus restore the database file to
  2684  ** the state it was in before we started making changes.  
  2685  **
  2686  ** The journal file format is as follows: 
  2687  **
  2688  **  (1)  8 byte prefix.  A copy of aJournalMagic[].
  2689  **  (2)  4 byte big-endian integer which is the number of valid page records
  2690  **       in the journal.  If this value is 0xffffffff, then compute the
  2691  **       number of page records from the journal size.
  2692  **  (3)  4 byte big-endian integer which is the initial value for the 
  2693  **       sanity checksum.
  2694  **  (4)  4 byte integer which is the number of pages to truncate the
  2695  **       database to during a rollback.
  2696  **  (5)  4 byte big-endian integer which is the sector size.  The header
  2697  **       is this many bytes in size.
  2698  **  (6)  4 byte big-endian integer which is the page size.
  2699  **  (7)  zero padding out to the next sector size.
  2700  **  (8)  Zero or more pages instances, each as follows:
  2701  **        +  4 byte page number.
  2702  **        +  pPager->pageSize bytes of data.
  2703  **        +  4 byte checksum
  2704  **
  2705  ** When we speak of the journal header, we mean the first 7 items above.
  2706  ** Each entry in the journal is an instance of the 8th item.
  2707  **
  2708  ** Call the value from the second bullet "nRec".  nRec is the number of
  2709  ** valid page entries in the journal.  In most cases, you can compute the
  2710  ** value of nRec from the size of the journal file.  But if a power
  2711  ** failure occurred while the journal was being written, it could be the
  2712  ** case that the size of the journal file had already been increased but
  2713  ** the extra entries had not yet made it safely to disk.  In such a case,
  2714  ** the value of nRec computed from the file size would be too large.  For
  2715  ** that reason, we always use the nRec value in the header.
  2716  **
  2717  ** If the nRec value is 0xffffffff it means that nRec should be computed
  2718  ** from the file size.  This value is used when the user selects the
  2719  ** no-sync option for the journal.  A power failure could lead to corruption
  2720  ** in this case.  But for things like temporary table (which will be
  2721  ** deleted when the power is restored) we don't care.  
  2722  **
  2723  ** If the file opened as the journal file is not a well-formed
  2724  ** journal file then all pages up to the first corrupted page are rolled
  2725  ** back (or no pages if the journal header is corrupted). The journal file
  2726  ** is then deleted and SQLITE_OK returned, just as if no corruption had
  2727  ** been encountered.
  2728  **
  2729  ** If an I/O or malloc() error occurs, the journal-file is not deleted
  2730  ** and an error code is returned.
  2731  **
  2732  ** The isHot parameter indicates that we are trying to rollback a journal
  2733  ** that might be a hot journal.  Or, it could be that the journal is 
  2734  ** preserved because of JOURNALMODE_PERSIST or JOURNALMODE_TRUNCATE.
  2735  ** If the journal really is hot, reset the pager cache prior rolling
  2736  ** back any content.  If the journal is merely persistent, no reset is
  2737  ** needed.
  2738  */
  2739  static int pager_playback(Pager *pPager, int isHot){
  2740    sqlite3_vfs *pVfs = pPager->pVfs;
  2741    i64 szJ;                 /* Size of the journal file in bytes */
  2742    u32 nRec;                /* Number of Records in the journal */
  2743    u32 u;                   /* Unsigned loop counter */
  2744    Pgno mxPg = 0;           /* Size of the original file in pages */
  2745    int rc;                  /* Result code of a subroutine */
  2746    int res = 1;             /* Value returned by sqlite3OsAccess() */
  2747    char *zMaster = 0;       /* Name of master journal file if any */
  2748    int needPagerReset;      /* True to reset page prior to first page rollback */
  2749    int nPlayback = 0;       /* Total number of pages restored from journal */
  2750    u32 savedPageSize = pPager->pageSize;
  2751  
  2752    /* Figure out how many records are in the journal.  Abort early if
  2753    ** the journal is empty.
  2754    */
  2755    assert( isOpen(pPager->jfd) );
  2756    rc = sqlite3OsFileSize(pPager->jfd, &szJ);
  2757    if( rc!=SQLITE_OK ){
  2758      goto end_playback;
  2759    }
  2760  
  2761    /* Read the master journal name from the journal, if it is present.
  2762    ** If a master journal file name is specified, but the file is not
  2763    ** present on disk, then the journal is not hot and does not need to be
  2764    ** played back.
  2765    **
  2766    ** TODO: Technically the following is an error because it assumes that
  2767    ** buffer Pager.pTmpSpace is (mxPathname+1) bytes or larger. i.e. that
  2768    ** (pPager->pageSize >= pPager->pVfs->mxPathname+1). Using os_unix.c,
  2769    ** mxPathname is 512, which is the same as the minimum allowable value
  2770    ** for pageSize.
  2771    */
  2772    zMaster = pPager->pTmpSpace;
  2773    rc = readMasterJournal(pPager->jfd, zMaster, pPager->pVfs->mxPathname+1);
  2774    if( rc==SQLITE_OK && zMaster[0] ){
  2775      rc = sqlite3OsAccess(pVfs, zMaster, SQLITE_ACCESS_EXISTS, &res);
  2776    }
  2777    zMaster = 0;
  2778    if( rc!=SQLITE_OK || !res ){
  2779      goto end_playback;
  2780    }
  2781    pPager->journalOff = 0;
  2782    needPagerReset = isHot;
  2783  
  2784    /* This loop terminates either when a readJournalHdr() or 
  2785    ** pager_playback_one_page() call returns SQLITE_DONE or an IO error 
  2786    ** occurs. 
  2787    */
  2788    while( 1 ){
  2789      /* Read the next journal header from the journal file.  If there are
  2790      ** not enough bytes left in the journal file for a complete header, or
  2791      ** it is corrupted, then a process must have failed while writing it.
  2792      ** This indicates nothing more needs to be rolled back.
  2793      */
  2794      rc = readJournalHdr(pPager, isHot, szJ, &nRec, &mxPg);
  2795      if( rc!=SQLITE_OK ){ 
  2796        if( rc==SQLITE_DONE ){
  2797          rc = SQLITE_OK;
  2798        }
  2799        goto end_playback;
  2800      }
  2801  
  2802      /* If nRec is 0xffffffff, then this journal was created by a process
  2803      ** working in no-sync mode. This means that the rest of the journal
  2804      ** file consists of pages, there are no more journal headers. Compute
  2805      ** the value of nRec based on this assumption.
  2806      */
  2807      if( nRec==0xffffffff ){
  2808        assert( pPager->journalOff==JOURNAL_HDR_SZ(pPager) );
  2809        nRec = (int)((szJ - JOURNAL_HDR_SZ(pPager))/JOURNAL_PG_SZ(pPager));
  2810      }
  2811  
  2812      /* If nRec is 0 and this rollback is of a transaction created by this
  2813      ** process and if this is the final header in the journal, then it means
  2814      ** that this part of the journal was being filled but has not yet been
  2815      ** synced to disk.  Compute the number of pages based on the remaining
  2816      ** size of the file.
  2817      **
  2818      ** The third term of the test was added to fix ticket #2565.
  2819      ** When rolling back a hot journal, nRec==0 always means that the next
  2820      ** chunk of the journal contains zero pages to be rolled back.  But
  2821      ** when doing a ROLLBACK and the nRec==0 chunk is the last chunk in
  2822      ** the journal, it means that the journal might contain additional
  2823      ** pages that need to be rolled back and that the number of pages 
  2824      ** should be computed based on the journal file size.
  2825      */
  2826      if( nRec==0 && !isHot &&
  2827          pPager->journalHdr+JOURNAL_HDR_SZ(pPager)==pPager->journalOff ){
  2828        nRec = (int)((szJ - pPager->journalOff) / JOURNAL_PG_SZ(pPager));
  2829      }
  2830  
  2831      /* If this is the first header read from the journal, truncate the
  2832      ** database file back to its original size.
  2833      */
  2834      if( pPager->journalOff==JOURNAL_HDR_SZ(pPager) ){
  2835        rc = pager_truncate(pPager, mxPg);
  2836        if( rc!=SQLITE_OK ){
  2837          goto end_playback;
  2838        }
  2839        pPager->dbSize = mxPg;
  2840      }
  2841  
  2842      /* Copy original pages out of the journal and back into the 
  2843      ** database file and/or page cache.
  2844      */
  2845      for(u=0; u<nRec; u++){
  2846        if( needPagerReset ){
  2847          pager_reset(pPager);
  2848          needPagerReset = 0;
  2849        }
  2850        rc = pager_playback_one_page(pPager,&pPager->journalOff,0,1,0);
  2851        if( rc==SQLITE_OK ){
  2852          nPlayback++;
  2853        }else{
  2854          if( rc==SQLITE_DONE ){
  2855            pPager->journalOff = szJ;
  2856            break;
  2857          }else if( rc==SQLITE_IOERR_SHORT_READ ){
  2858            /* If the journal has been truncated, simply stop reading and
  2859            ** processing the journal. This might happen if the journal was
  2860            ** not completely written and synced prior to a crash.  In that
  2861            ** case, the database should have never been written in the
  2862            ** first place so it is OK to simply abandon the rollback. */
  2863            rc = SQLITE_OK;
  2864            goto end_playback;
  2865          }else{
  2866            /* If we are unable to rollback, quit and return the error
  2867            ** code.  This will cause the pager to enter the error state
  2868            ** so that no further harm will be done.  Perhaps the next
  2869            ** process to come along will be able to rollback the database.
  2870            */
  2871            goto end_playback;
  2872          }
  2873        }
  2874      }
  2875    }
  2876    /*NOTREACHED*/
  2877    assert( 0 );
  2878  
  2879  end_playback:
  2880    if( rc==SQLITE_OK ){
  2881      rc = sqlite3PagerSetPagesize(pPager, &savedPageSize, -1);
  2882    }
  2883    /* Following a rollback, the database file should be back in its original
  2884    ** state prior to the start of the transaction, so invoke the
  2885    ** SQLITE_FCNTL_DB_UNCHANGED file-control method to disable the
  2886    ** assertion that the transaction counter was modified.
  2887    */
  2888  #ifdef SQLITE_DEBUG
  2889    sqlite3OsFileControlHint(pPager->fd,SQLITE_FCNTL_DB_UNCHANGED,0);
  2890  #endif
  2891  
  2892    /* If this playback is happening automatically as a result of an IO or 
  2893    ** malloc error that occurred after the change-counter was updated but 
  2894    ** before the transaction was committed, then the change-counter 
  2895    ** modification may just have been reverted. If this happens in exclusive 
  2896    ** mode, then subsequent transactions performed by the connection will not
  2897    ** update the change-counter at all. This may lead to cache inconsistency
  2898    ** problems for other processes at some point in the future. So, just
  2899    ** in case this has happened, clear the changeCountDone flag now.
  2900    */
  2901    pPager->changeCountDone = pPager->tempFile;
  2902  
  2903    if( rc==SQLITE_OK ){
  2904      zMaster = pPager->pTmpSpace;
  2905      rc = readMasterJournal(pPager->jfd, zMaster, pPager->pVfs->mxPathname+1);
  2906      testcase( rc!=SQLITE_OK );
  2907    }
  2908    if( rc==SQLITE_OK
  2909     && (pPager->eState>=PAGER_WRITER_DBMOD || pPager->eState==PAGER_OPEN)
  2910    ){
  2911      rc = sqlite3PagerSync(pPager, 0);
  2912    }
  2913    if( rc==SQLITE_OK ){
  2914      rc = pager_end_transaction(pPager, zMaster[0]!='\0', 0);
  2915      testcase( rc!=SQLITE_OK );
  2916    }
  2917    if( rc==SQLITE_OK && zMaster[0] && res ){
  2918      /* If there was a master journal and this routine will return success,
  2919      ** see if it is possible to delete the master journal.
  2920      */
  2921      rc = pager_delmaster(pPager, zMaster);
  2922      testcase( rc!=SQLITE_OK );
  2923    }
  2924    if( isHot && nPlayback ){
  2925      sqlite3_log(SQLITE_NOTICE_RECOVER_ROLLBACK, "recovered %d pages from %s",
  2926                  nPlayback, pPager->zJournal);
  2927    }
  2928  
  2929    /* The Pager.sectorSize variable may have been updated while rolling
  2930    ** back a journal created by a process with a different sector size
  2931    ** value. Reset it to the correct value for this process.
  2932    */
  2933    setSectorSize(pPager);
  2934    return rc;
  2935  }
  2936  
  2937  
  2938  /*
  2939  ** Read the content for page pPg out of the database file (or out of
  2940  ** the WAL if that is where the most recent copy if found) into 
  2941  ** pPg->pData. A shared lock or greater must be held on the database
  2942  ** file before this function is called.
  2943  **
  2944  ** If page 1 is read, then the value of Pager.dbFileVers[] is set to
  2945  ** the value read from the database file.
  2946  **
  2947  ** If an IO error occurs, then the IO error is returned to the caller.
  2948  ** Otherwise, SQLITE_OK is returned.
  2949  */
  2950  static int readDbPage(PgHdr *pPg){
  2951    Pager *pPager = pPg->pPager; /* Pager object associated with page pPg */
  2952    int rc = SQLITE_OK;          /* Return code */
  2953  
  2954  #ifndef SQLITE_OMIT_WAL
  2955    u32 iFrame = 0;              /* Frame of WAL containing pgno */
  2956  
  2957    assert( pPager->eState>=PAGER_READER && !MEMDB );
  2958    assert( isOpen(pPager->fd) );
  2959  
  2960    if( pagerUseWal(pPager) ){
  2961      rc = sqlite3WalFindFrame(pPager->pWal, pPg->pgno, &iFrame);
  2962      if( rc ) return rc;
  2963    }
  2964    if( iFrame ){
  2965      rc = sqlite3WalReadFrame(pPager->pWal, iFrame,pPager->pageSize,pPg->pData);
  2966    }else
  2967  #endif
  2968    {
  2969      i64 iOffset = (pPg->pgno-1)*(i64)pPager->pageSize;
  2970      rc = sqlite3OsRead(pPager->fd, pPg->pData, pPager->pageSize, iOffset);
  2971      if( rc==SQLITE_IOERR_SHORT_READ ){
  2972        rc = SQLITE_OK;
  2973      }
  2974    }
  2975  
  2976    if( pPg->pgno==1 ){
  2977      if( rc ){
  2978        /* If the read is unsuccessful, set the dbFileVers[] to something
  2979        ** that will never be a valid file version.  dbFileVers[] is a copy
  2980        ** of bytes 24..39 of the database.  Bytes 28..31 should always be
  2981        ** zero or the size of the database in page. Bytes 32..35 and 35..39
  2982        ** should be page numbers which are never 0xffffffff.  So filling
  2983        ** pPager->dbFileVers[] with all 0xff bytes should suffice.
  2984        **
  2985        ** For an encrypted database, the situation is more complex:  bytes
  2986        ** 24..39 of the database are white noise.  But the probability of
  2987        ** white noise equaling 16 bytes of 0xff is vanishingly small so
  2988        ** we should still be ok.
  2989        */
  2990        memset(pPager->dbFileVers, 0xff, sizeof(pPager->dbFileVers));
  2991      }else{
  2992        u8 *dbFileVers = &((u8*)pPg->pData)[24];
  2993        memcpy(&pPager->dbFileVers, dbFileVers, sizeof(pPager->dbFileVers));
  2994      }
  2995    }
  2996    PAGER_INCR(sqlite3_pager_readdb_count);
  2997    PAGER_INCR(pPager->nRead);
  2998    IOTRACE(("PGIN %p %d\n", pPager, pPg->pgno));
  2999    PAGERTRACE(("FETCH %d page %d hash(%08x)\n",
  3000                 PAGERID(pPager), pPg->pgno, pager_pagehash(pPg)));
  3001  
  3002    return rc;
  3003  }
  3004  
  3005  /*
  3006  ** Update the value of the change-counter at offsets 24 and 92 in
  3007  ** the header and the sqlite version number at offset 96.
  3008  **
  3009  ** This is an unconditional update.  See also the pager_incr_changecounter()
  3010  ** routine which only updates the change-counter if the update is actually
  3011  ** needed, as determined by the pPager->changeCountDone state variable.
  3012  */
  3013  static void pager_write_changecounter(PgHdr *pPg){
  3014    u32 change_counter;
  3015  
  3016    /* Increment the value just read and write it back to byte 24. */
  3017    change_counter = sqlite3Get4byte((u8*)pPg->pPager->dbFileVers)+1;
  3018    put32bits(((char*)pPg->pData)+24, change_counter);
  3019  
  3020    /* Also store the SQLite version number in bytes 96..99 and in
  3021    ** bytes 92..95 store the change counter for which the version number
  3022    ** is valid. */
  3023    put32bits(((char*)pPg->pData)+92, change_counter);
  3024    put32bits(((char*)pPg->pData)+96, SQLITE_VERSION_NUMBER);
  3025  }
  3026  
  3027  #ifndef SQLITE_OMIT_WAL
  3028  /*
  3029  ** This function is invoked once for each page that has already been 
  3030  ** written into the log file when a WAL transaction is rolled back.
  3031  ** Parameter iPg is the page number of said page. The pCtx argument 
  3032  ** is actually a pointer to the Pager structure.
  3033  **
  3034  ** If page iPg is present in the cache, and has no outstanding references,
  3035  ** it is discarded. Otherwise, if there are one or more outstanding
  3036  ** references, the page content is reloaded from the database. If the
  3037  ** attempt to reload content from the database is required and fails, 
  3038  ** return an SQLite error code. Otherwise, SQLITE_OK.
  3039  */
  3040  static int pagerUndoCallback(void *pCtx, Pgno iPg){
  3041    int rc = SQLITE_OK;
  3042    Pager *pPager = (Pager *)pCtx;
  3043    PgHdr *pPg;
  3044  
  3045    assert( pagerUseWal(pPager) );
  3046    pPg = sqlite3PagerLookup(pPager, iPg);
  3047    if( pPg ){
  3048      if( sqlite3PcachePageRefcount(pPg)==1 ){
  3049        sqlite3PcacheDrop(pPg);
  3050      }else{
  3051        rc = readDbPage(pPg);
  3052        if( rc==SQLITE_OK ){
  3053          pPager->xReiniter(pPg);
  3054        }
  3055        sqlite3PagerUnrefNotNull(pPg);
  3056      }
  3057    }
  3058  
  3059    /* Normally, if a transaction is rolled back, any backup processes are
  3060    ** updated as data is copied out of the rollback journal and into the
  3061    ** database. This is not generally possible with a WAL database, as
  3062    ** rollback involves simply truncating the log file. Therefore, if one
  3063    ** or more frames have already been written to the log (and therefore 
  3064    ** also copied into the backup databases) as part of this transaction,
  3065    ** the backups must be restarted.
  3066    */
  3067    sqlite3BackupRestart(pPager->pBackup);
  3068  
  3069    return rc;
  3070  }
  3071  
  3072  /*
  3073  ** This function is called to rollback a transaction on a WAL database.
  3074  */
  3075  static int pagerRollbackWal(Pager *pPager){
  3076    int rc;                         /* Return Code */
  3077    PgHdr *pList;                   /* List of dirty pages to revert */
  3078  
  3079    /* For all pages in the cache that are currently dirty or have already
  3080    ** been written (but not committed) to the log file, do one of the 
  3081    ** following:
  3082    **
  3083    **   + Discard the cached page (if refcount==0), or
  3084    **   + Reload page content from the database (if refcount>0).
  3085    */
  3086    pPager->dbSize = pPager->dbOrigSize;
  3087    rc = sqlite3WalUndo(pPager->pWal, pagerUndoCallback, (void *)pPager);
  3088    pList = sqlite3PcacheDirtyList(pPager->pPCache);
  3089    while( pList && rc==SQLITE_OK ){
  3090      PgHdr *pNext = pList->pDirty;
  3091      rc = pagerUndoCallback((void *)pPager, pList->pgno);
  3092      pList = pNext;
  3093    }
  3094  
  3095    return rc;
  3096  }
  3097  
  3098  /*
  3099  ** This function is a wrapper around sqlite3WalFrames(). As well as logging
  3100  ** the contents of the list of pages headed by pList (connected by pDirty),
  3101  ** this function notifies any active backup processes that the pages have
  3102  ** changed. 
  3103  **
  3104  ** The list of pages passed into this routine is always sorted by page number.
  3105  ** Hence, if page 1 appears anywhere on the list, it will be the first page.
  3106  */ 
  3107  static int pagerWalFrames(
  3108    Pager *pPager,                  /* Pager object */
  3109    PgHdr *pList,                   /* List of frames to log */
  3110    Pgno nTruncate,                 /* Database size after this commit */
  3111    int isCommit                    /* True if this is a commit */
  3112  ){
  3113    int rc;                         /* Return code */
  3114    int nList;                      /* Number of pages in pList */
  3115    PgHdr *p;                       /* For looping over pages */
  3116  
  3117    assert( pPager->pWal );
  3118    assert( pList );
  3119  #ifdef SQLITE_DEBUG
  3120    /* Verify that the page list is in accending order */
  3121    for(p=pList; p && p->pDirty; p=p->pDirty){
  3122      assert( p->pgno < p->pDirty->pgno );
  3123    }
  3124  #endif
  3125  
  3126    assert( pList->pDirty==0 || isCommit );
  3127    if( isCommit ){
  3128      /* If a WAL transaction is being committed, there is no point in writing
  3129      ** any pages with page numbers greater than nTruncate into the WAL file.
  3130      ** They will never be read by any client. So remove them from the pDirty
  3131      ** list here. */
  3132      PgHdr **ppNext = &pList;
  3133      nList = 0;
  3134      for(p=pList; (*ppNext = p)!=0; p=p->pDirty){
  3135        if( p->pgno<=nTruncate ){
  3136          ppNext = &p->pDirty;
  3137          nList++;
  3138        }
  3139      }
  3140      assert( pList );
  3141    }else{
  3142      nList = 1;
  3143    }
  3144    pPager->aStat[PAGER_STAT_WRITE] += nList;
  3145  
  3146    if( pList->pgno==1 ) pager_write_changecounter(pList);
  3147    rc = sqlite3WalFrames(pPager->pWal, 
  3148        pPager->pageSize, pList, nTruncate, isCommit, pPager->walSyncFlags
  3149    );
  3150    if( rc==SQLITE_OK && pPager->pBackup ){
  3151      for(p=pList; p; p=p->pDirty){
  3152        sqlite3BackupUpdate(pPager->pBackup, p->pgno, (u8 *)p->pData);
  3153      }
  3154    }
  3155  
  3156  #ifdef SQLITE_CHECK_PAGES
  3157    pList = sqlite3PcacheDirtyList(pPager->pPCache);
  3158    for(p=pList; p; p=p->pDirty){
  3159      pager_set_pagehash(p);
  3160    }
  3161  #endif
  3162  
  3163    return rc;
  3164  }
  3165  
  3166  /*
  3167  ** Begin a read transaction on the WAL.
  3168  **
  3169  ** This routine used to be called "pagerOpenSnapshot()" because it essentially
  3170  ** makes a snapshot of the database at the current point in time and preserves
  3171  ** that snapshot for use by the reader in spite of concurrently changes by
  3172  ** other writers or checkpointers.
  3173  */
  3174  static int pagerBeginReadTransaction(Pager *pPager){
  3175    int rc;                         /* Return code */
  3176    int changed = 0;                /* True if cache must be reset */
  3177  
  3178    assert( pagerUseWal(pPager) );
  3179    assert( pPager->eState==PAGER_OPEN || pPager->eState==PAGER_READER );
  3180  
  3181    /* sqlite3WalEndReadTransaction() was not called for the previous
  3182    ** transaction in locking_mode=EXCLUSIVE.  So call it now.  If we
  3183    ** are in locking_mode=NORMAL and EndRead() was previously called,
  3184    ** the duplicate call is harmless.
  3185    */
  3186    sqlite3WalEndReadTransaction(pPager->pWal);
  3187  
  3188    rc = sqlite3WalBeginReadTransaction(pPager->pWal, &changed);
  3189    if( rc!=SQLITE_OK || changed ){
  3190      pager_reset(pPager);
  3191      if( USEFETCH(pPager) ) sqlite3OsUnfetch(pPager->fd, 0, 0);
  3192    }
  3193  
  3194    return rc;
  3195  }
  3196  #endif
  3197  
  3198  /*
  3199  ** This function is called as part of the transition from PAGER_OPEN
  3200  ** to PAGER_READER state to determine the size of the database file
  3201  ** in pages (assuming the page size currently stored in Pager.pageSize).
  3202  **
  3203  ** If no error occurs, SQLITE_OK is returned and the size of the database
  3204  ** in pages is stored in *pnPage. Otherwise, an error code (perhaps
  3205  ** SQLITE_IOERR_FSTAT) is returned and *pnPage is left unmodified.
  3206  */
  3207  static int pagerPagecount(Pager *pPager, Pgno *pnPage){
  3208    Pgno nPage;                     /* Value to return via *pnPage */
  3209  
  3210    /* Query the WAL sub-system for the database size. The WalDbsize()
  3211    ** function returns zero if the WAL is not open (i.e. Pager.pWal==0), or
  3212    ** if the database size is not available. The database size is not
  3213    ** available from the WAL sub-system if the log file is empty or
  3214    ** contains no valid committed transactions.
  3215    */
  3216    assert( pPager->eState==PAGER_OPEN );
  3217    assert( pPager->eLock>=SHARED_LOCK );
  3218    assert( isOpen(pPager->fd) );
  3219    assert( pPager->tempFile==0 );
  3220    nPage = sqlite3WalDbsize(pPager->pWal);
  3221  
  3222    /* If the number of pages in the database is not available from the
  3223    ** WAL sub-system, determine the page count based on the size of
  3224    ** the database file.  If the size of the database file is not an
  3225    ** integer multiple of the page-size, round up the result.
  3226    */
  3227    if( nPage==0 && ALWAYS(isOpen(pPager->fd)) ){
  3228      i64 n = 0;                    /* Size of db file in bytes */
  3229      int rc = sqlite3OsFileSize(pPager->fd, &n);
  3230      if( rc!=SQLITE_OK ){
  3231        return rc;
  3232      }
  3233      nPage = (Pgno)((n+pPager->pageSize-1) / pPager->pageSize);
  3234    }
  3235  
  3236    /* If the current number of pages in the file is greater than the
  3237    ** configured maximum pager number, increase the allowed limit so
  3238    ** that the file can be read.
  3239    */
  3240    if( nPage>pPager->mxPgno ){
  3241      pPager->mxPgno = (Pgno)nPage;
  3242    }
  3243  
  3244    *pnPage = nPage;
  3245    return SQLITE_OK;
  3246  }
  3247  
  3248  #ifndef SQLITE_OMIT_WAL
  3249  /*
  3250  ** Check if the *-wal file that corresponds to the database opened by pPager
  3251  ** exists if the database is not empy, or verify that the *-wal file does
  3252  ** not exist (by deleting it) if the database file is empty.
  3253  **
  3254  ** If the database is not empty and the *-wal file exists, open the pager
  3255  ** in WAL mode.  If the database is empty or if no *-wal file exists and
  3256  ** if no error occurs, make sure Pager.journalMode is not set to
  3257  ** PAGER_JOURNALMODE_WAL.
  3258  **
  3259  ** Return SQLITE_OK or an error code.
  3260  **
  3261  ** The caller must hold a SHARED lock on the database file to call this
  3262  ** function. Because an EXCLUSIVE lock on the db file is required to delete 
  3263  ** a WAL on a none-empty database, this ensures there is no race condition 
  3264  ** between the xAccess() below and an xDelete() being executed by some 
  3265  ** other connection.
  3266  */
  3267  static int pagerOpenWalIfPresent(Pager *pPager){
  3268    int rc = SQLITE_OK;
  3269    assert( pPager->eState==PAGER_OPEN );
  3270    assert( pPager->eLock>=SHARED_LOCK );
  3271  
  3272    if( !pPager->tempFile ){
  3273      int isWal;                    /* True if WAL file exists */
  3274      rc = sqlite3OsAccess(
  3275          pPager->pVfs, pPager->zWal, SQLITE_ACCESS_EXISTS, &isWal
  3276      );
  3277      if( rc==SQLITE_OK ){
  3278        if( isWal ){
  3279          Pgno nPage;                   /* Size of the database file */
  3280  
  3281          rc = pagerPagecount(pPager, &nPage);
  3282          if( rc ) return rc;
  3283          if( nPage==0 ){
  3284            rc = sqlite3OsDelete(pPager->pVfs, pPager->zWal, 0);
  3285          }else{
  3286            testcase( sqlite3PcachePagecount(pPager->pPCache)==0 );
  3287            rc = sqlite3PagerOpenWal(pPager, 0);
  3288          }
  3289        }else if( pPager->journalMode==PAGER_JOURNALMODE_WAL ){
  3290          pPager->journalMode = PAGER_JOURNALMODE_DELETE;
  3291        }
  3292      }
  3293    }
  3294    return rc;
  3295  }
  3296  #endif
  3297  
  3298  /*
  3299  ** Playback savepoint pSavepoint. Or, if pSavepoint==NULL, then playback
  3300  ** the entire master journal file. The case pSavepoint==NULL occurs when 
  3301  ** a ROLLBACK TO command is invoked on a SAVEPOINT that is a transaction 
  3302  ** savepoint.
  3303  **
  3304  ** When pSavepoint is not NULL (meaning a non-transaction savepoint is 
  3305  ** being rolled back), then the rollback consists of up to three stages,
  3306  ** performed in the order specified:
  3307  **
  3308  **   * Pages are played back from the main journal starting at byte
  3309  **     offset PagerSavepoint.iOffset and continuing to 
  3310  **     PagerSavepoint.iHdrOffset, or to the end of the main journal
  3311  **     file if PagerSavepoint.iHdrOffset is zero.
  3312  **
  3313  **   * If PagerSavepoint.iHdrOffset is not zero, then pages are played
  3314  **     back starting from the journal header immediately following 
  3315  **     PagerSavepoint.iHdrOffset to the end of the main journal file.
  3316  **
  3317  **   * Pages are then played back from the sub-journal file, starting
  3318  **     with the PagerSavepoint.iSubRec and continuing to the end of
  3319  **     the journal file.
  3320  **
  3321  ** Throughout the rollback process, each time a page is rolled back, the
  3322  ** corresponding bit is set in a bitvec structure (variable pDone in the
  3323  ** implementation below). This is used to ensure that a page is only
  3324  ** rolled back the first time it is encountered in either journal.
  3325  **
  3326  ** If pSavepoint is NULL, then pages are only played back from the main
  3327  ** journal file. There is no need for a bitvec in this case.
  3328  **
  3329  ** In either case, before playback commences the Pager.dbSize variable
  3330  ** is reset to the value that it held at the start of the savepoint 
  3331  ** (or transaction). No page with a page-number greater than this value
  3332  ** is played back. If one is encountered it is simply skipped.
  3333  */
  3334  static int pagerPlaybackSavepoint(Pager *pPager, PagerSavepoint *pSavepoint){
  3335    i64 szJ;                 /* Effective size of the main journal */
  3336    i64 iHdrOff;             /* End of first segment of main-journal records */
  3337    int rc = SQLITE_OK;      /* Return code */
  3338    Bitvec *pDone = 0;       /* Bitvec to ensure pages played back only once */
  3339  
  3340    assert( pPager->eState!=PAGER_ERROR );
  3341    assert( pPager->eState>=PAGER_WRITER_LOCKED );
  3342  
  3343    /* Allocate a bitvec to use to store the set of pages rolled back */
  3344    if( pSavepoint ){
  3345      pDone = sqlite3BitvecCreate(pSavepoint->nOrig);
  3346      if( !pDone ){
  3347        return SQLITE_NOMEM_BKPT;
  3348      }
  3349    }
  3350  
  3351    /* Set the database size back to the value it was before the savepoint 
  3352    ** being reverted was opened.
  3353    */
  3354    pPager->dbSize = pSavepoint ? pSavepoint->nOrig : pPager->dbOrigSize;
  3355    pPager->changeCountDone = pPager->tempFile;
  3356  
  3357    if( !pSavepoint && pagerUseWal(pPager) ){
  3358      return pagerRollbackWal(pPager);
  3359    }
  3360  
  3361    /* Use pPager->journalOff as the effective size of the main rollback
  3362    ** journal.  The actual file might be larger than this in
  3363    ** PAGER_JOURNALMODE_TRUNCATE or PAGER_JOURNALMODE_PERSIST.  But anything
  3364    ** past pPager->journalOff is off-limits to us.
  3365    */
  3366    szJ = pPager->journalOff;
  3367    assert( pagerUseWal(pPager)==0 || szJ==0 );
  3368  
  3369    /* Begin by rolling back records from the main journal starting at
  3370    ** PagerSavepoint.iOffset and continuing to the next journal header.
  3371    ** There might be records in the main journal that have a page number
  3372    ** greater than the current database size (pPager->dbSize) but those
  3373    ** will be skipped automatically.  Pages are added to pDone as they
  3374    ** are played back.
  3375    */
  3376    if( pSavepoint && !pagerUseWal(pPager) ){
  3377      iHdrOff = pSavepoint->iHdrOffset ? pSavepoint->iHdrOffset : szJ;
  3378      pPager->journalOff = pSavepoint->iOffset;
  3379      while( rc==SQLITE_OK && pPager->journalOff<iHdrOff ){
  3380        rc = pager_playback_one_page(pPager, &pPager->journalOff, pDone, 1, 1);
  3381      }
  3382      assert( rc!=SQLITE_DONE );
  3383    }else{
  3384      pPager->journalOff = 0;
  3385    }
  3386  
  3387    /* Continue rolling back records out of the main journal starting at
  3388    ** the first journal header seen and continuing until the effective end
  3389    ** of the main journal file.  Continue to skip out-of-range pages and
  3390    ** continue adding pages rolled back to pDone.
  3391    */
  3392    while( rc==SQLITE_OK && pPager->journalOff<szJ ){
  3393      u32 ii;            /* Loop counter */
  3394      u32 nJRec = 0;     /* Number of Journal Records */
  3395      u32 dummy;
  3396      rc = readJournalHdr(pPager, 0, szJ, &nJRec, &dummy);
  3397      assert( rc!=SQLITE_DONE );
  3398  
  3399      /*
  3400      ** The "pPager->journalHdr+JOURNAL_HDR_SZ(pPager)==pPager->journalOff"
  3401      ** test is related to ticket #2565.  See the discussion in the
  3402      ** pager_playback() function for additional information.
  3403      */
  3404      if( nJRec==0 
  3405       && pPager->journalHdr+JOURNAL_HDR_SZ(pPager)==pPager->journalOff
  3406      ){
  3407        nJRec = (u32)((szJ - pPager->journalOff)/JOURNAL_PG_SZ(pPager));
  3408      }
  3409      for(ii=0; rc==SQLITE_OK && ii<nJRec && pPager->journalOff<szJ; ii++){
  3410        rc = pager_playback_one_page(pPager, &pPager->journalOff, pDone, 1, 1);
  3411      }
  3412      assert( rc!=SQLITE_DONE );
  3413    }
  3414    assert( rc!=SQLITE_OK || pPager->journalOff>=szJ );
  3415  
  3416    /* Finally,  rollback pages from the sub-journal.  Page that were
  3417    ** previously rolled back out of the main journal (and are hence in pDone)
  3418    ** will be skipped.  Out-of-range pages are also skipped.
  3419    */
  3420    if( pSavepoint ){
  3421      u32 ii;            /* Loop counter */
  3422      i64 offset = (i64)pSavepoint->iSubRec*(4+pPager->pageSize);
  3423  
  3424      if( pagerUseWal(pPager) ){
  3425        rc = sqlite3WalSavepointUndo(pPager->pWal, pSavepoint->aWalData);
  3426      }
  3427      for(ii=pSavepoint->iSubRec; rc==SQLITE_OK && ii<pPager->nSubRec; ii++){
  3428        assert( offset==(i64)ii*(4+pPager->pageSize) );
  3429        rc = pager_playback_one_page(pPager, &offset, pDone, 0, 1);
  3430      }
  3431      assert( rc!=SQLITE_DONE );
  3432    }
  3433  
  3434    sqlite3BitvecDestroy(pDone);
  3435    if( rc==SQLITE_OK ){
  3436      pPager->journalOff = szJ;
  3437    }
  3438  
  3439    return rc;
  3440  }
  3441  
  3442  /*
  3443  ** Change the maximum number of in-memory pages that are allowed
  3444  ** before attempting to recycle clean and unused pages.
  3445  */
  3446  void sqlite3PagerSetCachesize(Pager *pPager, int mxPage){
  3447    sqlite3PcacheSetCachesize(pPager->pPCache, mxPage);
  3448  }
  3449  
  3450  /*
  3451  ** Change the maximum number of in-memory pages that are allowed
  3452  ** before attempting to spill pages to journal.
  3453  */
  3454  int sqlite3PagerSetSpillsize(Pager *pPager, int mxPage){
  3455    return sqlite3PcacheSetSpillsize(pPager->pPCache, mxPage);
  3456  }
  3457  
  3458  /*
  3459  ** Invoke SQLITE_FCNTL_MMAP_SIZE based on the current value of szMmap.
  3460  */
  3461  static void pagerFixMaplimit(Pager *pPager){
  3462  #if SQLITE_MAX_MMAP_SIZE>0
  3463    sqlite3_file *fd = pPager->fd;
  3464    if( isOpen(fd) && fd->pMethods->iVersion>=3 ){
  3465      sqlite3_int64 sz;
  3466      sz = pPager->szMmap;
  3467      pPager->bUseFetch = (sz>0);
  3468      setGetterMethod(pPager);
  3469      sqlite3OsFileControlHint(pPager->fd, SQLITE_FCNTL_MMAP_SIZE, &sz);
  3470    }
  3471  #endif
  3472  }
  3473  
  3474  /*
  3475  ** Change the maximum size of any memory mapping made of the database file.
  3476  */
  3477  void sqlite3PagerSetMmapLimit(Pager *pPager, sqlite3_int64 szMmap){
  3478    pPager->szMmap = szMmap;
  3479    pagerFixMaplimit(pPager);
  3480  }
  3481  
  3482  /*
  3483  ** Free as much memory as possible from the pager.
  3484  */
  3485  void sqlite3PagerShrink(Pager *pPager){
  3486    sqlite3PcacheShrink(pPager->pPCache);
  3487  }
  3488  
  3489  /*
  3490  ** Adjust settings of the pager to those specified in the pgFlags parameter.
  3491  **
  3492  ** The "level" in pgFlags & PAGER_SYNCHRONOUS_MASK sets the robustness
  3493  ** of the database to damage due to OS crashes or power failures by
  3494  ** changing the number of syncs()s when writing the journals.
  3495  ** There are four levels:
  3496  **
  3497  **    OFF       sqlite3OsSync() is never called.  This is the default
  3498  **              for temporary and transient files.
  3499  **
  3500  **    NORMAL    The journal is synced once before writes begin on the
  3501  **              database.  This is normally adequate protection, but
  3502  **              it is theoretically possible, though very unlikely,
  3503  **              that an inopertune power failure could leave the journal
  3504  **              in a state which would cause damage to the database
  3505  **              when it is rolled back.
  3506  **
  3507  **    FULL      The journal is synced twice before writes begin on the
  3508  **              database (with some additional information - the nRec field
  3509  **              of the journal header - being written in between the two
  3510  **              syncs).  If we assume that writing a
  3511  **              single disk sector is atomic, then this mode provides
  3512  **              assurance that the journal will not be corrupted to the
  3513  **              point of causing damage to the database during rollback.
  3514  **
  3515  **    EXTRA     This is like FULL except that is also syncs the directory
  3516  **              that contains the rollback journal after the rollback
  3517  **              journal is unlinked.
  3518  **
  3519  ** The above is for a rollback-journal mode.  For WAL mode, OFF continues
  3520  ** to mean that no syncs ever occur.  NORMAL means that the WAL is synced
  3521  ** prior to the start of checkpoint and that the database file is synced
  3522  ** at the conclusion of the checkpoint if the entire content of the WAL
  3523  ** was written back into the database.  But no sync operations occur for
  3524  ** an ordinary commit in NORMAL mode with WAL.  FULL means that the WAL
  3525  ** file is synced following each commit operation, in addition to the
  3526  ** syncs associated with NORMAL.  There is no difference between FULL
  3527  ** and EXTRA for WAL mode.
  3528  **
  3529  ** Do not confuse synchronous=FULL with SQLITE_SYNC_FULL.  The
  3530  ** SQLITE_SYNC_FULL macro means to use the MacOSX-style full-fsync
  3531  ** using fcntl(F_FULLFSYNC).  SQLITE_SYNC_NORMAL means to do an
  3532  ** ordinary fsync() call.  There is no difference between SQLITE_SYNC_FULL
  3533  ** and SQLITE_SYNC_NORMAL on platforms other than MacOSX.  But the
  3534  ** synchronous=FULL versus synchronous=NORMAL setting determines when
  3535  ** the xSync primitive is called and is relevant to all platforms.
  3536  **
  3537  ** Numeric values associated with these states are OFF==1, NORMAL=2,
  3538  ** and FULL=3.
  3539  */
  3540  #ifndef SQLITE_OMIT_PAGER_PRAGMAS
  3541  void sqlite3PagerSetFlags(
  3542    Pager *pPager,        /* The pager to set safety level for */
  3543    unsigned pgFlags      /* Various flags */
  3544  ){
  3545    unsigned level = pgFlags & PAGER_SYNCHRONOUS_MASK;
  3546    if( pPager->tempFile ){
  3547      pPager->noSync = 1;
  3548      pPager->fullSync = 0;
  3549      pPager->extraSync = 0;
  3550    }else{
  3551      pPager->noSync =  level==PAGER_SYNCHRONOUS_OFF ?1:0;
  3552      pPager->fullSync = level>=PAGER_SYNCHRONOUS_FULL ?1:0;
  3553      pPager->extraSync = level==PAGER_SYNCHRONOUS_EXTRA ?1:0;
  3554    }
  3555    if( pPager->noSync ){
  3556      pPager->syncFlags = 0;
  3557    }else if( pgFlags & PAGER_FULLFSYNC ){
  3558      pPager->syncFlags = SQLITE_SYNC_FULL;
  3559    }else{
  3560      pPager->syncFlags = SQLITE_SYNC_NORMAL;
  3561    }
  3562    pPager->walSyncFlags = (pPager->syncFlags<<2);
  3563    if( pPager->fullSync ){
  3564      pPager->walSyncFlags |= pPager->syncFlags;
  3565    }
  3566    if( (pgFlags & PAGER_CKPT_FULLFSYNC) && !pPager->noSync ){
  3567      pPager->walSyncFlags |= (SQLITE_SYNC_FULL<<2);
  3568    }
  3569    if( pgFlags & PAGER_CACHESPILL ){
  3570      pPager->doNotSpill &= ~SPILLFLAG_OFF;
  3571    }else{
  3572      pPager->doNotSpill |= SPILLFLAG_OFF;
  3573    }
  3574  }
  3575  #endif
  3576  
  3577  /*
  3578  ** The following global variable is incremented whenever the library
  3579  ** attempts to open a temporary file.  This information is used for
  3580  ** testing and analysis only.  
  3581  */
  3582  #ifdef SQLITE_TEST
  3583  int sqlite3_opentemp_count = 0;
  3584  #endif
  3585  
  3586  /*
  3587  ** Open a temporary file.
  3588  **
  3589  ** Write the file descriptor into *pFile. Return SQLITE_OK on success 
  3590  ** or some other error code if we fail. The OS will automatically 
  3591  ** delete the temporary file when it is closed.
  3592  **
  3593  ** The flags passed to the VFS layer xOpen() call are those specified
  3594  ** by parameter vfsFlags ORed with the following:
  3595  **
  3596  **     SQLITE_OPEN_READWRITE
  3597  **     SQLITE_OPEN_CREATE
  3598  **     SQLITE_OPEN_EXCLUSIVE
  3599  **     SQLITE_OPEN_DELETEONCLOSE
  3600  */
  3601  static int pagerOpentemp(
  3602    Pager *pPager,        /* The pager object */
  3603    sqlite3_file *pFile,  /* Write the file descriptor here */
  3604    int vfsFlags          /* Flags passed through to the VFS */
  3605  ){
  3606    int rc;               /* Return code */
  3607  
  3608  #ifdef SQLITE_TEST
  3609    sqlite3_opentemp_count++;  /* Used for testing and analysis only */
  3610  #endif
  3611  
  3612    vfsFlags |=  SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE |
  3613              SQLITE_OPEN_EXCLUSIVE | SQLITE_OPEN_DELETEONCLOSE;
  3614    rc = sqlite3OsOpen(pPager->pVfs, 0, pFile, vfsFlags, 0);
  3615    assert( rc!=SQLITE_OK || isOpen(pFile) );
  3616    return rc;
  3617  }
  3618  
  3619  /*
  3620  ** Set the busy handler function.
  3621  **
  3622  ** The pager invokes the busy-handler if sqlite3OsLock() returns 
  3623  ** SQLITE_BUSY when trying to upgrade from no-lock to a SHARED lock,
  3624  ** or when trying to upgrade from a RESERVED lock to an EXCLUSIVE 
  3625  ** lock. It does *not* invoke the busy handler when upgrading from
  3626  ** SHARED to RESERVED, or when upgrading from SHARED to EXCLUSIVE
  3627  ** (which occurs during hot-journal rollback). Summary:
  3628  **
  3629  **   Transition                        | Invokes xBusyHandler
  3630  **   --------------------------------------------------------
  3631  **   NO_LOCK       -> SHARED_LOCK      | Yes
  3632  **   SHARED_LOCK   -> RESERVED_LOCK    | No
  3633  **   SHARED_LOCK   -> EXCLUSIVE_LOCK   | No
  3634  **   RESERVED_LOCK -> EXCLUSIVE_LOCK   | Yes
  3635  **
  3636  ** If the busy-handler callback returns non-zero, the lock is 
  3637  ** retried. If it returns zero, then the SQLITE_BUSY error is
  3638  ** returned to the caller of the pager API function.
  3639  */
  3640  void sqlite3PagerSetBusyHandler(
  3641    Pager *pPager,                       /* Pager object */
  3642    int (*xBusyHandler)(void *),         /* Pointer to busy-handler function */
  3643    void *pBusyHandlerArg                /* Argument to pass to xBusyHandler */
  3644  ){
  3645    void **ap;
  3646    pPager->xBusyHandler = xBusyHandler;
  3647    pPager->pBusyHandlerArg = pBusyHandlerArg;
  3648    ap = (void **)&pPager->xBusyHandler;
  3649    assert( ((int(*)(void *))(ap[0]))==xBusyHandler );
  3650    assert( ap[1]==pBusyHandlerArg );
  3651    sqlite3OsFileControlHint(pPager->fd, SQLITE_FCNTL_BUSYHANDLER, (void *)ap);
  3652  }
  3653  
  3654  /*
  3655  ** Change the page size used by the Pager object. The new page size 
  3656  ** is passed in *pPageSize.
  3657  **
  3658  ** If the pager is in the error state when this function is called, it
  3659  ** is a no-op. The value returned is the error state error code (i.e. 
  3660  ** one of SQLITE_IOERR, an SQLITE_IOERR_xxx sub-code or SQLITE_FULL).
  3661  **
  3662  ** Otherwise, if all of the following are true:
  3663  **
  3664  **   * the new page size (value of *pPageSize) is valid (a power 
  3665  **     of two between 512 and SQLITE_MAX_PAGE_SIZE, inclusive), and
  3666  **
  3667  **   * there are no outstanding page references, and
  3668  **
  3669  **   * the database is either not an in-memory database or it is
  3670  **     an in-memory database that currently consists of zero pages.
  3671  **
  3672  ** then the pager object page size is set to *pPageSize.
  3673  **
  3674  ** If the page size is changed, then this function uses sqlite3PagerMalloc() 
  3675  ** to obtain a new Pager.pTmpSpace buffer. If this allocation attempt 
  3676  ** fails, SQLITE_NOMEM is returned and the page size remains unchanged. 
  3677  ** In all other cases, SQLITE_OK is returned.
  3678  **
  3679  ** If the page size is not changed, either because one of the enumerated
  3680  ** conditions above is not true, the pager was in error state when this
  3681  ** function was called, or because the memory allocation attempt failed, 
  3682  ** then *pPageSize is set to the old, retained page size before returning.
  3683  */
  3684  int sqlite3PagerSetPagesize(Pager *pPager, u32 *pPageSize, int nReserve){
  3685    int rc = SQLITE_OK;
  3686  
  3687    /* It is not possible to do a full assert_pager_state() here, as this
  3688    ** function may be called from within PagerOpen(), before the state
  3689    ** of the Pager object is internally consistent.
  3690    **
  3691    ** At one point this function returned an error if the pager was in 
  3692    ** PAGER_ERROR state. But since PAGER_ERROR state guarantees that
  3693    ** there is at least one outstanding page reference, this function
  3694    ** is a no-op for that case anyhow.
  3695    */
  3696  
  3697    u32 pageSize = *pPageSize;
  3698    assert( pageSize==0 || (pageSize>=512 && pageSize<=SQLITE_MAX_PAGE_SIZE) );
  3699    if( (pPager->memDb==0 || pPager->dbSize==0)
  3700     && sqlite3PcacheRefCount(pPager->pPCache)==0 
  3701     && pageSize && pageSize!=(u32)pPager->pageSize 
  3702    ){
  3703      char *pNew = NULL;             /* New temp space */
  3704      i64 nByte = 0;
  3705  
  3706      if( pPager->eState>PAGER_OPEN && isOpen(pPager->fd) ){
  3707        rc = sqlite3OsFileSize(pPager->fd, &nByte);
  3708      }
  3709      if( rc==SQLITE_OK ){
  3710        /* 8 bytes of zeroed overrun space is sufficient so that the b-tree
  3711        * cell header parser will never run off the end of the allocation */
  3712        pNew = (char *)sqlite3PageMalloc(pageSize+8);
  3713        if( !pNew ){
  3714          rc = SQLITE_NOMEM_BKPT;
  3715        }else{
  3716          memset(pNew+pageSize, 0, 8);
  3717        }
  3718      }
  3719  
  3720      if( rc==SQLITE_OK ){
  3721        pager_reset(pPager);
  3722        rc = sqlite3PcacheSetPageSize(pPager->pPCache, pageSize);
  3723      }
  3724      if( rc==SQLITE_OK ){
  3725        sqlite3PageFree(pPager->pTmpSpace);
  3726        pPager->pTmpSpace = pNew;
  3727        pPager->dbSize = (Pgno)((nByte+pageSize-1)/pageSize);
  3728        pPager->pageSize = pageSize;
  3729      }else{
  3730        sqlite3PageFree(pNew);
  3731      }
  3732    }
  3733  
  3734    *pPageSize = pPager->pageSize;
  3735    if( rc==SQLITE_OK ){
  3736      if( nReserve<0 ) nReserve = pPager->nReserve;
  3737      assert( nReserve>=0 && nReserve<1000 );
  3738      pPager->nReserve = (i16)nReserve;
  3739      pagerFixMaplimit(pPager);
  3740    }
  3741    return rc;
  3742  }
  3743  
  3744  /*
  3745  ** Return a pointer to the "temporary page" buffer held internally
  3746  ** by the pager.  This is a buffer that is big enough to hold the
  3747  ** entire content of a database page.  This buffer is used internally
  3748  ** during rollback and will be overwritten whenever a rollback
  3749  ** occurs.  But other modules are free to use it too, as long as
  3750  ** no rollbacks are happening.
  3751  */
  3752  void *sqlite3PagerTempSpace(Pager *pPager){
  3753    return pPager->pTmpSpace;
  3754  }
  3755  
  3756  /*
  3757  ** Attempt to set the maximum database page count if mxPage is positive. 
  3758  ** Make no changes if mxPage is zero or negative.  And never reduce the
  3759  ** maximum page count below the current size of the database.
  3760  **
  3761  ** Regardless of mxPage, return the current maximum page count.
  3762  */
  3763  int sqlite3PagerMaxPageCount(Pager *pPager, int mxPage){
  3764    if( mxPage>0 ){
  3765      pPager->mxPgno = mxPage;
  3766    }
  3767    assert( pPager->eState!=PAGER_OPEN );      /* Called only by OP_MaxPgcnt */
  3768    /* assert( pPager->mxPgno>=pPager->dbSize ); */
  3769    /* OP_MaxPgcnt ensures that the parameter passed to this function is not
  3770    ** less than the total number of valid pages in the database. But this
  3771    ** may be less than Pager.dbSize, and so the assert() above is not valid */
  3772    return pPager->mxPgno;
  3773  }
  3774  
  3775  /*
  3776  ** The following set of routines are used to disable the simulated
  3777  ** I/O error mechanism.  These routines are used to avoid simulated
  3778  ** errors in places where we do not care about errors.
  3779  **
  3780  ** Unless -DSQLITE_TEST=1 is used, these routines are all no-ops
  3781  ** and generate no code.
  3782  */
  3783  #ifdef SQLITE_TEST
  3784  extern int sqlite3_io_error_pending;
  3785  extern int sqlite3_io_error_hit;
  3786  static int saved_cnt;
  3787  void disable_simulated_io_errors(void){
  3788    saved_cnt = sqlite3_io_error_pending;
  3789    sqlite3_io_error_pending = -1;
  3790  }
  3791  void enable_simulated_io_errors(void){
  3792    sqlite3_io_error_pending = saved_cnt;
  3793  }
  3794  #else
  3795  # define disable_simulated_io_errors()
  3796  # define enable_simulated_io_errors()
  3797  #endif
  3798  
  3799  /*
  3800  ** Read the first N bytes from the beginning of the file into memory
  3801  ** that pDest points to. 
  3802  **
  3803  ** If the pager was opened on a transient file (zFilename==""), or
  3804  ** opened on a file less than N bytes in size, the output buffer is
  3805  ** zeroed and SQLITE_OK returned. The rationale for this is that this 
  3806  ** function is used to read database headers, and a new transient or
  3807  ** zero sized database has a header than consists entirely of zeroes.
  3808  **
  3809  ** If any IO error apart from SQLITE_IOERR_SHORT_READ is encountered,
  3810  ** the error code is returned to the caller and the contents of the
  3811  ** output buffer undefined.
  3812  */
  3813  int sqlite3PagerReadFileheader(Pager *pPager, int N, unsigned char *pDest){
  3814    int rc = SQLITE_OK;
  3815    memset(pDest, 0, N);
  3816    assert( isOpen(pPager->fd) || pPager->tempFile );
  3817  
  3818    /* This routine is only called by btree immediately after creating
  3819    ** the Pager object.  There has not been an opportunity to transition
  3820    ** to WAL mode yet.
  3821    */
  3822    assert( !pagerUseWal(pPager) );
  3823  
  3824    if( isOpen(pPager->fd) ){
  3825      IOTRACE(("DBHDR %p 0 %d\n", pPager, N))
  3826      rc = sqlite3OsRead(pPager->fd, pDest, N, 0);
  3827      if( rc==SQLITE_IOERR_SHORT_READ ){
  3828        rc = SQLITE_OK;
  3829      }
  3830    }
  3831    return rc;
  3832  }
  3833  
  3834  /*
  3835  ** This function may only be called when a read-transaction is open on
  3836  ** the pager. It returns the total number of pages in the database.
  3837  **
  3838  ** However, if the file is between 1 and <page-size> bytes in size, then 
  3839  ** this is considered a 1 page file.
  3840  */
  3841  void sqlite3PagerPagecount(Pager *pPager, int *pnPage){
  3842    assert( pPager->eState>=PAGER_READER );
  3843    assert( pPager->eState!=PAGER_WRITER_FINISHED );
  3844    *pnPage = (int)pPager->dbSize;
  3845  }
  3846  
  3847  
  3848  /*
  3849  ** Try to obtain a lock of type locktype on the database file. If
  3850  ** a similar or greater lock is already held, this function is a no-op
  3851  ** (returning SQLITE_OK immediately).
  3852  **
  3853  ** Otherwise, attempt to obtain the lock using sqlite3OsLock(). Invoke 
  3854  ** the busy callback if the lock is currently not available. Repeat 
  3855  ** until the busy callback returns false or until the attempt to 
  3856  ** obtain the lock succeeds.
  3857  **
  3858  ** Return SQLITE_OK on success and an error code if we cannot obtain
  3859  ** the lock. If the lock is obtained successfully, set the Pager.state 
  3860  ** variable to locktype before returning.
  3861  */
  3862  static int pager_wait_on_lock(Pager *pPager, int locktype){
  3863    int rc;                              /* Return code */
  3864  
  3865    /* Check that this is either a no-op (because the requested lock is 
  3866    ** already held), or one of the transitions that the busy-handler
  3867    ** may be invoked during, according to the comment above
  3868    ** sqlite3PagerSetBusyhandler().
  3869    */
  3870    assert( (pPager->eLock>=locktype)
  3871         || (pPager->eLock==NO_LOCK && locktype==SHARED_LOCK)
  3872         || (pPager->eLock==RESERVED_LOCK && locktype==EXCLUSIVE_LOCK)
  3873    );
  3874  
  3875    do {
  3876      rc = pagerLockDb(pPager, locktype);
  3877    }while( rc==SQLITE_BUSY && pPager->xBusyHandler(pPager->pBusyHandlerArg) );
  3878    return rc;
  3879  }
  3880  
  3881  /*
  3882  ** Function assertTruncateConstraint(pPager) checks that one of the 
  3883  ** following is true for all dirty pages currently in the page-cache:
  3884  **
  3885  **   a) The page number is less than or equal to the size of the 
  3886  **      current database image, in pages, OR
  3887  **
  3888  **   b) if the page content were written at this time, it would not
  3889  **      be necessary to write the current content out to the sub-journal
  3890  **      (as determined by function subjRequiresPage()).
  3891  **
  3892  ** If the condition asserted by this function were not true, and the
  3893  ** dirty page were to be discarded from the cache via the pagerStress()
  3894  ** routine, pagerStress() would not write the current page content to
  3895  ** the database file. If a savepoint transaction were rolled back after
  3896  ** this happened, the correct behavior would be to restore the current
  3897  ** content of the page. However, since this content is not present in either
  3898  ** the database file or the portion of the rollback journal and 
  3899  ** sub-journal rolled back the content could not be restored and the
  3900  ** database image would become corrupt. It is therefore fortunate that 
  3901  ** this circumstance cannot arise.
  3902  */
  3903  #if defined(SQLITE_DEBUG)
  3904  static void assertTruncateConstraintCb(PgHdr *pPg){
  3905    assert( pPg->flags&PGHDR_DIRTY );
  3906    assert( !subjRequiresPage(pPg) || pPg->pgno<=pPg->pPager->dbSize );
  3907  }
  3908  static void assertTruncateConstraint(Pager *pPager){
  3909    sqlite3PcacheIterateDirty(pPager->pPCache, assertTruncateConstraintCb);
  3910  }
  3911  #else
  3912  # define assertTruncateConstraint(pPager)
  3913  #endif
  3914  
  3915  /*
  3916  ** Truncate the in-memory database file image to nPage pages. This 
  3917  ** function does not actually modify the database file on disk. It 
  3918  ** just sets the internal state of the pager object so that the 
  3919  ** truncation will be done when the current transaction is committed.
  3920  **
  3921  ** This function is only called right before committing a transaction.
  3922  ** Once this function has been called, the transaction must either be
  3923  ** rolled back or committed. It is not safe to call this function and
  3924  ** then continue writing to the database.
  3925  */
  3926  void sqlite3PagerTruncateImage(Pager *pPager, Pgno nPage){
  3927    assert( pPager->dbSize>=nPage );
  3928    assert( pPager->eState>=PAGER_WRITER_CACHEMOD );
  3929    pPager->dbSize = nPage;
  3930  
  3931    /* At one point the code here called assertTruncateConstraint() to
  3932    ** ensure that all pages being truncated away by this operation are,
  3933    ** if one or more savepoints are open, present in the savepoint 
  3934    ** journal so that they can be restored if the savepoint is rolled
  3935    ** back. This is no longer necessary as this function is now only
  3936    ** called right before committing a transaction. So although the 
  3937    ** Pager object may still have open savepoints (Pager.nSavepoint!=0), 
  3938    ** they cannot be rolled back. So the assertTruncateConstraint() call
  3939    ** is no longer correct. */
  3940  }
  3941  
  3942  
  3943  /*
  3944  ** This function is called before attempting a hot-journal rollback. It
  3945  ** syncs the journal file to disk, then sets pPager->journalHdr to the
  3946  ** size of the journal file so that the pager_playback() routine knows
  3947  ** that the entire journal file has been synced.
  3948  **
  3949  ** Syncing a hot-journal to disk before attempting to roll it back ensures 
  3950  ** that if a power-failure occurs during the rollback, the process that
  3951  ** attempts rollback following system recovery sees the same journal
  3952  ** content as this process.
  3953  **
  3954  ** If everything goes as planned, SQLITE_OK is returned. Otherwise, 
  3955  ** an SQLite error code.
  3956  */
  3957  static int pagerSyncHotJournal(Pager *pPager){
  3958    int rc = SQLITE_OK;
  3959    if( !pPager->noSync ){
  3960      rc = sqlite3OsSync(pPager->jfd, SQLITE_SYNC_NORMAL);
  3961    }
  3962    if( rc==SQLITE_OK ){
  3963      rc = sqlite3OsFileSize(pPager->jfd, &pPager->journalHdr);
  3964    }
  3965    return rc;
  3966  }
  3967  
  3968  #if SQLITE_MAX_MMAP_SIZE>0
  3969  /*
  3970  ** Obtain a reference to a memory mapped page object for page number pgno. 
  3971  ** The new object will use the pointer pData, obtained from xFetch().
  3972  ** If successful, set *ppPage to point to the new page reference
  3973  ** and return SQLITE_OK. Otherwise, return an SQLite error code and set
  3974  ** *ppPage to zero.
  3975  **
  3976  ** Page references obtained by calling this function should be released
  3977  ** by calling pagerReleaseMapPage().
  3978  */
  3979  static int pagerAcquireMapPage(
  3980    Pager *pPager,                  /* Pager object */
  3981    Pgno pgno,                      /* Page number */
  3982    void *pData,                    /* xFetch()'d data for this page */
  3983    PgHdr **ppPage                  /* OUT: Acquired page object */
  3984  ){
  3985    PgHdr *p;                       /* Memory mapped page to return */
  3986    
  3987    if( pPager->pMmapFreelist ){
  3988      *ppPage = p = pPager->pMmapFreelist;
  3989      pPager->pMmapFreelist = p->pDirty;
  3990      p->pDirty = 0;
  3991      assert( pPager->nExtra>=8 );
  3992      memset(p->pExtra, 0, 8);
  3993    }else{
  3994      *ppPage = p = (PgHdr *)sqlite3MallocZero(sizeof(PgHdr) + pPager->nExtra);
  3995      if( p==0 ){
  3996        sqlite3OsUnfetch(pPager->fd, (i64)(pgno-1) * pPager->pageSize, pData);
  3997        return SQLITE_NOMEM_BKPT;
  3998      }
  3999      p->pExtra = (void *)&p[1];
  4000      p->flags = PGHDR_MMAP;
  4001      p->nRef = 1;
  4002      p->pPager = pPager;
  4003    }
  4004  
  4005    assert( p->pExtra==(void *)&p[1] );
  4006    assert( p->pPage==0 );
  4007    assert( p->flags==PGHDR_MMAP );
  4008    assert( p->pPager==pPager );
  4009    assert( p->nRef==1 );
  4010  
  4011    p->pgno = pgno;
  4012    p->pData = pData;
  4013    pPager->nMmapOut++;
  4014  
  4015    return SQLITE_OK;
  4016  }
  4017  #endif
  4018  
  4019  /*
  4020  ** Release a reference to page pPg. pPg must have been returned by an 
  4021  ** earlier call to pagerAcquireMapPage().
  4022  */
  4023  static void pagerReleaseMapPage(PgHdr *pPg){
  4024    Pager *pPager = pPg->pPager;
  4025    pPager->nMmapOut--;
  4026    pPg->pDirty = pPager->pMmapFreelist;
  4027    pPager->pMmapFreelist = pPg;
  4028  
  4029    assert( pPager->fd->pMethods->iVersion>=3 );
  4030    sqlite3OsUnfetch(pPager->fd, (i64)(pPg->pgno-1)*pPager->pageSize, pPg->pData);
  4031  }
  4032  
  4033  /*
  4034  ** Free all PgHdr objects stored in the Pager.pMmapFreelist list.
  4035  */
  4036  static void pagerFreeMapHdrs(Pager *pPager){
  4037    PgHdr *p;
  4038    PgHdr *pNext;
  4039    for(p=pPager->pMmapFreelist; p; p=pNext){
  4040      pNext = p->pDirty;
  4041      sqlite3_free(p);
  4042    }
  4043  }
  4044  
  4045  /* Verify that the database file has not be deleted or renamed out from
  4046  ** under the pager.  Return SQLITE_OK if the database is still where it ought
  4047  ** to be on disk.  Return non-zero (SQLITE_READONLY_DBMOVED or some other error
  4048  ** code from sqlite3OsAccess()) if the database has gone missing.
  4049  */
  4050  static int databaseIsUnmoved(Pager *pPager){
  4051    int bHasMoved = 0;
  4052    int rc;
  4053  
  4054    if( pPager->tempFile ) return SQLITE_OK;
  4055    if( pPager->dbSize==0 ) return SQLITE_OK;
  4056    assert( pPager->zFilename && pPager->zFilename[0] );
  4057    rc = sqlite3OsFileControl(pPager->fd, SQLITE_FCNTL_HAS_MOVED, &bHasMoved);
  4058    if( rc==SQLITE_NOTFOUND ){
  4059      /* If the HAS_MOVED file-control is unimplemented, assume that the file
  4060      ** has not been moved.  That is the historical behavior of SQLite: prior to
  4061      ** version 3.8.3, it never checked */
  4062      rc = SQLITE_OK;
  4063    }else if( rc==SQLITE_OK && bHasMoved ){
  4064      rc = SQLITE_READONLY_DBMOVED;
  4065    }
  4066    return rc;
  4067  }
  4068  
  4069  
  4070  /*
  4071  ** Shutdown the page cache.  Free all memory and close all files.
  4072  **
  4073  ** If a transaction was in progress when this routine is called, that
  4074  ** transaction is rolled back.  All outstanding pages are invalidated
  4075  ** and their memory is freed.  Any attempt to use a page associated
  4076  ** with this page cache after this function returns will likely
  4077  ** result in a coredump.
  4078  **
  4079  ** This function always succeeds. If a transaction is active an attempt
  4080  ** is made to roll it back. If an error occurs during the rollback 
  4081  ** a hot journal may be left in the filesystem but no error is returned
  4082  ** to the caller.
  4083  */
  4084  int sqlite3PagerClose(Pager *pPager, sqlite3 *db){
  4085    u8 *pTmp = (u8*)pPager->pTmpSpace;
  4086    assert( db || pagerUseWal(pPager)==0 );
  4087    assert( assert_pager_state(pPager) );
  4088    disable_simulated_io_errors();
  4089    sqlite3BeginBenignMalloc();
  4090    pagerFreeMapHdrs(pPager);
  4091    /* pPager->errCode = 0; */
  4092    pPager->exclusiveMode = 0;
  4093  #ifndef SQLITE_OMIT_WAL
  4094    {
  4095      u8 *a = 0;
  4096      assert( db || pPager->pWal==0 );
  4097      if( db && 0==(db->flags & SQLITE_NoCkptOnClose) 
  4098       && SQLITE_OK==databaseIsUnmoved(pPager)
  4099      ){
  4100        a = pTmp;
  4101      }
  4102      sqlite3WalClose(pPager->pWal, db, pPager->walSyncFlags, pPager->pageSize,a);
  4103      pPager->pWal = 0;
  4104    }
  4105  #endif
  4106    pager_reset(pPager);
  4107    if( MEMDB ){
  4108      pager_unlock(pPager);
  4109    }else{
  4110      /* If it is open, sync the journal file before calling UnlockAndRollback.
  4111      ** If this is not done, then an unsynced portion of the open journal 
  4112      ** file may be played back into the database. If a power failure occurs 
  4113      ** while this is happening, the database could become corrupt.
  4114      **
  4115      ** If an error occurs while trying to sync the journal, shift the pager
  4116      ** into the ERROR state. This causes UnlockAndRollback to unlock the
  4117      ** database and close the journal file without attempting to roll it
  4118      ** back or finalize it. The next database user will have to do hot-journal
  4119      ** rollback before accessing the database file.
  4120      */
  4121      if( isOpen(pPager->jfd) ){
  4122        pager_error(pPager, pagerSyncHotJournal(pPager));
  4123      }
  4124      pagerUnlockAndRollback(pPager);
  4125    }
  4126    sqlite3EndBenignMalloc();
  4127    enable_simulated_io_errors();
  4128    PAGERTRACE(("CLOSE %d\n", PAGERID(pPager)));
  4129    IOTRACE(("CLOSE %p\n", pPager))
  4130    sqlite3OsClose(pPager->jfd);
  4131    sqlite3OsClose(pPager->fd);
  4132    sqlite3PageFree(pTmp);
  4133    sqlite3PcacheClose(pPager->pPCache);
  4134    assert( !pPager->aSavepoint && !pPager->pInJournal );
  4135    assert( !isOpen(pPager->jfd) && !isOpen(pPager->sjfd) );
  4136  
  4137    sqlite3_free(pPager);
  4138    return SQLITE_OK;
  4139  }
  4140  
  4141  #if !defined(NDEBUG) || defined(SQLITE_TEST)
  4142  /*
  4143  ** Return the page number for page pPg.
  4144  */
  4145  Pgno sqlite3PagerPagenumber(DbPage *pPg){
  4146    return pPg->pgno;
  4147  }
  4148  #endif
  4149  
  4150  /*
  4151  ** Increment the reference count for page pPg.
  4152  */
  4153  void sqlite3PagerRef(DbPage *pPg){
  4154    sqlite3PcacheRef(pPg);
  4155  }
  4156  
  4157  /*
  4158  ** Sync the journal. In other words, make sure all the pages that have
  4159  ** been written to the journal have actually reached the surface of the
  4160  ** disk and can be restored in the event of a hot-journal rollback.
  4161  **
  4162  ** If the Pager.noSync flag is set, then this function is a no-op.
  4163  ** Otherwise, the actions required depend on the journal-mode and the 
  4164  ** device characteristics of the file-system, as follows:
  4165  **
  4166  **   * If the journal file is an in-memory journal file, no action need
  4167  **     be taken.
  4168  **
  4169  **   * Otherwise, if the device does not support the SAFE_APPEND property,
  4170  **     then the nRec field of the most recently written journal header
  4171  **     is updated to contain the number of journal records that have
  4172  **     been written following it. If the pager is operating in full-sync
  4173  **     mode, then the journal file is synced before this field is updated.
  4174  **
  4175  **   * If the device does not support the SEQUENTIAL property, then 
  4176  **     journal file is synced.
  4177  **
  4178  ** Or, in pseudo-code:
  4179  **
  4180  **   if( NOT <in-memory journal> ){
  4181  **     if( NOT SAFE_APPEND ){
  4182  **       if( <full-sync mode> ) xSync(<journal file>);
  4183  **       <update nRec field>
  4184  **     } 
  4185  **     if( NOT SEQUENTIAL ) xSync(<journal file>);
  4186  **   }
  4187  **
  4188  ** If successful, this routine clears the PGHDR_NEED_SYNC flag of every 
  4189  ** page currently held in memory before returning SQLITE_OK. If an IO
  4190  ** error is encountered, then the IO error code is returned to the caller.
  4191  */
  4192  static int syncJournal(Pager *pPager, int newHdr){
  4193    int rc;                         /* Return code */
  4194  
  4195    assert( pPager->eState==PAGER_WRITER_CACHEMOD
  4196         || pPager->eState==PAGER_WRITER_DBMOD
  4197    );
  4198    assert( assert_pager_state(pPager) );
  4199    assert( !pagerUseWal(pPager) );
  4200  
  4201    rc = sqlite3PagerExclusiveLock(pPager);
  4202    if( rc!=SQLITE_OK ) return rc;
  4203  
  4204    if( !pPager->noSync ){
  4205      assert( !pPager->tempFile );
  4206      if( isOpen(pPager->jfd) && pPager->journalMode!=PAGER_JOURNALMODE_MEMORY ){
  4207        const int iDc = sqlite3OsDeviceCharacteristics(pPager->fd);
  4208        assert( isOpen(pPager->jfd) );
  4209  
  4210        if( 0==(iDc&SQLITE_IOCAP_SAFE_APPEND) ){
  4211          /* This block deals with an obscure problem. If the last connection
  4212          ** that wrote to this database was operating in persistent-journal
  4213          ** mode, then the journal file may at this point actually be larger
  4214          ** than Pager.journalOff bytes. If the next thing in the journal
  4215          ** file happens to be a journal-header (written as part of the
  4216          ** previous connection's transaction), and a crash or power-failure 
  4217          ** occurs after nRec is updated but before this connection writes 
  4218          ** anything else to the journal file (or commits/rolls back its 
  4219          ** transaction), then SQLite may become confused when doing the 
  4220          ** hot-journal rollback following recovery. It may roll back all
  4221          ** of this connections data, then proceed to rolling back the old,
  4222          ** out-of-date data that follows it. Database corruption.
  4223          **
  4224          ** To work around this, if the journal file does appear to contain
  4225          ** a valid header following Pager.journalOff, then write a 0x00
  4226          ** byte to the start of it to prevent it from being recognized.
  4227          **
  4228          ** Variable iNextHdrOffset is set to the offset at which this
  4229          ** problematic header will occur, if it exists. aMagic is used 
  4230          ** as a temporary buffer to inspect the first couple of bytes of
  4231          ** the potential journal header.
  4232          */
  4233          i64 iNextHdrOffset;
  4234          u8 aMagic[8];
  4235          u8 zHeader[sizeof(aJournalMagic)+4];
  4236  
  4237          memcpy(zHeader, aJournalMagic, sizeof(aJournalMagic));
  4238          put32bits(&zHeader[sizeof(aJournalMagic)], pPager->nRec);
  4239  
  4240          iNextHdrOffset = journalHdrOffset(pPager);
  4241          rc = sqlite3OsRead(pPager->jfd, aMagic, 8, iNextHdrOffset);
  4242          if( rc==SQLITE_OK && 0==memcmp(aMagic, aJournalMagic, 8) ){
  4243            static const u8 zerobyte = 0;
  4244            rc = sqlite3OsWrite(pPager->jfd, &zerobyte, 1, iNextHdrOffset);
  4245          }
  4246          if( rc!=SQLITE_OK && rc!=SQLITE_IOERR_SHORT_READ ){
  4247            return rc;
  4248          }
  4249  
  4250          /* Write the nRec value into the journal file header. If in
  4251          ** full-synchronous mode, sync the journal first. This ensures that
  4252          ** all data has really hit the disk before nRec is updated to mark
  4253          ** it as a candidate for rollback.
  4254          **
  4255          ** This is not required if the persistent media supports the
  4256          ** SAFE_APPEND property. Because in this case it is not possible 
  4257          ** for garbage data to be appended to the file, the nRec field
  4258          ** is populated with 0xFFFFFFFF when the journal header is written
  4259          ** and never needs to be updated.
  4260          */
  4261          if( pPager->fullSync && 0==(iDc&SQLITE_IOCAP_SEQUENTIAL) ){
  4262            PAGERTRACE(("SYNC journal of %d\n", PAGERID(pPager)));
  4263            IOTRACE(("JSYNC %p\n", pPager))
  4264            rc = sqlite3OsSync(pPager->jfd, pPager->syncFlags);
  4265            if( rc!=SQLITE_OK ) return rc;
  4266          }
  4267          IOTRACE(("JHDR %p %lld\n", pPager, pPager->journalHdr));
  4268          rc = sqlite3OsWrite(
  4269              pPager->jfd, zHeader, sizeof(zHeader), pPager->journalHdr
  4270          );
  4271          if( rc!=SQLITE_OK ) return rc;
  4272        }
  4273        if( 0==(iDc&SQLITE_IOCAP_SEQUENTIAL) ){
  4274          PAGERTRACE(("SYNC journal of %d\n", PAGERID(pPager)));
  4275          IOTRACE(("JSYNC %p\n", pPager))
  4276          rc = sqlite3OsSync(pPager->jfd, pPager->syncFlags| 
  4277            (pPager->syncFlags==SQLITE_SYNC_FULL?SQLITE_SYNC_DATAONLY:0)
  4278          );
  4279          if( rc!=SQLITE_OK ) return rc;
  4280        }
  4281  
  4282        pPager->journalHdr = pPager->journalOff;
  4283        if( newHdr && 0==(iDc&SQLITE_IOCAP_SAFE_APPEND) ){
  4284          pPager->nRec = 0;
  4285          rc = writeJournalHdr(pPager);
  4286          if( rc!=SQLITE_OK ) return rc;
  4287        }
  4288      }else{
  4289        pPager->journalHdr = pPager->journalOff;
  4290      }
  4291    }
  4292  
  4293    /* Unless the pager is in noSync mode, the journal file was just 
  4294    ** successfully synced. Either way, clear the PGHDR_NEED_SYNC flag on 
  4295    ** all pages.
  4296    */
  4297    sqlite3PcacheClearSyncFlags(pPager->pPCache);
  4298    pPager->eState = PAGER_WRITER_DBMOD;
  4299    assert( assert_pager_state(pPager) );
  4300    return SQLITE_OK;
  4301  }
  4302  
  4303  /*
  4304  ** The argument is the first in a linked list of dirty pages connected
  4305  ** by the PgHdr.pDirty pointer. This function writes each one of the
  4306  ** in-memory pages in the list to the database file. The argument may
  4307  ** be NULL, representing an empty list. In this case this function is
  4308  ** a no-op.
  4309  **
  4310  ** The pager must hold at least a RESERVED lock when this function
  4311  ** is called. Before writing anything to the database file, this lock
  4312  ** is upgraded to an EXCLUSIVE lock. If the lock cannot be obtained,
  4313  ** SQLITE_BUSY is returned and no data is written to the database file.
  4314  ** 
  4315  ** If the pager is a temp-file pager and the actual file-system file
  4316  ** is not yet open, it is created and opened before any data is 
  4317  ** written out.
  4318  **
  4319  ** Once the lock has been upgraded and, if necessary, the file opened,
  4320  ** the pages are written out to the database file in list order. Writing
  4321  ** a page is skipped if it meets either of the following criteria:
  4322  **
  4323  **   * The page number is greater than Pager.dbSize, or
  4324  **   * The PGHDR_DONT_WRITE flag is set on the page.
  4325  **
  4326  ** If writing out a page causes the database file to grow, Pager.dbFileSize
  4327  ** is updated accordingly. If page 1 is written out, then the value cached
  4328  ** in Pager.dbFileVers[] is updated to match the new value stored in
  4329  ** the database file.
  4330  **
  4331  ** If everything is successful, SQLITE_OK is returned. If an IO error 
  4332  ** occurs, an IO error code is returned. Or, if the EXCLUSIVE lock cannot
  4333  ** be obtained, SQLITE_BUSY is returned.
  4334  */
  4335  static int pager_write_pagelist(Pager *pPager, PgHdr *pList){
  4336    int rc = SQLITE_OK;                  /* Return code */
  4337  
  4338    /* This function is only called for rollback pagers in WRITER_DBMOD state. */
  4339    assert( !pagerUseWal(pPager) );
  4340    assert( pPager->tempFile || pPager->eState==PAGER_WRITER_DBMOD );
  4341    assert( pPager->eLock==EXCLUSIVE_LOCK );
  4342    assert( isOpen(pPager->fd) || pList->pDirty==0 );
  4343  
  4344    /* If the file is a temp-file has not yet been opened, open it now. It
  4345    ** is not possible for rc to be other than SQLITE_OK if this branch
  4346    ** is taken, as pager_wait_on_lock() is a no-op for temp-files.
  4347    */
  4348    if( !isOpen(pPager->fd) ){
  4349      assert( pPager->tempFile && rc==SQLITE_OK );
  4350      rc = pagerOpentemp(pPager, pPager->fd, pPager->vfsFlags);
  4351    }
  4352  
  4353    /* Before the first write, give the VFS a hint of what the final
  4354    ** file size will be.
  4355    */
  4356    assert( rc!=SQLITE_OK || isOpen(pPager->fd) );
  4357    if( rc==SQLITE_OK 
  4358     && pPager->dbHintSize<pPager->dbSize
  4359     && (pList->pDirty || pList->pgno>pPager->dbHintSize)
  4360    ){
  4361      sqlite3_int64 szFile = pPager->pageSize * (sqlite3_int64)pPager->dbSize;
  4362      sqlite3OsFileControlHint(pPager->fd, SQLITE_FCNTL_SIZE_HINT, &szFile);
  4363      pPager->dbHintSize = pPager->dbSize;
  4364    }
  4365  
  4366    while( rc==SQLITE_OK && pList ){
  4367      Pgno pgno = pList->pgno;
  4368  
  4369      /* If there are dirty pages in the page cache with page numbers greater
  4370      ** than Pager.dbSize, this means sqlite3PagerTruncateImage() was called to
  4371      ** make the file smaller (presumably by auto-vacuum code). Do not write
  4372      ** any such pages to the file.
  4373      **
  4374      ** Also, do not write out any page that has the PGHDR_DONT_WRITE flag
  4375      ** set (set by sqlite3PagerDontWrite()).
  4376      */
  4377      if( pgno<=pPager->dbSize && 0==(pList->flags&PGHDR_DONT_WRITE) ){
  4378        i64 offset = (pgno-1)*(i64)pPager->pageSize;   /* Offset to write */
  4379        char *pData;                                   /* Data to write */    
  4380  
  4381        assert( (pList->flags&PGHDR_NEED_SYNC)==0 );
  4382        if( pList->pgno==1 ) pager_write_changecounter(pList);
  4383  
  4384        pData = pList->pData;
  4385  
  4386        /* Write out the page data. */
  4387        rc = sqlite3OsWrite(pPager->fd, pData, pPager->pageSize, offset);
  4388  
  4389        /* If page 1 was just written, update Pager.dbFileVers to match
  4390        ** the value now stored in the database file. If writing this 
  4391        ** page caused the database file to grow, update dbFileSize. 
  4392        */
  4393        if( pgno==1 ){
  4394          memcpy(&pPager->dbFileVers, &pData[24], sizeof(pPager->dbFileVers));
  4395        }
  4396        if( pgno>pPager->dbFileSize ){
  4397          pPager->dbFileSize = pgno;
  4398        }
  4399        pPager->aStat[PAGER_STAT_WRITE]++;
  4400  
  4401        /* Update any backup objects copying the contents of this pager. */
  4402        sqlite3BackupUpdate(pPager->pBackup, pgno, (u8*)pList->pData);
  4403  
  4404        PAGERTRACE(("STORE %d page %d hash(%08x)\n",
  4405                     PAGERID(pPager), pgno, pager_pagehash(pList)));
  4406        IOTRACE(("PGOUT %p %d\n", pPager, pgno));
  4407        PAGER_INCR(sqlite3_pager_writedb_count);
  4408      }else{
  4409        PAGERTRACE(("NOSTORE %d page %d\n", PAGERID(pPager), pgno));
  4410      }
  4411      pager_set_pagehash(pList);
  4412      pList = pList->pDirty;
  4413    }
  4414  
  4415    return rc;
  4416  }
  4417  
  4418  /*
  4419  ** Ensure that the sub-journal file is open. If it is already open, this 
  4420  ** function is a no-op.
  4421  **
  4422  ** SQLITE_OK is returned if everything goes according to plan. An 
  4423  ** SQLITE_IOERR_XXX error code is returned if a call to sqlite3OsOpen() 
  4424  ** fails.
  4425  */
  4426  static int openSubJournal(Pager *pPager){
  4427    int rc = SQLITE_OK;
  4428    if( !isOpen(pPager->sjfd) ){
  4429      const int flags =  SQLITE_OPEN_SUBJOURNAL | SQLITE_OPEN_READWRITE 
  4430        | SQLITE_OPEN_CREATE | SQLITE_OPEN_EXCLUSIVE 
  4431        | SQLITE_OPEN_DELETEONCLOSE;
  4432      int nStmtSpill = sqlite3Config.nStmtSpill;
  4433      if( pPager->journalMode==PAGER_JOURNALMODE_MEMORY || pPager->subjInMemory ){
  4434        nStmtSpill = -1;
  4435      }
  4436      rc = sqlite3JournalOpen(pPager->pVfs, 0, pPager->sjfd, flags, nStmtSpill);
  4437    }
  4438    return rc;
  4439  }
  4440  
  4441  /*
  4442  ** Append a record of the current state of page pPg to the sub-journal. 
  4443  **
  4444  ** If successful, set the bit corresponding to pPg->pgno in the bitvecs
  4445  ** for all open savepoints before returning.
  4446  **
  4447  ** This function returns SQLITE_OK if everything is successful, an IO
  4448  ** error code if the attempt to write to the sub-journal fails, or 
  4449  ** SQLITE_NOMEM if a malloc fails while setting a bit in a savepoint
  4450  ** bitvec.
  4451  */
  4452  static int subjournalPage(PgHdr *pPg){
  4453    int rc = SQLITE_OK;
  4454    Pager *pPager = pPg->pPager;
  4455    if( pPager->journalMode!=PAGER_JOURNALMODE_OFF ){
  4456  
  4457      /* Open the sub-journal, if it has not already been opened */
  4458      assert( pPager->useJournal );
  4459      assert( isOpen(pPager->jfd) || pagerUseWal(pPager) );
  4460      assert( isOpen(pPager->sjfd) || pPager->nSubRec==0 );
  4461      assert( pagerUseWal(pPager) 
  4462           || pageInJournal(pPager, pPg) 
  4463           || pPg->pgno>pPager->dbOrigSize 
  4464      );
  4465      rc = openSubJournal(pPager);
  4466  
  4467      /* If the sub-journal was opened successfully (or was already open),
  4468      ** write the journal record into the file.  */
  4469      if( rc==SQLITE_OK ){
  4470        void *pData = pPg->pData;
  4471        i64 offset = (i64)pPager->nSubRec*(4+pPager->pageSize);
  4472        char *pData2;
  4473        pData2 = pData;
  4474        PAGERTRACE(("STMT-JOURNAL %d page %d\n", PAGERID(pPager), pPg->pgno));
  4475        rc = write32bits(pPager->sjfd, offset, pPg->pgno);
  4476        if( rc==SQLITE_OK ){
  4477          rc = sqlite3OsWrite(pPager->sjfd, pData2, pPager->pageSize, offset+4);
  4478        }
  4479      }
  4480    }
  4481    if( rc==SQLITE_OK ){
  4482      pPager->nSubRec++;
  4483      assert( pPager->nSavepoint>0 );
  4484      rc = addToSavepointBitvecs(pPager, pPg->pgno);
  4485    }
  4486    return rc;
  4487  }
  4488  static int subjournalPageIfRequired(PgHdr *pPg){
  4489    if( subjRequiresPage(pPg) ){
  4490      return subjournalPage(pPg);
  4491    }else{
  4492      return SQLITE_OK;
  4493    }
  4494  }
  4495  
  4496  /*
  4497  ** This function is called by the pcache layer when it has reached some
  4498  ** soft memory limit. The first argument is a pointer to a Pager object
  4499  ** (cast as a void*). The pager is always 'purgeable' (not an in-memory
  4500  ** database). The second argument is a reference to a page that is 
  4501  ** currently dirty but has no outstanding references. The page
  4502  ** is always associated with the Pager object passed as the first 
  4503  ** argument.
  4504  **
  4505  ** The job of this function is to make pPg clean by writing its contents
  4506  ** out to the database file, if possible. This may involve syncing the
  4507  ** journal file. 
  4508  **
  4509  ** If successful, sqlite3PcacheMakeClean() is called on the page and
  4510  ** SQLITE_OK returned. If an IO error occurs while trying to make the
  4511  ** page clean, the IO error code is returned. If the page cannot be
  4512  ** made clean for some other reason, but no error occurs, then SQLITE_OK
  4513  ** is returned by sqlite3PcacheMakeClean() is not called.
  4514  */
  4515  static int pagerStress(void *p, PgHdr *pPg){
  4516    Pager *pPager = (Pager *)p;
  4517    int rc = SQLITE_OK;
  4518  
  4519    assert( pPg->pPager==pPager );
  4520    assert( pPg->flags&PGHDR_DIRTY );
  4521  
  4522    /* The doNotSpill NOSYNC bit is set during times when doing a sync of
  4523    ** journal (and adding a new header) is not allowed.  This occurs
  4524    ** during calls to sqlite3PagerWrite() while trying to journal multiple
  4525    ** pages belonging to the same sector.
  4526    **
  4527    ** The doNotSpill ROLLBACK and OFF bits inhibits all cache spilling
  4528    ** regardless of whether or not a sync is required.  This is set during
  4529    ** a rollback or by user request, respectively.
  4530    **
  4531    ** Spilling is also prohibited when in an error state since that could
  4532    ** lead to database corruption.   In the current implementation it 
  4533    ** is impossible for sqlite3PcacheFetch() to be called with createFlag==3
  4534    ** while in the error state, hence it is impossible for this routine to
  4535    ** be called in the error state.  Nevertheless, we include a NEVER()
  4536    ** test for the error state as a safeguard against future changes.
  4537    */
  4538    if( NEVER(pPager->errCode) ) return SQLITE_OK;
  4539    testcase( pPager->doNotSpill & SPILLFLAG_ROLLBACK );
  4540    testcase( pPager->doNotSpill & SPILLFLAG_OFF );
  4541    testcase( pPager->doNotSpill & SPILLFLAG_NOSYNC );
  4542    if( pPager->doNotSpill
  4543     && ((pPager->doNotSpill & (SPILLFLAG_ROLLBACK|SPILLFLAG_OFF))!=0
  4544        || (pPg->flags & PGHDR_NEED_SYNC)!=0)
  4545    ){
  4546      return SQLITE_OK;
  4547    }
  4548  
  4549    pPager->aStat[PAGER_STAT_SPILL]++;
  4550    pPg->pDirty = 0;
  4551    if( pagerUseWal(pPager) ){
  4552      /* Write a single frame for this page to the log. */
  4553      rc = subjournalPageIfRequired(pPg); 
  4554      if( rc==SQLITE_OK ){
  4555        rc = pagerWalFrames(pPager, pPg, 0, 0);
  4556      }
  4557    }else{
  4558      
  4559  #ifdef SQLITE_ENABLE_BATCH_ATOMIC_WRITE
  4560      if( pPager->tempFile==0 ){
  4561        rc = sqlite3JournalCreate(pPager->jfd);
  4562        if( rc!=SQLITE_OK ) return pager_error(pPager, rc);
  4563      }
  4564  #endif
  4565    
  4566      /* Sync the journal file if required. */
  4567      if( pPg->flags&PGHDR_NEED_SYNC 
  4568       || pPager->eState==PAGER_WRITER_CACHEMOD
  4569      ){
  4570        rc = syncJournal(pPager, 1);
  4571      }
  4572    
  4573      /* Write the contents of the page out to the database file. */
  4574      if( rc==SQLITE_OK ){
  4575        assert( (pPg->flags&PGHDR_NEED_SYNC)==0 );
  4576        rc = pager_write_pagelist(pPager, pPg);
  4577      }
  4578    }
  4579  
  4580    /* Mark the page as clean. */
  4581    if( rc==SQLITE_OK ){
  4582      PAGERTRACE(("STRESS %d page %d\n", PAGERID(pPager), pPg->pgno));
  4583      sqlite3PcacheMakeClean(pPg);
  4584    }
  4585  
  4586    return pager_error(pPager, rc); 
  4587  }
  4588  
  4589  /*
  4590  ** Flush all unreferenced dirty pages to disk.
  4591  */
  4592  int sqlite3PagerFlush(Pager *pPager){
  4593    int rc = pPager->errCode;
  4594    if( !MEMDB ){
  4595      PgHdr *pList = sqlite3PcacheDirtyList(pPager->pPCache);
  4596      assert( assert_pager_state(pPager) );
  4597      while( rc==SQLITE_OK && pList ){
  4598        PgHdr *pNext = pList->pDirty;
  4599        if( pList->nRef==0 ){
  4600          rc = pagerStress((void*)pPager, pList);
  4601        }
  4602        pList = pNext;
  4603      }
  4604    }
  4605  
  4606    return rc;
  4607  }
  4608  
  4609  /*
  4610  ** Allocate and initialize a new Pager object and put a pointer to it
  4611  ** in *ppPager. The pager should eventually be freed by passing it
  4612  ** to sqlite3PagerClose().
  4613  **
  4614  ** The zFilename argument is the path to the database file to open.
  4615  ** If zFilename is NULL then a randomly-named temporary file is created
  4616  ** and used as the file to be cached. Temporary files are be deleted
  4617  ** automatically when they are closed. If zFilename is ":memory:" then 
  4618  ** all information is held in cache. It is never written to disk. 
  4619  ** This can be used to implement an in-memory database.
  4620  **
  4621  ** The nExtra parameter specifies the number of bytes of space allocated
  4622  ** along with each page reference. This space is available to the user
  4623  ** via the sqlite3PagerGetExtra() API.  When a new page is allocated, the
  4624  ** first 8 bytes of this space are zeroed but the remainder is uninitialized.
  4625  ** (The extra space is used by btree as the MemPage object.)
  4626  **
  4627  ** The flags argument is used to specify properties that affect the
  4628  ** operation of the pager. It should be passed some bitwise combination
  4629  ** of the PAGER_* flags.
  4630  **
  4631  ** The vfsFlags parameter is a bitmask to pass to the flags parameter
  4632  ** of the xOpen() method of the supplied VFS when opening files. 
  4633  **
  4634  ** If the pager object is allocated and the specified file opened 
  4635  ** successfully, SQLITE_OK is returned and *ppPager set to point to
  4636  ** the new pager object. If an error occurs, *ppPager is set to NULL
  4637  ** and error code returned. This function may return SQLITE_NOMEM
  4638  ** (sqlite3Malloc() is used to allocate memory), SQLITE_CANTOPEN or 
  4639  ** various SQLITE_IO_XXX errors.
  4640  */
  4641  int sqlite3PagerOpen(
  4642    sqlite3_vfs *pVfs,       /* The virtual file system to use */
  4643    Pager **ppPager,         /* OUT: Return the Pager structure here */
  4644    const char *zFilename,   /* Name of the database file to open */
  4645    int nExtra,              /* Extra bytes append to each in-memory page */
  4646    int flags,               /* flags controlling this file */
  4647    int vfsFlags,            /* flags passed through to sqlite3_vfs.xOpen() */
  4648    void (*xReinit)(DbPage*) /* Function to reinitialize pages */
  4649  ){
  4650    u8 *pPtr;
  4651    Pager *pPager = 0;       /* Pager object to allocate and return */
  4652    int rc = SQLITE_OK;      /* Return code */
  4653    int tempFile = 0;        /* True for temp files (incl. in-memory files) */
  4654    int memDb = 0;           /* True if this is an in-memory file */
  4655  #ifdef SQLITE_ENABLE_DESERIALIZE
  4656    int memJM = 0;           /* Memory journal mode */
  4657  #else
  4658  # define memJM 0
  4659  #endif
  4660    int readOnly = 0;        /* True if this is a read-only file */
  4661    int journalFileSize;     /* Bytes to allocate for each journal fd */
  4662    char *zPathname = 0;     /* Full path to database file */
  4663    int nPathname = 0;       /* Number of bytes in zPathname */
  4664    int useJournal = (flags & PAGER_OMIT_JOURNAL)==0; /* False to omit journal */
  4665    int pcacheSize = sqlite3PcacheSize();       /* Bytes to allocate for PCache */
  4666    u32 szPageDflt = SQLITE_DEFAULT_PAGE_SIZE;  /* Default page size */
  4667    const char *zUri = 0;    /* URI args to copy */
  4668    int nUriByte = 1;        /* Number of bytes of URI args at *zUri */
  4669    int nUri = 0;            /* Number of URI parameters */
  4670  
  4671    /* Figure out how much space is required for each journal file-handle
  4672    ** (there are two of them, the main journal and the sub-journal).  */
  4673    journalFileSize = ROUND8(sqlite3JournalSize(pVfs));
  4674  
  4675    /* Set the output variable to NULL in case an error occurs. */
  4676    *ppPager = 0;
  4677  
  4678  #ifndef SQLITE_OMIT_MEMORYDB
  4679    if( flags & PAGER_MEMORY ){
  4680      memDb = 1;
  4681      if( zFilename && zFilename[0] ){
  4682        zPathname = sqlite3DbStrDup(0, zFilename);
  4683        if( zPathname==0  ) return SQLITE_NOMEM_BKPT;
  4684        nPathname = sqlite3Strlen30(zPathname);
  4685        zFilename = 0;
  4686      }
  4687    }
  4688  #endif
  4689  
  4690    /* Compute and store the full pathname in an allocated buffer pointed
  4691    ** to by zPathname, length nPathname. Or, if this is a temporary file,
  4692    ** leave both nPathname and zPathname set to 0.
  4693    */
  4694    if( zFilename && zFilename[0] ){
  4695      const char *z;
  4696      nPathname = pVfs->mxPathname+1;
  4697      zPathname = sqlite3DbMallocRaw(0, nPathname*2);
  4698      if( zPathname==0 ){
  4699        return SQLITE_NOMEM_BKPT;
  4700      }
  4701      zPathname[0] = 0; /* Make sure initialized even if FullPathname() fails */
  4702      rc = sqlite3OsFullPathname(pVfs, zFilename, nPathname, zPathname);
  4703      if( rc!=SQLITE_OK ){
  4704        if( rc==SQLITE_OK_SYMLINK ){
  4705          if( vfsFlags & SQLITE_OPEN_NOFOLLOW ){
  4706            rc = SQLITE_CANTOPEN_SYMLINK;
  4707          }else{
  4708            rc = SQLITE_OK;
  4709          }
  4710        }
  4711      }
  4712      nPathname = sqlite3Strlen30(zPathname);
  4713      z = zUri = &zFilename[sqlite3Strlen30(zFilename)+1];
  4714      while( *z ){
  4715        z += strlen(z)+1;
  4716        z += strlen(z)+1;
  4717        nUri++;
  4718      }
  4719      nUriByte = (int)(&z[1] - zUri);
  4720      assert( nUriByte>=1 );
  4721      if( rc==SQLITE_OK && nPathname+8>pVfs->mxPathname ){
  4722        /* This branch is taken when the journal path required by
  4723        ** the database being opened will be more than pVfs->mxPathname
  4724        ** bytes in length. This means the database cannot be opened,
  4725        ** as it will not be possible to open the journal file or even
  4726        ** check for a hot-journal before reading.
  4727        */
  4728        rc = SQLITE_CANTOPEN_BKPT;
  4729      }
  4730      if( rc!=SQLITE_OK ){
  4731        sqlite3DbFree(0, zPathname);
  4732        return rc;
  4733      }
  4734    }
  4735  
  4736    /* Allocate memory for the Pager structure, PCache object, the
  4737    ** three file descriptors, the database file name and the journal 
  4738    ** file name. The layout in memory is as follows:
  4739    **
  4740    **     Pager object                    (sizeof(Pager) bytes)
  4741    **     PCache object                   (sqlite3PcacheSize() bytes)
  4742    **     Database file handle            (pVfs->szOsFile bytes)
  4743    **     Sub-journal file handle         (journalFileSize bytes)
  4744    **     Main journal file handle        (journalFileSize bytes)
  4745    **     \0\0\0\0 database prefix        (4 bytes)
  4746    **     Database file name              (nPathname+1 bytes)
  4747    **     URI query parameters            (nUriByte bytes)
  4748    **     Journal filename                (nPathname+8+1 bytes)
  4749    **     WAL filename                    (nPathname+4+1 bytes)
  4750    **     \0\0\0 terminator               (3 bytes)
  4751    **
  4752    ** Some 3rd-party software, over which we have no control, depends on
  4753    ** the specific order of the filenames and the \0 separators between them
  4754    ** so that it can (for example) find the database filename given the WAL
  4755    ** filename without using the sqlite3_filename_database() API.  This is a
  4756    ** misuse of SQLite and a bug in the 3rd-party software, but the 3rd-party
  4757    ** software is in widespread use, so we try to avoid changing the filename
  4758    ** order and formatting if possible.  In particular, the details of the
  4759    ** filename format expected by 3rd-party software should be as follows:
  4760    **
  4761    **   - Main Database Path
  4762    **   - \0
  4763    **   - Multiple URI components consisting of:
  4764    **     - Key
  4765    **     - \0
  4766    **     - Value
  4767    **     - \0
  4768    **   - \0
  4769    **   - Journal Path
  4770    **   - \0
  4771    **   - WAL Path (zWALName)
  4772    **   - \0
  4773    */
  4774    pPtr = (u8 *)sqlite3MallocZero(
  4775      ROUND8(sizeof(*pPager)) +            /* Pager structure */
  4776      ROUND8(pcacheSize) +                 /* PCache object */
  4777      ROUND8(pVfs->szOsFile) +             /* The main db file */
  4778      journalFileSize * 2 +                /* The two journal files */
  4779      4 +                                  /* Database prefix */
  4780      nPathname + 1 +                      /* database filename */
  4781      nUriByte +                           /* query parameters */
  4782      nPathname + 8 + 1 +                  /* Journal filename */
  4783  #ifndef SQLITE_OMIT_WAL
  4784      nPathname + 4 + 1 +                  /* WAL filename */
  4785  #endif
  4786      3                                    /* Terminator */
  4787    );
  4788    assert( EIGHT_BYTE_ALIGNMENT(SQLITE_INT_TO_PTR(journalFileSize)) );
  4789    if( !pPtr ){
  4790      sqlite3DbFree(0, zPathname);
  4791      return SQLITE_NOMEM_BKPT;
  4792    }
  4793    pPager = (Pager*)pPtr;                  pPtr += ROUND8(sizeof(*pPager));
  4794    pPager->pPCache = (PCache*)pPtr;        pPtr += ROUND8(pcacheSize);
  4795    pPager->fd = (sqlite3_file*)pPtr;       pPtr += ROUND8(pVfs->szOsFile);
  4796    pPager->sjfd = (sqlite3_file*)pPtr;     pPtr += journalFileSize;
  4797    pPager->jfd =  (sqlite3_file*)pPtr;     pPtr += journalFileSize;
  4798    assert( EIGHT_BYTE_ALIGNMENT(pPager->jfd) );
  4799  
  4800    /* Fill in the Pager.zFilename and pPager.zQueryParam fields */
  4801                                            pPtr += 4;  /* Skip zero prefix */
  4802    pPager->zFilename = (char*)pPtr;
  4803    if( nPathname>0 ){
  4804      memcpy(pPtr, zPathname, nPathname);   pPtr += nPathname + 1;
  4805      if( zUri ){
  4806        memcpy(pPtr, zUri, nUriByte);       pPtr += nUriByte;
  4807      }else{
  4808                                            pPtr++;
  4809      }
  4810    }
  4811  
  4812  
  4813    /* Fill in Pager.zJournal */
  4814    if( nPathname>0 ){
  4815      pPager->zJournal = (char*)pPtr;
  4816      memcpy(pPtr, zPathname, nPathname);   pPtr += nPathname;
  4817      memcpy(pPtr, "-journal",8);           pPtr += 8 + 1;
  4818  #ifdef SQLITE_ENABLE_8_3_NAMES
  4819      sqlite3FileSuffix3(zFilename,pPager->zJournal);
  4820      pPtr = (u8*)(pPager->zJournal + sqlite3Strlen30(pPager->zJournal)+1);
  4821  #endif
  4822    }else{
  4823      pPager->zJournal = 0;
  4824    }
  4825  
  4826  #ifndef SQLITE_OMIT_WAL
  4827    /* Fill in Pager.zWal */
  4828    if( nPathname>0 ){
  4829      pPager->zWal = (char*)pPtr;
  4830      memcpy(pPtr, zPathname, nPathname);   pPtr += nPathname;
  4831      memcpy(pPtr, "-wal", 4);              pPtr += 4 + 1;
  4832  #ifdef SQLITE_ENABLE_8_3_NAMES
  4833      sqlite3FileSuffix3(zFilename, pPager->zWal);
  4834      pPtr = (u8*)(pPager->zWal + sqlite3Strlen30(pPager->zWal)+1);
  4835  #endif
  4836    }else{
  4837      pPager->zWal = 0;
  4838    }
  4839  #endif
  4840  
  4841    if( nPathname ) sqlite3DbFree(0, zPathname);
  4842    pPager->pVfs = pVfs;
  4843    pPager->vfsFlags = vfsFlags;
  4844  
  4845    /* Open the pager file.
  4846    */
  4847    if( zFilename && zFilename[0] ){
  4848      int fout = 0;                    /* VFS flags returned by xOpen() */
  4849      rc = sqlite3OsOpen(pVfs, pPager->zFilename, pPager->fd, vfsFlags, &fout);
  4850      assert( !memDb );
  4851  #ifdef SQLITE_ENABLE_DESERIALIZE
  4852      memJM = (fout&SQLITE_OPEN_MEMORY)!=0;
  4853  #endif
  4854      readOnly = (fout&SQLITE_OPEN_READONLY)!=0;
  4855  
  4856      /* If the file was successfully opened for read/write access,
  4857      ** choose a default page size in case we have to create the
  4858      ** database file. The default page size is the maximum of:
  4859      **
  4860      **    + SQLITE_DEFAULT_PAGE_SIZE,
  4861      **    + The value returned by sqlite3OsSectorSize()
  4862      **    + The largest page size that can be written atomically.
  4863      */
  4864      if( rc==SQLITE_OK ){
  4865        int iDc = sqlite3OsDeviceCharacteristics(pPager->fd);
  4866        if( !readOnly ){
  4867          setSectorSize(pPager);
  4868          assert(SQLITE_DEFAULT_PAGE_SIZE<=SQLITE_MAX_DEFAULT_PAGE_SIZE);
  4869          if( szPageDflt<pPager->sectorSize ){
  4870            if( pPager->sectorSize>SQLITE_MAX_DEFAULT_PAGE_SIZE ){
  4871              szPageDflt = SQLITE_MAX_DEFAULT_PAGE_SIZE;
  4872            }else{
  4873              szPageDflt = (u32)pPager->sectorSize;
  4874            }
  4875          }
  4876  #ifdef SQLITE_ENABLE_ATOMIC_WRITE
  4877          {
  4878            int ii;
  4879            assert(SQLITE_IOCAP_ATOMIC512==(512>>8));
  4880            assert(SQLITE_IOCAP_ATOMIC64K==(65536>>8));
  4881            assert(SQLITE_MAX_DEFAULT_PAGE_SIZE<=65536);
  4882            for(ii=szPageDflt; ii<=SQLITE_MAX_DEFAULT_PAGE_SIZE; ii=ii*2){
  4883              if( iDc&(SQLITE_IOCAP_ATOMIC|(ii>>8)) ){
  4884                szPageDflt = ii;
  4885              }
  4886            }
  4887          }
  4888  #endif
  4889        }
  4890        pPager->noLock = sqlite3_uri_boolean(pPager->zFilename, "nolock", 0);
  4891        if( (iDc & SQLITE_IOCAP_IMMUTABLE)!=0
  4892         || sqlite3_uri_boolean(pPager->zFilename, "immutable", 0) ){
  4893            vfsFlags |= SQLITE_OPEN_READONLY;
  4894            goto act_like_temp_file;
  4895        }
  4896      }
  4897    }else{
  4898      /* If a temporary file is requested, it is not opened immediately.
  4899      ** In this case we accept the default page size and delay actually
  4900      ** opening the file until the first call to OsWrite().
  4901      **
  4902      ** This branch is also run for an in-memory database. An in-memory
  4903      ** database is the same as a temp-file that is never written out to
  4904      ** disk and uses an in-memory rollback journal.
  4905      **
  4906      ** This branch also runs for files marked as immutable.
  4907      */ 
  4908  act_like_temp_file:
  4909      tempFile = 1;
  4910      pPager->eState = PAGER_READER;     /* Pretend we already have a lock */
  4911      pPager->eLock = EXCLUSIVE_LOCK;    /* Pretend we are in EXCLUSIVE mode */
  4912      pPager->noLock = 1;                /* Do no locking */
  4913      readOnly = (vfsFlags&SQLITE_OPEN_READONLY);
  4914    }
  4915  
  4916    /* The following call to PagerSetPagesize() serves to set the value of 
  4917    ** Pager.pageSize and to allocate the Pager.pTmpSpace buffer.
  4918    */
  4919    if( rc==SQLITE_OK ){
  4920      assert( pPager->memDb==0 );
  4921      rc = sqlite3PagerSetPagesize(pPager, &szPageDflt, -1);
  4922      testcase( rc!=SQLITE_OK );
  4923    }
  4924  
  4925    /* Initialize the PCache object. */
  4926    if( rc==SQLITE_OK ){
  4927      nExtra = ROUND8(nExtra);
  4928      assert( nExtra>=8 && nExtra<1000 );
  4929      rc = sqlite3PcacheOpen(szPageDflt, nExtra, !memDb,
  4930                         !memDb?pagerStress:0, (void *)pPager, pPager->pPCache);
  4931    }
  4932  
  4933    /* If an error occurred above, free the  Pager structure and close the file.
  4934    */
  4935    if( rc!=SQLITE_OK ){
  4936      sqlite3OsClose(pPager->fd);
  4937      sqlite3PageFree(pPager->pTmpSpace);
  4938      sqlite3_free(pPager);
  4939      return rc;
  4940    }
  4941  
  4942    PAGERTRACE(("OPEN %d %s\n", FILEHANDLEID(pPager->fd), pPager->zFilename));
  4943    IOTRACE(("OPEN %p %s\n", pPager, pPager->zFilename))
  4944  
  4945    pPager->useJournal = (u8)useJournal;
  4946    /* pPager->stmtOpen = 0; */
  4947    /* pPager->stmtInUse = 0; */
  4948    /* pPager->nRef = 0; */
  4949    /* pPager->stmtSize = 0; */
  4950    /* pPager->stmtJSize = 0; */
  4951    /* pPager->nPage = 0; */
  4952    pPager->mxPgno = SQLITE_MAX_PAGE_COUNT;
  4953    /* pPager->state = PAGER_UNLOCK; */
  4954    /* pPager->errMask = 0; */
  4955    pPager->tempFile = (u8)tempFile;
  4956    assert( tempFile==PAGER_LOCKINGMODE_NORMAL 
  4957            || tempFile==PAGER_LOCKINGMODE_EXCLUSIVE );
  4958    assert( PAGER_LOCKINGMODE_EXCLUSIVE==1 );
  4959    pPager->exclusiveMode = (u8)tempFile; 
  4960    pPager->changeCountDone = pPager->tempFile;
  4961    pPager->memDb = (u8)memDb;
  4962    pPager->readOnly = (u8)readOnly;
  4963    assert( useJournal || pPager->tempFile );
  4964    pPager->noSync = pPager->tempFile;
  4965    if( pPager->noSync ){
  4966      assert( pPager->fullSync==0 );
  4967      assert( pPager->extraSync==0 );
  4968      assert( pPager->syncFlags==0 );
  4969      assert( pPager->walSyncFlags==0 );
  4970    }else{
  4971      pPager->fullSync = 1;
  4972      pPager->extraSync = 0;
  4973      pPager->syncFlags = SQLITE_SYNC_NORMAL;
  4974      pPager->walSyncFlags = SQLITE_SYNC_NORMAL | (SQLITE_SYNC_NORMAL<<2);
  4975    }
  4976    /* pPager->pFirst = 0; */
  4977    /* pPager->pFirstSynced = 0; */
  4978    /* pPager->pLast = 0; */
  4979    pPager->nExtra = (u16)nExtra;
  4980    pPager->journalSizeLimit = SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT;
  4981    assert( isOpen(pPager->fd) || tempFile );
  4982    setSectorSize(pPager);
  4983    if( !useJournal ){
  4984      pPager->journalMode = PAGER_JOURNALMODE_OFF;
  4985    }else if( memDb || memJM ){
  4986      pPager->journalMode = PAGER_JOURNALMODE_MEMORY;
  4987    }
  4988    /* pPager->xBusyHandler = 0; */
  4989    /* pPager->pBusyHandlerArg = 0; */
  4990    pPager->xReiniter = xReinit;
  4991    setGetterMethod(pPager);
  4992    /* memset(pPager->aHash, 0, sizeof(pPager->aHash)); */
  4993    /* pPager->szMmap = SQLITE_DEFAULT_MMAP_SIZE // will be set by btree.c */
  4994  
  4995    *ppPager = pPager;
  4996    return SQLITE_OK;
  4997  }
  4998  
  4999  
  5000  
  5001  /*
  5002  ** This function is called after transitioning from PAGER_UNLOCK to
  5003  ** PAGER_SHARED state. It tests if there is a hot journal present in
  5004  ** the file-system for the given pager. A hot journal is one that 
  5005  ** needs to be played back. According to this function, a hot-journal
  5006  ** file exists if the following criteria are met:
  5007  **
  5008  **   * The journal file exists in the file system, and
  5009  **   * No process holds a RESERVED or greater lock on the database file, and
  5010  **   * The database file itself is greater than 0 bytes in size, and
  5011  **   * The first byte of the journal file exists and is not 0x00.
  5012  **
  5013  ** If the current size of the database file is 0 but a journal file
  5014  ** exists, that is probably an old journal left over from a prior
  5015  ** database with the same name. In this case the journal file is
  5016  ** just deleted using OsDelete, *pExists is set to 0 and SQLITE_OK
  5017  ** is returned.
  5018  **
  5019  ** This routine does not check if there is a master journal filename
  5020  ** at the end of the file. If there is, and that master journal file
  5021  ** does not exist, then the journal file is not really hot. In this
  5022  ** case this routine will return a false-positive. The pager_playback()
  5023  ** routine will discover that the journal file is not really hot and 
  5024  ** will not roll it back. 
  5025  **
  5026  ** If a hot-journal file is found to exist, *pExists is set to 1 and 
  5027  ** SQLITE_OK returned. If no hot-journal file is present, *pExists is
  5028  ** set to 0 and SQLITE_OK returned. If an IO error occurs while trying
  5029  ** to determine whether or not a hot-journal file exists, the IO error
  5030  ** code is returned and the value of *pExists is undefined.
  5031  */
  5032  static int hasHotJournal(Pager *pPager, int *pExists){
  5033    sqlite3_vfs * const pVfs = pPager->pVfs;
  5034    int rc = SQLITE_OK;           /* Return code */
  5035    int exists = 1;               /* True if a journal file is present */
  5036    int jrnlOpen = !!isOpen(pPager->jfd);
  5037  
  5038    assert( pPager->useJournal );
  5039    assert( isOpen(pPager->fd) );
  5040    assert( pPager->eState==PAGER_OPEN );
  5041  
  5042    assert( jrnlOpen==0 || ( sqlite3OsDeviceCharacteristics(pPager->jfd) &
  5043      SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
  5044    ));
  5045  
  5046    *pExists = 0;
  5047    if( !jrnlOpen ){
  5048      rc = sqlite3OsAccess(pVfs, pPager->zJournal, SQLITE_ACCESS_EXISTS, &exists);
  5049    }
  5050    if( rc==SQLITE_OK && exists ){
  5051      int locked = 0;             /* True if some process holds a RESERVED lock */
  5052  
  5053      /* Race condition here:  Another process might have been holding the
  5054      ** the RESERVED lock and have a journal open at the sqlite3OsAccess() 
  5055      ** call above, but then delete the journal and drop the lock before
  5056      ** we get to the following sqlite3OsCheckReservedLock() call.  If that
  5057      ** is the case, this routine might think there is a hot journal when
  5058      ** in fact there is none.  This results in a false-positive which will
  5059      ** be dealt with by the playback routine.  Ticket #3883.
  5060      */
  5061      rc = sqlite3OsCheckReservedLock(pPager->fd, &locked);
  5062      if( rc==SQLITE_OK && !locked ){
  5063        Pgno nPage;                 /* Number of pages in database file */
  5064  
  5065        assert( pPager->tempFile==0 );
  5066        rc = pagerPagecount(pPager, &nPage);
  5067        if( rc==SQLITE_OK ){
  5068          /* If the database is zero pages in size, that means that either (1) the
  5069          ** journal is a remnant from a prior database with the same name where
  5070          ** the database file but not the journal was deleted, or (2) the initial
  5071          ** transaction that populates a new database is being rolled back.
  5072          ** In either case, the journal file can be deleted.  However, take care
  5073          ** not to delete the journal file if it is already open due to
  5074          ** journal_mode=PERSIST.
  5075          */
  5076          if( nPage==0 && !jrnlOpen ){
  5077            sqlite3BeginBenignMalloc();
  5078            if( pagerLockDb(pPager, RESERVED_LOCK)==SQLITE_OK ){
  5079              sqlite3OsDelete(pVfs, pPager->zJournal, 0);
  5080              if( !pPager->exclusiveMode ) pagerUnlockDb(pPager, SHARED_LOCK);
  5081            }
  5082            sqlite3EndBenignMalloc();
  5083          }else{
  5084            /* The journal file exists and no other connection has a reserved
  5085            ** or greater lock on the database file. Now check that there is
  5086            ** at least one non-zero bytes at the start of the journal file.
  5087            ** If there is, then we consider this journal to be hot. If not, 
  5088            ** it can be ignored.
  5089            */
  5090            if( !jrnlOpen ){
  5091              int f = SQLITE_OPEN_READONLY|SQLITE_OPEN_MAIN_JOURNAL;
  5092              rc = sqlite3OsOpen(pVfs, pPager->zJournal, pPager->jfd, f, &f);
  5093            }
  5094            if( rc==SQLITE_OK ){
  5095              u8 first = 0;
  5096              rc = sqlite3OsRead(pPager->jfd, (void *)&first, 1, 0);
  5097              if( rc==SQLITE_IOERR_SHORT_READ ){
  5098                rc = SQLITE_OK;
  5099              }
  5100              if( !jrnlOpen ){
  5101                sqlite3OsClose(pPager->jfd);
  5102              }
  5103              *pExists = (first!=0);
  5104            }else if( rc==SQLITE_CANTOPEN ){
  5105              /* If we cannot open the rollback journal file in order to see if
  5106              ** it has a zero header, that might be due to an I/O error, or
  5107              ** it might be due to the race condition described above and in
  5108              ** ticket #3883.  Either way, assume that the journal is hot.
  5109              ** This might be a false positive.  But if it is, then the
  5110              ** automatic journal playback and recovery mechanism will deal
  5111              ** with it under an EXCLUSIVE lock where we do not need to
  5112              ** worry so much with race conditions.
  5113              */
  5114              *pExists = 1;
  5115              rc = SQLITE_OK;
  5116            }
  5117          }
  5118        }
  5119      }
  5120    }
  5121  
  5122    return rc;
  5123  }
  5124  
  5125  /*
  5126  ** This function is called to obtain a shared lock on the database file.
  5127  ** It is illegal to call sqlite3PagerGet() until after this function
  5128  ** has been successfully called. If a shared-lock is already held when
  5129  ** this function is called, it is a no-op.
  5130  **
  5131  ** The following operations are also performed by this function.
  5132  **
  5133  **   1) If the pager is currently in PAGER_OPEN state (no lock held
  5134  **      on the database file), then an attempt is made to obtain a
  5135  **      SHARED lock on the database file. Immediately after obtaining
  5136  **      the SHARED lock, the file-system is checked for a hot-journal,
  5137  **      which is played back if present. Following any hot-journal 
  5138  **      rollback, the contents of the cache are validated by checking
  5139  **      the 'change-counter' field of the database file header and
  5140  **      discarded if they are found to be invalid.
  5141  **
  5142  **   2) If the pager is running in exclusive-mode, and there are currently
  5143  **      no outstanding references to any pages, and is in the error state,
  5144  **      then an attempt is made to clear the error state by discarding
  5145  **      the contents of the page cache and rolling back any open journal
  5146  **      file.
  5147  **
  5148  ** If everything is successful, SQLITE_OK is returned. If an IO error 
  5149  ** occurs while locking the database, checking for a hot-journal file or 
  5150  ** rolling back a journal file, the IO error code is returned.
  5151  */
  5152  int sqlite3PagerSharedLock(Pager *pPager){
  5153    int rc = SQLITE_OK;                /* Return code */
  5154  
  5155    /* This routine is only called from b-tree and only when there are no
  5156    ** outstanding pages. This implies that the pager state should either
  5157    ** be OPEN or READER. READER is only possible if the pager is or was in 
  5158    ** exclusive access mode.  */
  5159    assert( sqlite3PcacheRefCount(pPager->pPCache)==0 );
  5160    assert( assert_pager_state(pPager) );
  5161    assert( pPager->eState==PAGER_OPEN || pPager->eState==PAGER_READER );
  5162    assert( pPager->errCode==SQLITE_OK );
  5163  
  5164    if( !pagerUseWal(pPager) && pPager->eState==PAGER_OPEN ){
  5165      int bHotJournal = 1;          /* True if there exists a hot journal-file */
  5166  
  5167      assert( !MEMDB );
  5168      assert( pPager->tempFile==0 || pPager->eLock==EXCLUSIVE_LOCK );
  5169  
  5170      rc = pager_wait_on_lock(pPager, SHARED_LOCK);
  5171      if( rc!=SQLITE_OK ){
  5172        assert( pPager->eLock==NO_LOCK || pPager->eLock==UNKNOWN_LOCK );
  5173        goto failed;
  5174      }
  5175  
  5176      /* If a journal file exists, and there is no RESERVED lock on the
  5177      ** database file, then it either needs to be played back or deleted.
  5178      */
  5179      if( pPager->eLock<=SHARED_LOCK ){
  5180        rc = hasHotJournal(pPager, &bHotJournal);
  5181      }
  5182      if( rc!=SQLITE_OK ){
  5183        goto failed;
  5184      }
  5185      if( bHotJournal ){
  5186        if( pPager->readOnly ){
  5187          rc = SQLITE_READONLY_ROLLBACK;
  5188          goto failed;
  5189        }
  5190  
  5191        /* Get an EXCLUSIVE lock on the database file. At this point it is
  5192        ** important that a RESERVED lock is not obtained on the way to the
  5193        ** EXCLUSIVE lock. If it were, another process might open the
  5194        ** database file, detect the RESERVED lock, and conclude that the
  5195        ** database is safe to read while this process is still rolling the 
  5196        ** hot-journal back.
  5197        ** 
  5198        ** Because the intermediate RESERVED lock is not requested, any
  5199        ** other process attempting to access the database file will get to 
  5200        ** this point in the code and fail to obtain its own EXCLUSIVE lock 
  5201        ** on the database file.
  5202        **
  5203        ** Unless the pager is in locking_mode=exclusive mode, the lock is
  5204        ** downgraded to SHARED_LOCK before this function returns.
  5205        */
  5206        rc = pagerLockDb(pPager, EXCLUSIVE_LOCK);
  5207        if( rc!=SQLITE_OK ){
  5208          goto failed;
  5209        }
  5210   
  5211        /* If it is not already open and the file exists on disk, open the 
  5212        ** journal for read/write access. Write access is required because 
  5213        ** in exclusive-access mode the file descriptor will be kept open 
  5214        ** and possibly used for a transaction later on. Also, write-access 
  5215        ** is usually required to finalize the journal in journal_mode=persist 
  5216        ** mode (and also for journal_mode=truncate on some systems).
  5217        **
  5218        ** If the journal does not exist, it usually means that some 
  5219        ** other connection managed to get in and roll it back before 
  5220        ** this connection obtained the exclusive lock above. Or, it 
  5221        ** may mean that the pager was in the error-state when this
  5222        ** function was called and the journal file does not exist.
  5223        */
  5224        if( !isOpen(pPager->jfd) ){
  5225          sqlite3_vfs * const pVfs = pPager->pVfs;
  5226          int bExists;              /* True if journal file exists */
  5227          rc = sqlite3OsAccess(
  5228              pVfs, pPager->zJournal, SQLITE_ACCESS_EXISTS, &bExists);
  5229          if( rc==SQLITE_OK && bExists ){
  5230            int fout = 0;
  5231            int f = SQLITE_OPEN_READWRITE|SQLITE_OPEN_MAIN_JOURNAL;
  5232            assert( !pPager->tempFile );
  5233            rc = sqlite3OsOpen(pVfs, pPager->zJournal, pPager->jfd, f, &fout);
  5234            assert( rc!=SQLITE_OK || isOpen(pPager->jfd) );
  5235            if( rc==SQLITE_OK && fout&SQLITE_OPEN_READONLY ){
  5236              rc = SQLITE_CANTOPEN_BKPT;
  5237              sqlite3OsClose(pPager->jfd);
  5238            }
  5239          }
  5240        }
  5241   
  5242        /* Playback and delete the journal.  Drop the database write
  5243        ** lock and reacquire the read lock. Purge the cache before
  5244        ** playing back the hot-journal so that we don't end up with
  5245        ** an inconsistent cache.  Sync the hot journal before playing
  5246        ** it back since the process that crashed and left the hot journal
  5247        ** probably did not sync it and we are required to always sync
  5248        ** the journal before playing it back.
  5249        */
  5250        if( isOpen(pPager->jfd) ){
  5251          assert( rc==SQLITE_OK );
  5252          rc = pagerSyncHotJournal(pPager);
  5253          if( rc==SQLITE_OK ){
  5254            rc = pager_playback(pPager, !pPager->tempFile);
  5255            pPager->eState = PAGER_OPEN;
  5256          }
  5257        }else if( !pPager->exclusiveMode ){
  5258          pagerUnlockDb(pPager, SHARED_LOCK);
  5259        }
  5260  
  5261        if( rc!=SQLITE_OK ){
  5262          /* This branch is taken if an error occurs while trying to open
  5263          ** or roll back a hot-journal while holding an EXCLUSIVE lock. The
  5264          ** pager_unlock() routine will be called before returning to unlock
  5265          ** the file. If the unlock attempt fails, then Pager.eLock must be
  5266          ** set to UNKNOWN_LOCK (see the comment above the #define for 
  5267          ** UNKNOWN_LOCK above for an explanation). 
  5268          **
  5269          ** In order to get pager_unlock() to do this, set Pager.eState to
  5270          ** PAGER_ERROR now. This is not actually counted as a transition
  5271          ** to ERROR state in the state diagram at the top of this file,
  5272          ** since we know that the same call to pager_unlock() will very
  5273          ** shortly transition the pager object to the OPEN state. Calling
  5274          ** assert_pager_state() would fail now, as it should not be possible
  5275          ** to be in ERROR state when there are zero outstanding page 
  5276          ** references.
  5277          */
  5278          pager_error(pPager, rc);
  5279          goto failed;
  5280        }
  5281  
  5282        assert( pPager->eState==PAGER_OPEN );
  5283        assert( (pPager->eLock==SHARED_LOCK)
  5284             || (pPager->exclusiveMode && pPager->eLock>SHARED_LOCK)
  5285        );
  5286      }
  5287  
  5288      if( !pPager->tempFile && pPager->hasHeldSharedLock ){
  5289        /* The shared-lock has just been acquired then check to
  5290        ** see if the database has been modified.  If the database has changed,
  5291        ** flush the cache.  The hasHeldSharedLock flag prevents this from
  5292        ** occurring on the very first access to a file, in order to save a
  5293        ** single unnecessary sqlite3OsRead() call at the start-up.
  5294        **
  5295        ** Database changes are detected by looking at 15 bytes beginning
  5296        ** at offset 24 into the file.  The first 4 of these 16 bytes are
  5297        ** a 32-bit counter that is incremented with each change.  The
  5298        ** other bytes change randomly with each file change when
  5299        ** a codec is in use.
  5300        ** 
  5301        ** There is a vanishingly small chance that a change will not be 
  5302        ** detected.  The chance of an undetected change is so small that
  5303        ** it can be neglected.
  5304        */
  5305        char dbFileVers[sizeof(pPager->dbFileVers)];
  5306  
  5307        IOTRACE(("CKVERS %p %d\n", pPager, sizeof(dbFileVers)));
  5308        rc = sqlite3OsRead(pPager->fd, &dbFileVers, sizeof(dbFileVers), 24);
  5309        if( rc!=SQLITE_OK ){
  5310          if( rc!=SQLITE_IOERR_SHORT_READ ){
  5311            goto failed;
  5312          }
  5313          memset(dbFileVers, 0, sizeof(dbFileVers));
  5314        }
  5315  
  5316        if( memcmp(pPager->dbFileVers, dbFileVers, sizeof(dbFileVers))!=0 ){
  5317          pager_reset(pPager);
  5318  
  5319          /* Unmap the database file. It is possible that external processes
  5320          ** may have truncated the database file and then extended it back
  5321          ** to its original size while this process was not holding a lock.
  5322          ** In this case there may exist a Pager.pMap mapping that appears
  5323          ** to be the right size but is not actually valid. Avoid this
  5324          ** possibility by unmapping the db here. */
  5325          if( USEFETCH(pPager) ){
  5326            sqlite3OsUnfetch(pPager->fd, 0, 0);
  5327          }
  5328        }
  5329      }
  5330  
  5331      /* If there is a WAL file in the file-system, open this database in WAL
  5332      ** mode. Otherwise, the following function call is a no-op.
  5333      */
  5334      rc = pagerOpenWalIfPresent(pPager);
  5335  #ifndef SQLITE_OMIT_WAL
  5336      assert( pPager->pWal==0 || rc==SQLITE_OK );
  5337  #endif
  5338    }
  5339  
  5340    if( pagerUseWal(pPager) ){
  5341      assert( rc==SQLITE_OK );
  5342      rc = pagerBeginReadTransaction(pPager);
  5343    }
  5344  
  5345    if( pPager->tempFile==0 && pPager->eState==PAGER_OPEN && rc==SQLITE_OK ){
  5346      rc = pagerPagecount(pPager, &pPager->dbSize);
  5347    }
  5348  
  5349   failed:
  5350    if( rc!=SQLITE_OK ){
  5351      assert( !MEMDB );
  5352      pager_unlock(pPager);
  5353      assert( pPager->eState==PAGER_OPEN );
  5354    }else{
  5355      pPager->eState = PAGER_READER;
  5356      pPager->hasHeldSharedLock = 1;
  5357    }
  5358    return rc;
  5359  }
  5360  
  5361  /*
  5362  ** If the reference count has reached zero, rollback any active
  5363  ** transaction and unlock the pager.
  5364  **
  5365  ** Except, in locking_mode=EXCLUSIVE when there is nothing to in
  5366  ** the rollback journal, the unlock is not performed and there is
  5367  ** nothing to rollback, so this routine is a no-op.
  5368  */ 
  5369  static void pagerUnlockIfUnused(Pager *pPager){
  5370    if( sqlite3PcacheRefCount(pPager->pPCache)==0 ){
  5371      assert( pPager->nMmapOut==0 ); /* because page1 is never memory mapped */
  5372      pagerUnlockAndRollback(pPager);
  5373    }
  5374  }
  5375  
  5376  /*
  5377  ** The page getter methods each try to acquire a reference to a
  5378  ** page with page number pgno. If the requested reference is 
  5379  ** successfully obtained, it is copied to *ppPage and SQLITE_OK returned.
  5380  **
  5381  ** There are different implementations of the getter method depending
  5382  ** on the current state of the pager.
  5383  **
  5384  **     getPageNormal()         --  The normal getter
  5385  **     getPageError()          --  Used if the pager is in an error state
  5386  **     getPageMmap()           --  Used if memory-mapped I/O is enabled
  5387  **
  5388  ** If the requested page is already in the cache, it is returned. 
  5389  ** Otherwise, a new page object is allocated and populated with data
  5390  ** read from the database file. In some cases, the pcache module may
  5391  ** choose not to allocate a new page object and may reuse an existing
  5392  ** object with no outstanding references.
  5393  **
  5394  ** The extra data appended to a page is always initialized to zeros the 
  5395  ** first time a page is loaded into memory. If the page requested is 
  5396  ** already in the cache when this function is called, then the extra
  5397  ** data is left as it was when the page object was last used.
  5398  **
  5399  ** If the database image is smaller than the requested page or if 
  5400  ** the flags parameter contains the PAGER_GET_NOCONTENT bit and the 
  5401  ** requested page is not already stored in the cache, then no 
  5402  ** actual disk read occurs. In this case the memory image of the 
  5403  ** page is initialized to all zeros. 
  5404  **
  5405  ** If PAGER_GET_NOCONTENT is true, it means that we do not care about
  5406  ** the contents of the page. This occurs in two scenarios:
  5407  **
  5408  **   a) When reading a free-list leaf page from the database, and
  5409  **
  5410  **   b) When a savepoint is being rolled back and we need to load
  5411  **      a new page into the cache to be filled with the data read
  5412  **      from the savepoint journal.
  5413  **
  5414  ** If PAGER_GET_NOCONTENT is true, then the data returned is zeroed instead
  5415  ** of being read from the database. Additionally, the bits corresponding
  5416  ** to pgno in Pager.pInJournal (bitvec of pages already written to the
  5417  ** journal file) and the PagerSavepoint.pInSavepoint bitvecs of any open
  5418  ** savepoints are set. This means if the page is made writable at any
  5419  ** point in the future, using a call to sqlite3PagerWrite(), its contents
  5420  ** will not be journaled. This saves IO.
  5421  **
  5422  ** The acquisition might fail for several reasons.  In all cases,
  5423  ** an appropriate error code is returned and *ppPage is set to NULL.
  5424  **
  5425  ** See also sqlite3PagerLookup().  Both this routine and Lookup() attempt
  5426  ** to find a page in the in-memory cache first.  If the page is not already
  5427  ** in memory, this routine goes to disk to read it in whereas Lookup()
  5428  ** just returns 0.  This routine acquires a read-lock the first time it
  5429  ** has to go to disk, and could also playback an old journal if necessary.
  5430  ** Since Lookup() never goes to disk, it never has to deal with locks
  5431  ** or journal files.
  5432  */
  5433  static int getPageNormal(
  5434    Pager *pPager,      /* The pager open on the database file */
  5435    Pgno pgno,          /* Page number to fetch */
  5436    DbPage **ppPage,    /* Write a pointer to the page here */
  5437    int flags           /* PAGER_GET_XXX flags */
  5438  ){
  5439    int rc = SQLITE_OK;
  5440    PgHdr *pPg;
  5441    u8 noContent;                   /* True if PAGER_GET_NOCONTENT is set */
  5442    sqlite3_pcache_page *pBase;
  5443  
  5444    assert( pPager->errCode==SQLITE_OK );
  5445    assert( pPager->eState>=PAGER_READER );
  5446    assert( assert_pager_state(pPager) );
  5447    assert( pPager->hasHeldSharedLock==1 );
  5448  
  5449    if( pgno==0 ) return SQLITE_CORRUPT_BKPT;
  5450    pBase = sqlite3PcacheFetch(pPager->pPCache, pgno, 3);
  5451    if( pBase==0 ){
  5452      pPg = 0;
  5453      rc = sqlite3PcacheFetchStress(pPager->pPCache, pgno, &pBase);
  5454      if( rc!=SQLITE_OK ) goto pager_acquire_err;
  5455      if( pBase==0 ){
  5456        rc = SQLITE_NOMEM_BKPT;
  5457        goto pager_acquire_err;
  5458      }
  5459    }
  5460    pPg = *ppPage = sqlite3PcacheFetchFinish(pPager->pPCache, pgno, pBase);
  5461    assert( pPg==(*ppPage) );
  5462    assert( pPg->pgno==pgno );
  5463    assert( pPg->pPager==pPager || pPg->pPager==0 );
  5464  
  5465    noContent = (flags & PAGER_GET_NOCONTENT)!=0;
  5466    if( pPg->pPager && !noContent ){
  5467      /* In this case the pcache already contains an initialized copy of
  5468      ** the page. Return without further ado.  */
  5469      assert( pgno<=PAGER_MAX_PGNO && pgno!=PAGER_MJ_PGNO(pPager) );
  5470      pPager->aStat[PAGER_STAT_HIT]++;
  5471      return SQLITE_OK;
  5472  
  5473    }else{
  5474      /* The pager cache has created a new page. Its content needs to 
  5475      ** be initialized. But first some error checks:
  5476      **
  5477      ** (1) The maximum page number is 2^31
  5478      ** (2) Never try to fetch the locking page
  5479      */
  5480      if( pgno>PAGER_MAX_PGNO || pgno==PAGER_MJ_PGNO(pPager) ){
  5481        rc = SQLITE_CORRUPT_BKPT;
  5482        goto pager_acquire_err;
  5483      }
  5484  
  5485      pPg->pPager = pPager;
  5486  
  5487      assert( !isOpen(pPager->fd) || !MEMDB );
  5488      if( !isOpen(pPager->fd) || pPager->dbSize<pgno || noContent ){
  5489        if( pgno>pPager->mxPgno ){
  5490          rc = SQLITE_FULL;
  5491          goto pager_acquire_err;
  5492        }
  5493        if( noContent ){
  5494          /* Failure to set the bits in the InJournal bit-vectors is benign.
  5495          ** It merely means that we might do some extra work to journal a 
  5496          ** page that does not need to be journaled.  Nevertheless, be sure 
  5497          ** to test the case where a malloc error occurs while trying to set 
  5498          ** a bit in a bit vector.
  5499          */
  5500          sqlite3BeginBenignMalloc();
  5501          if( pgno<=pPager->dbOrigSize ){
  5502            TESTONLY( rc = ) sqlite3BitvecSet(pPager->pInJournal, pgno);
  5503            testcase( rc==SQLITE_NOMEM );
  5504          }
  5505          TESTONLY( rc = ) addToSavepointBitvecs(pPager, pgno);
  5506          testcase( rc==SQLITE_NOMEM );
  5507          sqlite3EndBenignMalloc();
  5508        }
  5509        memset(pPg->pData, 0, pPager->pageSize);
  5510        IOTRACE(("ZERO %p %d\n", pPager, pgno));
  5511      }else{
  5512        assert( pPg->pPager==pPager );
  5513        pPager->aStat[PAGER_STAT_MISS]++;
  5514        rc = readDbPage(pPg);
  5515        if( rc!=SQLITE_OK ){
  5516          goto pager_acquire_err;
  5517        }
  5518      }
  5519      pager_set_pagehash(pPg);
  5520    }
  5521    return SQLITE_OK;
  5522  
  5523  pager_acquire_err:
  5524    assert( rc!=SQLITE_OK );
  5525    if( pPg ){
  5526      sqlite3PcacheDrop(pPg);
  5527    }
  5528    pagerUnlockIfUnused(pPager);
  5529    *ppPage = 0;
  5530    return rc;
  5531  }
  5532  
  5533  #if SQLITE_MAX_MMAP_SIZE>0
  5534  /* The page getter for when memory-mapped I/O is enabled */
  5535  static int getPageMMap(
  5536    Pager *pPager,      /* The pager open on the database file */
  5537    Pgno pgno,          /* Page number to fetch */
  5538    DbPage **ppPage,    /* Write a pointer to the page here */
  5539    int flags           /* PAGER_GET_XXX flags */
  5540  ){
  5541    int rc = SQLITE_OK;
  5542    PgHdr *pPg = 0;
  5543    u32 iFrame = 0;                 /* Frame to read from WAL file */
  5544  
  5545    /* It is acceptable to use a read-only (mmap) page for any page except
  5546    ** page 1 if there is no write-transaction open or the ACQUIRE_READONLY
  5547    ** flag was specified by the caller. And so long as the db is not a 
  5548    ** temporary or in-memory database.  */
  5549    const int bMmapOk = (pgno>1
  5550     && (pPager->eState==PAGER_READER || (flags & PAGER_GET_READONLY))
  5551    );
  5552  
  5553    assert( USEFETCH(pPager) );
  5554  
  5555    /* Optimization note:  Adding the "pgno<=1" term before "pgno==0" here
  5556    ** allows the compiler optimizer to reuse the results of the "pgno>1"
  5557    ** test in the previous statement, and avoid testing pgno==0 in the
  5558    ** common case where pgno is large. */
  5559    if( pgno<=1 && pgno==0 ){
  5560      return SQLITE_CORRUPT_BKPT;
  5561    }
  5562    assert( pPager->eState>=PAGER_READER );
  5563    assert( assert_pager_state(pPager) );
  5564    assert( pPager->hasHeldSharedLock==1 );
  5565    assert( pPager->errCode==SQLITE_OK );
  5566  
  5567    if( bMmapOk && pagerUseWal(pPager) ){
  5568      rc = sqlite3WalFindFrame(pPager->pWal, pgno, &iFrame);
  5569      if( rc!=SQLITE_OK ){
  5570        *ppPage = 0;
  5571        return rc;
  5572      }
  5573    }
  5574    if( bMmapOk && iFrame==0 ){
  5575      void *pData = 0;
  5576      rc = sqlite3OsFetch(pPager->fd, 
  5577          (i64)(pgno-1) * pPager->pageSize, pPager->pageSize, &pData
  5578      );
  5579      if( rc==SQLITE_OK && pData ){
  5580        if( pPager->eState>PAGER_READER || pPager->tempFile ){
  5581          pPg = sqlite3PagerLookup(pPager, pgno);
  5582        }
  5583        if( pPg==0 ){
  5584          rc = pagerAcquireMapPage(pPager, pgno, pData, &pPg);
  5585        }else{
  5586          sqlite3OsUnfetch(pPager->fd, (i64)(pgno-1)*pPager->pageSize, pData);
  5587        }
  5588        if( pPg ){
  5589          assert( rc==SQLITE_OK );
  5590          *ppPage = pPg;
  5591          return SQLITE_OK;
  5592        }
  5593      }
  5594      if( rc!=SQLITE_OK ){
  5595        *ppPage = 0;
  5596        return rc;
  5597      }
  5598    }
  5599    return getPageNormal(pPager, pgno, ppPage, flags);
  5600  }
  5601  #endif /* SQLITE_MAX_MMAP_SIZE>0 */
  5602  
  5603  /* The page getter method for when the pager is an error state */
  5604  static int getPageError(
  5605    Pager *pPager,      /* The pager open on the database file */
  5606    Pgno pgno,          /* Page number to fetch */
  5607    DbPage **ppPage,    /* Write a pointer to the page here */
  5608    int flags           /* PAGER_GET_XXX flags */
  5609  ){
  5610    UNUSED_PARAMETER(pgno);
  5611    UNUSED_PARAMETER(flags);
  5612    assert( pPager->errCode!=SQLITE_OK );
  5613    *ppPage = 0;
  5614    return pPager->errCode;
  5615  }
  5616  
  5617  
  5618  /* Dispatch all page fetch requests to the appropriate getter method.
  5619  */
  5620  int sqlite3PagerGet(
  5621    Pager *pPager,      /* The pager open on the database file */
  5622    Pgno pgno,          /* Page number to fetch */
  5623    DbPage **ppPage,    /* Write a pointer to the page here */
  5624    int flags           /* PAGER_GET_XXX flags */
  5625  ){
  5626    return pPager->xGet(pPager, pgno, ppPage, flags);
  5627  }
  5628  
  5629  /*
  5630  ** Acquire a page if it is already in the in-memory cache.  Do
  5631  ** not read the page from disk.  Return a pointer to the page,
  5632  ** or 0 if the page is not in cache. 
  5633  **
  5634  ** See also sqlite3PagerGet().  The difference between this routine
  5635  ** and sqlite3PagerGet() is that _get() will go to the disk and read
  5636  ** in the page if the page is not already in cache.  This routine
  5637  ** returns NULL if the page is not in cache or if a disk I/O error 
  5638  ** has ever happened.
  5639  */
  5640  DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno){
  5641    sqlite3_pcache_page *pPage;
  5642    assert( pPager!=0 );
  5643    assert( pgno!=0 );
  5644    assert( pPager->pPCache!=0 );
  5645    pPage = sqlite3PcacheFetch(pPager->pPCache, pgno, 0);
  5646    assert( pPage==0 || pPager->hasHeldSharedLock );
  5647    if( pPage==0 ) return 0;
  5648    return sqlite3PcacheFetchFinish(pPager->pPCache, pgno, pPage);
  5649  }
  5650  
  5651  /*
  5652  ** Release a page reference.
  5653  **
  5654  ** The sqlite3PagerUnref() and sqlite3PagerUnrefNotNull() may only be
  5655  ** used if we know that the page being released is not the last page.
  5656  ** The btree layer always holds page1 open until the end, so these first
  5657  ** to routines can be used to release any page other than BtShared.pPage1.
  5658  **
  5659  ** Use sqlite3PagerUnrefPageOne() to release page1.  This latter routine
  5660  ** checks the total number of outstanding pages and if the number of
  5661  ** pages reaches zero it drops the database lock.
  5662  */
  5663  void sqlite3PagerUnrefNotNull(DbPage *pPg){
  5664    TESTONLY( Pager *pPager = pPg->pPager; )
  5665    assert( pPg!=0 );
  5666    if( pPg->flags & PGHDR_MMAP ){
  5667      assert( pPg->pgno!=1 );  /* Page1 is never memory mapped */
  5668      pagerReleaseMapPage(pPg);
  5669    }else{
  5670      sqlite3PcacheRelease(pPg);
  5671    }
  5672    /* Do not use this routine to release the last reference to page1 */
  5673    assert( sqlite3PcacheRefCount(pPager->pPCache)>0 );
  5674  }
  5675  void sqlite3PagerUnref(DbPage *pPg){
  5676    if( pPg ) sqlite3PagerUnrefNotNull(pPg);
  5677  }
  5678  void sqlite3PagerUnrefPageOne(DbPage *pPg){
  5679    Pager *pPager;
  5680    assert( pPg!=0 );
  5681    assert( pPg->pgno==1 );
  5682    assert( (pPg->flags & PGHDR_MMAP)==0 ); /* Page1 is never memory mapped */
  5683    pPager = pPg->pPager;
  5684    sqlite3PagerResetLockTimeout(pPager);
  5685    sqlite3PcacheRelease(pPg);
  5686    pagerUnlockIfUnused(pPager);
  5687  }
  5688  
  5689  /*
  5690  ** This function is called at the start of every write transaction.
  5691  ** There must already be a RESERVED or EXCLUSIVE lock on the database 
  5692  ** file when this routine is called.
  5693  **
  5694  ** Open the journal file for pager pPager and write a journal header
  5695  ** to the start of it. If there are active savepoints, open the sub-journal
  5696  ** as well. This function is only used when the journal file is being 
  5697  ** opened to write a rollback log for a transaction. It is not used 
  5698  ** when opening a hot journal file to roll it back.
  5699  **
  5700  ** If the journal file is already open (as it may be in exclusive mode),
  5701  ** then this function just writes a journal header to the start of the
  5702  ** already open file. 
  5703  **
  5704  ** Whether or not the journal file is opened by this function, the
  5705  ** Pager.pInJournal bitvec structure is allocated.
  5706  **
  5707  ** Return SQLITE_OK if everything is successful. Otherwise, return 
  5708  ** SQLITE_NOMEM if the attempt to allocate Pager.pInJournal fails, or 
  5709  ** an IO error code if opening or writing the journal file fails.
  5710  */
  5711  static int pager_open_journal(Pager *pPager){
  5712    int rc = SQLITE_OK;                        /* Return code */
  5713    sqlite3_vfs * const pVfs = pPager->pVfs;   /* Local cache of vfs pointer */
  5714  
  5715    assert( pPager->eState==PAGER_WRITER_LOCKED );
  5716    assert( assert_pager_state(pPager) );
  5717    assert( pPager->pInJournal==0 );
  5718    
  5719    /* If already in the error state, this function is a no-op.  But on
  5720    ** the other hand, this routine is never called if we are already in
  5721    ** an error state. */
  5722    if( NEVER(pPager->errCode) ) return pPager->errCode;
  5723  
  5724    if( !pagerUseWal(pPager) && pPager->journalMode!=PAGER_JOURNALMODE_OFF ){
  5725      pPager->pInJournal = sqlite3BitvecCreate(pPager->dbSize);
  5726      if( pPager->pInJournal==0 ){
  5727        return SQLITE_NOMEM_BKPT;
  5728      }
  5729    
  5730      /* Open the journal file if it is not already open. */
  5731      if( !isOpen(pPager->jfd) ){
  5732        if( pPager->journalMode==PAGER_JOURNALMODE_MEMORY ){
  5733          sqlite3MemJournalOpen(pPager->jfd);
  5734        }else{
  5735          int flags = SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE;
  5736          int nSpill;
  5737  
  5738          if( pPager->tempFile ){
  5739            flags |= (SQLITE_OPEN_DELETEONCLOSE|SQLITE_OPEN_TEMP_JOURNAL);
  5740            nSpill = sqlite3Config.nStmtSpill;
  5741          }else{
  5742            flags |= SQLITE_OPEN_MAIN_JOURNAL;
  5743            nSpill = jrnlBufferSize(pPager);
  5744          }
  5745            
  5746          /* Verify that the database still has the same name as it did when
  5747          ** it was originally opened. */
  5748          rc = databaseIsUnmoved(pPager);
  5749          if( rc==SQLITE_OK ){
  5750            rc = sqlite3JournalOpen (
  5751                pVfs, pPager->zJournal, pPager->jfd, flags, nSpill
  5752            );
  5753          }
  5754        }
  5755        assert( rc!=SQLITE_OK || isOpen(pPager->jfd) );
  5756      }
  5757    
  5758    
  5759      /* Write the first journal header to the journal file and open 
  5760      ** the sub-journal if necessary.
  5761      */
  5762      if( rc==SQLITE_OK ){
  5763        /* TODO: Check if all of these are really required. */
  5764        pPager->nRec = 0;
  5765        pPager->journalOff = 0;
  5766        pPager->setMaster = 0;
  5767        pPager->journalHdr = 0;
  5768        rc = writeJournalHdr(pPager);
  5769      }
  5770    }
  5771  
  5772    if( rc!=SQLITE_OK ){
  5773      sqlite3BitvecDestroy(pPager->pInJournal);
  5774      pPager->pInJournal = 0;
  5775    }else{
  5776      assert( pPager->eState==PAGER_WRITER_LOCKED );
  5777      pPager->eState = PAGER_WRITER_CACHEMOD;
  5778    }
  5779  
  5780    return rc;
  5781  }
  5782  
  5783  /*
  5784  ** Begin a write-transaction on the specified pager object. If a 
  5785  ** write-transaction has already been opened, this function is a no-op.
  5786  **
  5787  ** If the exFlag argument is false, then acquire at least a RESERVED
  5788  ** lock on the database file. If exFlag is true, then acquire at least
  5789  ** an EXCLUSIVE lock. If such a lock is already held, no locking 
  5790  ** functions need be called.
  5791  **
  5792  ** If the subjInMemory argument is non-zero, then any sub-journal opened
  5793  ** within this transaction will be opened as an in-memory file. This
  5794  ** has no effect if the sub-journal is already opened (as it may be when
  5795  ** running in exclusive mode) or if the transaction does not require a
  5796  ** sub-journal. If the subjInMemory argument is zero, then any required
  5797  ** sub-journal is implemented in-memory if pPager is an in-memory database, 
  5798  ** or using a temporary file otherwise.
  5799  */
  5800  int sqlite3PagerBegin(Pager *pPager, int exFlag, int subjInMemory){
  5801    int rc = SQLITE_OK;
  5802  
  5803    if( pPager->errCode ) return pPager->errCode;
  5804    assert( pPager->eState>=PAGER_READER && pPager->eState<PAGER_ERROR );
  5805    pPager->subjInMemory = (u8)subjInMemory;
  5806  
  5807    if( ALWAYS(pPager->eState==PAGER_READER) ){
  5808      assert( pPager->pInJournal==0 );
  5809  
  5810      if( pagerUseWal(pPager) ){
  5811        /* If the pager is configured to use locking_mode=exclusive, and an
  5812        ** exclusive lock on the database is not already held, obtain it now.
  5813        */
  5814        if( pPager->exclusiveMode && sqlite3WalExclusiveMode(pPager->pWal, -1) ){
  5815          rc = pagerLockDb(pPager, EXCLUSIVE_LOCK);
  5816          if( rc!=SQLITE_OK ){
  5817            return rc;
  5818          }
  5819          (void)sqlite3WalExclusiveMode(pPager->pWal, 1);
  5820        }
  5821  
  5822        /* Grab the write lock on the log file. If successful, upgrade to
  5823        ** PAGER_RESERVED state. Otherwise, return an error code to the caller.
  5824        ** The busy-handler is not invoked if another connection already
  5825        ** holds the write-lock. If possible, the upper layer will call it.
  5826        */
  5827        rc = sqlite3WalBeginWriteTransaction(pPager->pWal);
  5828      }else{
  5829        /* Obtain a RESERVED lock on the database file. If the exFlag parameter
  5830        ** is true, then immediately upgrade this to an EXCLUSIVE lock. The
  5831        ** busy-handler callback can be used when upgrading to the EXCLUSIVE
  5832        ** lock, but not when obtaining the RESERVED lock.
  5833        */
  5834        rc = pagerLockDb(pPager, RESERVED_LOCK);
  5835        if( rc==SQLITE_OK && exFlag ){
  5836          rc = pager_wait_on_lock(pPager, EXCLUSIVE_LOCK);
  5837        }
  5838      }
  5839  
  5840      if( rc==SQLITE_OK ){
  5841        /* Change to WRITER_LOCKED state.
  5842        **
  5843        ** WAL mode sets Pager.eState to PAGER_WRITER_LOCKED or CACHEMOD
  5844        ** when it has an open transaction, but never to DBMOD or FINISHED.
  5845        ** This is because in those states the code to roll back savepoint 
  5846        ** transactions may copy data from the sub-journal into the database 
  5847        ** file as well as into the page cache. Which would be incorrect in 
  5848        ** WAL mode.
  5849        */
  5850        pPager->eState = PAGER_WRITER_LOCKED;
  5851        pPager->dbHintSize = pPager->dbSize;
  5852        pPager->dbFileSize = pPager->dbSize;
  5853        pPager->dbOrigSize = pPager->dbSize;
  5854        pPager->journalOff = 0;
  5855      }
  5856  
  5857      assert( rc==SQLITE_OK || pPager->eState==PAGER_READER );
  5858      assert( rc!=SQLITE_OK || pPager->eState==PAGER_WRITER_LOCKED );
  5859      assert( assert_pager_state(pPager) );
  5860    }
  5861  
  5862    PAGERTRACE(("TRANSACTION %d\n", PAGERID(pPager)));
  5863    return rc;
  5864  }
  5865  
  5866  /*
  5867  ** Write page pPg onto the end of the rollback journal.
  5868  */
  5869  static SQLITE_NOINLINE int pagerAddPageToRollbackJournal(PgHdr *pPg){
  5870    Pager *pPager = pPg->pPager;
  5871    int rc;
  5872    u32 cksum;
  5873    char *pData2;
  5874    i64 iOff = pPager->journalOff;
  5875  
  5876    /* We should never write to the journal file the page that
  5877    ** contains the database locks.  The following assert verifies
  5878    ** that we do not. */
  5879    assert( pPg->pgno!=PAGER_MJ_PGNO(pPager) );
  5880  
  5881    assert( pPager->journalHdr<=pPager->journalOff );
  5882    pData2 = pPg->pData;
  5883    cksum = pager_cksum(pPager, (u8*)pData2);
  5884  
  5885    /* Even if an IO or diskfull error occurs while journalling the
  5886    ** page in the block above, set the need-sync flag for the page.
  5887    ** Otherwise, when the transaction is rolled back, the logic in
  5888    ** playback_one_page() will think that the page needs to be restored
  5889    ** in the database file. And if an IO error occurs while doing so,
  5890    ** then corruption may follow.
  5891    */
  5892    pPg->flags |= PGHDR_NEED_SYNC;
  5893  
  5894    rc = write32bits(pPager->jfd, iOff, pPg->pgno);
  5895    if( rc!=SQLITE_OK ) return rc;
  5896    rc = sqlite3OsWrite(pPager->jfd, pData2, pPager->pageSize, iOff+4);
  5897    if( rc!=SQLITE_OK ) return rc;
  5898    rc = write32bits(pPager->jfd, iOff+pPager->pageSize+4, cksum);
  5899    if( rc!=SQLITE_OK ) return rc;
  5900  
  5901    IOTRACE(("JOUT %p %d %lld %d\n", pPager, pPg->pgno, 
  5902             pPager->journalOff, pPager->pageSize));
  5903    PAGER_INCR(sqlite3_pager_writej_count);
  5904    PAGERTRACE(("JOURNAL %d page %d needSync=%d hash(%08x)\n",
  5905         PAGERID(pPager), pPg->pgno, 
  5906         ((pPg->flags&PGHDR_NEED_SYNC)?1:0), pager_pagehash(pPg)));
  5907  
  5908    pPager->journalOff += 8 + pPager->pageSize;
  5909    pPager->nRec++;
  5910    assert( pPager->pInJournal!=0 );
  5911    rc = sqlite3BitvecSet(pPager->pInJournal, pPg->pgno);
  5912    testcase( rc==SQLITE_NOMEM );
  5913    assert( rc==SQLITE_OK || rc==SQLITE_NOMEM );
  5914    rc |= addToSavepointBitvecs(pPager, pPg->pgno);
  5915    assert( rc==SQLITE_OK || rc==SQLITE_NOMEM );
  5916    return rc;
  5917  }
  5918  
  5919  /*
  5920  ** Mark a single data page as writeable. The page is written into the 
  5921  ** main journal or sub-journal as required. If the page is written into
  5922  ** one of the journals, the corresponding bit is set in the 
  5923  ** Pager.pInJournal bitvec and the PagerSavepoint.pInSavepoint bitvecs
  5924  ** of any open savepoints as appropriate.
  5925  */
  5926  static int pager_write(PgHdr *pPg){
  5927    Pager *pPager = pPg->pPager;
  5928    int rc = SQLITE_OK;
  5929  
  5930    /* This routine is not called unless a write-transaction has already 
  5931    ** been started. The journal file may or may not be open at this point.
  5932    ** It is never called in the ERROR state.
  5933    */
  5934    assert( pPager->eState==PAGER_WRITER_LOCKED
  5935         || pPager->eState==PAGER_WRITER_CACHEMOD
  5936         || pPager->eState==PAGER_WRITER_DBMOD
  5937    );
  5938    assert( assert_pager_state(pPager) );
  5939    assert( pPager->errCode==0 );
  5940    assert( pPager->readOnly==0 );
  5941    CHECK_PAGE(pPg);
  5942  
  5943    /* The journal file needs to be opened. Higher level routines have already
  5944    ** obtained the necessary locks to begin the write-transaction, but the
  5945    ** rollback journal might not yet be open. Open it now if this is the case.
  5946    **
  5947    ** This is done before calling sqlite3PcacheMakeDirty() on the page. 
  5948    ** Otherwise, if it were done after calling sqlite3PcacheMakeDirty(), then
  5949    ** an error might occur and the pager would end up in WRITER_LOCKED state
  5950    ** with pages marked as dirty in the cache.
  5951    */
  5952    if( pPager->eState==PAGER_WRITER_LOCKED ){
  5953      rc = pager_open_journal(pPager);
  5954      if( rc!=SQLITE_OK ) return rc;
  5955    }
  5956    assert( pPager->eState>=PAGER_WRITER_CACHEMOD );
  5957    assert( assert_pager_state(pPager) );
  5958  
  5959    /* Mark the page that is about to be modified as dirty. */
  5960    sqlite3PcacheMakeDirty(pPg);
  5961  
  5962    /* If a rollback journal is in use, them make sure the page that is about
  5963    ** to change is in the rollback journal, or if the page is a new page off
  5964    ** then end of the file, make sure it is marked as PGHDR_NEED_SYNC.
  5965    */
  5966    assert( (pPager->pInJournal!=0) == isOpen(pPager->jfd) );
  5967    if( pPager->pInJournal!=0
  5968     && sqlite3BitvecTestNotNull(pPager->pInJournal, pPg->pgno)==0
  5969    ){
  5970      assert( pagerUseWal(pPager)==0 );
  5971      if( pPg->pgno<=pPager->dbOrigSize ){
  5972        rc = pagerAddPageToRollbackJournal(pPg);
  5973        if( rc!=SQLITE_OK ){
  5974          return rc;
  5975        }
  5976      }else{
  5977        if( pPager->eState!=PAGER_WRITER_DBMOD ){
  5978          pPg->flags |= PGHDR_NEED_SYNC;
  5979        }
  5980        PAGERTRACE(("APPEND %d page %d needSync=%d\n",
  5981                PAGERID(pPager), pPg->pgno,
  5982               ((pPg->flags&PGHDR_NEED_SYNC)?1:0)));
  5983      }
  5984    }
  5985  
  5986    /* The PGHDR_DIRTY bit is set above when the page was added to the dirty-list
  5987    ** and before writing the page into the rollback journal.  Wait until now,
  5988    ** after the page has been successfully journalled, before setting the
  5989    ** PGHDR_WRITEABLE bit that indicates that the page can be safely modified.
  5990    */
  5991    pPg->flags |= PGHDR_WRITEABLE;
  5992    
  5993    /* If the statement journal is open and the page is not in it,
  5994    ** then write the page into the statement journal.
  5995    */
  5996    if( pPager->nSavepoint>0 ){
  5997      rc = subjournalPageIfRequired(pPg);
  5998    }
  5999  
  6000    /* Update the database size and return. */
  6001    if( pPager->dbSize<pPg->pgno ){
  6002      pPager->dbSize = pPg->pgno;
  6003    }
  6004    return rc;
  6005  }
  6006  
  6007  /*
  6008  ** This is a variant of sqlite3PagerWrite() that runs when the sector size
  6009  ** is larger than the page size.  SQLite makes the (reasonable) assumption that
  6010  ** all bytes of a sector are written together by hardware.  Hence, all bytes of
  6011  ** a sector need to be journalled in case of a power loss in the middle of
  6012  ** a write.
  6013  **
  6014  ** Usually, the sector size is less than or equal to the page size, in which
  6015  ** case pages can be individually written.  This routine only runs in the
  6016  ** exceptional case where the page size is smaller than the sector size.
  6017  */
  6018  static SQLITE_NOINLINE int pagerWriteLargeSector(PgHdr *pPg){
  6019    int rc = SQLITE_OK;          /* Return code */
  6020    Pgno nPageCount;             /* Total number of pages in database file */
  6021    Pgno pg1;                    /* First page of the sector pPg is located on. */
  6022    int nPage = 0;               /* Number of pages starting at pg1 to journal */
  6023    int ii;                      /* Loop counter */
  6024    int needSync = 0;            /* True if any page has PGHDR_NEED_SYNC */
  6025    Pager *pPager = pPg->pPager; /* The pager that owns pPg */
  6026    Pgno nPagePerSector = (pPager->sectorSize/pPager->pageSize);
  6027  
  6028    /* Set the doNotSpill NOSYNC bit to 1. This is because we cannot allow
  6029    ** a journal header to be written between the pages journaled by
  6030    ** this function.
  6031    */
  6032    assert( !MEMDB );
  6033    assert( (pPager->doNotSpill & SPILLFLAG_NOSYNC)==0 );
  6034    pPager->doNotSpill |= SPILLFLAG_NOSYNC;
  6035  
  6036    /* This trick assumes that both the page-size and sector-size are
  6037    ** an integer power of 2. It sets variable pg1 to the identifier
  6038    ** of the first page of the sector pPg is located on.
  6039    */
  6040    pg1 = ((pPg->pgno-1) & ~(nPagePerSector-1)) + 1;
  6041  
  6042    nPageCount = pPager->dbSize;
  6043    if( pPg->pgno>nPageCount ){
  6044      nPage = (pPg->pgno - pg1)+1;
  6045    }else if( (pg1+nPagePerSector-1)>nPageCount ){
  6046      nPage = nPageCount+1-pg1;
  6047    }else{
  6048      nPage = nPagePerSector;
  6049    }
  6050    assert(nPage>0);
  6051    assert(pg1<=pPg->pgno);
  6052    assert((pg1+nPage)>pPg->pgno);
  6053  
  6054    for(ii=0; ii<nPage && rc==SQLITE_OK; ii++){
  6055      Pgno pg = pg1+ii;
  6056      PgHdr *pPage;
  6057      if( pg==pPg->pgno || !sqlite3BitvecTest(pPager->pInJournal, pg) ){
  6058        if( pg!=PAGER_MJ_PGNO(pPager) ){
  6059          rc = sqlite3PagerGet(pPager, pg, &pPage, 0);
  6060          if( rc==SQLITE_OK ){
  6061            rc = pager_write(pPage);
  6062            if( pPage->flags&PGHDR_NEED_SYNC ){
  6063              needSync = 1;
  6064            }
  6065            sqlite3PagerUnrefNotNull(pPage);
  6066          }
  6067        }
  6068      }else if( (pPage = sqlite3PagerLookup(pPager, pg))!=0 ){
  6069        if( pPage->flags&PGHDR_NEED_SYNC ){
  6070          needSync = 1;
  6071        }
  6072        sqlite3PagerUnrefNotNull(pPage);
  6073      }
  6074    }
  6075  
  6076    /* If the PGHDR_NEED_SYNC flag is set for any of the nPage pages 
  6077    ** starting at pg1, then it needs to be set for all of them. Because
  6078    ** writing to any of these nPage pages may damage the others, the
  6079    ** journal file must contain sync()ed copies of all of them
  6080    ** before any of them can be written out to the database file.
  6081    */
  6082    if( rc==SQLITE_OK && needSync ){
  6083      assert( !MEMDB );
  6084      for(ii=0; ii<nPage; ii++){
  6085        PgHdr *pPage = sqlite3PagerLookup(pPager, pg1+ii);
  6086        if( pPage ){
  6087          pPage->flags |= PGHDR_NEED_SYNC;
  6088          sqlite3PagerUnrefNotNull(pPage);
  6089        }
  6090      }
  6091    }
  6092  
  6093    assert( (pPager->doNotSpill & SPILLFLAG_NOSYNC)!=0 );
  6094    pPager->doNotSpill &= ~SPILLFLAG_NOSYNC;
  6095    return rc;
  6096  }
  6097  
  6098  /*
  6099  ** Mark a data page as writeable. This routine must be called before 
  6100  ** making changes to a page. The caller must check the return value 
  6101  ** of this function and be careful not to change any page data unless 
  6102  ** this routine returns SQLITE_OK.
  6103  **
  6104  ** The difference between this function and pager_write() is that this
  6105  ** function also deals with the special case where 2 or more pages
  6106  ** fit on a single disk sector. In this case all co-resident pages
  6107  ** must have been written to the journal file before returning.
  6108  **
  6109  ** If an error occurs, SQLITE_NOMEM or an IO error code is returned
  6110  ** as appropriate. Otherwise, SQLITE_OK.
  6111  */
  6112  int sqlite3PagerWrite(PgHdr *pPg){
  6113    Pager *pPager = pPg->pPager;
  6114    assert( (pPg->flags & PGHDR_MMAP)==0 );
  6115    assert( pPager->eState>=PAGER_WRITER_LOCKED );
  6116    assert( assert_pager_state(pPager) );
  6117    if( (pPg->flags & PGHDR_WRITEABLE)!=0 && pPager->dbSize>=pPg->pgno ){
  6118      if( pPager->nSavepoint ) return subjournalPageIfRequired(pPg);
  6119      return SQLITE_OK;
  6120    }else if( pPager->errCode ){
  6121      return pPager->errCode;
  6122    }else if( pPager->sectorSize > (u32)pPager->pageSize ){
  6123      assert( pPager->tempFile==0 );
  6124      return pagerWriteLargeSector(pPg);
  6125    }else{
  6126      return pager_write(pPg);
  6127    }
  6128  }
  6129  
  6130  /*
  6131  ** Return TRUE if the page given in the argument was previously passed
  6132  ** to sqlite3PagerWrite().  In other words, return TRUE if it is ok
  6133  ** to change the content of the page.
  6134  */
  6135  #ifndef NDEBUG
  6136  int sqlite3PagerIswriteable(DbPage *pPg){
  6137    return pPg->flags & PGHDR_WRITEABLE;
  6138  }
  6139  #endif
  6140  
  6141  /*
  6142  ** A call to this routine tells the pager that it is not necessary to
  6143  ** write the information on page pPg back to the disk, even though
  6144  ** that page might be marked as dirty.  This happens, for example, when
  6145  ** the page has been added as a leaf of the freelist and so its
  6146  ** content no longer matters.
  6147  **
  6148  ** The overlying software layer calls this routine when all of the data
  6149  ** on the given page is unused. The pager marks the page as clean so
  6150  ** that it does not get written to disk.
  6151  **
  6152  ** Tests show that this optimization can quadruple the speed of large 
  6153  ** DELETE operations.
  6154  **
  6155  ** This optimization cannot be used with a temp-file, as the page may
  6156  ** have been dirty at the start of the transaction. In that case, if
  6157  ** memory pressure forces page pPg out of the cache, the data does need 
  6158  ** to be written out to disk so that it may be read back in if the 
  6159  ** current transaction is rolled back.
  6160  */
  6161  void sqlite3PagerDontWrite(PgHdr *pPg){
  6162    Pager *pPager = pPg->pPager;
  6163    if( !pPager->tempFile && (pPg->flags&PGHDR_DIRTY) && pPager->nSavepoint==0 ){
  6164      PAGERTRACE(("DONT_WRITE page %d of %d\n", pPg->pgno, PAGERID(pPager)));
  6165      IOTRACE(("CLEAN %p %d\n", pPager, pPg->pgno))
  6166      pPg->flags |= PGHDR_DONT_WRITE;
  6167      pPg->flags &= ~PGHDR_WRITEABLE;
  6168      testcase( pPg->flags & PGHDR_NEED_SYNC );
  6169      pager_set_pagehash(pPg);
  6170    }
  6171  }
  6172  
  6173  /*
  6174  ** This routine is called to increment the value of the database file 
  6175  ** change-counter, stored as a 4-byte big-endian integer starting at 
  6176  ** byte offset 24 of the pager file.  The secondary change counter at
  6177  ** 92 is also updated, as is the SQLite version number at offset 96.
  6178  **
  6179  ** But this only happens if the pPager->changeCountDone flag is false.
  6180  ** To avoid excess churning of page 1, the update only happens once.
  6181  ** See also the pager_write_changecounter() routine that does an 
  6182  ** unconditional update of the change counters.
  6183  **
  6184  ** If the isDirectMode flag is zero, then this is done by calling 
  6185  ** sqlite3PagerWrite() on page 1, then modifying the contents of the
  6186  ** page data. In this case the file will be updated when the current
  6187  ** transaction is committed.
  6188  **
  6189  ** The isDirectMode flag may only be non-zero if the library was compiled
  6190  ** with the SQLITE_ENABLE_ATOMIC_WRITE macro defined. In this case,
  6191  ** if isDirect is non-zero, then the database file is updated directly
  6192  ** by writing an updated version of page 1 using a call to the 
  6193  ** sqlite3OsWrite() function.
  6194  */
  6195  static int pager_incr_changecounter(Pager *pPager, int isDirectMode){
  6196    int rc = SQLITE_OK;
  6197  
  6198    assert( pPager->eState==PAGER_WRITER_CACHEMOD
  6199         || pPager->eState==PAGER_WRITER_DBMOD
  6200    );
  6201    assert( assert_pager_state(pPager) );
  6202  
  6203    /* Declare and initialize constant integer 'isDirect'. If the
  6204    ** atomic-write optimization is enabled in this build, then isDirect
  6205    ** is initialized to the value passed as the isDirectMode parameter
  6206    ** to this function. Otherwise, it is always set to zero.
  6207    **
  6208    ** The idea is that if the atomic-write optimization is not
  6209    ** enabled at compile time, the compiler can omit the tests of
  6210    ** 'isDirect' below, as well as the block enclosed in the
  6211    ** "if( isDirect )" condition.
  6212    */
  6213  #ifndef SQLITE_ENABLE_ATOMIC_WRITE
  6214  # define DIRECT_MODE 0
  6215    assert( isDirectMode==0 );
  6216    UNUSED_PARAMETER(isDirectMode);
  6217  #else
  6218  # define DIRECT_MODE isDirectMode
  6219  #endif
  6220  
  6221    if( !pPager->changeCountDone && ALWAYS(pPager->dbSize>0) ){
  6222      PgHdr *pPgHdr;                /* Reference to page 1 */
  6223  
  6224      assert( !pPager->tempFile && isOpen(pPager->fd) );
  6225  
  6226      /* Open page 1 of the file for writing. */
  6227      rc = sqlite3PagerGet(pPager, 1, &pPgHdr, 0);
  6228      assert( pPgHdr==0 || rc==SQLITE_OK );
  6229  
  6230      /* If page one was fetched successfully, and this function is not
  6231      ** operating in direct-mode, make page 1 writable.  When not in 
  6232      ** direct mode, page 1 is always held in cache and hence the PagerGet()
  6233      ** above is always successful - hence the ALWAYS on rc==SQLITE_OK.
  6234      */
  6235      if( !DIRECT_MODE && ALWAYS(rc==SQLITE_OK) ){
  6236        rc = sqlite3PagerWrite(pPgHdr);
  6237      }
  6238  
  6239      if( rc==SQLITE_OK ){
  6240        /* Actually do the update of the change counter */
  6241        pager_write_changecounter(pPgHdr);
  6242  
  6243        /* If running in direct mode, write the contents of page 1 to the file. */
  6244        if( DIRECT_MODE ){
  6245          const void *zBuf;
  6246          assert( pPager->dbFileSize>0 );
  6247          zBuf = pPgHdr->pData;
  6248          if( rc==SQLITE_OK ){
  6249            rc = sqlite3OsWrite(pPager->fd, zBuf, pPager->pageSize, 0);
  6250            pPager->aStat[PAGER_STAT_WRITE]++;
  6251          }
  6252          if( rc==SQLITE_OK ){
  6253            /* Update the pager's copy of the change-counter. Otherwise, the
  6254            ** next time a read transaction is opened the cache will be
  6255            ** flushed (as the change-counter values will not match).  */
  6256            const void *pCopy = (const void *)&((const char *)zBuf)[24];
  6257            memcpy(&pPager->dbFileVers, pCopy, sizeof(pPager->dbFileVers));
  6258            pPager->changeCountDone = 1;
  6259          }
  6260        }else{
  6261          pPager->changeCountDone = 1;
  6262        }
  6263      }
  6264  
  6265      /* Release the page reference. */
  6266      sqlite3PagerUnref(pPgHdr);
  6267    }
  6268    return rc;
  6269  }
  6270  
  6271  /*
  6272  ** Sync the database file to disk. This is a no-op for in-memory databases
  6273  ** or pages with the Pager.noSync flag set.
  6274  **
  6275  ** If successful, or if called on a pager for which it is a no-op, this
  6276  ** function returns SQLITE_OK. Otherwise, an IO error code is returned.
  6277  */
  6278  int sqlite3PagerSync(Pager *pPager, const char *zMaster){
  6279    int rc = SQLITE_OK;
  6280    void *pArg = (void*)zMaster;
  6281    rc = sqlite3OsFileControl(pPager->fd, SQLITE_FCNTL_SYNC, pArg);
  6282    if( rc==SQLITE_NOTFOUND ) rc = SQLITE_OK;
  6283    if( rc==SQLITE_OK && !pPager->noSync ){
  6284      assert( !MEMDB );
  6285      rc = sqlite3OsSync(pPager->fd, pPager->syncFlags);
  6286    }
  6287    return rc;
  6288  }
  6289  
  6290  /*
  6291  ** This function may only be called while a write-transaction is active in
  6292  ** rollback. If the connection is in WAL mode, this call is a no-op. 
  6293  ** Otherwise, if the connection does not already have an EXCLUSIVE lock on 
  6294  ** the database file, an attempt is made to obtain one.
  6295  **
  6296  ** If the EXCLUSIVE lock is already held or the attempt to obtain it is
  6297  ** successful, or the connection is in WAL mode, SQLITE_OK is returned.
  6298  ** Otherwise, either SQLITE_BUSY or an SQLITE_IOERR_XXX error code is 
  6299  ** returned.
  6300  */
  6301  int sqlite3PagerExclusiveLock(Pager *pPager){
  6302    int rc = pPager->errCode;
  6303    assert( assert_pager_state(pPager) );
  6304    if( rc==SQLITE_OK ){
  6305      assert( pPager->eState==PAGER_WRITER_CACHEMOD 
  6306           || pPager->eState==PAGER_WRITER_DBMOD 
  6307           || pPager->eState==PAGER_WRITER_LOCKED 
  6308      );
  6309      assert( assert_pager_state(pPager) );
  6310      if( 0==pagerUseWal(pPager) ){
  6311        rc = pager_wait_on_lock(pPager, EXCLUSIVE_LOCK);
  6312      }
  6313    }
  6314    return rc;
  6315  }
  6316  
  6317  /*
  6318  ** Sync the database file for the pager pPager. zMaster points to the name
  6319  ** of a master journal file that should be written into the individual
  6320  ** journal file. zMaster may be NULL, which is interpreted as no master
  6321  ** journal (a single database transaction).
  6322  **
  6323  ** This routine ensures that:
  6324  **
  6325  **   * The database file change-counter is updated,
  6326  **   * the journal is synced (unless the atomic-write optimization is used),
  6327  **   * all dirty pages are written to the database file, 
  6328  **   * the database file is truncated (if required), and
  6329  **   * the database file synced. 
  6330  **
  6331  ** The only thing that remains to commit the transaction is to finalize 
  6332  ** (delete, truncate or zero the first part of) the journal file (or 
  6333  ** delete the master journal file if specified).
  6334  **
  6335  ** Note that if zMaster==NULL, this does not overwrite a previous value
  6336  ** passed to an sqlite3PagerCommitPhaseOne() call.
  6337  **
  6338  ** If the final parameter - noSync - is true, then the database file itself
  6339  ** is not synced. The caller must call sqlite3PagerSync() directly to
  6340  ** sync the database file before calling CommitPhaseTwo() to delete the
  6341  ** journal file in this case.
  6342  */
  6343  int sqlite3PagerCommitPhaseOne(
  6344    Pager *pPager,                  /* Pager object */
  6345    const char *zMaster,            /* If not NULL, the master journal name */
  6346    int noSync                      /* True to omit the xSync on the db file */
  6347  ){
  6348    int rc = SQLITE_OK;             /* Return code */
  6349  
  6350    assert( pPager->eState==PAGER_WRITER_LOCKED
  6351         || pPager->eState==PAGER_WRITER_CACHEMOD
  6352         || pPager->eState==PAGER_WRITER_DBMOD
  6353         || pPager->eState==PAGER_ERROR
  6354    );
  6355    assert( assert_pager_state(pPager) );
  6356  
  6357    /* If a prior error occurred, report that error again. */
  6358    if( NEVER(pPager->errCode) ) return pPager->errCode;
  6359  
  6360    /* Provide the ability to easily simulate an I/O error during testing */
  6361    if( sqlite3FaultSim(400) ) return SQLITE_IOERR;
  6362  
  6363    PAGERTRACE(("DATABASE SYNC: File=%s zMaster=%s nSize=%d\n", 
  6364        pPager->zFilename, zMaster, pPager->dbSize));
  6365  
  6366    /* If no database changes have been made, return early. */
  6367    if( pPager->eState<PAGER_WRITER_CACHEMOD ) return SQLITE_OK;
  6368  
  6369    assert( MEMDB==0 || pPager->tempFile );
  6370    assert( isOpen(pPager->fd) || pPager->tempFile );
  6371    if( 0==pagerFlushOnCommit(pPager, 1) ){
  6372      /* If this is an in-memory db, or no pages have been written to, or this
  6373      ** function has already been called, it is mostly a no-op.  However, any
  6374      ** backup in progress needs to be restarted.  */
  6375      sqlite3BackupRestart(pPager->pBackup);
  6376    }else{
  6377      PgHdr *pList;
  6378      if( pagerUseWal(pPager) ){
  6379        PgHdr *pPageOne = 0;
  6380        pList = sqlite3PcacheDirtyList(pPager->pPCache);
  6381        if( pList==0 ){
  6382          /* Must have at least one page for the WAL commit flag.
  6383          ** Ticket [2d1a5c67dfc2363e44f29d9bbd57f] 2011-05-18 */
  6384          rc = sqlite3PagerGet(pPager, 1, &pPageOne, 0);
  6385          pList = pPageOne;
  6386          pList->pDirty = 0;
  6387        }
  6388        assert( rc==SQLITE_OK );
  6389        if( ALWAYS(pList) ){
  6390          rc = pagerWalFrames(pPager, pList, pPager->dbSize, 1);
  6391        }
  6392        sqlite3PagerUnref(pPageOne);
  6393        if( rc==SQLITE_OK ){
  6394          sqlite3PcacheCleanAll(pPager->pPCache);
  6395        }
  6396      }else{
  6397        /* The bBatch boolean is true if the batch-atomic-write commit method
  6398        ** should be used.  No rollback journal is created if batch-atomic-write
  6399        ** is enabled.
  6400        */
  6401  #ifdef SQLITE_ENABLE_BATCH_ATOMIC_WRITE
  6402        sqlite3_file *fd = pPager->fd;
  6403        int bBatch = zMaster==0    /* An SQLITE_IOCAP_BATCH_ATOMIC commit */
  6404          && (sqlite3OsDeviceCharacteristics(fd) & SQLITE_IOCAP_BATCH_ATOMIC)
  6405          && !pPager->noSync
  6406          && sqlite3JournalIsInMemory(pPager->jfd);
  6407  #else
  6408  #     define bBatch 0
  6409  #endif
  6410  
  6411  #ifdef SQLITE_ENABLE_ATOMIC_WRITE
  6412        /* The following block updates the change-counter. Exactly how it
  6413        ** does this depends on whether or not the atomic-update optimization
  6414        ** was enabled at compile time, and if this transaction meets the 
  6415        ** runtime criteria to use the operation: 
  6416        **
  6417        **    * The file-system supports the atomic-write property for
  6418        **      blocks of size page-size, and 
  6419        **    * This commit is not part of a multi-file transaction, and
  6420        **    * Exactly one page has been modified and store in the journal file.
  6421        **
  6422        ** If the optimization was not enabled at compile time, then the
  6423        ** pager_incr_changecounter() function is called to update the change
  6424        ** counter in 'indirect-mode'. If the optimization is compiled in but
  6425        ** is not applicable to this transaction, call sqlite3JournalCreate()
  6426        ** to make sure the journal file has actually been created, then call
  6427        ** pager_incr_changecounter() to update the change-counter in indirect
  6428        ** mode. 
  6429        **
  6430        ** Otherwise, if the optimization is both enabled and applicable,
  6431        ** then call pager_incr_changecounter() to update the change-counter
  6432        ** in 'direct' mode. In this case the journal file will never be
  6433        ** created for this transaction.
  6434        */
  6435        if( bBatch==0 ){
  6436          PgHdr *pPg;
  6437          assert( isOpen(pPager->jfd) 
  6438              || pPager->journalMode==PAGER_JOURNALMODE_OFF 
  6439              || pPager->journalMode==PAGER_JOURNALMODE_WAL 
  6440              );
  6441          if( !zMaster && isOpen(pPager->jfd) 
  6442           && pPager->journalOff==jrnlBufferSize(pPager) 
  6443           && pPager->dbSize>=pPager->dbOrigSize
  6444           && (!(pPg = sqlite3PcacheDirtyList(pPager->pPCache)) || 0==pPg->pDirty)
  6445          ){
  6446            /* Update the db file change counter via the direct-write method. The 
  6447            ** following call will modify the in-memory representation of page 1 
  6448            ** to include the updated change counter and then write page 1 
  6449            ** directly to the database file. Because of the atomic-write 
  6450            ** property of the host file-system, this is safe.
  6451            */
  6452            rc = pager_incr_changecounter(pPager, 1);
  6453          }else{
  6454            rc = sqlite3JournalCreate(pPager->jfd);
  6455            if( rc==SQLITE_OK ){
  6456              rc = pager_incr_changecounter(pPager, 0);
  6457            }
  6458          }
  6459        }
  6460  #else  /* SQLITE_ENABLE_ATOMIC_WRITE */
  6461  #ifdef SQLITE_ENABLE_BATCH_ATOMIC_WRITE
  6462        if( zMaster ){
  6463          rc = sqlite3JournalCreate(pPager->jfd);
  6464          if( rc!=SQLITE_OK ) goto commit_phase_one_exit;
  6465          assert( bBatch==0 );
  6466        }
  6467  #endif
  6468        rc = pager_incr_changecounter(pPager, 0);
  6469  #endif /* !SQLITE_ENABLE_ATOMIC_WRITE */
  6470        if( rc!=SQLITE_OK ) goto commit_phase_one_exit;
  6471    
  6472        /* Write the master journal name into the journal file. If a master 
  6473        ** journal file name has already been written to the journal file, 
  6474        ** or if zMaster is NULL (no master journal), then this call is a no-op.
  6475        */
  6476        rc = writeMasterJournal(pPager, zMaster);
  6477        if( rc!=SQLITE_OK ) goto commit_phase_one_exit;
  6478    
  6479        /* Sync the journal file and write all dirty pages to the database.
  6480        ** If the atomic-update optimization is being used, this sync will not 
  6481        ** create the journal file or perform any real IO.
  6482        **
  6483        ** Because the change-counter page was just modified, unless the
  6484        ** atomic-update optimization is used it is almost certain that the
  6485        ** journal requires a sync here. However, in locking_mode=exclusive
  6486        ** on a system under memory pressure it is just possible that this is 
  6487        ** not the case. In this case it is likely enough that the redundant
  6488        ** xSync() call will be changed to a no-op by the OS anyhow. 
  6489        */
  6490        rc = syncJournal(pPager, 0);
  6491        if( rc!=SQLITE_OK ) goto commit_phase_one_exit;
  6492  
  6493        pList = sqlite3PcacheDirtyList(pPager->pPCache);
  6494  #ifdef SQLITE_ENABLE_BATCH_ATOMIC_WRITE
  6495        if( bBatch ){
  6496          rc = sqlite3OsFileControl(fd, SQLITE_FCNTL_BEGIN_ATOMIC_WRITE, 0);
  6497          if( rc==SQLITE_OK ){
  6498            rc = pager_write_pagelist(pPager, pList);
  6499            if( rc==SQLITE_OK ){
  6500              rc = sqlite3OsFileControl(fd, SQLITE_FCNTL_COMMIT_ATOMIC_WRITE, 0);
  6501            }
  6502            if( rc!=SQLITE_OK ){
  6503              sqlite3OsFileControlHint(fd, SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE, 0);
  6504            }
  6505          }
  6506  
  6507          if( (rc&0xFF)==SQLITE_IOERR && rc!=SQLITE_IOERR_NOMEM ){
  6508            rc = sqlite3JournalCreate(pPager->jfd);
  6509            if( rc!=SQLITE_OK ){
  6510              sqlite3OsClose(pPager->jfd);
  6511              goto commit_phase_one_exit;
  6512            }
  6513            bBatch = 0;
  6514          }else{
  6515            sqlite3OsClose(pPager->jfd);
  6516          }
  6517        }
  6518  #endif /* SQLITE_ENABLE_BATCH_ATOMIC_WRITE */
  6519  
  6520        if( bBatch==0 ){
  6521          rc = pager_write_pagelist(pPager, pList);
  6522        }
  6523        if( rc!=SQLITE_OK ){
  6524          assert( rc!=SQLITE_IOERR_BLOCKED );
  6525          goto commit_phase_one_exit;
  6526        }
  6527        sqlite3PcacheCleanAll(pPager->pPCache);
  6528  
  6529        /* If the file on disk is smaller than the database image, use 
  6530        ** pager_truncate to grow the file here. This can happen if the database
  6531        ** image was extended as part of the current transaction and then the
  6532        ** last page in the db image moved to the free-list. In this case the
  6533        ** last page is never written out to disk, leaving the database file
  6534        ** undersized. Fix this now if it is the case.  */
  6535        if( pPager->dbSize>pPager->dbFileSize ){
  6536          Pgno nNew = pPager->dbSize - (pPager->dbSize==PAGER_MJ_PGNO(pPager));
  6537          assert( pPager->eState==PAGER_WRITER_DBMOD );
  6538          rc = pager_truncate(pPager, nNew);
  6539          if( rc!=SQLITE_OK ) goto commit_phase_one_exit;
  6540        }
  6541    
  6542        /* Finally, sync the database file. */
  6543        if( !noSync ){
  6544          rc = sqlite3PagerSync(pPager, zMaster);
  6545        }
  6546        IOTRACE(("DBSYNC %p\n", pPager))
  6547      }
  6548    }
  6549  
  6550  commit_phase_one_exit:
  6551    if( rc==SQLITE_OK && !pagerUseWal(pPager) ){
  6552      pPager->eState = PAGER_WRITER_FINISHED;
  6553    }
  6554    return rc;
  6555  }
  6556  
  6557  
  6558  /*
  6559  ** When this function is called, the database file has been completely
  6560  ** updated to reflect the changes made by the current transaction and
  6561  ** synced to disk. The journal file still exists in the file-system 
  6562  ** though, and if a failure occurs at this point it will eventually
  6563  ** be used as a hot-journal and the current transaction rolled back.
  6564  **
  6565  ** This function finalizes the journal file, either by deleting, 
  6566  ** truncating or partially zeroing it, so that it cannot be used 
  6567  ** for hot-journal rollback. Once this is done the transaction is
  6568  ** irrevocably committed.
  6569  **
  6570  ** If an error occurs, an IO error code is returned and the pager
  6571  ** moves into the error state. Otherwise, SQLITE_OK is returned.
  6572  */
  6573  int sqlite3PagerCommitPhaseTwo(Pager *pPager){
  6574    int rc = SQLITE_OK;                  /* Return code */
  6575  
  6576    /* This routine should not be called if a prior error has occurred.
  6577    ** But if (due to a coding error elsewhere in the system) it does get
  6578    ** called, just return the same error code without doing anything. */
  6579    if( NEVER(pPager->errCode) ) return pPager->errCode;
  6580    pPager->iDataVersion++;
  6581  
  6582    assert( pPager->eState==PAGER_WRITER_LOCKED
  6583         || pPager->eState==PAGER_WRITER_FINISHED
  6584         || (pagerUseWal(pPager) && pPager->eState==PAGER_WRITER_CACHEMOD)
  6585    );
  6586    assert( assert_pager_state(pPager) );
  6587  
  6588    /* An optimization. If the database was not actually modified during
  6589    ** this transaction, the pager is running in exclusive-mode and is
  6590    ** using persistent journals, then this function is a no-op.
  6591    **
  6592    ** The start of the journal file currently contains a single journal 
  6593    ** header with the nRec field set to 0. If such a journal is used as
  6594    ** a hot-journal during hot-journal rollback, 0 changes will be made
  6595    ** to the database file. So there is no need to zero the journal 
  6596    ** header. Since the pager is in exclusive mode, there is no need
  6597    ** to drop any locks either.
  6598    */
  6599    if( pPager->eState==PAGER_WRITER_LOCKED 
  6600     && pPager->exclusiveMode 
  6601     && pPager->journalMode==PAGER_JOURNALMODE_PERSIST
  6602    ){
  6603      assert( pPager->journalOff==JOURNAL_HDR_SZ(pPager) || !pPager->journalOff );
  6604      pPager->eState = PAGER_READER;
  6605      return SQLITE_OK;
  6606    }
  6607  
  6608    PAGERTRACE(("COMMIT %d\n", PAGERID(pPager)));
  6609    rc = pager_end_transaction(pPager, pPager->setMaster, 1);
  6610    return pager_error(pPager, rc);
  6611  }
  6612  
  6613  /*
  6614  ** If a write transaction is open, then all changes made within the 
  6615  ** transaction are reverted and the current write-transaction is closed.
  6616  ** The pager falls back to PAGER_READER state if successful, or PAGER_ERROR
  6617  ** state if an error occurs.
  6618  **
  6619  ** If the pager is already in PAGER_ERROR state when this function is called,
  6620  ** it returns Pager.errCode immediately. No work is performed in this case.
  6621  **
  6622  ** Otherwise, in rollback mode, this function performs two functions:
  6623  **
  6624  **   1) It rolls back the journal file, restoring all database file and 
  6625  **      in-memory cache pages to the state they were in when the transaction
  6626  **      was opened, and
  6627  **
  6628  **   2) It finalizes the journal file, so that it is not used for hot
  6629  **      rollback at any point in the future.
  6630  **
  6631  ** Finalization of the journal file (task 2) is only performed if the 
  6632  ** rollback is successful.
  6633  **
  6634  ** In WAL mode, all cache-entries containing data modified within the
  6635  ** current transaction are either expelled from the cache or reverted to
  6636  ** their pre-transaction state by re-reading data from the database or
  6637  ** WAL files. The WAL transaction is then closed.
  6638  */
  6639  int sqlite3PagerRollback(Pager *pPager){
  6640    int rc = SQLITE_OK;                  /* Return code */
  6641    PAGERTRACE(("ROLLBACK %d\n", PAGERID(pPager)));
  6642  
  6643    /* PagerRollback() is a no-op if called in READER or OPEN state. If
  6644    ** the pager is already in the ERROR state, the rollback is not 
  6645    ** attempted here. Instead, the error code is returned to the caller.
  6646    */
  6647    assert( assert_pager_state(pPager) );
  6648    if( pPager->eState==PAGER_ERROR ) return pPager->errCode;
  6649    if( pPager->eState<=PAGER_READER ) return SQLITE_OK;
  6650  
  6651    if( pagerUseWal(pPager) ){
  6652      int rc2;
  6653      rc = sqlite3PagerSavepoint(pPager, SAVEPOINT_ROLLBACK, -1);
  6654      rc2 = pager_end_transaction(pPager, pPager->setMaster, 0);
  6655      if( rc==SQLITE_OK ) rc = rc2;
  6656    }else if( !isOpen(pPager->jfd) || pPager->eState==PAGER_WRITER_LOCKED ){
  6657      int eState = pPager->eState;
  6658      rc = pager_end_transaction(pPager, 0, 0);
  6659      if( !MEMDB && eState>PAGER_WRITER_LOCKED ){
  6660        /* This can happen using journal_mode=off. Move the pager to the error 
  6661        ** state to indicate that the contents of the cache may not be trusted.
  6662        ** Any active readers will get SQLITE_ABORT.
  6663        */
  6664        pPager->errCode = SQLITE_ABORT;
  6665        pPager->eState = PAGER_ERROR;
  6666        setGetterMethod(pPager);
  6667        return rc;
  6668      }
  6669    }else{
  6670      rc = pager_playback(pPager, 0);
  6671    }
  6672  
  6673    assert( pPager->eState==PAGER_READER || rc!=SQLITE_OK );
  6674    assert( rc==SQLITE_OK || rc==SQLITE_FULL || rc==SQLITE_CORRUPT
  6675            || rc==SQLITE_NOMEM || (rc&0xFF)==SQLITE_IOERR 
  6676            || rc==SQLITE_CANTOPEN
  6677    );
  6678  
  6679    /* If an error occurs during a ROLLBACK, we can no longer trust the pager
  6680    ** cache. So call pager_error() on the way out to make any error persistent.
  6681    */
  6682    return pager_error(pPager, rc);
  6683  }
  6684  
  6685  /*
  6686  ** Return TRUE if the database file is opened read-only.  Return FALSE
  6687  ** if the database is (in theory) writable.
  6688  */
  6689  u8 sqlite3PagerIsreadonly(Pager *pPager){
  6690    return pPager->readOnly;
  6691  }
  6692  
  6693  #ifdef SQLITE_DEBUG
  6694  /*
  6695  ** Return the sum of the reference counts for all pages held by pPager.
  6696  */
  6697  int sqlite3PagerRefcount(Pager *pPager){
  6698    return sqlite3PcacheRefCount(pPager->pPCache);
  6699  }
  6700  #endif
  6701  
  6702  /*
  6703  ** Return the approximate number of bytes of memory currently
  6704  ** used by the pager and its associated cache.
  6705  */
  6706  int sqlite3PagerMemUsed(Pager *pPager){
  6707    int perPageSize = pPager->pageSize + pPager->nExtra + sizeof(PgHdr)
  6708                                       + 5*sizeof(void*);
  6709    return perPageSize*sqlite3PcachePagecount(pPager->pPCache)
  6710             + sqlite3MallocSize(pPager)
  6711             + pPager->pageSize;
  6712  }
  6713  
  6714  /*
  6715  ** Return the number of references to the specified page.
  6716  */
  6717  int sqlite3PagerPageRefcount(DbPage *pPage){
  6718    return sqlite3PcachePageRefcount(pPage);
  6719  }
  6720  
  6721  #ifdef SQLITE_TEST
  6722  /*
  6723  ** This routine is used for testing and analysis only.
  6724  */
  6725  int *sqlite3PagerStats(Pager *pPager){
  6726    static int a[11];
  6727    a[0] = sqlite3PcacheRefCount(pPager->pPCache);
  6728    a[1] = sqlite3PcachePagecount(pPager->pPCache);
  6729    a[2] = sqlite3PcacheGetCachesize(pPager->pPCache);
  6730    a[3] = pPager->eState==PAGER_OPEN ? -1 : (int) pPager->dbSize;
  6731    a[4] = pPager->eState;
  6732    a[5] = pPager->errCode;
  6733    a[6] = pPager->aStat[PAGER_STAT_HIT];
  6734    a[7] = pPager->aStat[PAGER_STAT_MISS];
  6735    a[8] = 0;  /* Used to be pPager->nOvfl */
  6736    a[9] = pPager->nRead;
  6737    a[10] = pPager->aStat[PAGER_STAT_WRITE];
  6738    return a;
  6739  }
  6740  #endif
  6741  
  6742  /*
  6743  ** Parameter eStat must be one of SQLITE_DBSTATUS_CACHE_HIT, _MISS, _WRITE,
  6744  ** or _WRITE+1.  The SQLITE_DBSTATUS_CACHE_WRITE+1 case is a translation
  6745  ** of SQLITE_DBSTATUS_CACHE_SPILL.  The _SPILL case is not contiguous because
  6746  ** it was added later.
  6747  **
  6748  ** Before returning, *pnVal is incremented by the
  6749  ** current cache hit or miss count, according to the value of eStat. If the 
  6750  ** reset parameter is non-zero, the cache hit or miss count is zeroed before 
  6751  ** returning.
  6752  */
  6753  void sqlite3PagerCacheStat(Pager *pPager, int eStat, int reset, int *pnVal){
  6754  
  6755    assert( eStat==SQLITE_DBSTATUS_CACHE_HIT
  6756         || eStat==SQLITE_DBSTATUS_CACHE_MISS
  6757         || eStat==SQLITE_DBSTATUS_CACHE_WRITE
  6758         || eStat==SQLITE_DBSTATUS_CACHE_WRITE+1
  6759    );
  6760  
  6761    assert( SQLITE_DBSTATUS_CACHE_HIT+1==SQLITE_DBSTATUS_CACHE_MISS );
  6762    assert( SQLITE_DBSTATUS_CACHE_HIT+2==SQLITE_DBSTATUS_CACHE_WRITE );
  6763    assert( PAGER_STAT_HIT==0 && PAGER_STAT_MISS==1
  6764             && PAGER_STAT_WRITE==2 && PAGER_STAT_SPILL==3 );
  6765  
  6766    eStat -= SQLITE_DBSTATUS_CACHE_HIT;
  6767    *pnVal += pPager->aStat[eStat];
  6768    if( reset ){
  6769      pPager->aStat[eStat] = 0;
  6770    }
  6771  }
  6772  
  6773  /*
  6774  ** Return true if this is an in-memory or temp-file backed pager.
  6775  */
  6776  int sqlite3PagerIsMemdb(Pager *pPager){
  6777    return pPager->tempFile;
  6778  }
  6779  
  6780  /*
  6781  ** Check that there are at least nSavepoint savepoints open. If there are
  6782  ** currently less than nSavepoints open, then open one or more savepoints
  6783  ** to make up the difference. If the number of savepoints is already
  6784  ** equal to nSavepoint, then this function is a no-op.
  6785  **
  6786  ** If a memory allocation fails, SQLITE_NOMEM is returned. If an error 
  6787  ** occurs while opening the sub-journal file, then an IO error code is
  6788  ** returned. Otherwise, SQLITE_OK.
  6789  */
  6790  static SQLITE_NOINLINE int pagerOpenSavepoint(Pager *pPager, int nSavepoint){
  6791    int rc = SQLITE_OK;                       /* Return code */
  6792    int nCurrent = pPager->nSavepoint;        /* Current number of savepoints */
  6793    int ii;                                   /* Iterator variable */
  6794    PagerSavepoint *aNew;                     /* New Pager.aSavepoint array */
  6795  
  6796    assert( pPager->eState>=PAGER_WRITER_LOCKED );
  6797    assert( assert_pager_state(pPager) );
  6798    assert( nSavepoint>nCurrent && pPager->useJournal );
  6799  
  6800    /* Grow the Pager.aSavepoint array using realloc(). Return SQLITE_NOMEM
  6801    ** if the allocation fails. Otherwise, zero the new portion in case a 
  6802    ** malloc failure occurs while populating it in the for(...) loop below.
  6803    */
  6804    aNew = (PagerSavepoint *)sqlite3Realloc(
  6805        pPager->aSavepoint, sizeof(PagerSavepoint)*nSavepoint
  6806    );
  6807    if( !aNew ){
  6808      return SQLITE_NOMEM_BKPT;
  6809    }
  6810    memset(&aNew[nCurrent], 0, (nSavepoint-nCurrent) * sizeof(PagerSavepoint));
  6811    pPager->aSavepoint = aNew;
  6812  
  6813    /* Populate the PagerSavepoint structures just allocated. */
  6814    for(ii=nCurrent; ii<nSavepoint; ii++){
  6815      aNew[ii].nOrig = pPager->dbSize;
  6816      if( isOpen(pPager->jfd) && pPager->journalOff>0 ){
  6817        aNew[ii].iOffset = pPager->journalOff;
  6818      }else{
  6819        aNew[ii].iOffset = JOURNAL_HDR_SZ(pPager);
  6820      }
  6821      aNew[ii].iSubRec = pPager->nSubRec;
  6822      aNew[ii].pInSavepoint = sqlite3BitvecCreate(pPager->dbSize);
  6823      if( !aNew[ii].pInSavepoint ){
  6824        return SQLITE_NOMEM_BKPT;
  6825      }
  6826      if( pagerUseWal(pPager) ){
  6827        sqlite3WalSavepoint(pPager->pWal, aNew[ii].aWalData);
  6828      }
  6829      pPager->nSavepoint = ii+1;
  6830    }
  6831    assert( pPager->nSavepoint==nSavepoint );
  6832    assertTruncateConstraint(pPager);
  6833    return rc;
  6834  }
  6835  int sqlite3PagerOpenSavepoint(Pager *pPager, int nSavepoint){
  6836    assert( pPager->eState>=PAGER_WRITER_LOCKED );
  6837    assert( assert_pager_state(pPager) );
  6838  
  6839    if( nSavepoint>pPager->nSavepoint && pPager->useJournal ){
  6840      return pagerOpenSavepoint(pPager, nSavepoint);
  6841    }else{
  6842      return SQLITE_OK;
  6843    }
  6844  }
  6845  
  6846  
  6847  /*
  6848  ** This function is called to rollback or release (commit) a savepoint.
  6849  ** The savepoint to release or rollback need not be the most recently 
  6850  ** created savepoint.
  6851  **
  6852  ** Parameter op is always either SAVEPOINT_ROLLBACK or SAVEPOINT_RELEASE.
  6853  ** If it is SAVEPOINT_RELEASE, then release and destroy the savepoint with
  6854  ** index iSavepoint. If it is SAVEPOINT_ROLLBACK, then rollback all changes
  6855  ** that have occurred since the specified savepoint was created.
  6856  **
  6857  ** The savepoint to rollback or release is identified by parameter 
  6858  ** iSavepoint. A value of 0 means to operate on the outermost savepoint
  6859  ** (the first created). A value of (Pager.nSavepoint-1) means operate
  6860  ** on the most recently created savepoint. If iSavepoint is greater than
  6861  ** (Pager.nSavepoint-1), then this function is a no-op.
  6862  **
  6863  ** If a negative value is passed to this function, then the current
  6864  ** transaction is rolled back. This is different to calling 
  6865  ** sqlite3PagerRollback() because this function does not terminate
  6866  ** the transaction or unlock the database, it just restores the 
  6867  ** contents of the database to its original state. 
  6868  **
  6869  ** In any case, all savepoints with an index greater than iSavepoint 
  6870  ** are destroyed. If this is a release operation (op==SAVEPOINT_RELEASE),
  6871  ** then savepoint iSavepoint is also destroyed.
  6872  **
  6873  ** This function may return SQLITE_NOMEM if a memory allocation fails,
  6874  ** or an IO error code if an IO error occurs while rolling back a 
  6875  ** savepoint. If no errors occur, SQLITE_OK is returned.
  6876  */ 
  6877  int sqlite3PagerSavepoint(Pager *pPager, int op, int iSavepoint){
  6878    int rc = pPager->errCode;
  6879    
  6880  #ifdef SQLITE_ENABLE_ZIPVFS
  6881    if( op==SAVEPOINT_RELEASE ) rc = SQLITE_OK;
  6882  #endif
  6883  
  6884    assert( op==SAVEPOINT_RELEASE || op==SAVEPOINT_ROLLBACK );
  6885    assert( iSavepoint>=0 || op==SAVEPOINT_ROLLBACK );
  6886  
  6887    if( rc==SQLITE_OK && iSavepoint<pPager->nSavepoint ){
  6888      int ii;            /* Iterator variable */
  6889      int nNew;          /* Number of remaining savepoints after this op. */
  6890  
  6891      /* Figure out how many savepoints will still be active after this
  6892      ** operation. Store this value in nNew. Then free resources associated 
  6893      ** with any savepoints that are destroyed by this operation.
  6894      */
  6895      nNew = iSavepoint + (( op==SAVEPOINT_RELEASE ) ? 0 : 1);
  6896      for(ii=nNew; ii<pPager->nSavepoint; ii++){
  6897        sqlite3BitvecDestroy(pPager->aSavepoint[ii].pInSavepoint);
  6898      }
  6899      pPager->nSavepoint = nNew;
  6900  
  6901      /* If this is a release of the outermost savepoint, truncate 
  6902      ** the sub-journal to zero bytes in size. */
  6903      if( op==SAVEPOINT_RELEASE ){
  6904        if( nNew==0 && isOpen(pPager->sjfd) ){
  6905          /* Only truncate if it is an in-memory sub-journal. */
  6906          if( sqlite3JournalIsInMemory(pPager->sjfd) ){
  6907            rc = sqlite3OsTruncate(pPager->sjfd, 0);
  6908            assert( rc==SQLITE_OK );
  6909          }
  6910          pPager->nSubRec = 0;
  6911        }
  6912      }
  6913      /* Else this is a rollback operation, playback the specified savepoint.
  6914      ** If this is a temp-file, it is possible that the journal file has
  6915      ** not yet been opened. In this case there have been no changes to
  6916      ** the database file, so the playback operation can be skipped.
  6917      */
  6918      else if( pagerUseWal(pPager) || isOpen(pPager->jfd) ){
  6919        PagerSavepoint *pSavepoint = (nNew==0)?0:&pPager->aSavepoint[nNew-1];
  6920        rc = pagerPlaybackSavepoint(pPager, pSavepoint);
  6921        assert(rc!=SQLITE_DONE);
  6922      }
  6923      
  6924  #ifdef SQLITE_ENABLE_ZIPVFS
  6925      /* If the cache has been modified but the savepoint cannot be rolled 
  6926      ** back journal_mode=off, put the pager in the error state. This way,
  6927      ** if the VFS used by this pager includes ZipVFS, the entire transaction
  6928      ** can be rolled back at the ZipVFS level.  */
  6929      else if( 
  6930          pPager->journalMode==PAGER_JOURNALMODE_OFF 
  6931       && pPager->eState>=PAGER_WRITER_CACHEMOD
  6932      ){
  6933        pPager->errCode = SQLITE_ABORT;
  6934        pPager->eState = PAGER_ERROR;
  6935        setGetterMethod(pPager);
  6936      }
  6937  #endif
  6938    }
  6939  
  6940    return rc;
  6941  }
  6942  
  6943  /*
  6944  ** Return the full pathname of the database file.
  6945  **
  6946  ** Except, if the pager is in-memory only, then return an empty string if
  6947  ** nullIfMemDb is true.  This routine is called with nullIfMemDb==1 when
  6948  ** used to report the filename to the user, for compatibility with legacy
  6949  ** behavior.  But when the Btree needs to know the filename for matching to
  6950  ** shared cache, it uses nullIfMemDb==0 so that in-memory databases can
  6951  ** participate in shared-cache.
  6952  **
  6953  ** The return value to this routine is always safe to use with
  6954  ** sqlite3_uri_parameter() and sqlite3_filename_database() and friends.
  6955  */
  6956  const char *sqlite3PagerFilename(const Pager *pPager, int nullIfMemDb){
  6957    static const char zFake[] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };
  6958    return (nullIfMemDb && pPager->memDb) ? &zFake[4] : pPager->zFilename;
  6959  }
  6960  
  6961  /*
  6962  ** Return the VFS structure for the pager.
  6963  */
  6964  sqlite3_vfs *sqlite3PagerVfs(Pager *pPager){
  6965    return pPager->pVfs;
  6966  }
  6967  
  6968  /*
  6969  ** Return the file handle for the database file associated
  6970  ** with the pager.  This might return NULL if the file has
  6971  ** not yet been opened.
  6972  */
  6973  sqlite3_file *sqlite3PagerFile(Pager *pPager){
  6974    return pPager->fd;
  6975  }
  6976  
  6977  #ifdef SQLITE_ENABLE_SETLK_TIMEOUT
  6978  /*
  6979  ** Reset the lock timeout for pager.
  6980  */
  6981  void sqlite3PagerResetLockTimeout(Pager *pPager){
  6982    int x = 0;
  6983    sqlite3OsFileControl(pPager->fd, SQLITE_FCNTL_LOCK_TIMEOUT, &x);
  6984  }
  6985  #endif
  6986  
  6987  /*
  6988  ** Return the file handle for the journal file (if it exists).
  6989  ** This will be either the rollback journal or the WAL file.
  6990  */
  6991  sqlite3_file *sqlite3PagerJrnlFile(Pager *pPager){
  6992  #if SQLITE_OMIT_WAL
  6993    return pPager->jfd;
  6994  #else
  6995    return pPager->pWal ? sqlite3WalFile(pPager->pWal) : pPager->jfd;
  6996  #endif
  6997  }
  6998  
  6999  /*
  7000  ** Return the full pathname of the journal file.
  7001  */
  7002  const char *sqlite3PagerJournalname(Pager *pPager){
  7003    return pPager->zJournal;
  7004  }
  7005  
  7006  #ifndef SQLITE_OMIT_AUTOVACUUM
  7007  /*
  7008  ** Move the page pPg to location pgno in the file.
  7009  **
  7010  ** There must be no references to the page previously located at
  7011  ** pgno (which we call pPgOld) though that page is allowed to be
  7012  ** in cache.  If the page previously located at pgno is not already
  7013  ** in the rollback journal, it is not put there by by this routine.
  7014  **
  7015  ** References to the page pPg remain valid. Updating any
  7016  ** meta-data associated with pPg (i.e. data stored in the nExtra bytes
  7017  ** allocated along with the page) is the responsibility of the caller.
  7018  **
  7019  ** A transaction must be active when this routine is called. It used to be
  7020  ** required that a statement transaction was not active, but this restriction
  7021  ** has been removed (CREATE INDEX needs to move a page when a statement
  7022  ** transaction is active).
  7023  **
  7024  ** If the fourth argument, isCommit, is non-zero, then this page is being
  7025  ** moved as part of a database reorganization just before the transaction 
  7026  ** is being committed. In this case, it is guaranteed that the database page 
  7027  ** pPg refers to will not be written to again within this transaction.
  7028  **
  7029  ** This function may return SQLITE_NOMEM or an IO error code if an error
  7030  ** occurs. Otherwise, it returns SQLITE_OK.
  7031  */
  7032  int sqlite3PagerMovepage(Pager *pPager, DbPage *pPg, Pgno pgno, int isCommit){
  7033    PgHdr *pPgOld;               /* The page being overwritten. */
  7034    Pgno needSyncPgno = 0;       /* Old value of pPg->pgno, if sync is required */
  7035    int rc;                      /* Return code */
  7036    Pgno origPgno;               /* The original page number */
  7037  
  7038    assert( pPg->nRef>0 );
  7039    assert( pPager->eState==PAGER_WRITER_CACHEMOD
  7040         || pPager->eState==PAGER_WRITER_DBMOD
  7041    );
  7042    assert( assert_pager_state(pPager) );
  7043  
  7044    /* In order to be able to rollback, an in-memory database must journal
  7045    ** the page we are moving from.
  7046    */
  7047    assert( pPager->tempFile || !MEMDB );
  7048    if( pPager->tempFile ){
  7049      rc = sqlite3PagerWrite(pPg);
  7050      if( rc ) return rc;
  7051    }
  7052  
  7053    /* If the page being moved is dirty and has not been saved by the latest
  7054    ** savepoint, then save the current contents of the page into the 
  7055    ** sub-journal now. This is required to handle the following scenario:
  7056    **
  7057    **   BEGIN;
  7058    **     <journal page X, then modify it in memory>
  7059    **     SAVEPOINT one;
  7060    **       <Move page X to location Y>
  7061    **     ROLLBACK TO one;
  7062    **
  7063    ** If page X were not written to the sub-journal here, it would not
  7064    ** be possible to restore its contents when the "ROLLBACK TO one"
  7065    ** statement were is processed.
  7066    **
  7067    ** subjournalPage() may need to allocate space to store pPg->pgno into
  7068    ** one or more savepoint bitvecs. This is the reason this function
  7069    ** may return SQLITE_NOMEM.
  7070    */
  7071    if( (pPg->flags & PGHDR_DIRTY)!=0
  7072     && SQLITE_OK!=(rc = subjournalPageIfRequired(pPg))
  7073    ){
  7074      return rc;
  7075    }
  7076  
  7077    PAGERTRACE(("MOVE %d page %d (needSync=%d) moves to %d\n", 
  7078        PAGERID(pPager), pPg->pgno, (pPg->flags&PGHDR_NEED_SYNC)?1:0, pgno));
  7079    IOTRACE(("MOVE %p %d %d\n", pPager, pPg->pgno, pgno))
  7080  
  7081    /* If the journal needs to be sync()ed before page pPg->pgno can
  7082    ** be written to, store pPg->pgno in local variable needSyncPgno.
  7083    **
  7084    ** If the isCommit flag is set, there is no need to remember that
  7085    ** the journal needs to be sync()ed before database page pPg->pgno 
  7086    ** can be written to. The caller has already promised not to write to it.
  7087    */
  7088    if( (pPg->flags&PGHDR_NEED_SYNC) && !isCommit ){
  7089      needSyncPgno = pPg->pgno;
  7090      assert( pPager->journalMode==PAGER_JOURNALMODE_OFF ||
  7091              pageInJournal(pPager, pPg) || pPg->pgno>pPager->dbOrigSize );
  7092      assert( pPg->flags&PGHDR_DIRTY );
  7093    }
  7094  
  7095    /* If the cache contains a page with page-number pgno, remove it
  7096    ** from its hash chain. Also, if the PGHDR_NEED_SYNC flag was set for 
  7097    ** page pgno before the 'move' operation, it needs to be retained 
  7098    ** for the page moved there.
  7099    */
  7100    pPg->flags &= ~PGHDR_NEED_SYNC;
  7101    pPgOld = sqlite3PagerLookup(pPager, pgno);
  7102    assert( !pPgOld || pPgOld->nRef==1 || CORRUPT_DB );
  7103    if( pPgOld ){
  7104      if( pPgOld->nRef>1 ){
  7105        sqlite3PagerUnrefNotNull(pPgOld);
  7106        return SQLITE_CORRUPT_BKPT;
  7107      }
  7108      pPg->flags |= (pPgOld->flags&PGHDR_NEED_SYNC);
  7109      if( pPager->tempFile ){
  7110        /* Do not discard pages from an in-memory database since we might
  7111        ** need to rollback later.  Just move the page out of the way. */
  7112        sqlite3PcacheMove(pPgOld, pPager->dbSize+1);
  7113      }else{
  7114        sqlite3PcacheDrop(pPgOld);
  7115      }
  7116    }
  7117  
  7118    origPgno = pPg->pgno;
  7119    sqlite3PcacheMove(pPg, pgno);
  7120    sqlite3PcacheMakeDirty(pPg);
  7121  
  7122    /* For an in-memory database, make sure the original page continues
  7123    ** to exist, in case the transaction needs to roll back.  Use pPgOld
  7124    ** as the original page since it has already been allocated.
  7125    */
  7126    if( pPager->tempFile && pPgOld ){
  7127      sqlite3PcacheMove(pPgOld, origPgno);
  7128      sqlite3PagerUnrefNotNull(pPgOld);
  7129    }
  7130  
  7131    if( needSyncPgno ){
  7132      /* If needSyncPgno is non-zero, then the journal file needs to be 
  7133      ** sync()ed before any data is written to database file page needSyncPgno.
  7134      ** Currently, no such page exists in the page-cache and the 
  7135      ** "is journaled" bitvec flag has been set. This needs to be remedied by
  7136      ** loading the page into the pager-cache and setting the PGHDR_NEED_SYNC
  7137      ** flag.
  7138      **
  7139      ** If the attempt to load the page into the page-cache fails, (due
  7140      ** to a malloc() or IO failure), clear the bit in the pInJournal[]
  7141      ** array. Otherwise, if the page is loaded and written again in
  7142      ** this transaction, it may be written to the database file before
  7143      ** it is synced into the journal file. This way, it may end up in
  7144      ** the journal file twice, but that is not a problem.
  7145      */
  7146      PgHdr *pPgHdr;
  7147      rc = sqlite3PagerGet(pPager, needSyncPgno, &pPgHdr, 0);
  7148      if( rc!=SQLITE_OK ){
  7149        if( needSyncPgno<=pPager->dbOrigSize ){
  7150          assert( pPager->pTmpSpace!=0 );
  7151          sqlite3BitvecClear(pPager->pInJournal, needSyncPgno, pPager->pTmpSpace);
  7152        }
  7153        return rc;
  7154      }
  7155      pPgHdr->flags |= PGHDR_NEED_SYNC;
  7156      sqlite3PcacheMakeDirty(pPgHdr);
  7157      sqlite3PagerUnrefNotNull(pPgHdr);
  7158    }
  7159  
  7160    return SQLITE_OK;
  7161  }
  7162  #endif
  7163  
  7164  /*
  7165  ** The page handle passed as the first argument refers to a dirty page 
  7166  ** with a page number other than iNew. This function changes the page's 
  7167  ** page number to iNew and sets the value of the PgHdr.flags field to 
  7168  ** the value passed as the third parameter.
  7169  */
  7170  void sqlite3PagerRekey(DbPage *pPg, Pgno iNew, u16 flags){
  7171    assert( pPg->pgno!=iNew );
  7172    pPg->flags = flags;
  7173    sqlite3PcacheMove(pPg, iNew);
  7174  }
  7175  
  7176  /*
  7177  ** Return a pointer to the data for the specified page.
  7178  */
  7179  void *sqlite3PagerGetData(DbPage *pPg){
  7180    assert( pPg->nRef>0 || pPg->pPager->memDb );
  7181    return pPg->pData;
  7182  }
  7183  
  7184  /*
  7185  ** Return a pointer to the Pager.nExtra bytes of "extra" space 
  7186  ** allocated along with the specified page.
  7187  */
  7188  void *sqlite3PagerGetExtra(DbPage *pPg){
  7189    return pPg->pExtra;
  7190  }
  7191  
  7192  /*
  7193  ** Get/set the locking-mode for this pager. Parameter eMode must be one
  7194  ** of PAGER_LOCKINGMODE_QUERY, PAGER_LOCKINGMODE_NORMAL or 
  7195  ** PAGER_LOCKINGMODE_EXCLUSIVE. If the parameter is not _QUERY, then
  7196  ** the locking-mode is set to the value specified.
  7197  **
  7198  ** The returned value is either PAGER_LOCKINGMODE_NORMAL or
  7199  ** PAGER_LOCKINGMODE_EXCLUSIVE, indicating the current (possibly updated)
  7200  ** locking-mode.
  7201  */
  7202  int sqlite3PagerLockingMode(Pager *pPager, int eMode){
  7203    assert( eMode==PAGER_LOCKINGMODE_QUERY
  7204              || eMode==PAGER_LOCKINGMODE_NORMAL
  7205              || eMode==PAGER_LOCKINGMODE_EXCLUSIVE );
  7206    assert( PAGER_LOCKINGMODE_QUERY<0 );
  7207    assert( PAGER_LOCKINGMODE_NORMAL>=0 && PAGER_LOCKINGMODE_EXCLUSIVE>=0 );
  7208    assert( pPager->exclusiveMode || 0==sqlite3WalHeapMemory(pPager->pWal) );
  7209    if( eMode>=0 && !pPager->tempFile && !sqlite3WalHeapMemory(pPager->pWal) ){
  7210      pPager->exclusiveMode = (u8)eMode;
  7211    }
  7212    return (int)pPager->exclusiveMode;
  7213  }
  7214  
  7215  /*
  7216  ** Set the journal-mode for this pager. Parameter eMode must be one of:
  7217  **
  7218  **    PAGER_JOURNALMODE_DELETE
  7219  **    PAGER_JOURNALMODE_TRUNCATE
  7220  **    PAGER_JOURNALMODE_PERSIST
  7221  **    PAGER_JOURNALMODE_OFF
  7222  **    PAGER_JOURNALMODE_MEMORY
  7223  **    PAGER_JOURNALMODE_WAL
  7224  **
  7225  ** The journalmode is set to the value specified if the change is allowed.
  7226  ** The change may be disallowed for the following reasons:
  7227  **
  7228  **   *  An in-memory database can only have its journal_mode set to _OFF
  7229  **      or _MEMORY.
  7230  **
  7231  **   *  Temporary databases cannot have _WAL journalmode.
  7232  **
  7233  ** The returned indicate the current (possibly updated) journal-mode.
  7234  */
  7235  int sqlite3PagerSetJournalMode(Pager *pPager, int eMode){
  7236    u8 eOld = pPager->journalMode;    /* Prior journalmode */
  7237  
  7238    /* The eMode parameter is always valid */
  7239    assert(      eMode==PAGER_JOURNALMODE_DELETE
  7240              || eMode==PAGER_JOURNALMODE_TRUNCATE
  7241              || eMode==PAGER_JOURNALMODE_PERSIST
  7242              || eMode==PAGER_JOURNALMODE_OFF 
  7243              || eMode==PAGER_JOURNALMODE_WAL 
  7244              || eMode==PAGER_JOURNALMODE_MEMORY );
  7245  
  7246    /* This routine is only called from the OP_JournalMode opcode, and
  7247    ** the logic there will never allow a temporary file to be changed
  7248    ** to WAL mode.
  7249    */
  7250    assert( pPager->tempFile==0 || eMode!=PAGER_JOURNALMODE_WAL );
  7251  
  7252    /* Do allow the journalmode of an in-memory database to be set to
  7253    ** anything other than MEMORY or OFF
  7254    */
  7255    if( MEMDB ){
  7256      assert( eOld==PAGER_JOURNALMODE_MEMORY || eOld==PAGER_JOURNALMODE_OFF );
  7257      if( eMode!=PAGER_JOURNALMODE_MEMORY && eMode!=PAGER_JOURNALMODE_OFF ){
  7258        eMode = eOld;
  7259      }
  7260    }
  7261  
  7262    if( eMode!=eOld ){
  7263  
  7264      /* Change the journal mode. */
  7265      assert( pPager->eState!=PAGER_ERROR );
  7266      pPager->journalMode = (u8)eMode;
  7267  
  7268      /* When transistioning from TRUNCATE or PERSIST to any other journal
  7269      ** mode except WAL, unless the pager is in locking_mode=exclusive mode,
  7270      ** delete the journal file.
  7271      */
  7272      assert( (PAGER_JOURNALMODE_TRUNCATE & 5)==1 );
  7273      assert( (PAGER_JOURNALMODE_PERSIST & 5)==1 );
  7274      assert( (PAGER_JOURNALMODE_DELETE & 5)==0 );
  7275      assert( (PAGER_JOURNALMODE_MEMORY & 5)==4 );
  7276      assert( (PAGER_JOURNALMODE_OFF & 5)==0 );
  7277      assert( (PAGER_JOURNALMODE_WAL & 5)==5 );
  7278  
  7279      assert( isOpen(pPager->fd) || pPager->exclusiveMode );
  7280      if( !pPager->exclusiveMode && (eOld & 5)==1 && (eMode & 1)==0 ){
  7281  
  7282        /* In this case we would like to delete the journal file. If it is
  7283        ** not possible, then that is not a problem. Deleting the journal file
  7284        ** here is an optimization only.
  7285        **
  7286        ** Before deleting the journal file, obtain a RESERVED lock on the
  7287        ** database file. This ensures that the journal file is not deleted
  7288        ** while it is in use by some other client.
  7289        */
  7290        sqlite3OsClose(pPager->jfd);
  7291        if( pPager->eLock>=RESERVED_LOCK ){
  7292          sqlite3OsDelete(pPager->pVfs, pPager->zJournal, 0);
  7293        }else{
  7294          int rc = SQLITE_OK;
  7295          int state = pPager->eState;
  7296          assert( state==PAGER_OPEN || state==PAGER_READER );
  7297          if( state==PAGER_OPEN ){
  7298            rc = sqlite3PagerSharedLock(pPager);
  7299          }
  7300          if( pPager->eState==PAGER_READER ){
  7301            assert( rc==SQLITE_OK );
  7302            rc = pagerLockDb(pPager, RESERVED_LOCK);
  7303          }
  7304          if( rc==SQLITE_OK ){
  7305            sqlite3OsDelete(pPager->pVfs, pPager->zJournal, 0);
  7306          }
  7307          if( rc==SQLITE_OK && state==PAGER_READER ){
  7308            pagerUnlockDb(pPager, SHARED_LOCK);
  7309          }else if( state==PAGER_OPEN ){
  7310            pager_unlock(pPager);
  7311          }
  7312          assert( state==pPager->eState );
  7313        }
  7314      }else if( eMode==PAGER_JOURNALMODE_OFF ){
  7315        sqlite3OsClose(pPager->jfd);
  7316      }
  7317    }
  7318  
  7319    /* Return the new journal mode */
  7320    return (int)pPager->journalMode;
  7321  }
  7322  
  7323  /*
  7324  ** Return the current journal mode.
  7325  */
  7326  int sqlite3PagerGetJournalMode(Pager *pPager){
  7327    return (int)pPager->journalMode;
  7328  }
  7329  
  7330  /*
  7331  ** Return TRUE if the pager is in a state where it is OK to change the
  7332  ** journalmode.  Journalmode changes can only happen when the database
  7333  ** is unmodified.
  7334  */
  7335  int sqlite3PagerOkToChangeJournalMode(Pager *pPager){
  7336    assert( assert_pager_state(pPager) );
  7337    if( pPager->eState>=PAGER_WRITER_CACHEMOD ) return 0;
  7338    if( NEVER(isOpen(pPager->jfd) && pPager->journalOff>0) ) return 0;
  7339    return 1;
  7340  }
  7341  
  7342  /*
  7343  ** Get/set the size-limit used for persistent journal files.
  7344  **
  7345  ** Setting the size limit to -1 means no limit is enforced.
  7346  ** An attempt to set a limit smaller than -1 is a no-op.
  7347  */
  7348  i64 sqlite3PagerJournalSizeLimit(Pager *pPager, i64 iLimit){
  7349    if( iLimit>=-1 ){
  7350      pPager->journalSizeLimit = iLimit;
  7351      sqlite3WalLimit(pPager->pWal, iLimit);
  7352    }
  7353    return pPager->journalSizeLimit;
  7354  }
  7355  
  7356  /*
  7357  ** Return a pointer to the pPager->pBackup variable. The backup module
  7358  ** in backup.c maintains the content of this variable. This module
  7359  ** uses it opaquely as an argument to sqlite3BackupRestart() and
  7360  ** sqlite3BackupUpdate() only.
  7361  */
  7362  sqlite3_backup **sqlite3PagerBackupPtr(Pager *pPager){
  7363    return &pPager->pBackup;
  7364  }
  7365  
  7366  #ifndef SQLITE_OMIT_VACUUM
  7367  /*
  7368  ** Unless this is an in-memory or temporary database, clear the pager cache.
  7369  */
  7370  void sqlite3PagerClearCache(Pager *pPager){
  7371    assert( MEMDB==0 || pPager->tempFile );
  7372    if( pPager->tempFile==0 ) pager_reset(pPager);
  7373  }
  7374  #endif
  7375  
  7376  
  7377  #ifndef SQLITE_OMIT_WAL
  7378  /*
  7379  ** This function is called when the user invokes "PRAGMA wal_checkpoint",
  7380  ** "PRAGMA wal_blocking_checkpoint" or calls the sqlite3_wal_checkpoint()
  7381  ** or wal_blocking_checkpoint() API functions.
  7382  **
  7383  ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART.
  7384  */
  7385  int sqlite3PagerCheckpoint(
  7386    Pager *pPager,                  /* Checkpoint on this pager */
  7387    sqlite3 *db,                    /* Db handle used to check for interrupts */
  7388    int eMode,                      /* Type of checkpoint */
  7389    int *pnLog,                     /* OUT: Final number of frames in log */
  7390    int *pnCkpt                     /* OUT: Final number of checkpointed frames */
  7391  ){
  7392    int rc = SQLITE_OK;
  7393    if( pPager->pWal ){
  7394      rc = sqlite3WalCheckpoint(pPager->pWal, db, eMode,
  7395          (eMode==SQLITE_CHECKPOINT_PASSIVE ? 0 : pPager->xBusyHandler),
  7396          pPager->pBusyHandlerArg,
  7397          pPager->walSyncFlags, pPager->pageSize, (u8 *)pPager->pTmpSpace,
  7398          pnLog, pnCkpt
  7399      );
  7400      sqlite3PagerResetLockTimeout(pPager);
  7401    }
  7402    return rc;
  7403  }
  7404  
  7405  int sqlite3PagerWalCallback(Pager *pPager){
  7406    return sqlite3WalCallback(pPager->pWal);
  7407  }
  7408  
  7409  /*
  7410  ** Return true if the underlying VFS for the given pager supports the
  7411  ** primitives necessary for write-ahead logging.
  7412  */
  7413  int sqlite3PagerWalSupported(Pager *pPager){
  7414    const sqlite3_io_methods *pMethods = pPager->fd->pMethods;
  7415    if( pPager->noLock ) return 0;
  7416    return pPager->exclusiveMode || (pMethods->iVersion>=2 && pMethods->xShmMap);
  7417  }
  7418  
  7419  /*
  7420  ** Attempt to take an exclusive lock on the database file. If a PENDING lock
  7421  ** is obtained instead, immediately release it.
  7422  */
  7423  static int pagerExclusiveLock(Pager *pPager){
  7424    int rc;                         /* Return code */
  7425  
  7426    assert( pPager->eLock==SHARED_LOCK || pPager->eLock==EXCLUSIVE_LOCK );
  7427    rc = pagerLockDb(pPager, EXCLUSIVE_LOCK);
  7428    if( rc!=SQLITE_OK ){
  7429      /* If the attempt to grab the exclusive lock failed, release the 
  7430      ** pending lock that may have been obtained instead.  */
  7431      pagerUnlockDb(pPager, SHARED_LOCK);
  7432    }
  7433  
  7434    return rc;
  7435  }
  7436  
  7437  /*
  7438  ** Call sqlite3WalOpen() to open the WAL handle. If the pager is in 
  7439  ** exclusive-locking mode when this function is called, take an EXCLUSIVE
  7440  ** lock on the database file and use heap-memory to store the wal-index
  7441  ** in. Otherwise, use the normal shared-memory.
  7442  */
  7443  static int pagerOpenWal(Pager *pPager){
  7444    int rc = SQLITE_OK;
  7445  
  7446    assert( pPager->pWal==0 && pPager->tempFile==0 );
  7447    assert( pPager->eLock==SHARED_LOCK || pPager->eLock==EXCLUSIVE_LOCK );
  7448  
  7449    /* If the pager is already in exclusive-mode, the WAL module will use 
  7450    ** heap-memory for the wal-index instead of the VFS shared-memory 
  7451    ** implementation. Take the exclusive lock now, before opening the WAL
  7452    ** file, to make sure this is safe.
  7453    */
  7454    if( pPager->exclusiveMode ){
  7455      rc = pagerExclusiveLock(pPager);
  7456    }
  7457  
  7458    /* Open the connection to the log file. If this operation fails, 
  7459    ** (e.g. due to malloc() failure), return an error code.
  7460    */
  7461    if( rc==SQLITE_OK ){
  7462      rc = sqlite3WalOpen(pPager->pVfs,
  7463          pPager->fd, pPager->zWal, pPager->exclusiveMode,
  7464          pPager->journalSizeLimit, &pPager->pWal
  7465      );
  7466    }
  7467    pagerFixMaplimit(pPager);
  7468  
  7469    return rc;
  7470  }
  7471  
  7472  
  7473  /*
  7474  ** The caller must be holding a SHARED lock on the database file to call
  7475  ** this function.
  7476  **
  7477  ** If the pager passed as the first argument is open on a real database
  7478  ** file (not a temp file or an in-memory database), and the WAL file
  7479  ** is not already open, make an attempt to open it now. If successful,
  7480  ** return SQLITE_OK. If an error occurs or the VFS used by the pager does 
  7481  ** not support the xShmXXX() methods, return an error code. *pbOpen is
  7482  ** not modified in either case.
  7483  **
  7484  ** If the pager is open on a temp-file (or in-memory database), or if
  7485  ** the WAL file is already open, set *pbOpen to 1 and return SQLITE_OK
  7486  ** without doing anything.
  7487  */
  7488  int sqlite3PagerOpenWal(
  7489    Pager *pPager,                  /* Pager object */
  7490    int *pbOpen                     /* OUT: Set to true if call is a no-op */
  7491  ){
  7492    int rc = SQLITE_OK;             /* Return code */
  7493  
  7494    assert( assert_pager_state(pPager) );
  7495    assert( pPager->eState==PAGER_OPEN   || pbOpen );
  7496    assert( pPager->eState==PAGER_READER || !pbOpen );
  7497    assert( pbOpen==0 || *pbOpen==0 );
  7498    assert( pbOpen!=0 || (!pPager->tempFile && !pPager->pWal) );
  7499  
  7500    if( !pPager->tempFile && !pPager->pWal ){
  7501      if( !sqlite3PagerWalSupported(pPager) ) return SQLITE_CANTOPEN;
  7502  
  7503      /* Close any rollback journal previously open */
  7504      sqlite3OsClose(pPager->jfd);
  7505  
  7506      rc = pagerOpenWal(pPager);
  7507      if( rc==SQLITE_OK ){
  7508        pPager->journalMode = PAGER_JOURNALMODE_WAL;
  7509        pPager->eState = PAGER_OPEN;
  7510      }
  7511    }else{
  7512      *pbOpen = 1;
  7513    }
  7514  
  7515    return rc;
  7516  }
  7517  
  7518  /*
  7519  ** This function is called to close the connection to the log file prior
  7520  ** to switching from WAL to rollback mode.
  7521  **
  7522  ** Before closing the log file, this function attempts to take an 
  7523  ** EXCLUSIVE lock on the database file. If this cannot be obtained, an
  7524  ** error (SQLITE_BUSY) is returned and the log connection is not closed.
  7525  ** If successful, the EXCLUSIVE lock is not released before returning.
  7526  */
  7527  int sqlite3PagerCloseWal(Pager *pPager, sqlite3 *db){
  7528    int rc = SQLITE_OK;
  7529  
  7530    assert( pPager->journalMode==PAGER_JOURNALMODE_WAL );
  7531  
  7532    /* If the log file is not already open, but does exist in the file-system,
  7533    ** it may need to be checkpointed before the connection can switch to
  7534    ** rollback mode. Open it now so this can happen.
  7535    */
  7536    if( !pPager->pWal ){
  7537      int logexists = 0;
  7538      rc = pagerLockDb(pPager, SHARED_LOCK);
  7539      if( rc==SQLITE_OK ){
  7540        rc = sqlite3OsAccess(
  7541            pPager->pVfs, pPager->zWal, SQLITE_ACCESS_EXISTS, &logexists
  7542        );
  7543      }
  7544      if( rc==SQLITE_OK && logexists ){
  7545        rc = pagerOpenWal(pPager);
  7546      }
  7547    }
  7548      
  7549    /* Checkpoint and close the log. Because an EXCLUSIVE lock is held on
  7550    ** the database file, the log and log-summary files will be deleted.
  7551    */
  7552    if( rc==SQLITE_OK && pPager->pWal ){
  7553      rc = pagerExclusiveLock(pPager);
  7554      if( rc==SQLITE_OK ){
  7555        rc = sqlite3WalClose(pPager->pWal, db, pPager->walSyncFlags,
  7556                             pPager->pageSize, (u8*)pPager->pTmpSpace);
  7557        pPager->pWal = 0;
  7558        pagerFixMaplimit(pPager);
  7559        if( rc && !pPager->exclusiveMode ) pagerUnlockDb(pPager, SHARED_LOCK);
  7560      }
  7561    }
  7562    return rc;
  7563  }
  7564  
  7565  
  7566  
  7567  #ifdef SQLITE_ENABLE_SNAPSHOT
  7568  /*
  7569  ** If this is a WAL database, obtain a snapshot handle for the snapshot
  7570  ** currently open. Otherwise, return an error.
  7571  */
  7572  int sqlite3PagerSnapshotGet(Pager *pPager, sqlite3_snapshot **ppSnapshot){
  7573    int rc = SQLITE_ERROR;
  7574    if( pPager->pWal ){
  7575      rc = sqlite3WalSnapshotGet(pPager->pWal, ppSnapshot);
  7576    }
  7577    return rc;
  7578  }
  7579  
  7580  /*
  7581  ** If this is a WAL database, store a pointer to pSnapshot. Next time a
  7582  ** read transaction is opened, attempt to read from the snapshot it 
  7583  ** identifies. If this is not a WAL database, return an error.
  7584  */
  7585  int sqlite3PagerSnapshotOpen(Pager *pPager, sqlite3_snapshot *pSnapshot){
  7586    int rc = SQLITE_OK;
  7587    if( pPager->pWal ){
  7588      sqlite3WalSnapshotOpen(pPager->pWal, pSnapshot);
  7589    }else{
  7590      rc = SQLITE_ERROR;
  7591    }
  7592    return rc;
  7593  }
  7594  
  7595  /*
  7596  ** If this is a WAL database, call sqlite3WalSnapshotRecover(). If this 
  7597  ** is not a WAL database, return an error.
  7598  */
  7599  int sqlite3PagerSnapshotRecover(Pager *pPager){
  7600    int rc;
  7601    if( pPager->pWal ){
  7602      rc = sqlite3WalSnapshotRecover(pPager->pWal);
  7603    }else{
  7604      rc = SQLITE_ERROR;
  7605    }
  7606    return rc;
  7607  }
  7608  
  7609  /*
  7610  ** The caller currently has a read transaction open on the database.
  7611  ** If this is not a WAL database, SQLITE_ERROR is returned. Otherwise,
  7612  ** this function takes a SHARED lock on the CHECKPOINTER slot and then
  7613  ** checks if the snapshot passed as the second argument is still 
  7614  ** available. If so, SQLITE_OK is returned.
  7615  **
  7616  ** If the snapshot is not available, SQLITE_ERROR is returned. Or, if
  7617  ** the CHECKPOINTER lock cannot be obtained, SQLITE_BUSY. If any error
  7618  ** occurs (any value other than SQLITE_OK is returned), the CHECKPOINTER
  7619  ** lock is released before returning.
  7620  */
  7621  int sqlite3PagerSnapshotCheck(Pager *pPager, sqlite3_snapshot *pSnapshot){
  7622    int rc;
  7623    if( pPager->pWal ){
  7624      rc = sqlite3WalSnapshotCheck(pPager->pWal, pSnapshot);
  7625    }else{
  7626      rc = SQLITE_ERROR;
  7627    }
  7628    return rc;
  7629  }
  7630  
  7631  /*
  7632  ** Release a lock obtained by an earlier successful call to
  7633  ** sqlite3PagerSnapshotCheck().
  7634  */
  7635  void sqlite3PagerSnapshotUnlock(Pager *pPager){
  7636    assert( pPager->pWal );
  7637    sqlite3WalSnapshotUnlock(pPager->pWal);
  7638  }
  7639  
  7640  #endif /* SQLITE_ENABLE_SNAPSHOT */
  7641  #endif /* !SQLITE_OMIT_WAL */
  7642  
  7643  #ifdef SQLITE_ENABLE_ZIPVFS
  7644  /*
  7645  ** A read-lock must be held on the pager when this function is called. If
  7646  ** the pager is in WAL mode and the WAL file currently contains one or more
  7647  ** frames, return the size in bytes of the page images stored within the
  7648  ** WAL frames. Otherwise, if this is not a WAL database or the WAL file
  7649  ** is empty, return 0.
  7650  */
  7651  int sqlite3PagerWalFramesize(Pager *pPager){
  7652    assert( pPager->eState>=PAGER_READER );
  7653    return sqlite3WalFramesize(pPager->pWal);
  7654  }
  7655  #endif
  7656  
  7657  #endif /* SQLITE_OMIT_DISKIO */