Merge Chromium + Blink git repositories
[chromium-blink-merge.git] / third_party / sqlite / sqlite-src-3080704 / src / pager.c
blobd840a39a159f4d56b1d45234ed54e012c843bf73
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.
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.
21 #ifndef SQLITE_OMIT_DISKIO
22 #include "sqliteInt.h"
23 #include "wal.h"
26 /******************* NOTES ON THE DESIGN OF THE PAGER ************************
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.
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.
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.
98 ** (10) The pattern of bits in bytes 24 through 39 shall not repeat in less
99 ** than one billion transactions.
101 ** (11) A database file is well-formed at the beginning and at the conclusion
102 ** of every transaction.
104 ** (12) An EXCLUSIVE lock is held on the database file when writing to
105 ** the database file.
107 ** (13) A SHARED lock is held on the database file while reading any
108 ** content out of the database file.
110 ******************************************************************************/
113 ** Macros for troubleshooting. Normally turned off
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
124 ** The following two macros are used within the PAGERTRACE() macros above
125 ** to print out file-descriptors.
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.
131 #define PAGERID(p) ((int)(p->fd))
132 #define FILEHANDLEID(fd) ((int)fd)
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.
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-------->+
157 ** List of state transitions and the C [function] that performs each:
159 ** OPEN -> READER [sqlite3PagerSharedLock]
160 ** READER -> OPEN [pager_unlock]
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]
168 ** WRITER_*** -> ERROR [pager_error]
169 ** ERROR -> OPEN [pager_unlock]
172 ** OPEN:
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.
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.
182 ** READER:
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.
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).
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.
206 ** WRITER_LOCKED:
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.
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.
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.
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.
235 ** WRITER_CACHEMOD:
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.
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.
248 ** WRITER_DBMOD:
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).
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).
262 ** WRITER_FINISHED:
264 ** It is not possible for a WAL connection to enter this state.
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.
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.
280 ** ERROR:
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.
287 ** Temporary pager files may enter the ERROR state, but in-memory pagers
288 ** cannot.
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.
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.
309 ** Specifically, the pager jumps into the ERROR state if:
311 ** 1. An error occurs while attempting a rollback. This happens in
312 ** function sqlite3PagerRollback().
314 ** 2. An error occurs while attempting to finalize a journal file
315 ** following a commit in function sqlite3PagerCommitPhaseTwo().
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.
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.
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.
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.
338 ** Notes:
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.
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".
349 ** * See also: assert_pager_state().
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
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.
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.
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.
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.
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.
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.
404 ** Pager.eLock may only be set to UNKNOWN_LOCK when the pager is in
405 ** PAGER_OPEN state.
407 #define UNKNOWN_LOCK (EXCLUSIVE_LOCK+1)
410 ** A macro used for invoking the codec if there is one
412 #ifdef SQLITE_HAS_CODEC
413 # define CODEC1(P,D,N,X,E) \
414 if( P->xCodec && P->xCodec(P->pCodec,D,N,X)==0 ){ E; }
415 # define CODEC2(P,D,N,X,E,O) \
416 if( P->xCodec==0 ){ O=(char*)D; }else \
417 if( (O=(char*)(P->xCodec(P->pCodec,D,N,X)))==0 ){ E; }
418 #else
419 # define CODEC1(P,D,N,X,E) /* NO-OP */
420 # define CODEC2(P,D,N,X,E,O) O=(char*)D
421 #endif
424 ** The maximum allowed sector size. 64KiB. If the xSectorsize() method
425 ** returns a value larger than this, then MAX_SECTOR_SIZE is used instead.
426 ** This could conceivably cause corruption following a power failure on
427 ** such a system. This is currently an undocumented limit.
429 #define MAX_SECTOR_SIZE 0x10000
432 ** An instance of the following structure is allocated for each active
433 ** savepoint and statement transaction in the system. All such structures
434 ** are stored in the Pager.aSavepoint[] array, which is allocated and
435 ** resized using sqlite3Realloc().
437 ** When a savepoint is created, the PagerSavepoint.iHdrOffset field is
438 ** set to 0. If a journal-header is written into the main journal while
439 ** the savepoint is active, then iHdrOffset is set to the byte offset
440 ** immediately following the last journal record written into the main
441 ** journal before the journal-header. This is required during savepoint
442 ** rollback (see pagerPlaybackSavepoint()).
444 typedef struct PagerSavepoint PagerSavepoint;
445 struct PagerSavepoint {
446 i64 iOffset; /* Starting offset in main journal */
447 i64 iHdrOffset; /* See above */
448 Bitvec *pInSavepoint; /* Set of pages in this savepoint */
449 Pgno nOrig; /* Original number of pages in file */
450 Pgno iSubRec; /* Index of first record in sub-journal */
451 #ifndef SQLITE_OMIT_WAL
452 u32 aWalData[WAL_SAVEPOINT_NDATA]; /* WAL savepoint context */
453 #endif
457 ** Bits of the Pager.doNotSpill flag. See further description below.
459 #define SPILLFLAG_OFF 0x01 /* Never spill cache. Set via pragma */
460 #define SPILLFLAG_ROLLBACK 0x02 /* Current rolling back, so do not spill */
461 #define SPILLFLAG_NOSYNC 0x04 /* Spill is ok, but do not sync */
464 ** An open page cache is an instance of struct Pager. A description of
465 ** some of the more important member variables follows:
467 ** eState
469 ** The current 'state' of the pager object. See the comment and state
470 ** diagram above for a description of the pager state.
472 ** eLock
474 ** For a real on-disk database, the current lock held on the database file -
475 ** NO_LOCK, SHARED_LOCK, RESERVED_LOCK or EXCLUSIVE_LOCK.
477 ** For a temporary or in-memory database (neither of which require any
478 ** locks), this variable is always set to EXCLUSIVE_LOCK. Since such
479 ** databases always have Pager.exclusiveMode==1, this tricks the pager
480 ** logic into thinking that it already has all the locks it will ever
481 ** need (and no reason to release them).
483 ** In some (obscure) circumstances, this variable may also be set to
484 ** UNKNOWN_LOCK. See the comment above the #define of UNKNOWN_LOCK for
485 ** details.
487 ** changeCountDone
489 ** This boolean variable is used to make sure that the change-counter
490 ** (the 4-byte header field at byte offset 24 of the database file) is
491 ** not updated more often than necessary.
493 ** It is set to true when the change-counter field is updated, which
494 ** can only happen if an exclusive lock is held on the database file.
495 ** It is cleared (set to false) whenever an exclusive lock is
496 ** relinquished on the database file. Each time a transaction is committed,
497 ** The changeCountDone flag is inspected. If it is true, the work of
498 ** updating the change-counter is omitted for the current transaction.
500 ** This mechanism means that when running in exclusive mode, a connection
501 ** need only update the change-counter once, for the first transaction
502 ** committed.
504 ** setMaster
506 ** When PagerCommitPhaseOne() is called to commit a transaction, it may
507 ** (or may not) specify a master-journal name to be written into the
508 ** journal file before it is synced to disk.
510 ** Whether or not a journal file contains a master-journal pointer affects
511 ** the way in which the journal file is finalized after the transaction is
512 ** committed or rolled back when running in "journal_mode=PERSIST" mode.
513 ** If a journal file does not contain a master-journal pointer, it is
514 ** finalized by overwriting the first journal header with zeroes. If
515 ** it does contain a master-journal pointer the journal file is finalized
516 ** by truncating it to zero bytes, just as if the connection were
517 ** running in "journal_mode=truncate" mode.
519 ** Journal files that contain master journal pointers cannot be finalized
520 ** simply by overwriting the first journal-header with zeroes, as the
521 ** master journal pointer could interfere with hot-journal rollback of any
522 ** subsequently interrupted transaction that reuses the journal file.
524 ** The flag is cleared as soon as the journal file is finalized (either
525 ** by PagerCommitPhaseTwo or PagerRollback). If an IO error prevents the
526 ** journal file from being successfully finalized, the setMaster flag
527 ** is cleared anyway (and the pager will move to ERROR state).
529 ** doNotSpill
531 ** This variables control the behavior of cache-spills (calls made by
532 ** the pcache module to the pagerStress() routine to write cached data
533 ** to the file-system in order to free up memory).
535 ** When bits SPILLFLAG_OFF or SPILLFLAG_ROLLBACK of doNotSpill are set,
536 ** writing to the database from pagerStress() is disabled altogether.
537 ** The SPILLFLAG_ROLLBACK case is done in a very obscure case that
538 ** comes up during savepoint rollback that requires the pcache module
539 ** to allocate a new page to prevent the journal file from being written
540 ** while it is being traversed by code in pager_playback(). The SPILLFLAG_OFF
541 ** case is a user preference.
543 ** If the SPILLFLAG_NOSYNC bit is set, writing to the database from pagerStress()
544 ** is permitted, but syncing the journal file is not. This flag is set
545 ** by sqlite3PagerWrite() when the file-system sector-size is larger than
546 ** the database page-size in order to prevent a journal sync from happening
547 ** in between the journalling of two pages on the same sector.
549 ** subjInMemory
551 ** This is a boolean variable. If true, then any required sub-journal
552 ** is opened as an in-memory journal file. If false, then in-memory
553 ** sub-journals are only used for in-memory pager files.
555 ** This variable is updated by the upper layer each time a new
556 ** write-transaction is opened.
558 ** dbSize, dbOrigSize, dbFileSize
560 ** Variable dbSize is set to the number of pages in the database file.
561 ** It is valid in PAGER_READER and higher states (all states except for
562 ** OPEN and ERROR).
564 ** dbSize is set based on the size of the database file, which may be
565 ** larger than the size of the database (the value stored at offset
566 ** 28 of the database header by the btree). If the size of the file
567 ** is not an integer multiple of the page-size, the value stored in
568 ** dbSize is rounded down (i.e. a 5KB file with 2K page-size has dbSize==2).
569 ** Except, any file that is greater than 0 bytes in size is considered
570 ** to have at least one page. (i.e. a 1KB file with 2K page-size leads
571 ** to dbSize==1).
573 ** During a write-transaction, if pages with page-numbers greater than
574 ** dbSize are modified in the cache, dbSize is updated accordingly.
575 ** Similarly, if the database is truncated using PagerTruncateImage(),
576 ** dbSize is updated.
578 ** Variables dbOrigSize and dbFileSize are valid in states
579 ** PAGER_WRITER_LOCKED and higher. dbOrigSize is a copy of the dbSize
580 ** variable at the start of the transaction. It is used during rollback,
581 ** and to determine whether or not pages need to be journalled before
582 ** being modified.
584 ** Throughout a write-transaction, dbFileSize contains the size of
585 ** the file on disk in pages. It is set to a copy of dbSize when the
586 ** write-transaction is first opened, and updated when VFS calls are made
587 ** to write or truncate the database file on disk.
589 ** The only reason the dbFileSize variable is required is to suppress
590 ** unnecessary calls to xTruncate() after committing a transaction. If,
591 ** when a transaction is committed, the dbFileSize variable indicates
592 ** that the database file is larger than the database image (Pager.dbSize),
593 ** pager_truncate() is called. The pager_truncate() call uses xFilesize()
594 ** to measure the database file on disk, and then truncates it if required.
595 ** dbFileSize is not used when rolling back a transaction. In this case
596 ** pager_truncate() is called unconditionally (which means there may be
597 ** a call to xFilesize() that is not strictly required). In either case,
598 ** pager_truncate() may cause the file to become smaller or larger.
600 ** dbHintSize
602 ** The dbHintSize variable is used to limit the number of calls made to
603 ** the VFS xFileControl(FCNTL_SIZE_HINT) method.
605 ** dbHintSize is set to a copy of the dbSize variable when a
606 ** write-transaction is opened (at the same time as dbFileSize and
607 ** dbOrigSize). If the xFileControl(FCNTL_SIZE_HINT) method is called,
608 ** dbHintSize is increased to the number of pages that correspond to the
609 ** size-hint passed to the method call. See pager_write_pagelist() for
610 ** details.
612 ** errCode
614 ** The Pager.errCode variable is only ever used in PAGER_ERROR state. It
615 ** is set to zero in all other states. In PAGER_ERROR state, Pager.errCode
616 ** is always set to SQLITE_FULL, SQLITE_IOERR or one of the SQLITE_IOERR_XXX
617 ** sub-codes.
619 struct Pager {
620 sqlite3_vfs *pVfs; /* OS functions to use for IO */
621 u8 exclusiveMode; /* Boolean. True if locking_mode==EXCLUSIVE */
622 u8 journalMode; /* One of the PAGER_JOURNALMODE_* values */
623 u8 useJournal; /* Use a rollback journal on this file */
624 u8 noSync; /* Do not sync the journal if true */
625 u8 fullSync; /* Do extra syncs of the journal for robustness */
626 u8 ckptSyncFlags; /* SYNC_NORMAL or SYNC_FULL for checkpoint */
627 u8 walSyncFlags; /* SYNC_NORMAL or SYNC_FULL for wal writes */
628 u8 syncFlags; /* SYNC_NORMAL or SYNC_FULL otherwise */
629 u8 tempFile; /* zFilename is a temporary or immutable file */
630 u8 noLock; /* Do not lock (except in WAL mode) */
631 u8 readOnly; /* True for a read-only database */
632 u8 memDb; /* True to inhibit all file I/O */
634 /**************************************************************************
635 ** The following block contains those class members that change during
636 ** routine operation. Class members not in this block are either fixed
637 ** when the pager is first created or else only change when there is a
638 ** significant mode change (such as changing the page_size, locking_mode,
639 ** or the journal_mode). From another view, these class members describe
640 ** the "state" of the pager, while other class members describe the
641 ** "configuration" of the pager.
643 u8 eState; /* Pager state (OPEN, READER, WRITER_LOCKED..) */
644 u8 eLock; /* Current lock held on database file */
645 u8 changeCountDone; /* Set after incrementing the change-counter */
646 u8 setMaster; /* True if a m-j name has been written to jrnl */
647 u8 doNotSpill; /* Do not spill the cache when non-zero */
648 u8 subjInMemory; /* True to use in-memory sub-journals */
649 Pgno dbSize; /* Number of pages in the database */
650 Pgno dbOrigSize; /* dbSize before the current transaction */
651 Pgno dbFileSize; /* Number of pages in the database file */
652 Pgno dbHintSize; /* Value passed to FCNTL_SIZE_HINT call */
653 int errCode; /* One of several kinds of errors */
654 int nRec; /* Pages journalled since last j-header written */
655 u32 cksumInit; /* Quasi-random value added to every checksum */
656 u32 nSubRec; /* Number of records written to sub-journal */
657 Bitvec *pInJournal; /* One bit for each page in the database file */
658 sqlite3_file *fd; /* File descriptor for database */
659 sqlite3_file *jfd; /* File descriptor for main journal */
660 sqlite3_file *sjfd; /* File descriptor for sub-journal */
661 i64 journalOff; /* Current write offset in the journal file */
662 i64 journalHdr; /* Byte offset to previous journal header */
663 sqlite3_backup *pBackup; /* Pointer to list of ongoing backup processes */
664 PagerSavepoint *aSavepoint; /* Array of active savepoints */
665 int nSavepoint; /* Number of elements in aSavepoint[] */
666 char dbFileVers[16]; /* Changes whenever database file changes */
668 u8 bUseFetch; /* True to use xFetch() */
669 int nMmapOut; /* Number of mmap pages currently outstanding */
670 sqlite3_int64 szMmap; /* Desired maximum mmap size */
671 PgHdr *pMmapFreelist; /* List of free mmap page headers (pDirty) */
673 ** End of the routinely-changing class members
674 ***************************************************************************/
676 u16 nExtra; /* Add this many bytes to each in-memory page */
677 i16 nReserve; /* Number of unused bytes at end of each page */
678 u32 vfsFlags; /* Flags for sqlite3_vfs.xOpen() */
679 u32 sectorSize; /* Assumed sector size during rollback */
680 int pageSize; /* Number of bytes in a page */
681 Pgno mxPgno; /* Maximum allowed size of the database */
682 i64 journalSizeLimit; /* Size limit for persistent journal files */
683 char *zFilename; /* Name of the database file */
684 char *zJournal; /* Name of the journal file */
685 int (*xBusyHandler)(void*); /* Function to call when busy */
686 void *pBusyHandlerArg; /* Context argument for xBusyHandler */
687 int aStat[3]; /* Total cache hits, misses and writes */
688 #ifdef SQLITE_TEST
689 int nRead; /* Database pages read */
690 #endif
691 void (*xReiniter)(DbPage*); /* Call this routine when reloading pages */
692 #ifdef SQLITE_HAS_CODEC
693 void *(*xCodec)(void*,void*,Pgno,int); /* Routine for en/decoding data */
694 void (*xCodecSizeChng)(void*,int,int); /* Notify of page size changes */
695 void (*xCodecFree)(void*); /* Destructor for the codec */
696 void *pCodec; /* First argument to xCodec... methods */
697 #endif
698 char *pTmpSpace; /* Pager.pageSize bytes of space for tmp use */
699 PCache *pPCache; /* Pointer to page cache object */
700 #ifndef SQLITE_OMIT_WAL
701 Wal *pWal; /* Write-ahead log used by "journal_mode=wal" */
702 char *zWal; /* File name for write-ahead log */
703 #endif
707 ** Indexes for use with Pager.aStat[]. The Pager.aStat[] array contains
708 ** the values accessed by passing SQLITE_DBSTATUS_CACHE_HIT, CACHE_MISS
709 ** or CACHE_WRITE to sqlite3_db_status().
711 #define PAGER_STAT_HIT 0
712 #define PAGER_STAT_MISS 1
713 #define PAGER_STAT_WRITE 2
716 ** The following global variables hold counters used for
717 ** testing purposes only. These variables do not exist in
718 ** a non-testing build. These variables are not thread-safe.
720 #ifdef SQLITE_TEST
721 int sqlite3_pager_readdb_count = 0; /* Number of full pages read from DB */
722 int sqlite3_pager_writedb_count = 0; /* Number of full pages written to DB */
723 int sqlite3_pager_writej_count = 0; /* Number of pages written to journal */
724 # define PAGER_INCR(v) v++
725 #else
726 # define PAGER_INCR(v)
727 #endif
732 ** Journal files begin with the following magic string. The data
733 ** was obtained from /dev/random. It is used only as a sanity check.
735 ** Since version 2.8.0, the journal format contains additional sanity
736 ** checking information. If the power fails while the journal is being
737 ** written, semi-random garbage data might appear in the journal
738 ** file after power is restored. If an attempt is then made
739 ** to roll the journal back, the database could be corrupted. The additional
740 ** sanity checking data is an attempt to discover the garbage in the
741 ** journal and ignore it.
743 ** The sanity checking information for the new journal format consists
744 ** of a 32-bit checksum on each page of data. The checksum covers both
745 ** the page number and the pPager->pageSize bytes of data for the page.
746 ** This cksum is initialized to a 32-bit random value that appears in the
747 ** journal file right after the header. The random initializer is important,
748 ** because garbage data that appears at the end of a journal is likely
749 ** data that was once in other files that have now been deleted. If the
750 ** garbage data came from an obsolete journal file, the checksums might
751 ** be correct. But by initializing the checksum to random value which
752 ** is different for every journal, we minimize that risk.
754 static const unsigned char aJournalMagic[] = {
755 0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, 0xd7,
759 ** The size of the of each page record in the journal is given by
760 ** the following macro.
762 #define JOURNAL_PG_SZ(pPager) ((pPager->pageSize) + 8)
765 ** The journal header size for this pager. This is usually the same
766 ** size as a single disk sector. See also setSectorSize().
768 #define JOURNAL_HDR_SZ(pPager) (pPager->sectorSize)
771 ** The macro MEMDB is true if we are dealing with an in-memory database.
772 ** We do this as a macro so that if the SQLITE_OMIT_MEMORYDB macro is set,
773 ** the value of MEMDB will be a constant and the compiler will optimize
774 ** out code that would never execute.
776 #ifdef SQLITE_OMIT_MEMORYDB
777 # define MEMDB 0
778 #else
779 # define MEMDB pPager->memDb
780 #endif
783 ** The macro USEFETCH is true if we are allowed to use the xFetch and xUnfetch
784 ** interfaces to access the database using memory-mapped I/O.
786 #if SQLITE_MAX_MMAP_SIZE>0
787 # define USEFETCH(x) ((x)->bUseFetch)
788 #else
789 # define USEFETCH(x) 0
790 #endif
793 ** The maximum legal page number is (2^31 - 1).
795 #define PAGER_MAX_PGNO 2147483647
798 ** The argument to this macro is a file descriptor (type sqlite3_file*).
799 ** Return 0 if it is not open, or non-zero (but not 1) if it is.
801 ** This is so that expressions can be written as:
803 ** if( isOpen(pPager->jfd) ){ ...
805 ** instead of
807 ** if( pPager->jfd->pMethods ){ ...
809 #define isOpen(pFd) ((pFd)->pMethods)
812 ** Return true if this pager uses a write-ahead log instead of the usual
813 ** rollback journal. Otherwise false.
815 #ifndef SQLITE_OMIT_WAL
816 static int pagerUseWal(Pager *pPager){
817 return (pPager->pWal!=0);
819 #else
820 # define pagerUseWal(x) 0
821 # define pagerRollbackWal(x) 0
822 # define pagerWalFrames(v,w,x,y) 0
823 # define pagerOpenWalIfPresent(z) SQLITE_OK
824 # define pagerBeginReadTransaction(z) SQLITE_OK
825 #endif
827 #ifndef NDEBUG
829 ** Usage:
831 ** assert( assert_pager_state(pPager) );
833 ** This function runs many asserts to try to find inconsistencies in
834 ** the internal state of the Pager object.
836 static int assert_pager_state(Pager *p){
837 Pager *pPager = p;
839 /* State must be valid. */
840 assert( p->eState==PAGER_OPEN
841 || p->eState==PAGER_READER
842 || p->eState==PAGER_WRITER_LOCKED
843 || p->eState==PAGER_WRITER_CACHEMOD
844 || p->eState==PAGER_WRITER_DBMOD
845 || p->eState==PAGER_WRITER_FINISHED
846 || p->eState==PAGER_ERROR
849 /* Regardless of the current state, a temp-file connection always behaves
850 ** as if it has an exclusive lock on the database file. It never updates
851 ** the change-counter field, so the changeCountDone flag is always set.
853 assert( p->tempFile==0 || p->eLock==EXCLUSIVE_LOCK );
854 assert( p->tempFile==0 || pPager->changeCountDone );
856 /* If the useJournal flag is clear, the journal-mode must be "OFF".
857 ** And if the journal-mode is "OFF", the journal file must not be open.
859 assert( p->journalMode==PAGER_JOURNALMODE_OFF || p->useJournal );
860 assert( p->journalMode!=PAGER_JOURNALMODE_OFF || !isOpen(p->jfd) );
862 /* Check that MEMDB implies noSync. And an in-memory journal. Since
863 ** this means an in-memory pager performs no IO at all, it cannot encounter
864 ** either SQLITE_IOERR or SQLITE_FULL during rollback or while finalizing
865 ** a journal file. (although the in-memory journal implementation may
866 ** return SQLITE_IOERR_NOMEM while the journal file is being written). It
867 ** is therefore not possible for an in-memory pager to enter the ERROR
868 ** state.
870 if( MEMDB ){
871 assert( p->noSync );
872 assert( p->journalMode==PAGER_JOURNALMODE_OFF
873 || p->journalMode==PAGER_JOURNALMODE_MEMORY
875 assert( p->eState!=PAGER_ERROR && p->eState!=PAGER_OPEN );
876 assert( pagerUseWal(p)==0 );
879 /* If changeCountDone is set, a RESERVED lock or greater must be held
880 ** on the file.
882 assert( pPager->changeCountDone==0 || pPager->eLock>=RESERVED_LOCK );
883 assert( p->eLock!=PENDING_LOCK );
885 switch( p->eState ){
886 case PAGER_OPEN:
887 assert( !MEMDB );
888 assert( pPager->errCode==SQLITE_OK );
889 assert( sqlite3PcacheRefCount(pPager->pPCache)==0 || pPager->tempFile );
890 break;
892 case PAGER_READER:
893 assert( pPager->errCode==SQLITE_OK );
894 assert( p->eLock!=UNKNOWN_LOCK );
895 assert( p->eLock>=SHARED_LOCK );
896 break;
898 case PAGER_WRITER_LOCKED:
899 assert( p->eLock!=UNKNOWN_LOCK );
900 assert( pPager->errCode==SQLITE_OK );
901 if( !pagerUseWal(pPager) ){
902 assert( p->eLock>=RESERVED_LOCK );
904 assert( pPager->dbSize==pPager->dbOrigSize );
905 assert( pPager->dbOrigSize==pPager->dbFileSize );
906 assert( pPager->dbOrigSize==pPager->dbHintSize );
907 assert( pPager->setMaster==0 );
908 break;
910 case PAGER_WRITER_CACHEMOD:
911 assert( p->eLock!=UNKNOWN_LOCK );
912 assert( pPager->errCode==SQLITE_OK );
913 if( !pagerUseWal(pPager) ){
914 /* It is possible that if journal_mode=wal here that neither the
915 ** journal file nor the WAL file are open. This happens during
916 ** a rollback transaction that switches from journal_mode=off
917 ** to journal_mode=wal.
919 assert( p->eLock>=RESERVED_LOCK );
920 assert( isOpen(p->jfd)
921 || p->journalMode==PAGER_JOURNALMODE_OFF
922 || p->journalMode==PAGER_JOURNALMODE_WAL
925 assert( pPager->dbOrigSize==pPager->dbFileSize );
926 assert( pPager->dbOrigSize==pPager->dbHintSize );
927 break;
929 case PAGER_WRITER_DBMOD:
930 assert( p->eLock==EXCLUSIVE_LOCK );
931 assert( pPager->errCode==SQLITE_OK );
932 assert( !pagerUseWal(pPager) );
933 assert( p->eLock>=EXCLUSIVE_LOCK );
934 assert( isOpen(p->jfd)
935 || p->journalMode==PAGER_JOURNALMODE_OFF
936 || p->journalMode==PAGER_JOURNALMODE_WAL
938 assert( pPager->dbOrigSize<=pPager->dbHintSize );
939 break;
941 case PAGER_WRITER_FINISHED:
942 assert( p->eLock==EXCLUSIVE_LOCK );
943 assert( pPager->errCode==SQLITE_OK );
944 assert( !pagerUseWal(pPager) );
945 assert( isOpen(p->jfd)
946 || p->journalMode==PAGER_JOURNALMODE_OFF
947 || p->journalMode==PAGER_JOURNALMODE_WAL
949 break;
951 case PAGER_ERROR:
952 /* There must be at least one outstanding reference to the pager if
953 ** in ERROR state. Otherwise the pager should have already dropped
954 ** back to OPEN state.
956 assert( pPager->errCode!=SQLITE_OK );
957 assert( sqlite3PcacheRefCount(pPager->pPCache)>0 );
958 break;
961 return 1;
963 #endif /* ifndef NDEBUG */
965 #ifdef SQLITE_DEBUG
967 ** Return a pointer to a human readable string in a static buffer
968 ** containing the state of the Pager object passed as an argument. This
969 ** is intended to be used within debuggers. For example, as an alternative
970 ** to "print *pPager" in gdb:
972 ** (gdb) printf "%s", print_pager_state(pPager)
974 static char *print_pager_state(Pager *p){
975 static char zRet[1024];
977 sqlite3_snprintf(1024, zRet,
978 "Filename: %s\n"
979 "State: %s errCode=%d\n"
980 "Lock: %s\n"
981 "Locking mode: locking_mode=%s\n"
982 "Journal mode: journal_mode=%s\n"
983 "Backing store: tempFile=%d memDb=%d useJournal=%d\n"
984 "Journal: journalOff=%lld journalHdr=%lld\n"
985 "Size: dbsize=%d dbOrigSize=%d dbFileSize=%d\n"
986 , p->zFilename
987 , p->eState==PAGER_OPEN ? "OPEN" :
988 p->eState==PAGER_READER ? "READER" :
989 p->eState==PAGER_WRITER_LOCKED ? "WRITER_LOCKED" :
990 p->eState==PAGER_WRITER_CACHEMOD ? "WRITER_CACHEMOD" :
991 p->eState==PAGER_WRITER_DBMOD ? "WRITER_DBMOD" :
992 p->eState==PAGER_WRITER_FINISHED ? "WRITER_FINISHED" :
993 p->eState==PAGER_ERROR ? "ERROR" : "?error?"
994 , (int)p->errCode
995 , p->eLock==NO_LOCK ? "NO_LOCK" :
996 p->eLock==RESERVED_LOCK ? "RESERVED" :
997 p->eLock==EXCLUSIVE_LOCK ? "EXCLUSIVE" :
998 p->eLock==SHARED_LOCK ? "SHARED" :
999 p->eLock==UNKNOWN_LOCK ? "UNKNOWN" : "?error?"
1000 , p->exclusiveMode ? "exclusive" : "normal"
1001 , p->journalMode==PAGER_JOURNALMODE_MEMORY ? "memory" :
1002 p->journalMode==PAGER_JOURNALMODE_OFF ? "off" :
1003 p->journalMode==PAGER_JOURNALMODE_DELETE ? "delete" :
1004 p->journalMode==PAGER_JOURNALMODE_PERSIST ? "persist" :
1005 p->journalMode==PAGER_JOURNALMODE_TRUNCATE ? "truncate" :
1006 p->journalMode==PAGER_JOURNALMODE_WAL ? "wal" : "?error?"
1007 , (int)p->tempFile, (int)p->memDb, (int)p->useJournal
1008 , p->journalOff, p->journalHdr
1009 , (int)p->dbSize, (int)p->dbOrigSize, (int)p->dbFileSize
1012 return zRet;
1014 #endif
1017 ** Return true if it is necessary to write page *pPg into the sub-journal.
1018 ** A page needs to be written into the sub-journal if there exists one
1019 ** or more open savepoints for which:
1021 ** * The page-number is less than or equal to PagerSavepoint.nOrig, and
1022 ** * The bit corresponding to the page-number is not set in
1023 ** PagerSavepoint.pInSavepoint.
1025 static int subjRequiresPage(PgHdr *pPg){
1026 Pager *pPager = pPg->pPager;
1027 PagerSavepoint *p;
1028 Pgno pgno = pPg->pgno;
1029 int i;
1030 for(i=0; i<pPager->nSavepoint; i++){
1031 p = &pPager->aSavepoint[i];
1032 if( p->nOrig>=pgno && 0==sqlite3BitvecTest(p->pInSavepoint, pgno) ){
1033 return 1;
1036 return 0;
1040 ** Return true if the page is already in the journal file.
1042 static int pageInJournal(Pager *pPager, PgHdr *pPg){
1043 return sqlite3BitvecTest(pPager->pInJournal, pPg->pgno);
1047 ** Read a 32-bit integer from the given file descriptor. Store the integer
1048 ** that is read in *pRes. Return SQLITE_OK if everything worked, or an
1049 ** error code is something goes wrong.
1051 ** All values are stored on disk as big-endian.
1053 static int read32bits(sqlite3_file *fd, i64 offset, u32 *pRes){
1054 unsigned char ac[4];
1055 int rc = sqlite3OsRead(fd, ac, sizeof(ac), offset);
1056 if( rc==SQLITE_OK ){
1057 *pRes = sqlite3Get4byte(ac);
1059 return rc;
1063 ** Write a 32-bit integer into a string buffer in big-endian byte order.
1065 #define put32bits(A,B) sqlite3Put4byte((u8*)A,B)
1069 ** Write a 32-bit integer into the given file descriptor. Return SQLITE_OK
1070 ** on success or an error code is something goes wrong.
1072 static int write32bits(sqlite3_file *fd, i64 offset, u32 val){
1073 char ac[4];
1074 put32bits(ac, val);
1075 return sqlite3OsWrite(fd, ac, 4, offset);
1079 ** Unlock the database file to level eLock, which must be either NO_LOCK
1080 ** or SHARED_LOCK. Regardless of whether or not the call to xUnlock()
1081 ** succeeds, set the Pager.eLock variable to match the (attempted) new lock.
1083 ** Except, if Pager.eLock is set to UNKNOWN_LOCK when this function is
1084 ** called, do not modify it. See the comment above the #define of
1085 ** UNKNOWN_LOCK for an explanation of this.
1087 static int pagerUnlockDb(Pager *pPager, int eLock){
1088 int rc = SQLITE_OK;
1090 assert( !pPager->exclusiveMode || pPager->eLock==eLock );
1091 assert( eLock==NO_LOCK || eLock==SHARED_LOCK );
1092 assert( eLock!=NO_LOCK || pagerUseWal(pPager)==0 );
1093 if( isOpen(pPager->fd) ){
1094 assert( pPager->eLock>=eLock );
1095 rc = pPager->noLock ? SQLITE_OK : sqlite3OsUnlock(pPager->fd, eLock);
1096 if( pPager->eLock!=UNKNOWN_LOCK ){
1097 pPager->eLock = (u8)eLock;
1099 IOTRACE(("UNLOCK %p %d\n", pPager, eLock))
1101 return rc;
1105 ** Lock the database file to level eLock, which must be either SHARED_LOCK,
1106 ** RESERVED_LOCK or EXCLUSIVE_LOCK. If the caller is successful, set the
1107 ** Pager.eLock variable to the new locking state.
1109 ** Except, if Pager.eLock is set to UNKNOWN_LOCK when this function is
1110 ** called, do not modify it unless the new locking state is EXCLUSIVE_LOCK.
1111 ** See the comment above the #define of UNKNOWN_LOCK for an explanation
1112 ** of this.
1114 static int pagerLockDb(Pager *pPager, int eLock){
1115 int rc = SQLITE_OK;
1117 assert( eLock==SHARED_LOCK || eLock==RESERVED_LOCK || eLock==EXCLUSIVE_LOCK );
1118 if( pPager->eLock<eLock || pPager->eLock==UNKNOWN_LOCK ){
1119 rc = pPager->noLock ? SQLITE_OK : sqlite3OsLock(pPager->fd, eLock);
1120 if( rc==SQLITE_OK && (pPager->eLock!=UNKNOWN_LOCK||eLock==EXCLUSIVE_LOCK) ){
1121 pPager->eLock = (u8)eLock;
1122 IOTRACE(("LOCK %p %d\n", pPager, eLock))
1125 return rc;
1129 ** This function determines whether or not the atomic-write optimization
1130 ** can be used with this pager. The optimization can be used if:
1132 ** (a) the value returned by OsDeviceCharacteristics() indicates that
1133 ** a database page may be written atomically, and
1134 ** (b) the value returned by OsSectorSize() is less than or equal
1135 ** to the page size.
1137 ** The optimization is also always enabled for temporary files. It is
1138 ** an error to call this function if pPager is opened on an in-memory
1139 ** database.
1141 ** If the optimization cannot be used, 0 is returned. If it can be used,
1142 ** then the value returned is the size of the journal file when it
1143 ** contains rollback data for exactly one page.
1145 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
1146 static int jrnlBufferSize(Pager *pPager){
1147 assert( !MEMDB );
1148 if( !pPager->tempFile ){
1149 int dc; /* Device characteristics */
1150 int nSector; /* Sector size */
1151 int szPage; /* Page size */
1153 assert( isOpen(pPager->fd) );
1154 dc = sqlite3OsDeviceCharacteristics(pPager->fd);
1155 nSector = pPager->sectorSize;
1156 szPage = pPager->pageSize;
1158 assert(SQLITE_IOCAP_ATOMIC512==(512>>8));
1159 assert(SQLITE_IOCAP_ATOMIC64K==(65536>>8));
1160 if( 0==(dc&(SQLITE_IOCAP_ATOMIC|(szPage>>8)) || nSector>szPage) ){
1161 return 0;
1165 return JOURNAL_HDR_SZ(pPager) + JOURNAL_PG_SZ(pPager);
1167 #endif
1170 ** If SQLITE_CHECK_PAGES is defined then we do some sanity checking
1171 ** on the cache using a hash function. This is used for testing
1172 ** and debugging only.
1174 #ifdef SQLITE_CHECK_PAGES
1176 ** Return a 32-bit hash of the page data for pPage.
1178 static u32 pager_datahash(int nByte, unsigned char *pData){
1179 u32 hash = 0;
1180 int i;
1181 for(i=0; i<nByte; i++){
1182 hash = (hash*1039) + pData[i];
1184 return hash;
1186 static u32 pager_pagehash(PgHdr *pPage){
1187 return pager_datahash(pPage->pPager->pageSize, (unsigned char *)pPage->pData);
1189 static void pager_set_pagehash(PgHdr *pPage){
1190 pPage->pageHash = pager_pagehash(pPage);
1194 ** The CHECK_PAGE macro takes a PgHdr* as an argument. If SQLITE_CHECK_PAGES
1195 ** is defined, and NDEBUG is not defined, an assert() statement checks
1196 ** that the page is either dirty or still matches the calculated page-hash.
1198 #define CHECK_PAGE(x) checkPage(x)
1199 static void checkPage(PgHdr *pPg){
1200 Pager *pPager = pPg->pPager;
1201 assert( pPager->eState!=PAGER_ERROR );
1202 assert( (pPg->flags&PGHDR_DIRTY) || pPg->pageHash==pager_pagehash(pPg) );
1205 #else
1206 #define pager_datahash(X,Y) 0
1207 #define pager_pagehash(X) 0
1208 #define pager_set_pagehash(X)
1209 #define CHECK_PAGE(x)
1210 #endif /* SQLITE_CHECK_PAGES */
1213 ** When this is called the journal file for pager pPager must be open.
1214 ** This function attempts to read a master journal file name from the
1215 ** end of the file and, if successful, copies it into memory supplied
1216 ** by the caller. See comments above writeMasterJournal() for the format
1217 ** used to store a master journal file name at the end of a journal file.
1219 ** zMaster must point to a buffer of at least nMaster bytes allocated by
1220 ** the caller. This should be sqlite3_vfs.mxPathname+1 (to ensure there is
1221 ** enough space to write the master journal name). If the master journal
1222 ** name in the journal is longer than nMaster bytes (including a
1223 ** nul-terminator), then this is handled as if no master journal name
1224 ** were present in the journal.
1226 ** If a master journal file name is present at the end of the journal
1227 ** file, then it is copied into the buffer pointed to by zMaster. A
1228 ** nul-terminator byte is appended to the buffer following the master
1229 ** journal file name.
1231 ** If it is determined that no master journal file name is present
1232 ** zMaster[0] is set to 0 and SQLITE_OK returned.
1234 ** If an error occurs while reading from the journal file, an SQLite
1235 ** error code is returned.
1237 static int readMasterJournal(sqlite3_file *pJrnl, char *zMaster, u32 nMaster){
1238 int rc; /* Return code */
1239 u32 len; /* Length in bytes of master journal name */
1240 i64 szJ; /* Total size in bytes of journal file pJrnl */
1241 u32 cksum; /* MJ checksum value read from journal */
1242 u32 u; /* Unsigned loop counter */
1243 unsigned char aMagic[8]; /* A buffer to hold the magic header */
1244 zMaster[0] = '\0';
1246 if( SQLITE_OK!=(rc = sqlite3OsFileSize(pJrnl, &szJ))
1247 || szJ<16
1248 || SQLITE_OK!=(rc = read32bits(pJrnl, szJ-16, &len))
1249 || len>=nMaster
1250 || len==0
1251 || SQLITE_OK!=(rc = read32bits(pJrnl, szJ-12, &cksum))
1252 || SQLITE_OK!=(rc = sqlite3OsRead(pJrnl, aMagic, 8, szJ-8))
1253 || memcmp(aMagic, aJournalMagic, 8)
1254 || SQLITE_OK!=(rc = sqlite3OsRead(pJrnl, zMaster, len, szJ-16-len))
1256 return rc;
1259 /* See if the checksum matches the master journal name */
1260 for(u=0; u<len; u++){
1261 cksum -= zMaster[u];
1263 if( cksum ){
1264 /* If the checksum doesn't add up, then one or more of the disk sectors
1265 ** containing the master journal filename is corrupted. This means
1266 ** definitely roll back, so just return SQLITE_OK and report a (nul)
1267 ** master-journal filename.
1269 len = 0;
1271 zMaster[len] = '\0';
1273 return SQLITE_OK;
1277 ** Return the offset of the sector boundary at or immediately
1278 ** following the value in pPager->journalOff, assuming a sector
1279 ** size of pPager->sectorSize bytes.
1281 ** i.e for a sector size of 512:
1283 ** Pager.journalOff Return value
1284 ** ---------------------------------------
1285 ** 0 0
1286 ** 512 512
1287 ** 100 512
1288 ** 2000 2048
1291 static i64 journalHdrOffset(Pager *pPager){
1292 i64 offset = 0;
1293 i64 c = pPager->journalOff;
1294 if( c ){
1295 offset = ((c-1)/JOURNAL_HDR_SZ(pPager) + 1) * JOURNAL_HDR_SZ(pPager);
1297 assert( offset%JOURNAL_HDR_SZ(pPager)==0 );
1298 assert( offset>=c );
1299 assert( (offset-c)<JOURNAL_HDR_SZ(pPager) );
1300 return offset;
1304 ** The journal file must be open when this function is called.
1306 ** This function is a no-op if the journal file has not been written to
1307 ** within the current transaction (i.e. if Pager.journalOff==0).
1309 ** If doTruncate is non-zero or the Pager.journalSizeLimit variable is
1310 ** set to 0, then truncate the journal file to zero bytes in size. Otherwise,
1311 ** zero the 28-byte header at the start of the journal file. In either case,
1312 ** if the pager is not in no-sync mode, sync the journal file immediately
1313 ** after writing or truncating it.
1315 ** If Pager.journalSizeLimit is set to a positive, non-zero value, and
1316 ** following the truncation or zeroing described above the size of the
1317 ** journal file in bytes is larger than this value, then truncate the
1318 ** journal file to Pager.journalSizeLimit bytes. The journal file does
1319 ** not need to be synced following this operation.
1321 ** If an IO error occurs, abandon processing and return the IO error code.
1322 ** Otherwise, return SQLITE_OK.
1324 static int zeroJournalHdr(Pager *pPager, int doTruncate){
1325 int rc = SQLITE_OK; /* Return code */
1326 assert( isOpen(pPager->jfd) );
1327 if( pPager->journalOff ){
1328 const i64 iLimit = pPager->journalSizeLimit; /* Local cache of jsl */
1330 IOTRACE(("JZEROHDR %p\n", pPager))
1331 if( doTruncate || iLimit==0 ){
1332 rc = sqlite3OsTruncate(pPager->jfd, 0);
1333 }else{
1334 static const char zeroHdr[28] = {0};
1335 rc = sqlite3OsWrite(pPager->jfd, zeroHdr, sizeof(zeroHdr), 0);
1337 if( rc==SQLITE_OK && !pPager->noSync ){
1338 rc = sqlite3OsSync(pPager->jfd, SQLITE_SYNC_DATAONLY|pPager->syncFlags);
1341 /* At this point the transaction is committed but the write lock
1342 ** is still held on the file. If there is a size limit configured for
1343 ** the persistent journal and the journal file currently consumes more
1344 ** space than that limit allows for, truncate it now. There is no need
1345 ** to sync the file following this operation.
1347 if( rc==SQLITE_OK && iLimit>0 ){
1348 i64 sz;
1349 rc = sqlite3OsFileSize(pPager->jfd, &sz);
1350 if( rc==SQLITE_OK && sz>iLimit ){
1351 rc = sqlite3OsTruncate(pPager->jfd, iLimit);
1355 return rc;
1359 ** The journal file must be open when this routine is called. A journal
1360 ** header (JOURNAL_HDR_SZ bytes) is written into the journal file at the
1361 ** current location.
1363 ** The format for the journal header is as follows:
1364 ** - 8 bytes: Magic identifying journal format.
1365 ** - 4 bytes: Number of records in journal, or -1 no-sync mode is on.
1366 ** - 4 bytes: Random number used for page hash.
1367 ** - 4 bytes: Initial database page count.
1368 ** - 4 bytes: Sector size used by the process that wrote this journal.
1369 ** - 4 bytes: Database page size.
1371 ** Followed by (JOURNAL_HDR_SZ - 28) bytes of unused space.
1373 static int writeJournalHdr(Pager *pPager){
1374 int rc = SQLITE_OK; /* Return code */
1375 char *zHeader = pPager->pTmpSpace; /* Temporary space used to build header */
1376 u32 nHeader = (u32)pPager->pageSize;/* Size of buffer pointed to by zHeader */
1377 u32 nWrite; /* Bytes of header sector written */
1378 int ii; /* Loop counter */
1380 assert( isOpen(pPager->jfd) ); /* Journal file must be open. */
1382 if( nHeader>JOURNAL_HDR_SZ(pPager) ){
1383 nHeader = JOURNAL_HDR_SZ(pPager);
1386 /* If there are active savepoints and any of them were created
1387 ** since the most recent journal header was written, update the
1388 ** PagerSavepoint.iHdrOffset fields now.
1390 for(ii=0; ii<pPager->nSavepoint; ii++){
1391 if( pPager->aSavepoint[ii].iHdrOffset==0 ){
1392 pPager->aSavepoint[ii].iHdrOffset = pPager->journalOff;
1396 pPager->journalHdr = pPager->journalOff = journalHdrOffset(pPager);
1399 ** Write the nRec Field - the number of page records that follow this
1400 ** journal header. Normally, zero is written to this value at this time.
1401 ** After the records are added to the journal (and the journal synced,
1402 ** if in full-sync mode), the zero is overwritten with the true number
1403 ** of records (see syncJournal()).
1405 ** A faster alternative is to write 0xFFFFFFFF to the nRec field. When
1406 ** reading the journal this value tells SQLite to assume that the
1407 ** rest of the journal file contains valid page records. This assumption
1408 ** is dangerous, as if a failure occurred whilst writing to the journal
1409 ** file it may contain some garbage data. There are two scenarios
1410 ** where this risk can be ignored:
1412 ** * When the pager is in no-sync mode. Corruption can follow a
1413 ** power failure in this case anyway.
1415 ** * When the SQLITE_IOCAP_SAFE_APPEND flag is set. This guarantees
1416 ** that garbage data is never appended to the journal file.
1418 assert( isOpen(pPager->fd) || pPager->noSync );
1419 if( pPager->noSync || (pPager->journalMode==PAGER_JOURNALMODE_MEMORY)
1420 || (sqlite3OsDeviceCharacteristics(pPager->fd)&SQLITE_IOCAP_SAFE_APPEND)
1422 memcpy(zHeader, aJournalMagic, sizeof(aJournalMagic));
1423 put32bits(&zHeader[sizeof(aJournalMagic)], 0xffffffff);
1424 }else{
1425 memset(zHeader, 0, sizeof(aJournalMagic)+4);
1428 /* The random check-hash initializer */
1429 sqlite3_randomness(sizeof(pPager->cksumInit), &pPager->cksumInit);
1430 put32bits(&zHeader[sizeof(aJournalMagic)+4], pPager->cksumInit);
1431 /* The initial database size */
1432 put32bits(&zHeader[sizeof(aJournalMagic)+8], pPager->dbOrigSize);
1433 /* The assumed sector size for this process */
1434 put32bits(&zHeader[sizeof(aJournalMagic)+12], pPager->sectorSize);
1436 /* The page size */
1437 put32bits(&zHeader[sizeof(aJournalMagic)+16], pPager->pageSize);
1439 /* Initializing the tail of the buffer is not necessary. Everything
1440 ** works find if the following memset() is omitted. But initializing
1441 ** the memory prevents valgrind from complaining, so we are willing to
1442 ** take the performance hit.
1444 memset(&zHeader[sizeof(aJournalMagic)+20], 0,
1445 nHeader-(sizeof(aJournalMagic)+20));
1447 /* In theory, it is only necessary to write the 28 bytes that the
1448 ** journal header consumes to the journal file here. Then increment the
1449 ** Pager.journalOff variable by JOURNAL_HDR_SZ so that the next
1450 ** record is written to the following sector (leaving a gap in the file
1451 ** that will be implicitly filled in by the OS).
1453 ** However it has been discovered that on some systems this pattern can
1454 ** be significantly slower than contiguously writing data to the file,
1455 ** even if that means explicitly writing data to the block of
1456 ** (JOURNAL_HDR_SZ - 28) bytes that will not be used. So that is what
1457 ** is done.
1459 ** The loop is required here in case the sector-size is larger than the
1460 ** database page size. Since the zHeader buffer is only Pager.pageSize
1461 ** bytes in size, more than one call to sqlite3OsWrite() may be required
1462 ** to populate the entire journal header sector.
1464 for(nWrite=0; rc==SQLITE_OK&&nWrite<JOURNAL_HDR_SZ(pPager); nWrite+=nHeader){
1465 IOTRACE(("JHDR %p %lld %d\n", pPager, pPager->journalHdr, nHeader))
1466 rc = sqlite3OsWrite(pPager->jfd, zHeader, nHeader, pPager->journalOff);
1467 assert( pPager->journalHdr <= pPager->journalOff );
1468 pPager->journalOff += nHeader;
1471 return rc;
1475 ** The journal file must be open when this is called. A journal header file
1476 ** (JOURNAL_HDR_SZ bytes) is read from the current location in the journal
1477 ** file. The current location in the journal file is given by
1478 ** pPager->journalOff. See comments above function writeJournalHdr() for
1479 ** a description of the journal header format.
1481 ** If the header is read successfully, *pNRec is set to the number of
1482 ** page records following this header and *pDbSize is set to the size of the
1483 ** database before the transaction began, in pages. Also, pPager->cksumInit
1484 ** is set to the value read from the journal header. SQLITE_OK is returned
1485 ** in this case.
1487 ** If the journal header file appears to be corrupted, SQLITE_DONE is
1488 ** returned and *pNRec and *PDbSize are undefined. If JOURNAL_HDR_SZ bytes
1489 ** cannot be read from the journal file an error code is returned.
1491 static int readJournalHdr(
1492 Pager *pPager, /* Pager object */
1493 int isHot,
1494 i64 journalSize, /* Size of the open journal file in bytes */
1495 u32 *pNRec, /* OUT: Value read from the nRec field */
1496 u32 *pDbSize /* OUT: Value of original database size field */
1498 int rc; /* Return code */
1499 unsigned char aMagic[8]; /* A buffer to hold the magic header */
1500 i64 iHdrOff; /* Offset of journal header being read */
1502 assert( isOpen(pPager->jfd) ); /* Journal file must be open. */
1504 /* Advance Pager.journalOff to the start of the next sector. If the
1505 ** journal file is too small for there to be a header stored at this
1506 ** point, return SQLITE_DONE.
1508 pPager->journalOff = journalHdrOffset(pPager);
1509 if( pPager->journalOff+JOURNAL_HDR_SZ(pPager) > journalSize ){
1510 return SQLITE_DONE;
1512 iHdrOff = pPager->journalOff;
1514 /* Read in the first 8 bytes of the journal header. If they do not match
1515 ** the magic string found at the start of each journal header, return
1516 ** SQLITE_DONE. If an IO error occurs, return an error code. Otherwise,
1517 ** proceed.
1519 if( isHot || iHdrOff!=pPager->journalHdr ){
1520 rc = sqlite3OsRead(pPager->jfd, aMagic, sizeof(aMagic), iHdrOff);
1521 if( rc ){
1522 return rc;
1524 if( memcmp(aMagic, aJournalMagic, sizeof(aMagic))!=0 ){
1525 return SQLITE_DONE;
1529 /* Read the first three 32-bit fields of the journal header: The nRec
1530 ** field, the checksum-initializer and the database size at the start
1531 ** of the transaction. Return an error code if anything goes wrong.
1533 if( SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+8, pNRec))
1534 || SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+12, &pPager->cksumInit))
1535 || SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+16, pDbSize))
1537 return rc;
1540 if( pPager->journalOff==0 ){
1541 u32 iPageSize; /* Page-size field of journal header */
1542 u32 iSectorSize; /* Sector-size field of journal header */
1544 /* Read the page-size and sector-size journal header fields. */
1545 if( SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+20, &iSectorSize))
1546 || SQLITE_OK!=(rc = read32bits(pPager->jfd, iHdrOff+24, &iPageSize))
1548 return rc;
1551 /* Versions of SQLite prior to 3.5.8 set the page-size field of the
1552 ** journal header to zero. In this case, assume that the Pager.pageSize
1553 ** variable is already set to the correct page size.
1555 if( iPageSize==0 ){
1556 iPageSize = pPager->pageSize;
1559 /* Check that the values read from the page-size and sector-size fields
1560 ** are within range. To be 'in range', both values need to be a power
1561 ** of two greater than or equal to 512 or 32, and not greater than their
1562 ** respective compile time maximum limits.
1564 if( iPageSize<512 || iSectorSize<32
1565 || iPageSize>SQLITE_MAX_PAGE_SIZE || iSectorSize>MAX_SECTOR_SIZE
1566 || ((iPageSize-1)&iPageSize)!=0 || ((iSectorSize-1)&iSectorSize)!=0
1568 /* If the either the page-size or sector-size in the journal-header is
1569 ** invalid, then the process that wrote the journal-header must have
1570 ** crashed before the header was synced. In this case stop reading
1571 ** the journal file here.
1573 return SQLITE_DONE;
1576 /* Update the page-size to match the value read from the journal.
1577 ** Use a testcase() macro to make sure that malloc failure within
1578 ** PagerSetPagesize() is tested.
1580 rc = sqlite3PagerSetPagesize(pPager, &iPageSize, -1);
1581 testcase( rc!=SQLITE_OK );
1583 /* Update the assumed sector-size to match the value used by
1584 ** the process that created this journal. If this journal was
1585 ** created by a process other than this one, then this routine
1586 ** is being called from within pager_playback(). The local value
1587 ** of Pager.sectorSize is restored at the end of that routine.
1589 pPager->sectorSize = iSectorSize;
1592 pPager->journalOff += JOURNAL_HDR_SZ(pPager);
1593 return rc;
1598 ** Write the supplied master journal name into the journal file for pager
1599 ** pPager at the current location. The master journal name must be the last
1600 ** thing written to a journal file. If the pager is in full-sync mode, the
1601 ** journal file descriptor is advanced to the next sector boundary before
1602 ** anything is written. The format is:
1604 ** + 4 bytes: PAGER_MJ_PGNO.
1605 ** + N bytes: Master journal filename in utf-8.
1606 ** + 4 bytes: N (length of master journal name in bytes, no nul-terminator).
1607 ** + 4 bytes: Master journal name checksum.
1608 ** + 8 bytes: aJournalMagic[].
1610 ** The master journal page checksum is the sum of the bytes in the master
1611 ** journal name, where each byte is interpreted as a signed 8-bit integer.
1613 ** If zMaster is a NULL pointer (occurs for a single database transaction),
1614 ** this call is a no-op.
1616 static int writeMasterJournal(Pager *pPager, const char *zMaster){
1617 int rc; /* Return code */
1618 int nMaster; /* Length of string zMaster */
1619 i64 iHdrOff; /* Offset of header in journal file */
1620 i64 jrnlSize; /* Size of journal file on disk */
1621 u32 cksum = 0; /* Checksum of string zMaster */
1623 assert( pPager->setMaster==0 );
1624 assert( !pagerUseWal(pPager) );
1626 if( !zMaster
1627 || pPager->journalMode==PAGER_JOURNALMODE_MEMORY
1628 || !isOpen(pPager->jfd)
1630 return SQLITE_OK;
1632 pPager->setMaster = 1;
1633 assert( pPager->journalHdr <= pPager->journalOff );
1635 /* Calculate the length in bytes and the checksum of zMaster */
1636 for(nMaster=0; zMaster[nMaster]; nMaster++){
1637 cksum += zMaster[nMaster];
1640 /* If in full-sync mode, advance to the next disk sector before writing
1641 ** the master journal name. This is in case the previous page written to
1642 ** the journal has already been synced.
1644 if( pPager->fullSync ){
1645 pPager->journalOff = journalHdrOffset(pPager);
1647 iHdrOff = pPager->journalOff;
1649 /* Write the master journal data to the end of the journal file. If
1650 ** an error occurs, return the error code to the caller.
1652 if( (0 != (rc = write32bits(pPager->jfd, iHdrOff, PAGER_MJ_PGNO(pPager))))
1653 || (0 != (rc = sqlite3OsWrite(pPager->jfd, zMaster, nMaster, iHdrOff+4)))
1654 || (0 != (rc = write32bits(pPager->jfd, iHdrOff+4+nMaster, nMaster)))
1655 || (0 != (rc = write32bits(pPager->jfd, iHdrOff+4+nMaster+4, cksum)))
1656 || (0 != (rc = sqlite3OsWrite(pPager->jfd, aJournalMagic, 8, iHdrOff+4+nMaster+8)))
1658 return rc;
1660 pPager->journalOff += (nMaster+20);
1662 /* If the pager is in peristent-journal mode, then the physical
1663 ** journal-file may extend past the end of the master-journal name
1664 ** and 8 bytes of magic data just written to the file. This is
1665 ** dangerous because the code to rollback a hot-journal file
1666 ** will not be able to find the master-journal name to determine
1667 ** whether or not the journal is hot.
1669 ** Easiest thing to do in this scenario is to truncate the journal
1670 ** file to the required size.
1672 if( SQLITE_OK==(rc = sqlite3OsFileSize(pPager->jfd, &jrnlSize))
1673 && jrnlSize>pPager->journalOff
1675 rc = sqlite3OsTruncate(pPager->jfd, pPager->journalOff);
1677 return rc;
1681 ** Discard the entire contents of the in-memory page-cache.
1683 static void pager_reset(Pager *pPager){
1684 sqlite3BackupRestart(pPager->pBackup);
1685 sqlite3PcacheClear(pPager->pPCache);
1689 ** Free all structures in the Pager.aSavepoint[] array and set both
1690 ** Pager.aSavepoint and Pager.nSavepoint to zero. Close the sub-journal
1691 ** if it is open and the pager is not in exclusive mode.
1693 static void releaseAllSavepoints(Pager *pPager){
1694 int ii; /* Iterator for looping through Pager.aSavepoint */
1695 for(ii=0; ii<pPager->nSavepoint; ii++){
1696 sqlite3BitvecDestroy(pPager->aSavepoint[ii].pInSavepoint);
1698 if( !pPager->exclusiveMode || sqlite3IsMemJournal(pPager->sjfd) ){
1699 sqlite3OsClose(pPager->sjfd);
1701 sqlite3_free(pPager->aSavepoint);
1702 pPager->aSavepoint = 0;
1703 pPager->nSavepoint = 0;
1704 pPager->nSubRec = 0;
1708 ** Set the bit number pgno in the PagerSavepoint.pInSavepoint
1709 ** bitvecs of all open savepoints. Return SQLITE_OK if successful
1710 ** or SQLITE_NOMEM if a malloc failure occurs.
1712 static int addToSavepointBitvecs(Pager *pPager, Pgno pgno){
1713 int ii; /* Loop counter */
1714 int rc = SQLITE_OK; /* Result code */
1716 for(ii=0; ii<pPager->nSavepoint; ii++){
1717 PagerSavepoint *p = &pPager->aSavepoint[ii];
1718 if( pgno<=p->nOrig ){
1719 rc |= sqlite3BitvecSet(p->pInSavepoint, pgno);
1720 testcase( rc==SQLITE_NOMEM );
1721 assert( rc==SQLITE_OK || rc==SQLITE_NOMEM );
1724 return rc;
1728 ** This function is a no-op if the pager is in exclusive mode and not
1729 ** in the ERROR state. Otherwise, it switches the pager to PAGER_OPEN
1730 ** state.
1732 ** If the pager is not in exclusive-access mode, the database file is
1733 ** completely unlocked. If the file is unlocked and the file-system does
1734 ** not exhibit the UNDELETABLE_WHEN_OPEN property, the journal file is
1735 ** closed (if it is open).
1737 ** If the pager is in ERROR state when this function is called, the
1738 ** contents of the pager cache are discarded before switching back to
1739 ** the OPEN state. Regardless of whether the pager is in exclusive-mode
1740 ** or not, any journal file left in the file-system will be treated
1741 ** as a hot-journal and rolled back the next time a read-transaction
1742 ** is opened (by this or by any other connection).
1744 static void pager_unlock(Pager *pPager){
1746 assert( pPager->eState==PAGER_READER
1747 || pPager->eState==PAGER_OPEN
1748 || pPager->eState==PAGER_ERROR
1751 sqlite3BitvecDestroy(pPager->pInJournal);
1752 pPager->pInJournal = 0;
1753 releaseAllSavepoints(pPager);
1755 if( pagerUseWal(pPager) ){
1756 assert( !isOpen(pPager->jfd) );
1757 sqlite3WalEndReadTransaction(pPager->pWal);
1758 pPager->eState = PAGER_OPEN;
1759 }else if( !pPager->exclusiveMode ){
1760 int rc; /* Error code returned by pagerUnlockDb() */
1761 int iDc = isOpen(pPager->fd)?sqlite3OsDeviceCharacteristics(pPager->fd):0;
1763 /* If the operating system support deletion of open files, then
1764 ** close the journal file when dropping the database lock. Otherwise
1765 ** another connection with journal_mode=delete might delete the file
1766 ** out from under us.
1768 assert( (PAGER_JOURNALMODE_MEMORY & 5)!=1 );
1769 assert( (PAGER_JOURNALMODE_OFF & 5)!=1 );
1770 assert( (PAGER_JOURNALMODE_WAL & 5)!=1 );
1771 assert( (PAGER_JOURNALMODE_DELETE & 5)!=1 );
1772 assert( (PAGER_JOURNALMODE_TRUNCATE & 5)==1 );
1773 assert( (PAGER_JOURNALMODE_PERSIST & 5)==1 );
1774 if( 0==(iDc & SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN)
1775 || 1!=(pPager->journalMode & 5)
1777 sqlite3OsClose(pPager->jfd);
1780 /* If the pager is in the ERROR state and the call to unlock the database
1781 ** file fails, set the current lock to UNKNOWN_LOCK. See the comment
1782 ** above the #define for UNKNOWN_LOCK for an explanation of why this
1783 ** is necessary.
1785 rc = pagerUnlockDb(pPager, NO_LOCK);
1786 if( rc!=SQLITE_OK && pPager->eState==PAGER_ERROR ){
1787 pPager->eLock = UNKNOWN_LOCK;
1790 /* The pager state may be changed from PAGER_ERROR to PAGER_OPEN here
1791 ** without clearing the error code. This is intentional - the error
1792 ** code is cleared and the cache reset in the block below.
1794 assert( pPager->errCode || pPager->eState!=PAGER_ERROR );
1795 pPager->changeCountDone = 0;
1796 pPager->eState = PAGER_OPEN;
1799 /* If Pager.errCode is set, the contents of the pager cache cannot be
1800 ** trusted. Now that there are no outstanding references to the pager,
1801 ** it can safely move back to PAGER_OPEN state. This happens in both
1802 ** normal and exclusive-locking mode.
1804 if( pPager->errCode ){
1805 assert( !MEMDB );
1806 pager_reset(pPager);
1807 pPager->changeCountDone = pPager->tempFile;
1808 pPager->eState = PAGER_OPEN;
1809 pPager->errCode = SQLITE_OK;
1810 if( USEFETCH(pPager) ) sqlite3OsUnfetch(pPager->fd, 0, 0);
1813 pPager->journalOff = 0;
1814 pPager->journalHdr = 0;
1815 pPager->setMaster = 0;
1819 ** This function is called whenever an IOERR or FULL error that requires
1820 ** the pager to transition into the ERROR state may ahve occurred.
1821 ** The first argument is a pointer to the pager structure, the second
1822 ** the error-code about to be returned by a pager API function. The
1823 ** value returned is a copy of the second argument to this function.
1825 ** If the second argument is SQLITE_FULL, SQLITE_IOERR or one of the
1826 ** IOERR sub-codes, the pager enters the ERROR state and the error code
1827 ** is stored in Pager.errCode. While the pager remains in the ERROR state,
1828 ** all major API calls on the Pager will immediately return Pager.errCode.
1830 ** The ERROR state indicates that the contents of the pager-cache
1831 ** cannot be trusted. This state can be cleared by completely discarding
1832 ** the contents of the pager-cache. If a transaction was active when
1833 ** the persistent error occurred, then the rollback journal may need
1834 ** to be replayed to restore the contents of the database file (as if
1835 ** it were a hot-journal).
1837 static int pager_error(Pager *pPager, int rc){
1838 int rc2 = rc & 0xff;
1839 assert( rc==SQLITE_OK || !MEMDB );
1840 assert(
1841 pPager->errCode==SQLITE_FULL ||
1842 pPager->errCode==SQLITE_OK ||
1843 (pPager->errCode & 0xff)==SQLITE_IOERR
1845 if( rc2==SQLITE_FULL || rc2==SQLITE_IOERR ){
1846 pPager->errCode = rc;
1847 pPager->eState = PAGER_ERROR;
1849 return rc;
1852 static int pager_truncate(Pager *pPager, Pgno nPage);
1855 ** This routine ends a transaction. A transaction is usually ended by
1856 ** either a COMMIT or a ROLLBACK operation. This routine may be called
1857 ** after rollback of a hot-journal, or if an error occurs while opening
1858 ** the journal file or writing the very first journal-header of a
1859 ** database transaction.
1861 ** This routine is never called in PAGER_ERROR state. If it is called
1862 ** in PAGER_NONE or PAGER_SHARED state and the lock held is less
1863 ** exclusive than a RESERVED lock, it is a no-op.
1865 ** Otherwise, any active savepoints are released.
1867 ** If the journal file is open, then it is "finalized". Once a journal
1868 ** file has been finalized it is not possible to use it to roll back a
1869 ** transaction. Nor will it be considered to be a hot-journal by this
1870 ** or any other database connection. Exactly how a journal is finalized
1871 ** depends on whether or not the pager is running in exclusive mode and
1872 ** the current journal-mode (Pager.journalMode value), as follows:
1874 ** journalMode==MEMORY
1875 ** Journal file descriptor is simply closed. This destroys an
1876 ** in-memory journal.
1878 ** journalMode==TRUNCATE
1879 ** Journal file is truncated to zero bytes in size.
1881 ** journalMode==PERSIST
1882 ** The first 28 bytes of the journal file are zeroed. This invalidates
1883 ** the first journal header in the file, and hence the entire journal
1884 ** file. An invalid journal file cannot be rolled back.
1886 ** journalMode==DELETE
1887 ** The journal file is closed and deleted using sqlite3OsDelete().
1889 ** If the pager is running in exclusive mode, this method of finalizing
1890 ** the journal file is never used. Instead, if the journalMode is
1891 ** DELETE and the pager is in exclusive mode, the method described under
1892 ** journalMode==PERSIST is used instead.
1894 ** After the journal is finalized, the pager moves to PAGER_READER state.
1895 ** If running in non-exclusive rollback mode, the lock on the file is
1896 ** downgraded to a SHARED_LOCK.
1898 ** SQLITE_OK is returned if no error occurs. If an error occurs during
1899 ** any of the IO operations to finalize the journal file or unlock the
1900 ** database then the IO error code is returned to the user. If the
1901 ** operation to finalize the journal file fails, then the code still
1902 ** tries to unlock the database file if not in exclusive mode. If the
1903 ** unlock operation fails as well, then the first error code related
1904 ** to the first error encountered (the journal finalization one) is
1905 ** returned.
1907 static int pager_end_transaction(Pager *pPager, int hasMaster, int bCommit){
1908 int rc = SQLITE_OK; /* Error code from journal finalization operation */
1909 int rc2 = SQLITE_OK; /* Error code from db file unlock operation */
1911 /* Do nothing if the pager does not have an open write transaction
1912 ** or at least a RESERVED lock. This function may be called when there
1913 ** is no write-transaction active but a RESERVED or greater lock is
1914 ** held under two circumstances:
1916 ** 1. After a successful hot-journal rollback, it is called with
1917 ** eState==PAGER_NONE and eLock==EXCLUSIVE_LOCK.
1919 ** 2. If a connection with locking_mode=exclusive holding an EXCLUSIVE
1920 ** lock switches back to locking_mode=normal and then executes a
1921 ** read-transaction, this function is called with eState==PAGER_READER
1922 ** and eLock==EXCLUSIVE_LOCK when the read-transaction is closed.
1924 assert( assert_pager_state(pPager) );
1925 assert( pPager->eState!=PAGER_ERROR );
1926 if( pPager->eState<PAGER_WRITER_LOCKED && pPager->eLock<RESERVED_LOCK ){
1927 return SQLITE_OK;
1930 releaseAllSavepoints(pPager);
1931 assert( isOpen(pPager->jfd) || pPager->pInJournal==0 );
1932 if( isOpen(pPager->jfd) ){
1933 assert( !pagerUseWal(pPager) );
1935 /* Finalize the journal file. */
1936 if( sqlite3IsMemJournal(pPager->jfd) ){
1937 assert( pPager->journalMode==PAGER_JOURNALMODE_MEMORY );
1938 sqlite3OsClose(pPager->jfd);
1939 }else if( pPager->journalMode==PAGER_JOURNALMODE_TRUNCATE ){
1940 if( pPager->journalOff==0 ){
1941 rc = SQLITE_OK;
1942 }else{
1943 rc = sqlite3OsTruncate(pPager->jfd, 0);
1944 if( rc==SQLITE_OK && pPager->fullSync ){
1945 /* Make sure the new file size is written into the inode right away.
1946 ** Otherwise the journal might resurrect following a power loss and
1947 ** cause the last transaction to roll back. See
1948 ** https://bugzilla.mozilla.org/show_bug.cgi?id=1072773
1950 rc = sqlite3OsSync(pPager->jfd, pPager->syncFlags);
1953 pPager->journalOff = 0;
1954 }else if( pPager->journalMode==PAGER_JOURNALMODE_PERSIST
1955 || (pPager->exclusiveMode && pPager->journalMode!=PAGER_JOURNALMODE_WAL)
1957 rc = zeroJournalHdr(pPager, hasMaster);
1958 pPager->journalOff = 0;
1959 }else{
1960 /* This branch may be executed with Pager.journalMode==MEMORY if
1961 ** a hot-journal was just rolled back. In this case the journal
1962 ** file should be closed and deleted. If this connection writes to
1963 ** the database file, it will do so using an in-memory journal.
1965 int bDelete = (!pPager->tempFile && sqlite3JournalExists(pPager->jfd));
1966 assert( pPager->journalMode==PAGER_JOURNALMODE_DELETE
1967 || pPager->journalMode==PAGER_JOURNALMODE_MEMORY
1968 || pPager->journalMode==PAGER_JOURNALMODE_WAL
1970 sqlite3OsClose(pPager->jfd);
1971 if( bDelete ){
1972 rc = sqlite3OsDelete(pPager->pVfs, pPager->zJournal, 0);
1977 #ifdef SQLITE_CHECK_PAGES
1978 sqlite3PcacheIterateDirty(pPager->pPCache, pager_set_pagehash);
1979 if( pPager->dbSize==0 && sqlite3PcacheRefCount(pPager->pPCache)>0 ){
1980 PgHdr *p = sqlite3PagerLookup(pPager, 1);
1981 if( p ){
1982 p->pageHash = 0;
1983 sqlite3PagerUnrefNotNull(p);
1986 #endif
1988 sqlite3BitvecDestroy(pPager->pInJournal);
1989 pPager->pInJournal = 0;
1990 pPager->nRec = 0;
1991 sqlite3PcacheCleanAll(pPager->pPCache);
1992 sqlite3PcacheTruncate(pPager->pPCache, pPager->dbSize);
1994 if( pagerUseWal(pPager) ){
1995 /* Drop the WAL write-lock, if any. Also, if the connection was in
1996 ** locking_mode=exclusive mode but is no longer, drop the EXCLUSIVE
1997 ** lock held on the database file.
1999 rc2 = sqlite3WalEndWriteTransaction(pPager->pWal);
2000 assert( rc2==SQLITE_OK );
2001 }else if( rc==SQLITE_OK && bCommit && pPager->dbFileSize>pPager->dbSize ){
2002 /* This branch is taken when committing a transaction in rollback-journal
2003 ** mode if the database file on disk is larger than the database image.
2004 ** At this point the journal has been finalized and the transaction
2005 ** successfully committed, but the EXCLUSIVE lock is still held on the
2006 ** file. So it is safe to truncate the database file to its minimum
2007 ** required size. */
2008 assert( pPager->eLock==EXCLUSIVE_LOCK );
2009 rc = pager_truncate(pPager, pPager->dbSize);
2012 if( rc==SQLITE_OK && bCommit && isOpen(pPager->fd) ){
2013 rc = sqlite3OsFileControl(pPager->fd, SQLITE_FCNTL_COMMIT_PHASETWO, 0);
2014 if( rc==SQLITE_NOTFOUND ) rc = SQLITE_OK;
2017 if( !pPager->exclusiveMode
2018 && (!pagerUseWal(pPager) || sqlite3WalExclusiveMode(pPager->pWal, 0))
2020 rc2 = pagerUnlockDb(pPager, SHARED_LOCK);
2021 pPager->changeCountDone = 0;
2023 pPager->eState = PAGER_READER;
2024 pPager->setMaster = 0;
2026 return (rc==SQLITE_OK?rc2:rc);
2030 ** Execute a rollback if a transaction is active and unlock the
2031 ** database file.
2033 ** If the pager has already entered the ERROR state, do not attempt
2034 ** the rollback at this time. Instead, pager_unlock() is called. The
2035 ** call to pager_unlock() will discard all in-memory pages, unlock
2036 ** the database file and move the pager back to OPEN state. If this
2037 ** means that there is a hot-journal left in the file-system, the next
2038 ** connection to obtain a shared lock on the pager (which may be this one)
2039 ** will roll it back.
2041 ** If the pager has not already entered the ERROR state, but an IO or
2042 ** malloc error occurs during a rollback, then this will itself cause
2043 ** the pager to enter the ERROR state. Which will be cleared by the
2044 ** call to pager_unlock(), as described above.
2046 static void pagerUnlockAndRollback(Pager *pPager){
2047 if( pPager->eState!=PAGER_ERROR && pPager->eState!=PAGER_OPEN ){
2048 assert( assert_pager_state(pPager) );
2049 if( pPager->eState>=PAGER_WRITER_LOCKED ){
2050 sqlite3BeginBenignMalloc();
2051 sqlite3PagerRollback(pPager);
2052 sqlite3EndBenignMalloc();
2053 }else if( !pPager->exclusiveMode ){
2054 assert( pPager->eState==PAGER_READER );
2055 pager_end_transaction(pPager, 0, 0);
2058 pager_unlock(pPager);
2062 ** Parameter aData must point to a buffer of pPager->pageSize bytes
2063 ** of data. Compute and return a checksum based ont the contents of the
2064 ** page of data and the current value of pPager->cksumInit.
2066 ** This is not a real checksum. It is really just the sum of the
2067 ** random initial value (pPager->cksumInit) and every 200th byte
2068 ** of the page data, starting with byte offset (pPager->pageSize%200).
2069 ** Each byte is interpreted as an 8-bit unsigned integer.
2071 ** Changing the formula used to compute this checksum results in an
2072 ** incompatible journal file format.
2074 ** If journal corruption occurs due to a power failure, the most likely
2075 ** scenario is that one end or the other of the record will be changed.
2076 ** It is much less likely that the two ends of the journal record will be
2077 ** correct and the middle be corrupt. Thus, this "checksum" scheme,
2078 ** though fast and simple, catches the mostly likely kind of corruption.
2080 static u32 pager_cksum(Pager *pPager, const u8 *aData){
2081 u32 cksum = pPager->cksumInit; /* Checksum value to return */
2082 int i = pPager->pageSize-200; /* Loop counter */
2083 while( i>0 ){
2084 cksum += aData[i];
2085 i -= 200;
2087 return cksum;
2091 ** Report the current page size and number of reserved bytes back
2092 ** to the codec.
2094 #ifdef SQLITE_HAS_CODEC
2095 static void pagerReportSize(Pager *pPager){
2096 if( pPager->xCodecSizeChng ){
2097 pPager->xCodecSizeChng(pPager->pCodec, pPager->pageSize,
2098 (int)pPager->nReserve);
2101 #else
2102 # define pagerReportSize(X) /* No-op if we do not support a codec */
2103 #endif
2106 ** Read a single page from either the journal file (if isMainJrnl==1) or
2107 ** from the sub-journal (if isMainJrnl==0) and playback that page.
2108 ** The page begins at offset *pOffset into the file. The *pOffset
2109 ** value is increased to the start of the next page in the journal.
2111 ** The main rollback journal uses checksums - the statement journal does
2112 ** not.
2114 ** If the page number of the page record read from the (sub-)journal file
2115 ** is greater than the current value of Pager.dbSize, then playback is
2116 ** skipped and SQLITE_OK is returned.
2118 ** If pDone is not NULL, then it is a record of pages that have already
2119 ** been played back. If the page at *pOffset has already been played back
2120 ** (if the corresponding pDone bit is set) then skip the playback.
2121 ** Make sure the pDone bit corresponding to the *pOffset page is set
2122 ** prior to returning.
2124 ** If the page record is successfully read from the (sub-)journal file
2125 ** and played back, then SQLITE_OK is returned. If an IO error occurs
2126 ** while reading the record from the (sub-)journal file or while writing
2127 ** to the database file, then the IO error code is returned. If data
2128 ** is successfully read from the (sub-)journal file but appears to be
2129 ** corrupted, SQLITE_DONE is returned. Data is considered corrupted in
2130 ** two circumstances:
2132 ** * If the record page-number is illegal (0 or PAGER_MJ_PGNO), or
2133 ** * If the record is being rolled back from the main journal file
2134 ** and the checksum field does not match the record content.
2136 ** Neither of these two scenarios are possible during a savepoint rollback.
2138 ** If this is a savepoint rollback, then memory may have to be dynamically
2139 ** allocated by this function. If this is the case and an allocation fails,
2140 ** SQLITE_NOMEM is returned.
2142 static int pager_playback_one_page(
2143 Pager *pPager, /* The pager being played back */
2144 i64 *pOffset, /* Offset of record to playback */
2145 Bitvec *pDone, /* Bitvec of pages already played back */
2146 int isMainJrnl, /* 1 -> main journal. 0 -> sub-journal. */
2147 int isSavepnt /* True for a savepoint rollback */
2149 int rc;
2150 PgHdr *pPg; /* An existing page in the cache */
2151 Pgno pgno; /* The page number of a page in journal */
2152 u32 cksum; /* Checksum used for sanity checking */
2153 char *aData; /* Temporary storage for the page */
2154 sqlite3_file *jfd; /* The file descriptor for the journal file */
2155 int isSynced; /* True if journal page is synced */
2157 assert( (isMainJrnl&~1)==0 ); /* isMainJrnl is 0 or 1 */
2158 assert( (isSavepnt&~1)==0 ); /* isSavepnt is 0 or 1 */
2159 assert( isMainJrnl || pDone ); /* pDone always used on sub-journals */
2160 assert( isSavepnt || pDone==0 ); /* pDone never used on non-savepoint */
2162 aData = pPager->pTmpSpace;
2163 assert( aData ); /* Temp storage must have already been allocated */
2164 assert( pagerUseWal(pPager)==0 || (!isMainJrnl && isSavepnt) );
2166 /* Either the state is greater than PAGER_WRITER_CACHEMOD (a transaction
2167 ** or savepoint rollback done at the request of the caller) or this is
2168 ** a hot-journal rollback. If it is a hot-journal rollback, the pager
2169 ** is in state OPEN and holds an EXCLUSIVE lock. Hot-journal rollback
2170 ** only reads from the main journal, not the sub-journal.
2172 assert( pPager->eState>=PAGER_WRITER_CACHEMOD
2173 || (pPager->eState==PAGER_OPEN && pPager->eLock==EXCLUSIVE_LOCK)
2175 assert( pPager->eState>=PAGER_WRITER_CACHEMOD || isMainJrnl );
2177 /* Read the page number and page data from the journal or sub-journal
2178 ** file. Return an error code to the caller if an IO error occurs.
2180 jfd = isMainJrnl ? pPager->jfd : pPager->sjfd;
2181 rc = read32bits(jfd, *pOffset, &pgno);
2182 if( rc!=SQLITE_OK ) return rc;
2183 rc = sqlite3OsRead(jfd, (u8*)aData, pPager->pageSize, (*pOffset)+4);
2184 if( rc!=SQLITE_OK ) return rc;
2185 *pOffset += pPager->pageSize + 4 + isMainJrnl*4;
2187 /* Sanity checking on the page. This is more important that I originally
2188 ** thought. If a power failure occurs while the journal is being written,
2189 ** it could cause invalid data to be written into the journal. We need to
2190 ** detect this invalid data (with high probability) and ignore it.
2192 if( pgno==0 || pgno==PAGER_MJ_PGNO(pPager) ){
2193 assert( !isSavepnt );
2194 return SQLITE_DONE;
2196 if( pgno>(Pgno)pPager->dbSize || sqlite3BitvecTest(pDone, pgno) ){
2197 return SQLITE_OK;
2199 if( isMainJrnl ){
2200 rc = read32bits(jfd, (*pOffset)-4, &cksum);
2201 if( rc ) return rc;
2202 if( !isSavepnt && pager_cksum(pPager, (u8*)aData)!=cksum ){
2203 return SQLITE_DONE;
2207 /* If this page has already been played by before during the current
2208 ** rollback, then don't bother to play it back again.
2210 if( pDone && (rc = sqlite3BitvecSet(pDone, pgno))!=SQLITE_OK ){
2211 return rc;
2214 /* When playing back page 1, restore the nReserve setting
2216 if( pgno==1 && pPager->nReserve!=((u8*)aData)[20] ){
2217 pPager->nReserve = ((u8*)aData)[20];
2218 pagerReportSize(pPager);
2221 /* If the pager is in CACHEMOD state, then there must be a copy of this
2222 ** page in the pager cache. In this case just update the pager cache,
2223 ** not the database file. The page is left marked dirty in this case.
2225 ** An exception to the above rule: If the database is in no-sync mode
2226 ** and a page is moved during an incremental vacuum then the page may
2227 ** not be in the pager cache. Later: if a malloc() or IO error occurs
2228 ** during a Movepage() call, then the page may not be in the cache
2229 ** either. So the condition described in the above paragraph is not
2230 ** assert()able.
2232 ** If in WRITER_DBMOD, WRITER_FINISHED or OPEN state, then we update the
2233 ** pager cache if it exists and the main file. The page is then marked
2234 ** not dirty. Since this code is only executed in PAGER_OPEN state for
2235 ** a hot-journal rollback, it is guaranteed that the page-cache is empty
2236 ** if the pager is in OPEN state.
2238 ** Ticket #1171: The statement journal might contain page content that is
2239 ** different from the page content at the start of the transaction.
2240 ** This occurs when a page is changed prior to the start of a statement
2241 ** then changed again within the statement. When rolling back such a
2242 ** statement we must not write to the original database unless we know
2243 ** for certain that original page contents are synced into the main rollback
2244 ** journal. Otherwise, a power loss might leave modified data in the
2245 ** database file without an entry in the rollback journal that can
2246 ** restore the database to its original form. Two conditions must be
2247 ** met before writing to the database files. (1) the database must be
2248 ** locked. (2) we know that the original page content is fully synced
2249 ** in the main journal either because the page is not in cache or else
2250 ** the page is marked as needSync==0.
2252 ** 2008-04-14: When attempting to vacuum a corrupt database file, it
2253 ** is possible to fail a statement on a database that does not yet exist.
2254 ** Do not attempt to write if database file has never been opened.
2256 if( pagerUseWal(pPager) ){
2257 pPg = 0;
2258 }else{
2259 pPg = sqlite3PagerLookup(pPager, pgno);
2261 assert( pPg || !MEMDB );
2262 assert( pPager->eState!=PAGER_OPEN || pPg==0 );
2263 PAGERTRACE(("PLAYBACK %d page %d hash(%08x) %s\n",
2264 PAGERID(pPager), pgno, pager_datahash(pPager->pageSize, (u8*)aData),
2265 (isMainJrnl?"main-journal":"sub-journal")
2267 if( isMainJrnl ){
2268 isSynced = pPager->noSync || (*pOffset <= pPager->journalHdr);
2269 }else{
2270 isSynced = (pPg==0 || 0==(pPg->flags & PGHDR_NEED_SYNC));
2272 if( isOpen(pPager->fd)
2273 && (pPager->eState>=PAGER_WRITER_DBMOD || pPager->eState==PAGER_OPEN)
2274 && isSynced
2276 i64 ofst = (pgno-1)*(i64)pPager->pageSize;
2277 testcase( !isSavepnt && pPg!=0 && (pPg->flags&PGHDR_NEED_SYNC)!=0 );
2278 assert( !pagerUseWal(pPager) );
2279 rc = sqlite3OsWrite(pPager->fd, (u8 *)aData, pPager->pageSize, ofst);
2280 if( pgno>pPager->dbFileSize ){
2281 pPager->dbFileSize = pgno;
2283 if( pPager->pBackup ){
2284 CODEC1(pPager, aData, pgno, 3, rc=SQLITE_NOMEM);
2285 sqlite3BackupUpdate(pPager->pBackup, pgno, (u8*)aData);
2286 CODEC2(pPager, aData, pgno, 7, rc=SQLITE_NOMEM, aData);
2288 }else if( !isMainJrnl && pPg==0 ){
2289 /* If this is a rollback of a savepoint and data was not written to
2290 ** the database and the page is not in-memory, there is a potential
2291 ** problem. When the page is next fetched by the b-tree layer, it
2292 ** will be read from the database file, which may or may not be
2293 ** current.
2295 ** There are a couple of different ways this can happen. All are quite
2296 ** obscure. When running in synchronous mode, this can only happen
2297 ** if the page is on the free-list at the start of the transaction, then
2298 ** populated, then moved using sqlite3PagerMovepage().
2300 ** The solution is to add an in-memory page to the cache containing
2301 ** the data just read from the sub-journal. Mark the page as dirty
2302 ** and if the pager requires a journal-sync, then mark the page as
2303 ** requiring a journal-sync before it is written.
2305 assert( isSavepnt );
2306 assert( (pPager->doNotSpill & SPILLFLAG_ROLLBACK)==0 );
2307 pPager->doNotSpill |= SPILLFLAG_ROLLBACK;
2308 rc = sqlite3PagerAcquire(pPager, pgno, &pPg, 1);
2309 assert( (pPager->doNotSpill & SPILLFLAG_ROLLBACK)!=0 );
2310 pPager->doNotSpill &= ~SPILLFLAG_ROLLBACK;
2311 if( rc!=SQLITE_OK ) return rc;
2312 pPg->flags &= ~PGHDR_NEED_READ;
2313 sqlite3PcacheMakeDirty(pPg);
2315 if( pPg ){
2316 /* No page should ever be explicitly rolled back that is in use, except
2317 ** for page 1 which is held in use in order to keep the lock on the
2318 ** database active. However such a page may be rolled back as a result
2319 ** of an internal error resulting in an automatic call to
2320 ** sqlite3PagerRollback().
2322 void *pData;
2323 pData = pPg->pData;
2324 memcpy(pData, (u8*)aData, pPager->pageSize);
2325 pPager->xReiniter(pPg);
2326 if( isMainJrnl && (!isSavepnt || *pOffset<=pPager->journalHdr) ){
2327 /* If the contents of this page were just restored from the main
2328 ** journal file, then its content must be as they were when the
2329 ** transaction was first opened. In this case we can mark the page
2330 ** as clean, since there will be no need to write it out to the
2331 ** database.
2333 ** There is one exception to this rule. If the page is being rolled
2334 ** back as part of a savepoint (or statement) rollback from an
2335 ** unsynced portion of the main journal file, then it is not safe
2336 ** to mark the page as clean. This is because marking the page as
2337 ** clean will clear the PGHDR_NEED_SYNC flag. Since the page is
2338 ** already in the journal file (recorded in Pager.pInJournal) and
2339 ** the PGHDR_NEED_SYNC flag is cleared, if the page is written to
2340 ** again within this transaction, it will be marked as dirty but
2341 ** the PGHDR_NEED_SYNC flag will not be set. It could then potentially
2342 ** be written out into the database file before its journal file
2343 ** segment is synced. If a crash occurs during or following this,
2344 ** database corruption may ensue.
2346 assert( !pagerUseWal(pPager) );
2347 sqlite3PcacheMakeClean(pPg);
2349 pager_set_pagehash(pPg);
2351 /* If this was page 1, then restore the value of Pager.dbFileVers.
2352 ** Do this before any decoding. */
2353 if( pgno==1 ){
2354 memcpy(&pPager->dbFileVers, &((u8*)pData)[24],sizeof(pPager->dbFileVers));
2357 /* Decode the page just read from disk */
2358 CODEC1(pPager, pData, pPg->pgno, 3, rc=SQLITE_NOMEM);
2359 sqlite3PcacheRelease(pPg);
2361 return rc;
2365 ** Parameter zMaster is the name of a master journal file. A single journal
2366 ** file that referred to the master journal file has just been rolled back.
2367 ** This routine checks if it is possible to delete the master journal file,
2368 ** and does so if it is.
2370 ** Argument zMaster may point to Pager.pTmpSpace. So that buffer is not
2371 ** available for use within this function.
2373 ** When a master journal file is created, it is populated with the names
2374 ** of all of its child journals, one after another, formatted as utf-8
2375 ** encoded text. The end of each child journal file is marked with a
2376 ** nul-terminator byte (0x00). i.e. the entire contents of a master journal
2377 ** file for a transaction involving two databases might be:
2379 ** "/home/bill/a.db-journal\x00/home/bill/b.db-journal\x00"
2381 ** A master journal file may only be deleted once all of its child
2382 ** journals have been rolled back.
2384 ** This function reads the contents of the master-journal file into
2385 ** memory and loops through each of the child journal names. For
2386 ** each child journal, it checks if:
2388 ** * if the child journal exists, and if so
2389 ** * if the child journal contains a reference to master journal
2390 ** file zMaster
2392 ** If a child journal can be found that matches both of the criteria
2393 ** above, this function returns without doing anything. Otherwise, if
2394 ** no such child journal can be found, file zMaster is deleted from
2395 ** the file-system using sqlite3OsDelete().
2397 ** If an IO error within this function, an error code is returned. This
2398 ** function allocates memory by calling sqlite3Malloc(). If an allocation
2399 ** fails, SQLITE_NOMEM is returned. Otherwise, if no IO or malloc errors
2400 ** occur, SQLITE_OK is returned.
2402 ** TODO: This function allocates a single block of memory to load
2403 ** the entire contents of the master journal file. This could be
2404 ** a couple of kilobytes or so - potentially larger than the page
2405 ** size.
2407 static int pager_delmaster(Pager *pPager, const char *zMaster){
2408 sqlite3_vfs *pVfs = pPager->pVfs;
2409 int rc; /* Return code */
2410 sqlite3_file *pMaster; /* Malloc'd master-journal file descriptor */
2411 sqlite3_file *pJournal; /* Malloc'd child-journal file descriptor */
2412 char *zMasterJournal = 0; /* Contents of master journal file */
2413 i64 nMasterJournal; /* Size of master journal file */
2414 char *zJournal; /* Pointer to one journal within MJ file */
2415 char *zMasterPtr; /* Space to hold MJ filename from a journal file */
2416 int nMasterPtr; /* Amount of space allocated to zMasterPtr[] */
2418 /* Allocate space for both the pJournal and pMaster file descriptors.
2419 ** If successful, open the master journal file for reading.
2421 pMaster = (sqlite3_file *)sqlite3MallocZero(pVfs->szOsFile * 2);
2422 pJournal = (sqlite3_file *)(((u8 *)pMaster) + pVfs->szOsFile);
2423 if( !pMaster ){
2424 rc = SQLITE_NOMEM;
2425 }else{
2426 const int flags = (SQLITE_OPEN_READONLY|SQLITE_OPEN_MASTER_JOURNAL);
2427 rc = sqlite3OsOpen(pVfs, zMaster, pMaster, flags, 0);
2429 if( rc!=SQLITE_OK ) goto delmaster_out;
2431 /* Load the entire master journal file into space obtained from
2432 ** sqlite3_malloc() and pointed to by zMasterJournal. Also obtain
2433 ** sufficient space (in zMasterPtr) to hold the names of master
2434 ** journal files extracted from regular rollback-journals.
2436 rc = sqlite3OsFileSize(pMaster, &nMasterJournal);
2437 if( rc!=SQLITE_OK ) goto delmaster_out;
2438 nMasterPtr = pVfs->mxPathname+1;
2439 zMasterJournal = sqlite3Malloc(nMasterJournal + nMasterPtr + 1);
2440 if( !zMasterJournal ){
2441 rc = SQLITE_NOMEM;
2442 goto delmaster_out;
2444 zMasterPtr = &zMasterJournal[nMasterJournal+1];
2445 rc = sqlite3OsRead(pMaster, zMasterJournal, (int)nMasterJournal, 0);
2446 if( rc!=SQLITE_OK ) goto delmaster_out;
2447 zMasterJournal[nMasterJournal] = 0;
2449 zJournal = zMasterJournal;
2450 while( (zJournal-zMasterJournal)<nMasterJournal ){
2451 int exists;
2452 rc = sqlite3OsAccess(pVfs, zJournal, SQLITE_ACCESS_EXISTS, &exists);
2453 if( rc!=SQLITE_OK ){
2454 goto delmaster_out;
2456 if( exists ){
2457 /* One of the journals pointed to by the master journal exists.
2458 ** Open it and check if it points at the master journal. If
2459 ** so, return without deleting the master journal file.
2461 int c;
2462 int flags = (SQLITE_OPEN_READONLY|SQLITE_OPEN_MAIN_JOURNAL);
2463 rc = sqlite3OsOpen(pVfs, zJournal, pJournal, flags, 0);
2464 if( rc!=SQLITE_OK ){
2465 goto delmaster_out;
2468 rc = readMasterJournal(pJournal, zMasterPtr, nMasterPtr);
2469 sqlite3OsClose(pJournal);
2470 if( rc!=SQLITE_OK ){
2471 goto delmaster_out;
2474 c = zMasterPtr[0]!=0 && strcmp(zMasterPtr, zMaster)==0;
2475 if( c ){
2476 /* We have a match. Do not delete the master journal file. */
2477 goto delmaster_out;
2480 zJournal += (sqlite3Strlen30(zJournal)+1);
2483 sqlite3OsClose(pMaster);
2484 rc = sqlite3OsDelete(pVfs, zMaster, 0);
2486 delmaster_out:
2487 sqlite3_free(zMasterJournal);
2488 if( pMaster ){
2489 sqlite3OsClose(pMaster);
2490 assert( !isOpen(pJournal) );
2491 sqlite3_free(pMaster);
2493 return rc;
2498 ** This function is used to change the actual size of the database
2499 ** file in the file-system. This only happens when committing a transaction,
2500 ** or rolling back a transaction (including rolling back a hot-journal).
2502 ** If the main database file is not open, or the pager is not in either
2503 ** DBMOD or OPEN state, this function is a no-op. Otherwise, the size
2504 ** of the file is changed to nPage pages (nPage*pPager->pageSize bytes).
2505 ** If the file on disk is currently larger than nPage pages, then use the VFS
2506 ** xTruncate() method to truncate it.
2508 ** Or, it might be the case that the file on disk is smaller than
2509 ** nPage pages. Some operating system implementations can get confused if
2510 ** you try to truncate a file to some size that is larger than it
2511 ** currently is, so detect this case and write a single zero byte to
2512 ** the end of the new file instead.
2514 ** If successful, return SQLITE_OK. If an IO error occurs while modifying
2515 ** the database file, return the error code to the caller.
2517 static int pager_truncate(Pager *pPager, Pgno nPage){
2518 int rc = SQLITE_OK;
2519 assert( pPager->eState!=PAGER_ERROR );
2520 assert( pPager->eState!=PAGER_READER );
2522 if( isOpen(pPager->fd)
2523 && (pPager->eState>=PAGER_WRITER_DBMOD || pPager->eState==PAGER_OPEN)
2525 i64 currentSize, newSize;
2526 int szPage = pPager->pageSize;
2527 assert( pPager->eLock==EXCLUSIVE_LOCK );
2528 /* TODO: Is it safe to use Pager.dbFileSize here? */
2529 rc = sqlite3OsFileSize(pPager->fd, &currentSize);
2530 newSize = szPage*(i64)nPage;
2531 if( rc==SQLITE_OK && currentSize!=newSize ){
2532 if( currentSize>newSize ){
2533 rc = sqlite3OsTruncate(pPager->fd, newSize);
2534 }else if( (currentSize+szPage)<=newSize ){
2535 char *pTmp = pPager->pTmpSpace;
2536 memset(pTmp, 0, szPage);
2537 testcase( (newSize-szPage) == currentSize );
2538 testcase( (newSize-szPage) > currentSize );
2539 rc = sqlite3OsWrite(pPager->fd, pTmp, szPage, newSize-szPage);
2541 if( rc==SQLITE_OK ){
2542 pPager->dbFileSize = nPage;
2546 return rc;
2550 ** Return a sanitized version of the sector-size of OS file pFile. The
2551 ** return value is guaranteed to lie between 32 and MAX_SECTOR_SIZE.
2553 int sqlite3SectorSize(sqlite3_file *pFile){
2554 int iRet = sqlite3OsSectorSize(pFile);
2555 if( iRet<32 ){
2556 iRet = 512;
2557 }else if( iRet>MAX_SECTOR_SIZE ){
2558 assert( MAX_SECTOR_SIZE>=512 );
2559 iRet = MAX_SECTOR_SIZE;
2561 return iRet;
2565 ** Set the value of the Pager.sectorSize variable for the given
2566 ** pager based on the value returned by the xSectorSize method
2567 ** of the open database file. The sector size will be used
2568 ** to determine the size and alignment of journal header and
2569 ** master journal pointers within created journal files.
2571 ** For temporary files the effective sector size is always 512 bytes.
2573 ** Otherwise, for non-temporary files, the effective sector size is
2574 ** the value returned by the xSectorSize() method rounded up to 32 if
2575 ** it is less than 32, or rounded down to MAX_SECTOR_SIZE if it
2576 ** is greater than MAX_SECTOR_SIZE.
2578 ** If the file has the SQLITE_IOCAP_POWERSAFE_OVERWRITE property, then set
2579 ** the effective sector size to its minimum value (512). The purpose of
2580 ** pPager->sectorSize is to define the "blast radius" of bytes that
2581 ** might change if a crash occurs while writing to a single byte in
2582 ** that range. But with POWERSAFE_OVERWRITE, the blast radius is zero
2583 ** (that is what POWERSAFE_OVERWRITE means), so we minimize the sector
2584 ** size. For backwards compatibility of the rollback journal file format,
2585 ** we cannot reduce the effective sector size below 512.
2587 static void setSectorSize(Pager *pPager){
2588 assert( isOpen(pPager->fd) || pPager->tempFile );
2590 if( pPager->tempFile
2591 || (sqlite3OsDeviceCharacteristics(pPager->fd) &
2592 SQLITE_IOCAP_POWERSAFE_OVERWRITE)!=0
2594 /* Sector size doesn't matter for temporary files. Also, the file
2595 ** may not have been opened yet, in which case the OsSectorSize()
2596 ** call will segfault. */
2597 pPager->sectorSize = 512;
2598 }else{
2599 pPager->sectorSize = sqlite3SectorSize(pPager->fd);
2604 ** Playback the journal and thus restore the database file to
2605 ** the state it was in before we started making changes.
2607 ** The journal file format is as follows:
2609 ** (1) 8 byte prefix. A copy of aJournalMagic[].
2610 ** (2) 4 byte big-endian integer which is the number of valid page records
2611 ** in the journal. If this value is 0xffffffff, then compute the
2612 ** number of page records from the journal size.
2613 ** (3) 4 byte big-endian integer which is the initial value for the
2614 ** sanity checksum.
2615 ** (4) 4 byte integer which is the number of pages to truncate the
2616 ** database to during a rollback.
2617 ** (5) 4 byte big-endian integer which is the sector size. The header
2618 ** is this many bytes in size.
2619 ** (6) 4 byte big-endian integer which is the page size.
2620 ** (7) zero padding out to the next sector size.
2621 ** (8) Zero or more pages instances, each as follows:
2622 ** + 4 byte page number.
2623 ** + pPager->pageSize bytes of data.
2624 ** + 4 byte checksum
2626 ** When we speak of the journal header, we mean the first 7 items above.
2627 ** Each entry in the journal is an instance of the 8th item.
2629 ** Call the value from the second bullet "nRec". nRec is the number of
2630 ** valid page entries in the journal. In most cases, you can compute the
2631 ** value of nRec from the size of the journal file. But if a power
2632 ** failure occurred while the journal was being written, it could be the
2633 ** case that the size of the journal file had already been increased but
2634 ** the extra entries had not yet made it safely to disk. In such a case,
2635 ** the value of nRec computed from the file size would be too large. For
2636 ** that reason, we always use the nRec value in the header.
2638 ** If the nRec value is 0xffffffff it means that nRec should be computed
2639 ** from the file size. This value is used when the user selects the
2640 ** no-sync option for the journal. A power failure could lead to corruption
2641 ** in this case. But for things like temporary table (which will be
2642 ** deleted when the power is restored) we don't care.
2644 ** If the file opened as the journal file is not a well-formed
2645 ** journal file then all pages up to the first corrupted page are rolled
2646 ** back (or no pages if the journal header is corrupted). The journal file
2647 ** is then deleted and SQLITE_OK returned, just as if no corruption had
2648 ** been encountered.
2650 ** If an I/O or malloc() error occurs, the journal-file is not deleted
2651 ** and an error code is returned.
2653 ** The isHot parameter indicates that we are trying to rollback a journal
2654 ** that might be a hot journal. Or, it could be that the journal is
2655 ** preserved because of JOURNALMODE_PERSIST or JOURNALMODE_TRUNCATE.
2656 ** If the journal really is hot, reset the pager cache prior rolling
2657 ** back any content. If the journal is merely persistent, no reset is
2658 ** needed.
2660 static int pager_playback(Pager *pPager, int isHot){
2661 sqlite3_vfs *pVfs = pPager->pVfs;
2662 i64 szJ; /* Size of the journal file in bytes */
2663 u32 nRec; /* Number of Records in the journal */
2664 u32 u; /* Unsigned loop counter */
2665 Pgno mxPg = 0; /* Size of the original file in pages */
2666 int rc; /* Result code of a subroutine */
2667 int res = 1; /* Value returned by sqlite3OsAccess() */
2668 char *zMaster = 0; /* Name of master journal file if any */
2669 int needPagerReset; /* True to reset page prior to first page rollback */
2670 int nPlayback = 0; /* Total number of pages restored from journal */
2672 /* Figure out how many records are in the journal. Abort early if
2673 ** the journal is empty.
2675 assert( isOpen(pPager->jfd) );
2676 rc = sqlite3OsFileSize(pPager->jfd, &szJ);
2677 if( rc!=SQLITE_OK ){
2678 goto end_playback;
2681 /* Read the master journal name from the journal, if it is present.
2682 ** If a master journal file name is specified, but the file is not
2683 ** present on disk, then the journal is not hot and does not need to be
2684 ** played back.
2686 ** TODO: Technically the following is an error because it assumes that
2687 ** buffer Pager.pTmpSpace is (mxPathname+1) bytes or larger. i.e. that
2688 ** (pPager->pageSize >= pPager->pVfs->mxPathname+1). Using os_unix.c,
2689 ** mxPathname is 512, which is the same as the minimum allowable value
2690 ** for pageSize.
2692 zMaster = pPager->pTmpSpace;
2693 rc = readMasterJournal(pPager->jfd, zMaster, pPager->pVfs->mxPathname+1);
2694 if( rc==SQLITE_OK && zMaster[0] ){
2695 rc = sqlite3OsAccess(pVfs, zMaster, SQLITE_ACCESS_EXISTS, &res);
2697 zMaster = 0;
2698 if( rc!=SQLITE_OK || !res ){
2699 goto end_playback;
2701 pPager->journalOff = 0;
2702 needPagerReset = isHot;
2704 /* This loop terminates either when a readJournalHdr() or
2705 ** pager_playback_one_page() call returns SQLITE_DONE or an IO error
2706 ** occurs.
2708 while( 1 ){
2709 /* Read the next journal header from the journal file. If there are
2710 ** not enough bytes left in the journal file for a complete header, or
2711 ** it is corrupted, then a process must have failed while writing it.
2712 ** This indicates nothing more needs to be rolled back.
2714 rc = readJournalHdr(pPager, isHot, szJ, &nRec, &mxPg);
2715 if( rc!=SQLITE_OK ){
2716 if( rc==SQLITE_DONE ){
2717 rc = SQLITE_OK;
2719 goto end_playback;
2722 /* If nRec is 0xffffffff, then this journal was created by a process
2723 ** working in no-sync mode. This means that the rest of the journal
2724 ** file consists of pages, there are no more journal headers. Compute
2725 ** the value of nRec based on this assumption.
2727 if( nRec==0xffffffff ){
2728 assert( pPager->journalOff==JOURNAL_HDR_SZ(pPager) );
2729 nRec = (int)((szJ - JOURNAL_HDR_SZ(pPager))/JOURNAL_PG_SZ(pPager));
2732 /* If nRec is 0 and this rollback is of a transaction created by this
2733 ** process and if this is the final header in the journal, then it means
2734 ** that this part of the journal was being filled but has not yet been
2735 ** synced to disk. Compute the number of pages based on the remaining
2736 ** size of the file.
2738 ** The third term of the test was added to fix ticket #2565.
2739 ** When rolling back a hot journal, nRec==0 always means that the next
2740 ** chunk of the journal contains zero pages to be rolled back. But
2741 ** when doing a ROLLBACK and the nRec==0 chunk is the last chunk in
2742 ** the journal, it means that the journal might contain additional
2743 ** pages that need to be rolled back and that the number of pages
2744 ** should be computed based on the journal file size.
2746 if( nRec==0 && !isHot &&
2747 pPager->journalHdr+JOURNAL_HDR_SZ(pPager)==pPager->journalOff ){
2748 nRec = (int)((szJ - pPager->journalOff) / JOURNAL_PG_SZ(pPager));
2751 /* If this is the first header read from the journal, truncate the
2752 ** database file back to its original size.
2754 if( pPager->journalOff==JOURNAL_HDR_SZ(pPager) ){
2755 rc = pager_truncate(pPager, mxPg);
2756 if( rc!=SQLITE_OK ){
2757 goto end_playback;
2759 pPager->dbSize = mxPg;
2762 /* Copy original pages out of the journal and back into the
2763 ** database file and/or page cache.
2765 for(u=0; u<nRec; u++){
2766 if( needPagerReset ){
2767 pager_reset(pPager);
2768 needPagerReset = 0;
2770 rc = pager_playback_one_page(pPager,&pPager->journalOff,0,1,0);
2771 if( rc==SQLITE_OK ){
2772 nPlayback++;
2773 }else{
2774 if( rc==SQLITE_DONE ){
2775 pPager->journalOff = szJ;
2776 break;
2777 }else if( rc==SQLITE_IOERR_SHORT_READ ){
2778 /* If the journal has been truncated, simply stop reading and
2779 ** processing the journal. This might happen if the journal was
2780 ** not completely written and synced prior to a crash. In that
2781 ** case, the database should have never been written in the
2782 ** first place so it is OK to simply abandon the rollback. */
2783 rc = SQLITE_OK;
2784 goto end_playback;
2785 }else{
2786 /* If we are unable to rollback, quit and return the error
2787 ** code. This will cause the pager to enter the error state
2788 ** so that no further harm will be done. Perhaps the next
2789 ** process to come along will be able to rollback the database.
2791 goto end_playback;
2796 /*NOTREACHED*/
2797 assert( 0 );
2799 end_playback:
2800 /* Following a rollback, the database file should be back in its original
2801 ** state prior to the start of the transaction, so invoke the
2802 ** SQLITE_FCNTL_DB_UNCHANGED file-control method to disable the
2803 ** assertion that the transaction counter was modified.
2805 #ifdef SQLITE_DEBUG
2806 if( pPager->fd->pMethods ){
2807 sqlite3OsFileControlHint(pPager->fd,SQLITE_FCNTL_DB_UNCHANGED,0);
2809 #endif
2811 /* If this playback is happening automatically as a result of an IO or
2812 ** malloc error that occurred after the change-counter was updated but
2813 ** before the transaction was committed, then the change-counter
2814 ** modification may just have been reverted. If this happens in exclusive
2815 ** mode, then subsequent transactions performed by the connection will not
2816 ** update the change-counter at all. This may lead to cache inconsistency
2817 ** problems for other processes at some point in the future. So, just
2818 ** in case this has happened, clear the changeCountDone flag now.
2820 pPager->changeCountDone = pPager->tempFile;
2822 if( rc==SQLITE_OK ){
2823 zMaster = pPager->pTmpSpace;
2824 rc = readMasterJournal(pPager->jfd, zMaster, pPager->pVfs->mxPathname+1);
2825 testcase( rc!=SQLITE_OK );
2827 if( rc==SQLITE_OK
2828 && (pPager->eState>=PAGER_WRITER_DBMOD || pPager->eState==PAGER_OPEN)
2830 rc = sqlite3PagerSync(pPager, 0);
2832 if( rc==SQLITE_OK ){
2833 rc = pager_end_transaction(pPager, zMaster[0]!='\0', 0);
2834 testcase( rc!=SQLITE_OK );
2836 if( rc==SQLITE_OK && zMaster[0] && res ){
2837 /* If there was a master journal and this routine will return success,
2838 ** see if it is possible to delete the master journal.
2840 rc = pager_delmaster(pPager, zMaster);
2841 testcase( rc!=SQLITE_OK );
2843 if( isHot && nPlayback ){
2844 sqlite3_log(SQLITE_NOTICE_RECOVER_ROLLBACK, "recovered %d pages from %s",
2845 nPlayback, pPager->zJournal);
2848 /* The Pager.sectorSize variable may have been updated while rolling
2849 ** back a journal created by a process with a different sector size
2850 ** value. Reset it to the correct value for this process.
2852 setSectorSize(pPager);
2853 return rc;
2858 ** Read the content for page pPg out of the database file and into
2859 ** pPg->pData. A shared lock or greater must be held on the database
2860 ** file before this function is called.
2862 ** If page 1 is read, then the value of Pager.dbFileVers[] is set to
2863 ** the value read from the database file.
2865 ** If an IO error occurs, then the IO error is returned to the caller.
2866 ** Otherwise, SQLITE_OK is returned.
2868 static int readDbPage(PgHdr *pPg, u32 iFrame){
2869 Pager *pPager = pPg->pPager; /* Pager object associated with page pPg */
2870 Pgno pgno = pPg->pgno; /* Page number to read */
2871 int rc = SQLITE_OK; /* Return code */
2872 int pgsz = pPager->pageSize; /* Number of bytes to read */
2874 assert( pPager->eState>=PAGER_READER && !MEMDB );
2875 assert( isOpen(pPager->fd) );
2877 #ifndef SQLITE_OMIT_WAL
2878 if( iFrame ){
2879 /* Try to pull the page from the write-ahead log. */
2880 rc = sqlite3WalReadFrame(pPager->pWal, iFrame, pgsz, pPg->pData);
2881 }else
2882 #endif
2884 i64 iOffset = (pgno-1)*(i64)pPager->pageSize;
2885 rc = sqlite3OsRead(pPager->fd, pPg->pData, pgsz, iOffset);
2886 if( rc==SQLITE_IOERR_SHORT_READ ){
2887 rc = SQLITE_OK;
2891 if( pgno==1 ){
2892 if( rc ){
2893 /* If the read is unsuccessful, set the dbFileVers[] to something
2894 ** that will never be a valid file version. dbFileVers[] is a copy
2895 ** of bytes 24..39 of the database. Bytes 28..31 should always be
2896 ** zero or the size of the database in page. Bytes 32..35 and 35..39
2897 ** should be page numbers which are never 0xffffffff. So filling
2898 ** pPager->dbFileVers[] with all 0xff bytes should suffice.
2900 ** For an encrypted database, the situation is more complex: bytes
2901 ** 24..39 of the database are white noise. But the probability of
2902 ** white noising equaling 16 bytes of 0xff is vanishingly small so
2903 ** we should still be ok.
2905 memset(pPager->dbFileVers, 0xff, sizeof(pPager->dbFileVers));
2906 }else{
2907 u8 *dbFileVers = &((u8*)pPg->pData)[24];
2908 memcpy(&pPager->dbFileVers, dbFileVers, sizeof(pPager->dbFileVers));
2911 CODEC1(pPager, pPg->pData, pgno, 3, rc = SQLITE_NOMEM);
2913 PAGER_INCR(sqlite3_pager_readdb_count);
2914 PAGER_INCR(pPager->nRead);
2915 IOTRACE(("PGIN %p %d\n", pPager, pgno));
2916 PAGERTRACE(("FETCH %d page %d hash(%08x)\n",
2917 PAGERID(pPager), pgno, pager_pagehash(pPg)));
2919 return rc;
2923 ** Update the value of the change-counter at offsets 24 and 92 in
2924 ** the header and the sqlite version number at offset 96.
2926 ** This is an unconditional update. See also the pager_incr_changecounter()
2927 ** routine which only updates the change-counter if the update is actually
2928 ** needed, as determined by the pPager->changeCountDone state variable.
2930 static void pager_write_changecounter(PgHdr *pPg){
2931 u32 change_counter;
2933 /* Increment the value just read and write it back to byte 24. */
2934 change_counter = sqlite3Get4byte((u8*)pPg->pPager->dbFileVers)+1;
2935 put32bits(((char*)pPg->pData)+24, change_counter);
2937 /* Also store the SQLite version number in bytes 96..99 and in
2938 ** bytes 92..95 store the change counter for which the version number
2939 ** is valid. */
2940 put32bits(((char*)pPg->pData)+92, change_counter);
2941 put32bits(((char*)pPg->pData)+96, SQLITE_VERSION_NUMBER);
2944 #ifndef SQLITE_OMIT_WAL
2946 ** This function is invoked once for each page that has already been
2947 ** written into the log file when a WAL transaction is rolled back.
2948 ** Parameter iPg is the page number of said page. The pCtx argument
2949 ** is actually a pointer to the Pager structure.
2951 ** If page iPg is present in the cache, and has no outstanding references,
2952 ** it is discarded. Otherwise, if there are one or more outstanding
2953 ** references, the page content is reloaded from the database. If the
2954 ** attempt to reload content from the database is required and fails,
2955 ** return an SQLite error code. Otherwise, SQLITE_OK.
2957 static int pagerUndoCallback(void *pCtx, Pgno iPg){
2958 int rc = SQLITE_OK;
2959 Pager *pPager = (Pager *)pCtx;
2960 PgHdr *pPg;
2962 assert( pagerUseWal(pPager) );
2963 pPg = sqlite3PagerLookup(pPager, iPg);
2964 if( pPg ){
2965 if( sqlite3PcachePageRefcount(pPg)==1 ){
2966 sqlite3PcacheDrop(pPg);
2967 }else{
2968 u32 iFrame = 0;
2969 rc = sqlite3WalFindFrame(pPager->pWal, pPg->pgno, &iFrame);
2970 if( rc==SQLITE_OK ){
2971 rc = readDbPage(pPg, iFrame);
2973 if( rc==SQLITE_OK ){
2974 pPager->xReiniter(pPg);
2976 sqlite3PagerUnrefNotNull(pPg);
2980 /* Normally, if a transaction is rolled back, any backup processes are
2981 ** updated as data is copied out of the rollback journal and into the
2982 ** database. This is not generally possible with a WAL database, as
2983 ** rollback involves simply truncating the log file. Therefore, if one
2984 ** or more frames have already been written to the log (and therefore
2985 ** also copied into the backup databases) as part of this transaction,
2986 ** the backups must be restarted.
2988 sqlite3BackupRestart(pPager->pBackup);
2990 return rc;
2994 ** This function is called to rollback a transaction on a WAL database.
2996 static int pagerRollbackWal(Pager *pPager){
2997 int rc; /* Return Code */
2998 PgHdr *pList; /* List of dirty pages to revert */
3000 /* For all pages in the cache that are currently dirty or have already
3001 ** been written (but not committed) to the log file, do one of the
3002 ** following:
3004 ** + Discard the cached page (if refcount==0), or
3005 ** + Reload page content from the database (if refcount>0).
3007 pPager->dbSize = pPager->dbOrigSize;
3008 rc = sqlite3WalUndo(pPager->pWal, pagerUndoCallback, (void *)pPager);
3009 pList = sqlite3PcacheDirtyList(pPager->pPCache);
3010 while( pList && rc==SQLITE_OK ){
3011 PgHdr *pNext = pList->pDirty;
3012 rc = pagerUndoCallback((void *)pPager, pList->pgno);
3013 pList = pNext;
3016 return rc;
3020 ** This function is a wrapper around sqlite3WalFrames(). As well as logging
3021 ** the contents of the list of pages headed by pList (connected by pDirty),
3022 ** this function notifies any active backup processes that the pages have
3023 ** changed.
3025 ** The list of pages passed into this routine is always sorted by page number.
3026 ** Hence, if page 1 appears anywhere on the list, it will be the first page.
3028 static int pagerWalFrames(
3029 Pager *pPager, /* Pager object */
3030 PgHdr *pList, /* List of frames to log */
3031 Pgno nTruncate, /* Database size after this commit */
3032 int isCommit /* True if this is a commit */
3034 int rc; /* Return code */
3035 int nList; /* Number of pages in pList */
3036 #if defined(SQLITE_DEBUG) || defined(SQLITE_CHECK_PAGES)
3037 PgHdr *p; /* For looping over pages */
3038 #endif
3040 assert( pPager->pWal );
3041 assert( pList );
3042 #ifdef SQLITE_DEBUG
3043 /* Verify that the page list is in accending order */
3044 for(p=pList; p && p->pDirty; p=p->pDirty){
3045 assert( p->pgno < p->pDirty->pgno );
3047 #endif
3049 assert( pList->pDirty==0 || isCommit );
3050 if( isCommit ){
3051 /* If a WAL transaction is being committed, there is no point in writing
3052 ** any pages with page numbers greater than nTruncate into the WAL file.
3053 ** They will never be read by any client. So remove them from the pDirty
3054 ** list here. */
3055 PgHdr *p;
3056 PgHdr **ppNext = &pList;
3057 nList = 0;
3058 for(p=pList; (*ppNext = p)!=0; p=p->pDirty){
3059 if( p->pgno<=nTruncate ){
3060 ppNext = &p->pDirty;
3061 nList++;
3064 assert( pList );
3065 }else{
3066 nList = 1;
3068 pPager->aStat[PAGER_STAT_WRITE] += nList;
3070 if( pList->pgno==1 ) pager_write_changecounter(pList);
3071 rc = sqlite3WalFrames(pPager->pWal,
3072 pPager->pageSize, pList, nTruncate, isCommit, pPager->walSyncFlags
3074 if( rc==SQLITE_OK && pPager->pBackup ){
3075 PgHdr *p;
3076 for(p=pList; p; p=p->pDirty){
3077 sqlite3BackupUpdate(pPager->pBackup, p->pgno, (u8 *)p->pData);
3081 #ifdef SQLITE_CHECK_PAGES
3082 pList = sqlite3PcacheDirtyList(pPager->pPCache);
3083 for(p=pList; p; p=p->pDirty){
3084 pager_set_pagehash(p);
3086 #endif
3088 return rc;
3092 ** Begin a read transaction on the WAL.
3094 ** This routine used to be called "pagerOpenSnapshot()" because it essentially
3095 ** makes a snapshot of the database at the current point in time and preserves
3096 ** that snapshot for use by the reader in spite of concurrently changes by
3097 ** other writers or checkpointers.
3099 static int pagerBeginReadTransaction(Pager *pPager){
3100 int rc; /* Return code */
3101 int changed = 0; /* True if cache must be reset */
3103 assert( pagerUseWal(pPager) );
3104 assert( pPager->eState==PAGER_OPEN || pPager->eState==PAGER_READER );
3106 /* sqlite3WalEndReadTransaction() was not called for the previous
3107 ** transaction in locking_mode=EXCLUSIVE. So call it now. If we
3108 ** are in locking_mode=NORMAL and EndRead() was previously called,
3109 ** the duplicate call is harmless.
3111 sqlite3WalEndReadTransaction(pPager->pWal);
3113 rc = sqlite3WalBeginReadTransaction(pPager->pWal, &changed);
3114 if( rc!=SQLITE_OK || changed ){
3115 pager_reset(pPager);
3116 if( USEFETCH(pPager) ) sqlite3OsUnfetch(pPager->fd, 0, 0);
3119 return rc;
3121 #endif
3124 ** This function is called as part of the transition from PAGER_OPEN
3125 ** to PAGER_READER state to determine the size of the database file
3126 ** in pages (assuming the page size currently stored in Pager.pageSize).
3128 ** If no error occurs, SQLITE_OK is returned and the size of the database
3129 ** in pages is stored in *pnPage. Otherwise, an error code (perhaps
3130 ** SQLITE_IOERR_FSTAT) is returned and *pnPage is left unmodified.
3132 static int pagerPagecount(Pager *pPager, Pgno *pnPage){
3133 Pgno nPage; /* Value to return via *pnPage */
3135 /* Query the WAL sub-system for the database size. The WalDbsize()
3136 ** function returns zero if the WAL is not open (i.e. Pager.pWal==0), or
3137 ** if the database size is not available. The database size is not
3138 ** available from the WAL sub-system if the log file is empty or
3139 ** contains no valid committed transactions.
3141 assert( pPager->eState==PAGER_OPEN );
3142 assert( pPager->eLock>=SHARED_LOCK );
3143 nPage = sqlite3WalDbsize(pPager->pWal);
3145 /* If the database size was not available from the WAL sub-system,
3146 ** determine it based on the size of the database file. If the size
3147 ** of the database file is not an integer multiple of the page-size,
3148 ** round down to the nearest page. Except, any file larger than 0
3149 ** bytes in size is considered to contain at least one page.
3151 if( nPage==0 ){
3152 i64 n = 0; /* Size of db file in bytes */
3153 assert( isOpen(pPager->fd) || pPager->tempFile );
3154 if( isOpen(pPager->fd) ){
3155 int rc = sqlite3OsFileSize(pPager->fd, &n);
3156 if( rc!=SQLITE_OK ){
3157 return rc;
3160 nPage = (Pgno)((n+pPager->pageSize-1) / pPager->pageSize);
3163 /* If the current number of pages in the file is greater than the
3164 ** configured maximum pager number, increase the allowed limit so
3165 ** that the file can be read.
3167 if( nPage>pPager->mxPgno ){
3168 pPager->mxPgno = (Pgno)nPage;
3171 *pnPage = nPage;
3172 return SQLITE_OK;
3175 #ifndef SQLITE_OMIT_WAL
3177 ** Check if the *-wal file that corresponds to the database opened by pPager
3178 ** exists if the database is not empy, or verify that the *-wal file does
3179 ** not exist (by deleting it) if the database file is empty.
3181 ** If the database is not empty and the *-wal file exists, open the pager
3182 ** in WAL mode. If the database is empty or if no *-wal file exists and
3183 ** if no error occurs, make sure Pager.journalMode is not set to
3184 ** PAGER_JOURNALMODE_WAL.
3186 ** Return SQLITE_OK or an error code.
3188 ** The caller must hold a SHARED lock on the database file to call this
3189 ** function. Because an EXCLUSIVE lock on the db file is required to delete
3190 ** a WAL on a none-empty database, this ensures there is no race condition
3191 ** between the xAccess() below and an xDelete() being executed by some
3192 ** other connection.
3194 static int pagerOpenWalIfPresent(Pager *pPager){
3195 int rc = SQLITE_OK;
3196 assert( pPager->eState==PAGER_OPEN );
3197 assert( pPager->eLock>=SHARED_LOCK );
3199 if( !pPager->tempFile ){
3200 int isWal; /* True if WAL file exists */
3201 Pgno nPage; /* Size of the database file */
3203 rc = pagerPagecount(pPager, &nPage);
3204 if( rc ) return rc;
3205 if( nPage==0 ){
3206 rc = sqlite3OsDelete(pPager->pVfs, pPager->zWal, 0);
3207 if( rc==SQLITE_IOERR_DELETE_NOENT ) rc = SQLITE_OK;
3208 isWal = 0;
3209 }else{
3210 rc = sqlite3OsAccess(
3211 pPager->pVfs, pPager->zWal, SQLITE_ACCESS_EXISTS, &isWal
3214 if( rc==SQLITE_OK ){
3215 if( isWal ){
3216 testcase( sqlite3PcachePagecount(pPager->pPCache)==0 );
3217 rc = sqlite3PagerOpenWal(pPager, 0);
3218 }else if( pPager->journalMode==PAGER_JOURNALMODE_WAL ){
3219 pPager->journalMode = PAGER_JOURNALMODE_DELETE;
3223 return rc;
3225 #endif
3228 ** Playback savepoint pSavepoint. Or, if pSavepoint==NULL, then playback
3229 ** the entire master journal file. The case pSavepoint==NULL occurs when
3230 ** a ROLLBACK TO command is invoked on a SAVEPOINT that is a transaction
3231 ** savepoint.
3233 ** When pSavepoint is not NULL (meaning a non-transaction savepoint is
3234 ** being rolled back), then the rollback consists of up to three stages,
3235 ** performed in the order specified:
3237 ** * Pages are played back from the main journal starting at byte
3238 ** offset PagerSavepoint.iOffset and continuing to
3239 ** PagerSavepoint.iHdrOffset, or to the end of the main journal
3240 ** file if PagerSavepoint.iHdrOffset is zero.
3242 ** * If PagerSavepoint.iHdrOffset is not zero, then pages are played
3243 ** back starting from the journal header immediately following
3244 ** PagerSavepoint.iHdrOffset to the end of the main journal file.
3246 ** * Pages are then played back from the sub-journal file, starting
3247 ** with the PagerSavepoint.iSubRec and continuing to the end of
3248 ** the journal file.
3250 ** Throughout the rollback process, each time a page is rolled back, the
3251 ** corresponding bit is set in a bitvec structure (variable pDone in the
3252 ** implementation below). This is used to ensure that a page is only
3253 ** rolled back the first time it is encountered in either journal.
3255 ** If pSavepoint is NULL, then pages are only played back from the main
3256 ** journal file. There is no need for a bitvec in this case.
3258 ** In either case, before playback commences the Pager.dbSize variable
3259 ** is reset to the value that it held at the start of the savepoint
3260 ** (or transaction). No page with a page-number greater than this value
3261 ** is played back. If one is encountered it is simply skipped.
3263 static int pagerPlaybackSavepoint(Pager *pPager, PagerSavepoint *pSavepoint){
3264 i64 szJ; /* Effective size of the main journal */
3265 i64 iHdrOff; /* End of first segment of main-journal records */
3266 int rc = SQLITE_OK; /* Return code */
3267 Bitvec *pDone = 0; /* Bitvec to ensure pages played back only once */
3269 assert( pPager->eState!=PAGER_ERROR );
3270 assert( pPager->eState>=PAGER_WRITER_LOCKED );
3272 /* Allocate a bitvec to use to store the set of pages rolled back */
3273 if( pSavepoint ){
3274 pDone = sqlite3BitvecCreate(pSavepoint->nOrig);
3275 if( !pDone ){
3276 return SQLITE_NOMEM;
3280 /* Set the database size back to the value it was before the savepoint
3281 ** being reverted was opened.
3283 pPager->dbSize = pSavepoint ? pSavepoint->nOrig : pPager->dbOrigSize;
3284 pPager->changeCountDone = pPager->tempFile;
3286 if( !pSavepoint && pagerUseWal(pPager) ){
3287 return pagerRollbackWal(pPager);
3290 /* Use pPager->journalOff as the effective size of the main rollback
3291 ** journal. The actual file might be larger than this in
3292 ** PAGER_JOURNALMODE_TRUNCATE or PAGER_JOURNALMODE_PERSIST. But anything
3293 ** past pPager->journalOff is off-limits to us.
3295 szJ = pPager->journalOff;
3296 assert( pagerUseWal(pPager)==0 || szJ==0 );
3298 /* Begin by rolling back records from the main journal starting at
3299 ** PagerSavepoint.iOffset and continuing to the next journal header.
3300 ** There might be records in the main journal that have a page number
3301 ** greater than the current database size (pPager->dbSize) but those
3302 ** will be skipped automatically. Pages are added to pDone as they
3303 ** are played back.
3305 if( pSavepoint && !pagerUseWal(pPager) ){
3306 iHdrOff = pSavepoint->iHdrOffset ? pSavepoint->iHdrOffset : szJ;
3307 pPager->journalOff = pSavepoint->iOffset;
3308 while( rc==SQLITE_OK && pPager->journalOff<iHdrOff ){
3309 rc = pager_playback_one_page(pPager, &pPager->journalOff, pDone, 1, 1);
3311 assert( rc!=SQLITE_DONE );
3312 }else{
3313 pPager->journalOff = 0;
3316 /* Continue rolling back records out of the main journal starting at
3317 ** the first journal header seen and continuing until the effective end
3318 ** of the main journal file. Continue to skip out-of-range pages and
3319 ** continue adding pages rolled back to pDone.
3321 while( rc==SQLITE_OK && pPager->journalOff<szJ ){
3322 u32 ii; /* Loop counter */
3323 u32 nJRec = 0; /* Number of Journal Records */
3324 u32 dummy;
3325 rc = readJournalHdr(pPager, 0, szJ, &nJRec, &dummy);
3326 assert( rc!=SQLITE_DONE );
3329 ** The "pPager->journalHdr+JOURNAL_HDR_SZ(pPager)==pPager->journalOff"
3330 ** test is related to ticket #2565. See the discussion in the
3331 ** pager_playback() function for additional information.
3333 if( nJRec==0
3334 && pPager->journalHdr+JOURNAL_HDR_SZ(pPager)==pPager->journalOff
3336 nJRec = (u32)((szJ - pPager->journalOff)/JOURNAL_PG_SZ(pPager));
3338 for(ii=0; rc==SQLITE_OK && ii<nJRec && pPager->journalOff<szJ; ii++){
3339 rc = pager_playback_one_page(pPager, &pPager->journalOff, pDone, 1, 1);
3341 assert( rc!=SQLITE_DONE );
3343 assert( rc!=SQLITE_OK || pPager->journalOff>=szJ );
3345 /* Finally, rollback pages from the sub-journal. Page that were
3346 ** previously rolled back out of the main journal (and are hence in pDone)
3347 ** will be skipped. Out-of-range pages are also skipped.
3349 if( pSavepoint ){
3350 u32 ii; /* Loop counter */
3351 i64 offset = (i64)pSavepoint->iSubRec*(4+pPager->pageSize);
3353 if( pagerUseWal(pPager) ){
3354 rc = sqlite3WalSavepointUndo(pPager->pWal, pSavepoint->aWalData);
3356 for(ii=pSavepoint->iSubRec; rc==SQLITE_OK && ii<pPager->nSubRec; ii++){
3357 assert( offset==(i64)ii*(4+pPager->pageSize) );
3358 rc = pager_playback_one_page(pPager, &offset, pDone, 0, 1);
3360 assert( rc!=SQLITE_DONE );
3363 sqlite3BitvecDestroy(pDone);
3364 if( rc==SQLITE_OK ){
3365 pPager->journalOff = szJ;
3368 return rc;
3372 ** Change the maximum number of in-memory pages that are allowed.
3374 void sqlite3PagerSetCachesize(Pager *pPager, int mxPage){
3375 sqlite3PcacheSetCachesize(pPager->pPCache, mxPage);
3379 ** Invoke SQLITE_FCNTL_MMAP_SIZE based on the current value of szMmap.
3381 static void pagerFixMaplimit(Pager *pPager){
3382 #if SQLITE_MAX_MMAP_SIZE>0
3383 sqlite3_file *fd = pPager->fd;
3384 if( isOpen(fd) && fd->pMethods->iVersion>=3 ){
3385 sqlite3_int64 sz;
3386 sz = pPager->szMmap;
3387 pPager->bUseFetch = (sz>0);
3388 sqlite3OsFileControlHint(pPager->fd, SQLITE_FCNTL_MMAP_SIZE, &sz);
3390 #endif
3394 ** Change the maximum size of any memory mapping made of the database file.
3396 void sqlite3PagerSetMmapLimit(Pager *pPager, sqlite3_int64 szMmap){
3397 pPager->szMmap = szMmap;
3398 pagerFixMaplimit(pPager);
3402 ** Free as much memory as possible from the pager.
3404 void sqlite3PagerShrink(Pager *pPager){
3405 sqlite3PcacheShrink(pPager->pPCache);
3409 ** Adjust settings of the pager to those specified in the pgFlags parameter.
3411 ** The "level" in pgFlags & PAGER_SYNCHRONOUS_MASK sets the robustness
3412 ** of the database to damage due to OS crashes or power failures by
3413 ** changing the number of syncs()s when writing the journals.
3414 ** There are three levels:
3416 ** OFF sqlite3OsSync() is never called. This is the default
3417 ** for temporary and transient files.
3419 ** NORMAL The journal is synced once before writes begin on the
3420 ** database. This is normally adequate protection, but
3421 ** it is theoretically possible, though very unlikely,
3422 ** that an inopertune power failure could leave the journal
3423 ** in a state which would cause damage to the database
3424 ** when it is rolled back.
3426 ** FULL The journal is synced twice before writes begin on the
3427 ** database (with some additional information - the nRec field
3428 ** of the journal header - being written in between the two
3429 ** syncs). If we assume that writing a
3430 ** single disk sector is atomic, then this mode provides
3431 ** assurance that the journal will not be corrupted to the
3432 ** point of causing damage to the database during rollback.
3434 ** The above is for a rollback-journal mode. For WAL mode, OFF continues
3435 ** to mean that no syncs ever occur. NORMAL means that the WAL is synced
3436 ** prior to the start of checkpoint and that the database file is synced
3437 ** at the conclusion of the checkpoint if the entire content of the WAL
3438 ** was written back into the database. But no sync operations occur for
3439 ** an ordinary commit in NORMAL mode with WAL. FULL means that the WAL
3440 ** file is synced following each commit operation, in addition to the
3441 ** syncs associated with NORMAL.
3443 ** Do not confuse synchronous=FULL with SQLITE_SYNC_FULL. The
3444 ** SQLITE_SYNC_FULL macro means to use the MacOSX-style full-fsync
3445 ** using fcntl(F_FULLFSYNC). SQLITE_SYNC_NORMAL means to do an
3446 ** ordinary fsync() call. There is no difference between SQLITE_SYNC_FULL
3447 ** and SQLITE_SYNC_NORMAL on platforms other than MacOSX. But the
3448 ** synchronous=FULL versus synchronous=NORMAL setting determines when
3449 ** the xSync primitive is called and is relevant to all platforms.
3451 ** Numeric values associated with these states are OFF==1, NORMAL=2,
3452 ** and FULL=3.
3454 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
3455 void sqlite3PagerSetFlags(
3456 Pager *pPager, /* The pager to set safety level for */
3457 unsigned pgFlags /* Various flags */
3459 unsigned level = pgFlags & PAGER_SYNCHRONOUS_MASK;
3460 assert( level>=1 && level<=3 );
3461 pPager->noSync = (level==1 || pPager->tempFile) ?1:0;
3462 pPager->fullSync = (level==3 && !pPager->tempFile) ?1:0;
3463 if( pPager->noSync ){
3464 pPager->syncFlags = 0;
3465 pPager->ckptSyncFlags = 0;
3466 }else if( pgFlags & PAGER_FULLFSYNC ){
3467 pPager->syncFlags = SQLITE_SYNC_FULL;
3468 pPager->ckptSyncFlags = SQLITE_SYNC_FULL;
3469 }else if( pgFlags & PAGER_CKPT_FULLFSYNC ){
3470 pPager->syncFlags = SQLITE_SYNC_NORMAL;
3471 pPager->ckptSyncFlags = SQLITE_SYNC_FULL;
3472 }else{
3473 pPager->syncFlags = SQLITE_SYNC_NORMAL;
3474 pPager->ckptSyncFlags = SQLITE_SYNC_NORMAL;
3476 pPager->walSyncFlags = pPager->syncFlags;
3477 if( pPager->fullSync ){
3478 pPager->walSyncFlags |= WAL_SYNC_TRANSACTIONS;
3480 if( pgFlags & PAGER_CACHESPILL ){
3481 pPager->doNotSpill &= ~SPILLFLAG_OFF;
3482 }else{
3483 pPager->doNotSpill |= SPILLFLAG_OFF;
3486 #endif
3489 ** The following global variable is incremented whenever the library
3490 ** attempts to open a temporary file. This information is used for
3491 ** testing and analysis only.
3493 #ifdef SQLITE_TEST
3494 int sqlite3_opentemp_count = 0;
3495 #endif
3498 ** Open a temporary file.
3500 ** Write the file descriptor into *pFile. Return SQLITE_OK on success
3501 ** or some other error code if we fail. The OS will automatically
3502 ** delete the temporary file when it is closed.
3504 ** The flags passed to the VFS layer xOpen() call are those specified
3505 ** by parameter vfsFlags ORed with the following:
3507 ** SQLITE_OPEN_READWRITE
3508 ** SQLITE_OPEN_CREATE
3509 ** SQLITE_OPEN_EXCLUSIVE
3510 ** SQLITE_OPEN_DELETEONCLOSE
3512 static int pagerOpentemp(
3513 Pager *pPager, /* The pager object */
3514 sqlite3_file *pFile, /* Write the file descriptor here */
3515 int vfsFlags /* Flags passed through to the VFS */
3517 int rc; /* Return code */
3519 #ifdef SQLITE_TEST
3520 sqlite3_opentemp_count++; /* Used for testing and analysis only */
3521 #endif
3523 vfsFlags |= SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE |
3524 SQLITE_OPEN_EXCLUSIVE | SQLITE_OPEN_DELETEONCLOSE;
3525 rc = sqlite3OsOpen(pPager->pVfs, 0, pFile, vfsFlags, 0);
3526 assert( rc!=SQLITE_OK || isOpen(pFile) );
3527 return rc;
3531 ** Set the busy handler function.
3533 ** The pager invokes the busy-handler if sqlite3OsLock() returns
3534 ** SQLITE_BUSY when trying to upgrade from no-lock to a SHARED lock,
3535 ** or when trying to upgrade from a RESERVED lock to an EXCLUSIVE
3536 ** lock. It does *not* invoke the busy handler when upgrading from
3537 ** SHARED to RESERVED, or when upgrading from SHARED to EXCLUSIVE
3538 ** (which occurs during hot-journal rollback). Summary:
3540 ** Transition | Invokes xBusyHandler
3541 ** --------------------------------------------------------
3542 ** NO_LOCK -> SHARED_LOCK | Yes
3543 ** SHARED_LOCK -> RESERVED_LOCK | No
3544 ** SHARED_LOCK -> EXCLUSIVE_LOCK | No
3545 ** RESERVED_LOCK -> EXCLUSIVE_LOCK | Yes
3547 ** If the busy-handler callback returns non-zero, the lock is
3548 ** retried. If it returns zero, then the SQLITE_BUSY error is
3549 ** returned to the caller of the pager API function.
3551 void sqlite3PagerSetBusyhandler(
3552 Pager *pPager, /* Pager object */
3553 int (*xBusyHandler)(void *), /* Pointer to busy-handler function */
3554 void *pBusyHandlerArg /* Argument to pass to xBusyHandler */
3556 pPager->xBusyHandler = xBusyHandler;
3557 pPager->pBusyHandlerArg = pBusyHandlerArg;
3559 if( isOpen(pPager->fd) ){
3560 void **ap = (void **)&pPager->xBusyHandler;
3561 assert( ((int(*)(void *))(ap[0]))==xBusyHandler );
3562 assert( ap[1]==pBusyHandlerArg );
3563 sqlite3OsFileControlHint(pPager->fd, SQLITE_FCNTL_BUSYHANDLER, (void *)ap);
3568 ** Change the page size used by the Pager object. The new page size
3569 ** is passed in *pPageSize.
3571 ** If the pager is in the error state when this function is called, it
3572 ** is a no-op. The value returned is the error state error code (i.e.
3573 ** one of SQLITE_IOERR, an SQLITE_IOERR_xxx sub-code or SQLITE_FULL).
3575 ** Otherwise, if all of the following are true:
3577 ** * the new page size (value of *pPageSize) is valid (a power
3578 ** of two between 512 and SQLITE_MAX_PAGE_SIZE, inclusive), and
3580 ** * there are no outstanding page references, and
3582 ** * the database is either not an in-memory database or it is
3583 ** an in-memory database that currently consists of zero pages.
3585 ** then the pager object page size is set to *pPageSize.
3587 ** If the page size is changed, then this function uses sqlite3PagerMalloc()
3588 ** to obtain a new Pager.pTmpSpace buffer. If this allocation attempt
3589 ** fails, SQLITE_NOMEM is returned and the page size remains unchanged.
3590 ** In all other cases, SQLITE_OK is returned.
3592 ** If the page size is not changed, either because one of the enumerated
3593 ** conditions above is not true, the pager was in error state when this
3594 ** function was called, or because the memory allocation attempt failed,
3595 ** then *pPageSize is set to the old, retained page size before returning.
3597 int sqlite3PagerSetPagesize(Pager *pPager, u32 *pPageSize, int nReserve){
3598 int rc = SQLITE_OK;
3600 /* It is not possible to do a full assert_pager_state() here, as this
3601 ** function may be called from within PagerOpen(), before the state
3602 ** of the Pager object is internally consistent.
3604 ** At one point this function returned an error if the pager was in
3605 ** PAGER_ERROR state. But since PAGER_ERROR state guarantees that
3606 ** there is at least one outstanding page reference, this function
3607 ** is a no-op for that case anyhow.
3610 u32 pageSize = *pPageSize;
3611 assert( pageSize==0 || (pageSize>=512 && pageSize<=SQLITE_MAX_PAGE_SIZE) );
3612 if( (pPager->memDb==0 || pPager->dbSize==0)
3613 && sqlite3PcacheRefCount(pPager->pPCache)==0
3614 && pageSize && pageSize!=(u32)pPager->pageSize
3616 char *pNew = NULL; /* New temp space */
3617 i64 nByte = 0;
3619 if( pPager->eState>PAGER_OPEN && isOpen(pPager->fd) ){
3620 rc = sqlite3OsFileSize(pPager->fd, &nByte);
3622 if( rc==SQLITE_OK ){
3623 pNew = (char *)sqlite3PageMalloc(pageSize);
3624 if( !pNew ) rc = SQLITE_NOMEM;
3627 if( rc==SQLITE_OK ){
3628 pager_reset(pPager);
3629 rc = sqlite3PcacheSetPageSize(pPager->pPCache, pageSize);
3631 if( rc==SQLITE_OK ){
3632 sqlite3PageFree(pPager->pTmpSpace);
3633 pPager->pTmpSpace = pNew;
3634 pPager->dbSize = (Pgno)((nByte+pageSize-1)/pageSize);
3635 pPager->pageSize = pageSize;
3636 }else{
3637 sqlite3PageFree(pNew);
3641 *pPageSize = pPager->pageSize;
3642 if( rc==SQLITE_OK ){
3643 if( nReserve<0 ) nReserve = pPager->nReserve;
3644 assert( nReserve>=0 && nReserve<1000 );
3645 pPager->nReserve = (i16)nReserve;
3646 pagerReportSize(pPager);
3647 pagerFixMaplimit(pPager);
3649 return rc;
3653 ** Return a pointer to the "temporary page" buffer held internally
3654 ** by the pager. This is a buffer that is big enough to hold the
3655 ** entire content of a database page. This buffer is used internally
3656 ** during rollback and will be overwritten whenever a rollback
3657 ** occurs. But other modules are free to use it too, as long as
3658 ** no rollbacks are happening.
3660 void *sqlite3PagerTempSpace(Pager *pPager){
3661 return pPager->pTmpSpace;
3665 ** Attempt to set the maximum database page count if mxPage is positive.
3666 ** Make no changes if mxPage is zero or negative. And never reduce the
3667 ** maximum page count below the current size of the database.
3669 ** Regardless of mxPage, return the current maximum page count.
3671 int sqlite3PagerMaxPageCount(Pager *pPager, int mxPage){
3672 if( mxPage>0 ){
3673 pPager->mxPgno = mxPage;
3675 assert( pPager->eState!=PAGER_OPEN ); /* Called only by OP_MaxPgcnt */
3676 assert( pPager->mxPgno>=pPager->dbSize ); /* OP_MaxPgcnt enforces this */
3677 return pPager->mxPgno;
3681 ** The following set of routines are used to disable the simulated
3682 ** I/O error mechanism. These routines are used to avoid simulated
3683 ** errors in places where we do not care about errors.
3685 ** Unless -DSQLITE_TEST=1 is used, these routines are all no-ops
3686 ** and generate no code.
3688 #ifdef SQLITE_TEST
3689 extern int sqlite3_io_error_pending;
3690 extern int sqlite3_io_error_hit;
3691 static int saved_cnt;
3692 void disable_simulated_io_errors(void){
3693 saved_cnt = sqlite3_io_error_pending;
3694 sqlite3_io_error_pending = -1;
3696 void enable_simulated_io_errors(void){
3697 sqlite3_io_error_pending = saved_cnt;
3699 #else
3700 # define disable_simulated_io_errors()
3701 # define enable_simulated_io_errors()
3702 #endif
3705 ** Read the first N bytes from the beginning of the file into memory
3706 ** that pDest points to.
3708 ** If the pager was opened on a transient file (zFilename==""), or
3709 ** opened on a file less than N bytes in size, the output buffer is
3710 ** zeroed and SQLITE_OK returned. The rationale for this is that this
3711 ** function is used to read database headers, and a new transient or
3712 ** zero sized database has a header than consists entirely of zeroes.
3714 ** If any IO error apart from SQLITE_IOERR_SHORT_READ is encountered,
3715 ** the error code is returned to the caller and the contents of the
3716 ** output buffer undefined.
3718 int sqlite3PagerReadFileheader(Pager *pPager, int N, unsigned char *pDest){
3719 int rc = SQLITE_OK;
3720 memset(pDest, 0, N);
3721 assert( isOpen(pPager->fd) || pPager->tempFile );
3723 /* This routine is only called by btree immediately after creating
3724 ** the Pager object. There has not been an opportunity to transition
3725 ** to WAL mode yet.
3727 assert( !pagerUseWal(pPager) );
3729 if( isOpen(pPager->fd) ){
3730 IOTRACE(("DBHDR %p 0 %d\n", pPager, N))
3731 rc = sqlite3OsRead(pPager->fd, pDest, N, 0);
3732 if( rc==SQLITE_IOERR_SHORT_READ ){
3733 rc = SQLITE_OK;
3736 return rc;
3740 ** This function may only be called when a read-transaction is open on
3741 ** the pager. It returns the total number of pages in the database.
3743 ** However, if the file is between 1 and <page-size> bytes in size, then
3744 ** this is considered a 1 page file.
3746 void sqlite3PagerPagecount(Pager *pPager, int *pnPage){
3747 assert( pPager->eState>=PAGER_READER );
3748 assert( pPager->eState!=PAGER_WRITER_FINISHED );
3749 *pnPage = (int)pPager->dbSize;
3754 ** Try to obtain a lock of type locktype on the database file. If
3755 ** a similar or greater lock is already held, this function is a no-op
3756 ** (returning SQLITE_OK immediately).
3758 ** Otherwise, attempt to obtain the lock using sqlite3OsLock(). Invoke
3759 ** the busy callback if the lock is currently not available. Repeat
3760 ** until the busy callback returns false or until the attempt to
3761 ** obtain the lock succeeds.
3763 ** Return SQLITE_OK on success and an error code if we cannot obtain
3764 ** the lock. If the lock is obtained successfully, set the Pager.state
3765 ** variable to locktype before returning.
3767 static int pager_wait_on_lock(Pager *pPager, int locktype){
3768 int rc; /* Return code */
3770 /* Check that this is either a no-op (because the requested lock is
3771 ** already held), or one of the transitions that the busy-handler
3772 ** may be invoked during, according to the comment above
3773 ** sqlite3PagerSetBusyhandler().
3775 assert( (pPager->eLock>=locktype)
3776 || (pPager->eLock==NO_LOCK && locktype==SHARED_LOCK)
3777 || (pPager->eLock==RESERVED_LOCK && locktype==EXCLUSIVE_LOCK)
3780 do {
3781 rc = pagerLockDb(pPager, locktype);
3782 }while( rc==SQLITE_BUSY && pPager->xBusyHandler(pPager->pBusyHandlerArg) );
3783 return rc;
3787 ** Function assertTruncateConstraint(pPager) checks that one of the
3788 ** following is true for all dirty pages currently in the page-cache:
3790 ** a) The page number is less than or equal to the size of the
3791 ** current database image, in pages, OR
3793 ** b) if the page content were written at this time, it would not
3794 ** be necessary to write the current content out to the sub-journal
3795 ** (as determined by function subjRequiresPage()).
3797 ** If the condition asserted by this function were not true, and the
3798 ** dirty page were to be discarded from the cache via the pagerStress()
3799 ** routine, pagerStress() would not write the current page content to
3800 ** the database file. If a savepoint transaction were rolled back after
3801 ** this happened, the correct behavior would be to restore the current
3802 ** content of the page. However, since this content is not present in either
3803 ** the database file or the portion of the rollback journal and
3804 ** sub-journal rolled back the content could not be restored and the
3805 ** database image would become corrupt. It is therefore fortunate that
3806 ** this circumstance cannot arise.
3808 #if defined(SQLITE_DEBUG)
3809 static void assertTruncateConstraintCb(PgHdr *pPg){
3810 assert( pPg->flags&PGHDR_DIRTY );
3811 assert( !subjRequiresPage(pPg) || pPg->pgno<=pPg->pPager->dbSize );
3813 static void assertTruncateConstraint(Pager *pPager){
3814 sqlite3PcacheIterateDirty(pPager->pPCache, assertTruncateConstraintCb);
3816 #else
3817 # define assertTruncateConstraint(pPager)
3818 #endif
3821 ** Truncate the in-memory database file image to nPage pages. This
3822 ** function does not actually modify the database file on disk. It
3823 ** just sets the internal state of the pager object so that the
3824 ** truncation will be done when the current transaction is committed.
3826 ** This function is only called right before committing a transaction.
3827 ** Once this function has been called, the transaction must either be
3828 ** rolled back or committed. It is not safe to call this function and
3829 ** then continue writing to the database.
3831 void sqlite3PagerTruncateImage(Pager *pPager, Pgno nPage){
3832 assert( pPager->dbSize>=nPage );
3833 assert( pPager->eState>=PAGER_WRITER_CACHEMOD );
3834 pPager->dbSize = nPage;
3836 /* At one point the code here called assertTruncateConstraint() to
3837 ** ensure that all pages being truncated away by this operation are,
3838 ** if one or more savepoints are open, present in the savepoint
3839 ** journal so that they can be restored if the savepoint is rolled
3840 ** back. This is no longer necessary as this function is now only
3841 ** called right before committing a transaction. So although the
3842 ** Pager object may still have open savepoints (Pager.nSavepoint!=0),
3843 ** they cannot be rolled back. So the assertTruncateConstraint() call
3844 ** is no longer correct. */
3849 ** This function is called before attempting a hot-journal rollback. It
3850 ** syncs the journal file to disk, then sets pPager->journalHdr to the
3851 ** size of the journal file so that the pager_playback() routine knows
3852 ** that the entire journal file has been synced.
3854 ** Syncing a hot-journal to disk before attempting to roll it back ensures
3855 ** that if a power-failure occurs during the rollback, the process that
3856 ** attempts rollback following system recovery sees the same journal
3857 ** content as this process.
3859 ** If everything goes as planned, SQLITE_OK is returned. Otherwise,
3860 ** an SQLite error code.
3862 static int pagerSyncHotJournal(Pager *pPager){
3863 int rc = SQLITE_OK;
3864 if( !pPager->noSync ){
3865 rc = sqlite3OsSync(pPager->jfd, SQLITE_SYNC_NORMAL);
3867 if( rc==SQLITE_OK ){
3868 rc = sqlite3OsFileSize(pPager->jfd, &pPager->journalHdr);
3870 return rc;
3874 ** Obtain a reference to a memory mapped page object for page number pgno.
3875 ** The new object will use the pointer pData, obtained from xFetch().
3876 ** If successful, set *ppPage to point to the new page reference
3877 ** and return SQLITE_OK. Otherwise, return an SQLite error code and set
3878 ** *ppPage to zero.
3880 ** Page references obtained by calling this function should be released
3881 ** by calling pagerReleaseMapPage().
3883 static int pagerAcquireMapPage(
3884 Pager *pPager, /* Pager object */
3885 Pgno pgno, /* Page number */
3886 void *pData, /* xFetch()'d data for this page */
3887 PgHdr **ppPage /* OUT: Acquired page object */
3889 PgHdr *p; /* Memory mapped page to return */
3891 if( pPager->pMmapFreelist ){
3892 *ppPage = p = pPager->pMmapFreelist;
3893 pPager->pMmapFreelist = p->pDirty;
3894 p->pDirty = 0;
3895 memset(p->pExtra, 0, pPager->nExtra);
3896 }else{
3897 *ppPage = p = (PgHdr *)sqlite3MallocZero(sizeof(PgHdr) + pPager->nExtra);
3898 if( p==0 ){
3899 sqlite3OsUnfetch(pPager->fd, (i64)(pgno-1) * pPager->pageSize, pData);
3900 return SQLITE_NOMEM;
3902 p->pExtra = (void *)&p[1];
3903 p->flags = PGHDR_MMAP;
3904 p->nRef = 1;
3905 p->pPager = pPager;
3908 assert( p->pExtra==(void *)&p[1] );
3909 assert( p->pPage==0 );
3910 assert( p->flags==PGHDR_MMAP );
3911 assert( p->pPager==pPager );
3912 assert( p->nRef==1 );
3914 p->pgno = pgno;
3915 p->pData = pData;
3916 pPager->nMmapOut++;
3918 return SQLITE_OK;
3922 ** Release a reference to page pPg. pPg must have been returned by an
3923 ** earlier call to pagerAcquireMapPage().
3925 static void pagerReleaseMapPage(PgHdr *pPg){
3926 Pager *pPager = pPg->pPager;
3927 pPager->nMmapOut--;
3928 pPg->pDirty = pPager->pMmapFreelist;
3929 pPager->pMmapFreelist = pPg;
3931 assert( pPager->fd->pMethods->iVersion>=3 );
3932 sqlite3OsUnfetch(pPager->fd, (i64)(pPg->pgno-1)*pPager->pageSize, pPg->pData);
3936 ** Free all PgHdr objects stored in the Pager.pMmapFreelist list.
3938 static void pagerFreeMapHdrs(Pager *pPager){
3939 PgHdr *p;
3940 PgHdr *pNext;
3941 for(p=pPager->pMmapFreelist; p; p=pNext){
3942 pNext = p->pDirty;
3943 sqlite3_free(p);
3949 ** Shutdown the page cache. Free all memory and close all files.
3951 ** If a transaction was in progress when this routine is called, that
3952 ** transaction is rolled back. All outstanding pages are invalidated
3953 ** and their memory is freed. Any attempt to use a page associated
3954 ** with this page cache after this function returns will likely
3955 ** result in a coredump.
3957 ** This function always succeeds. If a transaction is active an attempt
3958 ** is made to roll it back. If an error occurs during the rollback
3959 ** a hot journal may be left in the filesystem but no error is returned
3960 ** to the caller.
3962 int sqlite3PagerClose(Pager *pPager){
3963 u8 *pTmp = (u8 *)pPager->pTmpSpace;
3965 assert( assert_pager_state(pPager) );
3966 disable_simulated_io_errors();
3967 sqlite3BeginBenignMalloc();
3968 pagerFreeMapHdrs(pPager);
3969 /* pPager->errCode = 0; */
3970 pPager->exclusiveMode = 0;
3971 #ifndef SQLITE_OMIT_WAL
3972 sqlite3WalClose(pPager->pWal, pPager->ckptSyncFlags, pPager->pageSize, pTmp);
3973 pPager->pWal = 0;
3974 #endif
3975 pager_reset(pPager);
3976 if( MEMDB ){
3977 pager_unlock(pPager);
3978 }else{
3979 /* If it is open, sync the journal file before calling UnlockAndRollback.
3980 ** If this is not done, then an unsynced portion of the open journal
3981 ** file may be played back into the database. If a power failure occurs
3982 ** while this is happening, the database could become corrupt.
3984 ** If an error occurs while trying to sync the journal, shift the pager
3985 ** into the ERROR state. This causes UnlockAndRollback to unlock the
3986 ** database and close the journal file without attempting to roll it
3987 ** back or finalize it. The next database user will have to do hot-journal
3988 ** rollback before accessing the database file.
3990 if( isOpen(pPager->jfd) ){
3991 pager_error(pPager, pagerSyncHotJournal(pPager));
3993 pagerUnlockAndRollback(pPager);
3995 sqlite3EndBenignMalloc();
3996 enable_simulated_io_errors();
3997 PAGERTRACE(("CLOSE %d\n", PAGERID(pPager)));
3998 IOTRACE(("CLOSE %p\n", pPager))
3999 sqlite3OsClose(pPager->jfd);
4000 sqlite3OsClose(pPager->fd);
4001 sqlite3PageFree(pTmp);
4002 sqlite3PcacheClose(pPager->pPCache);
4004 #ifdef SQLITE_HAS_CODEC
4005 if( pPager->xCodecFree ) pPager->xCodecFree(pPager->pCodec);
4006 #endif
4008 assert( !pPager->aSavepoint && !pPager->pInJournal );
4009 assert( !isOpen(pPager->jfd) && !isOpen(pPager->sjfd) );
4011 sqlite3_free(pPager);
4012 return SQLITE_OK;
4015 #if !defined(NDEBUG) || defined(SQLITE_TEST)
4017 ** Return the page number for page pPg.
4019 Pgno sqlite3PagerPagenumber(DbPage *pPg){
4020 return pPg->pgno;
4022 #endif
4025 ** Increment the reference count for page pPg.
4027 void sqlite3PagerRef(DbPage *pPg){
4028 sqlite3PcacheRef(pPg);
4032 ** Sync the journal. In other words, make sure all the pages that have
4033 ** been written to the journal have actually reached the surface of the
4034 ** disk and can be restored in the event of a hot-journal rollback.
4036 ** If the Pager.noSync flag is set, then this function is a no-op.
4037 ** Otherwise, the actions required depend on the journal-mode and the
4038 ** device characteristics of the file-system, as follows:
4040 ** * If the journal file is an in-memory journal file, no action need
4041 ** be taken.
4043 ** * Otherwise, if the device does not support the SAFE_APPEND property,
4044 ** then the nRec field of the most recently written journal header
4045 ** is updated to contain the number of journal records that have
4046 ** been written following it. If the pager is operating in full-sync
4047 ** mode, then the journal file is synced before this field is updated.
4049 ** * If the device does not support the SEQUENTIAL property, then
4050 ** journal file is synced.
4052 ** Or, in pseudo-code:
4054 ** if( NOT <in-memory journal> ){
4055 ** if( NOT SAFE_APPEND ){
4056 ** if( <full-sync mode> ) xSync(<journal file>);
4057 ** <update nRec field>
4058 ** }
4059 ** if( NOT SEQUENTIAL ) xSync(<journal file>);
4060 ** }
4062 ** If successful, this routine clears the PGHDR_NEED_SYNC flag of every
4063 ** page currently held in memory before returning SQLITE_OK. If an IO
4064 ** error is encountered, then the IO error code is returned to the caller.
4066 static int syncJournal(Pager *pPager, int newHdr){
4067 int rc; /* Return code */
4069 assert( pPager->eState==PAGER_WRITER_CACHEMOD
4070 || pPager->eState==PAGER_WRITER_DBMOD
4072 assert( assert_pager_state(pPager) );
4073 assert( !pagerUseWal(pPager) );
4075 rc = sqlite3PagerExclusiveLock(pPager);
4076 if( rc!=SQLITE_OK ) return rc;
4078 if( !pPager->noSync ){
4079 assert( !pPager->tempFile );
4080 if( isOpen(pPager->jfd) && pPager->journalMode!=PAGER_JOURNALMODE_MEMORY ){
4081 const int iDc = sqlite3OsDeviceCharacteristics(pPager->fd);
4082 assert( isOpen(pPager->jfd) );
4084 if( 0==(iDc&SQLITE_IOCAP_SAFE_APPEND) ){
4085 /* This block deals with an obscure problem. If the last connection
4086 ** that wrote to this database was operating in persistent-journal
4087 ** mode, then the journal file may at this point actually be larger
4088 ** than Pager.journalOff bytes. If the next thing in the journal
4089 ** file happens to be a journal-header (written as part of the
4090 ** previous connection's transaction), and a crash or power-failure
4091 ** occurs after nRec is updated but before this connection writes
4092 ** anything else to the journal file (or commits/rolls back its
4093 ** transaction), then SQLite may become confused when doing the
4094 ** hot-journal rollback following recovery. It may roll back all
4095 ** of this connections data, then proceed to rolling back the old,
4096 ** out-of-date data that follows it. Database corruption.
4098 ** To work around this, if the journal file does appear to contain
4099 ** a valid header following Pager.journalOff, then write a 0x00
4100 ** byte to the start of it to prevent it from being recognized.
4102 ** Variable iNextHdrOffset is set to the offset at which this
4103 ** problematic header will occur, if it exists. aMagic is used
4104 ** as a temporary buffer to inspect the first couple of bytes of
4105 ** the potential journal header.
4107 i64 iNextHdrOffset;
4108 u8 aMagic[8];
4109 u8 zHeader[sizeof(aJournalMagic)+4];
4111 memcpy(zHeader, aJournalMagic, sizeof(aJournalMagic));
4112 put32bits(&zHeader[sizeof(aJournalMagic)], pPager->nRec);
4114 iNextHdrOffset = journalHdrOffset(pPager);
4115 rc = sqlite3OsRead(pPager->jfd, aMagic, 8, iNextHdrOffset);
4116 if( rc==SQLITE_OK && 0==memcmp(aMagic, aJournalMagic, 8) ){
4117 static const u8 zerobyte = 0;
4118 rc = sqlite3OsWrite(pPager->jfd, &zerobyte, 1, iNextHdrOffset);
4120 if( rc!=SQLITE_OK && rc!=SQLITE_IOERR_SHORT_READ ){
4121 return rc;
4124 /* Write the nRec value into the journal file header. If in
4125 ** full-synchronous mode, sync the journal first. This ensures that
4126 ** all data has really hit the disk before nRec is updated to mark
4127 ** it as a candidate for rollback.
4129 ** This is not required if the persistent media supports the
4130 ** SAFE_APPEND property. Because in this case it is not possible
4131 ** for garbage data to be appended to the file, the nRec field
4132 ** is populated with 0xFFFFFFFF when the journal header is written
4133 ** and never needs to be updated.
4135 if( pPager->fullSync && 0==(iDc&SQLITE_IOCAP_SEQUENTIAL) ){
4136 PAGERTRACE(("SYNC journal of %d\n", PAGERID(pPager)));
4137 IOTRACE(("JSYNC %p\n", pPager))
4138 rc = sqlite3OsSync(pPager->jfd, pPager->syncFlags);
4139 if( rc!=SQLITE_OK ) return rc;
4141 IOTRACE(("JHDR %p %lld\n", pPager, pPager->journalHdr));
4142 rc = sqlite3OsWrite(
4143 pPager->jfd, zHeader, sizeof(zHeader), pPager->journalHdr
4145 if( rc!=SQLITE_OK ) return rc;
4147 if( 0==(iDc&SQLITE_IOCAP_SEQUENTIAL) ){
4148 PAGERTRACE(("SYNC journal of %d\n", PAGERID(pPager)));
4149 IOTRACE(("JSYNC %p\n", pPager))
4150 rc = sqlite3OsSync(pPager->jfd, pPager->syncFlags|
4151 (pPager->syncFlags==SQLITE_SYNC_FULL?SQLITE_SYNC_DATAONLY:0)
4153 if( rc!=SQLITE_OK ) return rc;
4156 pPager->journalHdr = pPager->journalOff;
4157 if( newHdr && 0==(iDc&SQLITE_IOCAP_SAFE_APPEND) ){
4158 pPager->nRec = 0;
4159 rc = writeJournalHdr(pPager);
4160 if( rc!=SQLITE_OK ) return rc;
4162 }else{
4163 pPager->journalHdr = pPager->journalOff;
4167 /* Unless the pager is in noSync mode, the journal file was just
4168 ** successfully synced. Either way, clear the PGHDR_NEED_SYNC flag on
4169 ** all pages.
4171 sqlite3PcacheClearSyncFlags(pPager->pPCache);
4172 pPager->eState = PAGER_WRITER_DBMOD;
4173 assert( assert_pager_state(pPager) );
4174 return SQLITE_OK;
4178 ** The argument is the first in a linked list of dirty pages connected
4179 ** by the PgHdr.pDirty pointer. This function writes each one of the
4180 ** in-memory pages in the list to the database file. The argument may
4181 ** be NULL, representing an empty list. In this case this function is
4182 ** a no-op.
4184 ** The pager must hold at least a RESERVED lock when this function
4185 ** is called. Before writing anything to the database file, this lock
4186 ** is upgraded to an EXCLUSIVE lock. If the lock cannot be obtained,
4187 ** SQLITE_BUSY is returned and no data is written to the database file.
4189 ** If the pager is a temp-file pager and the actual file-system file
4190 ** is not yet open, it is created and opened before any data is
4191 ** written out.
4193 ** Once the lock has been upgraded and, if necessary, the file opened,
4194 ** the pages are written out to the database file in list order. Writing
4195 ** a page is skipped if it meets either of the following criteria:
4197 ** * The page number is greater than Pager.dbSize, or
4198 ** * The PGHDR_DONT_WRITE flag is set on the page.
4200 ** If writing out a page causes the database file to grow, Pager.dbFileSize
4201 ** is updated accordingly. If page 1 is written out, then the value cached
4202 ** in Pager.dbFileVers[] is updated to match the new value stored in
4203 ** the database file.
4205 ** If everything is successful, SQLITE_OK is returned. If an IO error
4206 ** occurs, an IO error code is returned. Or, if the EXCLUSIVE lock cannot
4207 ** be obtained, SQLITE_BUSY is returned.
4209 static int pager_write_pagelist(Pager *pPager, PgHdr *pList){
4210 int rc = SQLITE_OK; /* Return code */
4212 /* This function is only called for rollback pagers in WRITER_DBMOD state. */
4213 assert( !pagerUseWal(pPager) );
4214 assert( pPager->eState==PAGER_WRITER_DBMOD );
4215 assert( pPager->eLock==EXCLUSIVE_LOCK );
4217 /* If the file is a temp-file has not yet been opened, open it now. It
4218 ** is not possible for rc to be other than SQLITE_OK if this branch
4219 ** is taken, as pager_wait_on_lock() is a no-op for temp-files.
4221 if( !isOpen(pPager->fd) ){
4222 assert( pPager->tempFile && rc==SQLITE_OK );
4223 rc = pagerOpentemp(pPager, pPager->fd, pPager->vfsFlags);
4226 /* Before the first write, give the VFS a hint of what the final
4227 ** file size will be.
4229 assert( rc!=SQLITE_OK || isOpen(pPager->fd) );
4230 if( rc==SQLITE_OK
4231 && pPager->dbHintSize<pPager->dbSize
4232 && (pList->pDirty || pList->pgno>pPager->dbHintSize)
4234 sqlite3_int64 szFile = pPager->pageSize * (sqlite3_int64)pPager->dbSize;
4235 sqlite3OsFileControlHint(pPager->fd, SQLITE_FCNTL_SIZE_HINT, &szFile);
4236 pPager->dbHintSize = pPager->dbSize;
4239 while( rc==SQLITE_OK && pList ){
4240 Pgno pgno = pList->pgno;
4242 /* If there are dirty pages in the page cache with page numbers greater
4243 ** than Pager.dbSize, this means sqlite3PagerTruncateImage() was called to
4244 ** make the file smaller (presumably by auto-vacuum code). Do not write
4245 ** any such pages to the file.
4247 ** Also, do not write out any page that has the PGHDR_DONT_WRITE flag
4248 ** set (set by sqlite3PagerDontWrite()).
4250 if( pgno<=pPager->dbSize && 0==(pList->flags&PGHDR_DONT_WRITE) ){
4251 i64 offset = (pgno-1)*(i64)pPager->pageSize; /* Offset to write */
4252 char *pData; /* Data to write */
4254 assert( (pList->flags&PGHDR_NEED_SYNC)==0 );
4255 if( pList->pgno==1 ) pager_write_changecounter(pList);
4257 /* Encode the database */
4258 CODEC2(pPager, pList->pData, pgno, 6, return SQLITE_NOMEM, pData);
4260 /* Write out the page data. */
4261 rc = sqlite3OsWrite(pPager->fd, pData, pPager->pageSize, offset);
4263 /* If page 1 was just written, update Pager.dbFileVers to match
4264 ** the value now stored in the database file. If writing this
4265 ** page caused the database file to grow, update dbFileSize.
4267 if( pgno==1 ){
4268 memcpy(&pPager->dbFileVers, &pData[24], sizeof(pPager->dbFileVers));
4270 if( pgno>pPager->dbFileSize ){
4271 pPager->dbFileSize = pgno;
4273 pPager->aStat[PAGER_STAT_WRITE]++;
4275 /* Update any backup objects copying the contents of this pager. */
4276 sqlite3BackupUpdate(pPager->pBackup, pgno, (u8*)pList->pData);
4278 PAGERTRACE(("STORE %d page %d hash(%08x)\n",
4279 PAGERID(pPager), pgno, pager_pagehash(pList)));
4280 IOTRACE(("PGOUT %p %d\n", pPager, pgno));
4281 PAGER_INCR(sqlite3_pager_writedb_count);
4282 }else{
4283 PAGERTRACE(("NOSTORE %d page %d\n", PAGERID(pPager), pgno));
4285 pager_set_pagehash(pList);
4286 pList = pList->pDirty;
4289 return rc;
4293 ** Ensure that the sub-journal file is open. If it is already open, this
4294 ** function is a no-op.
4296 ** SQLITE_OK is returned if everything goes according to plan. An
4297 ** SQLITE_IOERR_XXX error code is returned if a call to sqlite3OsOpen()
4298 ** fails.
4300 static int openSubJournal(Pager *pPager){
4301 int rc = SQLITE_OK;
4302 if( !isOpen(pPager->sjfd) ){
4303 if( pPager->journalMode==PAGER_JOURNALMODE_MEMORY || pPager->subjInMemory ){
4304 sqlite3MemJournalOpen(pPager->sjfd);
4305 }else{
4306 rc = pagerOpentemp(pPager, pPager->sjfd, SQLITE_OPEN_SUBJOURNAL);
4309 return rc;
4313 ** Append a record of the current state of page pPg to the sub-journal.
4314 ** It is the callers responsibility to use subjRequiresPage() to check
4315 ** that it is really required before calling this function.
4317 ** If successful, set the bit corresponding to pPg->pgno in the bitvecs
4318 ** for all open savepoints before returning.
4320 ** This function returns SQLITE_OK if everything is successful, an IO
4321 ** error code if the attempt to write to the sub-journal fails, or
4322 ** SQLITE_NOMEM if a malloc fails while setting a bit in a savepoint
4323 ** bitvec.
4325 static int subjournalPage(PgHdr *pPg){
4326 int rc = SQLITE_OK;
4327 Pager *pPager = pPg->pPager;
4328 if( pPager->journalMode!=PAGER_JOURNALMODE_OFF ){
4330 /* Open the sub-journal, if it has not already been opened */
4331 assert( pPager->useJournal );
4332 assert( isOpen(pPager->jfd) || pagerUseWal(pPager) );
4333 assert( isOpen(pPager->sjfd) || pPager->nSubRec==0 );
4334 assert( pagerUseWal(pPager)
4335 || pageInJournal(pPager, pPg)
4336 || pPg->pgno>pPager->dbOrigSize
4338 rc = openSubJournal(pPager);
4340 /* If the sub-journal was opened successfully (or was already open),
4341 ** write the journal record into the file. */
4342 if( rc==SQLITE_OK ){
4343 void *pData = pPg->pData;
4344 i64 offset = (i64)pPager->nSubRec*(4+pPager->pageSize);
4345 char *pData2;
4347 CODEC2(pPager, pData, pPg->pgno, 7, return SQLITE_NOMEM, pData2);
4348 PAGERTRACE(("STMT-JOURNAL %d page %d\n", PAGERID(pPager), pPg->pgno));
4349 rc = write32bits(pPager->sjfd, offset, pPg->pgno);
4350 if( rc==SQLITE_OK ){
4351 rc = sqlite3OsWrite(pPager->sjfd, pData2, pPager->pageSize, offset+4);
4355 if( rc==SQLITE_OK ){
4356 pPager->nSubRec++;
4357 assert( pPager->nSavepoint>0 );
4358 rc = addToSavepointBitvecs(pPager, pPg->pgno);
4360 return rc;
4364 ** This function is called by the pcache layer when it has reached some
4365 ** soft memory limit. The first argument is a pointer to a Pager object
4366 ** (cast as a void*). The pager is always 'purgeable' (not an in-memory
4367 ** database). The second argument is a reference to a page that is
4368 ** currently dirty but has no outstanding references. The page
4369 ** is always associated with the Pager object passed as the first
4370 ** argument.
4372 ** The job of this function is to make pPg clean by writing its contents
4373 ** out to the database file, if possible. This may involve syncing the
4374 ** journal file.
4376 ** If successful, sqlite3PcacheMakeClean() is called on the page and
4377 ** SQLITE_OK returned. If an IO error occurs while trying to make the
4378 ** page clean, the IO error code is returned. If the page cannot be
4379 ** made clean for some other reason, but no error occurs, then SQLITE_OK
4380 ** is returned by sqlite3PcacheMakeClean() is not called.
4382 static int pagerStress(void *p, PgHdr *pPg){
4383 Pager *pPager = (Pager *)p;
4384 int rc = SQLITE_OK;
4386 assert( pPg->pPager==pPager );
4387 assert( pPg->flags&PGHDR_DIRTY );
4389 /* The doNotSpill NOSYNC bit is set during times when doing a sync of
4390 ** journal (and adding a new header) is not allowed. This occurs
4391 ** during calls to sqlite3PagerWrite() while trying to journal multiple
4392 ** pages belonging to the same sector.
4394 ** The doNotSpill ROLLBACK and OFF bits inhibits all cache spilling
4395 ** regardless of whether or not a sync is required. This is set during
4396 ** a rollback or by user request, respectively.
4398 ** Spilling is also prohibited when in an error state since that could
4399 ** lead to database corruption. In the current implementation it
4400 ** is impossible for sqlite3PcacheFetch() to be called with createFlag==3
4401 ** while in the error state, hence it is impossible for this routine to
4402 ** be called in the error state. Nevertheless, we include a NEVER()
4403 ** test for the error state as a safeguard against future changes.
4405 if( NEVER(pPager->errCode) ) return SQLITE_OK;
4406 testcase( pPager->doNotSpill & SPILLFLAG_ROLLBACK );
4407 testcase( pPager->doNotSpill & SPILLFLAG_OFF );
4408 testcase( pPager->doNotSpill & SPILLFLAG_NOSYNC );
4409 if( pPager->doNotSpill
4410 && ((pPager->doNotSpill & (SPILLFLAG_ROLLBACK|SPILLFLAG_OFF))!=0
4411 || (pPg->flags & PGHDR_NEED_SYNC)!=0)
4413 return SQLITE_OK;
4416 pPg->pDirty = 0;
4417 if( pagerUseWal(pPager) ){
4418 /* Write a single frame for this page to the log. */
4419 if( subjRequiresPage(pPg) ){
4420 rc = subjournalPage(pPg);
4422 if( rc==SQLITE_OK ){
4423 rc = pagerWalFrames(pPager, pPg, 0, 0);
4425 }else{
4427 /* Sync the journal file if required. */
4428 if( pPg->flags&PGHDR_NEED_SYNC
4429 || pPager->eState==PAGER_WRITER_CACHEMOD
4431 rc = syncJournal(pPager, 1);
4434 /* If the page number of this page is larger than the current size of
4435 ** the database image, it may need to be written to the sub-journal.
4436 ** This is because the call to pager_write_pagelist() below will not
4437 ** actually write data to the file in this case.
4439 ** Consider the following sequence of events:
4441 ** BEGIN;
4442 ** <journal page X>
4443 ** <modify page X>
4444 ** SAVEPOINT sp;
4445 ** <shrink database file to Y pages>
4446 ** pagerStress(page X)
4447 ** ROLLBACK TO sp;
4449 ** If (X>Y), then when pagerStress is called page X will not be written
4450 ** out to the database file, but will be dropped from the cache. Then,
4451 ** following the "ROLLBACK TO sp" statement, reading page X will read
4452 ** data from the database file. This will be the copy of page X as it
4453 ** was when the transaction started, not as it was when "SAVEPOINT sp"
4454 ** was executed.
4456 ** The solution is to write the current data for page X into the
4457 ** sub-journal file now (if it is not already there), so that it will
4458 ** be restored to its current value when the "ROLLBACK TO sp" is
4459 ** executed.
4461 if( NEVER(
4462 rc==SQLITE_OK && pPg->pgno>pPager->dbSize && subjRequiresPage(pPg)
4463 ) ){
4464 rc = subjournalPage(pPg);
4467 /* Write the contents of the page out to the database file. */
4468 if( rc==SQLITE_OK ){
4469 assert( (pPg->flags&PGHDR_NEED_SYNC)==0 );
4470 rc = pager_write_pagelist(pPager, pPg);
4474 /* Mark the page as clean. */
4475 if( rc==SQLITE_OK ){
4476 PAGERTRACE(("STRESS %d page %d\n", PAGERID(pPager), pPg->pgno));
4477 sqlite3PcacheMakeClean(pPg);
4480 return pager_error(pPager, rc);
4485 ** Allocate and initialize a new Pager object and put a pointer to it
4486 ** in *ppPager. The pager should eventually be freed by passing it
4487 ** to sqlite3PagerClose().
4489 ** The zFilename argument is the path to the database file to open.
4490 ** If zFilename is NULL then a randomly-named temporary file is created
4491 ** and used as the file to be cached. Temporary files are be deleted
4492 ** automatically when they are closed. If zFilename is ":memory:" then
4493 ** all information is held in cache. It is never written to disk.
4494 ** This can be used to implement an in-memory database.
4496 ** The nExtra parameter specifies the number of bytes of space allocated
4497 ** along with each page reference. This space is available to the user
4498 ** via the sqlite3PagerGetExtra() API.
4500 ** The flags argument is used to specify properties that affect the
4501 ** operation of the pager. It should be passed some bitwise combination
4502 ** of the PAGER_* flags.
4504 ** The vfsFlags parameter is a bitmask to pass to the flags parameter
4505 ** of the xOpen() method of the supplied VFS when opening files.
4507 ** If the pager object is allocated and the specified file opened
4508 ** successfully, SQLITE_OK is returned and *ppPager set to point to
4509 ** the new pager object. If an error occurs, *ppPager is set to NULL
4510 ** and error code returned. This function may return SQLITE_NOMEM
4511 ** (sqlite3Malloc() is used to allocate memory), SQLITE_CANTOPEN or
4512 ** various SQLITE_IO_XXX errors.
4514 int sqlite3PagerOpen(
4515 sqlite3_vfs *pVfs, /* The virtual file system to use */
4516 Pager **ppPager, /* OUT: Return the Pager structure here */
4517 const char *zFilename, /* Name of the database file to open */
4518 int nExtra, /* Extra bytes append to each in-memory page */
4519 int flags, /* flags controlling this file */
4520 int vfsFlags, /* flags passed through to sqlite3_vfs.xOpen() */
4521 void (*xReinit)(DbPage*) /* Function to reinitialize pages */
4523 u8 *pPtr;
4524 Pager *pPager = 0; /* Pager object to allocate and return */
4525 int rc = SQLITE_OK; /* Return code */
4526 int tempFile = 0; /* True for temp files (incl. in-memory files) */
4527 int memDb = 0; /* True if this is an in-memory file */
4528 int readOnly = 0; /* True if this is a read-only file */
4529 int journalFileSize; /* Bytes to allocate for each journal fd */
4530 char *zPathname = 0; /* Full path to database file */
4531 int nPathname = 0; /* Number of bytes in zPathname */
4532 int useJournal = (flags & PAGER_OMIT_JOURNAL)==0; /* False to omit journal */
4533 int pcacheSize = sqlite3PcacheSize(); /* Bytes to allocate for PCache */
4534 u32 szPageDflt = SQLITE_DEFAULT_PAGE_SIZE; /* Default page size */
4535 const char *zUri = 0; /* URI args to copy */
4536 int nUri = 0; /* Number of bytes of URI args at *zUri */
4538 /* Figure out how much space is required for each journal file-handle
4539 ** (there are two of them, the main journal and the sub-journal). This
4540 ** is the maximum space required for an in-memory journal file handle
4541 ** and a regular journal file-handle. Note that a "regular journal-handle"
4542 ** may be a wrapper capable of caching the first portion of the journal
4543 ** file in memory to implement the atomic-write optimization (see
4544 ** source file journal.c).
4546 if( sqlite3JournalSize(pVfs)>sqlite3MemJournalSize() ){
4547 journalFileSize = ROUND8(sqlite3JournalSize(pVfs));
4548 }else{
4549 journalFileSize = ROUND8(sqlite3MemJournalSize());
4552 /* Set the output variable to NULL in case an error occurs. */
4553 *ppPager = 0;
4555 #ifndef SQLITE_OMIT_MEMORYDB
4556 if( flags & PAGER_MEMORY ){
4557 memDb = 1;
4558 if( zFilename && zFilename[0] ){
4559 zPathname = sqlite3DbStrDup(0, zFilename);
4560 if( zPathname==0 ) return SQLITE_NOMEM;
4561 nPathname = sqlite3Strlen30(zPathname);
4562 zFilename = 0;
4565 #endif
4567 /* Compute and store the full pathname in an allocated buffer pointed
4568 ** to by zPathname, length nPathname. Or, if this is a temporary file,
4569 ** leave both nPathname and zPathname set to 0.
4571 if( zFilename && zFilename[0] ){
4572 const char *z;
4573 nPathname = pVfs->mxPathname+1;
4574 zPathname = sqlite3DbMallocRaw(0, nPathname*2);
4575 if( zPathname==0 ){
4576 return SQLITE_NOMEM;
4578 zPathname[0] = 0; /* Make sure initialized even if FullPathname() fails */
4579 rc = sqlite3OsFullPathname(pVfs, zFilename, nPathname, zPathname);
4580 nPathname = sqlite3Strlen30(zPathname);
4581 z = zUri = &zFilename[sqlite3Strlen30(zFilename)+1];
4582 while( *z ){
4583 z += sqlite3Strlen30(z)+1;
4584 z += sqlite3Strlen30(z)+1;
4586 nUri = (int)(&z[1] - zUri);
4587 assert( nUri>=0 );
4588 if( rc==SQLITE_OK && nPathname+8>pVfs->mxPathname ){
4589 /* This branch is taken when the journal path required by
4590 ** the database being opened will be more than pVfs->mxPathname
4591 ** bytes in length. This means the database cannot be opened,
4592 ** as it will not be possible to open the journal file or even
4593 ** check for a hot-journal before reading.
4595 rc = SQLITE_CANTOPEN_BKPT;
4597 if( rc!=SQLITE_OK ){
4598 sqlite3DbFree(0, zPathname);
4599 return rc;
4603 /* Allocate memory for the Pager structure, PCache object, the
4604 ** three file descriptors, the database file name and the journal
4605 ** file name. The layout in memory is as follows:
4607 ** Pager object (sizeof(Pager) bytes)
4608 ** PCache object (sqlite3PcacheSize() bytes)
4609 ** Database file handle (pVfs->szOsFile bytes)
4610 ** Sub-journal file handle (journalFileSize bytes)
4611 ** Main journal file handle (journalFileSize bytes)
4612 ** Database file name (nPathname+1 bytes)
4613 ** Journal file name (nPathname+8+1 bytes)
4615 pPtr = (u8 *)sqlite3MallocZero(
4616 ROUND8(sizeof(*pPager)) + /* Pager structure */
4617 ROUND8(pcacheSize) + /* PCache object */
4618 ROUND8(pVfs->szOsFile) + /* The main db file */
4619 journalFileSize * 2 + /* The two journal files */
4620 nPathname + 1 + nUri + /* zFilename */
4621 nPathname + 8 + 2 /* zJournal */
4622 #ifndef SQLITE_OMIT_WAL
4623 + nPathname + 4 + 2 /* zWal */
4624 #endif
4626 assert( EIGHT_BYTE_ALIGNMENT(SQLITE_INT_TO_PTR(journalFileSize)) );
4627 if( !pPtr ){
4628 sqlite3DbFree(0, zPathname);
4629 return SQLITE_NOMEM;
4631 pPager = (Pager*)(pPtr);
4632 pPager->pPCache = (PCache*)(pPtr += ROUND8(sizeof(*pPager)));
4633 pPager->fd = (sqlite3_file*)(pPtr += ROUND8(pcacheSize));
4634 pPager->sjfd = (sqlite3_file*)(pPtr += ROUND8(pVfs->szOsFile));
4635 pPager->jfd = (sqlite3_file*)(pPtr += journalFileSize);
4636 pPager->zFilename = (char*)(pPtr += journalFileSize);
4637 assert( EIGHT_BYTE_ALIGNMENT(pPager->jfd) );
4639 /* Fill in the Pager.zFilename and Pager.zJournal buffers, if required. */
4640 if( zPathname ){
4641 assert( nPathname>0 );
4642 pPager->zJournal = (char*)(pPtr += nPathname + 1 + nUri);
4643 memcpy(pPager->zFilename, zPathname, nPathname);
4644 if( nUri ) memcpy(&pPager->zFilename[nPathname+1], zUri, nUri);
4645 memcpy(pPager->zJournal, zPathname, nPathname);
4646 memcpy(&pPager->zJournal[nPathname], "-journal\000", 8+2);
4647 sqlite3FileSuffix3(pPager->zFilename, pPager->zJournal);
4648 #ifndef SQLITE_OMIT_WAL
4649 pPager->zWal = &pPager->zJournal[nPathname+8+1];
4650 memcpy(pPager->zWal, zPathname, nPathname);
4651 memcpy(&pPager->zWal[nPathname], "-wal\000", 4+1);
4652 sqlite3FileSuffix3(pPager->zFilename, pPager->zWal);
4653 #endif
4654 sqlite3DbFree(0, zPathname);
4656 pPager->pVfs = pVfs;
4657 pPager->vfsFlags = vfsFlags;
4659 /* Open the pager file.
4661 if( zFilename && zFilename[0] ){
4662 int fout = 0; /* VFS flags returned by xOpen() */
4663 rc = sqlite3OsOpen(pVfs, pPager->zFilename, pPager->fd, vfsFlags, &fout);
4664 assert( !memDb );
4665 readOnly = (fout&SQLITE_OPEN_READONLY);
4667 /* If the file was successfully opened for read/write access,
4668 ** choose a default page size in case we have to create the
4669 ** database file. The default page size is the maximum of:
4671 ** + SQLITE_DEFAULT_PAGE_SIZE,
4672 ** + The value returned by sqlite3OsSectorSize()
4673 ** + The largest page size that can be written atomically.
4675 if( rc==SQLITE_OK ){
4676 int iDc = sqlite3OsDeviceCharacteristics(pPager->fd);
4677 if( !readOnly ){
4678 setSectorSize(pPager);
4679 assert(SQLITE_DEFAULT_PAGE_SIZE<=SQLITE_MAX_DEFAULT_PAGE_SIZE);
4680 if( szPageDflt<pPager->sectorSize ){
4681 if( pPager->sectorSize>SQLITE_MAX_DEFAULT_PAGE_SIZE ){
4682 szPageDflt = SQLITE_MAX_DEFAULT_PAGE_SIZE;
4683 }else{
4684 szPageDflt = (u32)pPager->sectorSize;
4687 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
4689 int ii;
4690 assert(SQLITE_IOCAP_ATOMIC512==(512>>8));
4691 assert(SQLITE_IOCAP_ATOMIC64K==(65536>>8));
4692 assert(SQLITE_MAX_DEFAULT_PAGE_SIZE<=65536);
4693 for(ii=szPageDflt; ii<=SQLITE_MAX_DEFAULT_PAGE_SIZE; ii=ii*2){
4694 if( iDc&(SQLITE_IOCAP_ATOMIC|(ii>>8)) ){
4695 szPageDflt = ii;
4699 #endif
4701 pPager->noLock = sqlite3_uri_boolean(zFilename, "nolock", 0);
4702 if( (iDc & SQLITE_IOCAP_IMMUTABLE)!=0
4703 || sqlite3_uri_boolean(zFilename, "immutable", 0) ){
4704 vfsFlags |= SQLITE_OPEN_READONLY;
4705 goto act_like_temp_file;
4708 }else{
4709 /* If a temporary file is requested, it is not opened immediately.
4710 ** In this case we accept the default page size and delay actually
4711 ** opening the file until the first call to OsWrite().
4713 ** This branch is also run for an in-memory database. An in-memory
4714 ** database is the same as a temp-file that is never written out to
4715 ** disk and uses an in-memory rollback journal.
4717 ** This branch also runs for files marked as immutable.
4719 act_like_temp_file:
4720 tempFile = 1;
4721 pPager->eState = PAGER_READER; /* Pretend we already have a lock */
4722 pPager->eLock = EXCLUSIVE_LOCK; /* Pretend we are in EXCLUSIVE locking mode */
4723 pPager->noLock = 1; /* Do no locking */
4724 readOnly = (vfsFlags&SQLITE_OPEN_READONLY);
4727 /* The following call to PagerSetPagesize() serves to set the value of
4728 ** Pager.pageSize and to allocate the Pager.pTmpSpace buffer.
4730 if( rc==SQLITE_OK ){
4731 assert( pPager->memDb==0 );
4732 rc = sqlite3PagerSetPagesize(pPager, &szPageDflt, -1);
4733 testcase( rc!=SQLITE_OK );
4736 /* Initialize the PCache object. */
4737 if( rc==SQLITE_OK ){
4738 assert( nExtra<1000 );
4739 nExtra = ROUND8(nExtra);
4740 rc = sqlite3PcacheOpen(szPageDflt, nExtra, !memDb,
4741 !memDb?pagerStress:0, (void *)pPager, pPager->pPCache);
4744 /* If an error occurred above, free the Pager structure and close the file.
4746 if( rc!=SQLITE_OK ){
4747 sqlite3OsClose(pPager->fd);
4748 sqlite3PageFree(pPager->pTmpSpace);
4749 sqlite3_free(pPager);
4750 return rc;
4753 PAGERTRACE(("OPEN %d %s\n", FILEHANDLEID(pPager->fd), pPager->zFilename));
4754 IOTRACE(("OPEN %p %s\n", pPager, pPager->zFilename))
4756 pPager->useJournal = (u8)useJournal;
4757 /* pPager->stmtOpen = 0; */
4758 /* pPager->stmtInUse = 0; */
4759 /* pPager->nRef = 0; */
4760 /* pPager->stmtSize = 0; */
4761 /* pPager->stmtJSize = 0; */
4762 /* pPager->nPage = 0; */
4763 pPager->mxPgno = SQLITE_MAX_PAGE_COUNT;
4764 /* pPager->state = PAGER_UNLOCK; */
4765 /* pPager->errMask = 0; */
4766 pPager->tempFile = (u8)tempFile;
4767 assert( tempFile==PAGER_LOCKINGMODE_NORMAL
4768 || tempFile==PAGER_LOCKINGMODE_EXCLUSIVE );
4769 assert( PAGER_LOCKINGMODE_EXCLUSIVE==1 );
4770 pPager->exclusiveMode = (u8)tempFile;
4771 pPager->changeCountDone = pPager->tempFile;
4772 pPager->memDb = (u8)memDb;
4773 pPager->readOnly = (u8)readOnly;
4774 assert( useJournal || pPager->tempFile );
4775 pPager->noSync = pPager->tempFile;
4776 if( pPager->noSync ){
4777 assert( pPager->fullSync==0 );
4778 assert( pPager->syncFlags==0 );
4779 assert( pPager->walSyncFlags==0 );
4780 assert( pPager->ckptSyncFlags==0 );
4781 }else{
4782 pPager->fullSync = 1;
4783 pPager->syncFlags = SQLITE_SYNC_NORMAL;
4784 pPager->walSyncFlags = SQLITE_SYNC_NORMAL | WAL_SYNC_TRANSACTIONS;
4785 pPager->ckptSyncFlags = SQLITE_SYNC_NORMAL;
4787 /* pPager->pFirst = 0; */
4788 /* pPager->pFirstSynced = 0; */
4789 /* pPager->pLast = 0; */
4790 pPager->nExtra = (u16)nExtra;
4791 pPager->journalSizeLimit = SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT;
4792 assert( isOpen(pPager->fd) || tempFile );
4793 setSectorSize(pPager);
4794 if( !useJournal ){
4795 pPager->journalMode = PAGER_JOURNALMODE_OFF;
4796 }else if( memDb ){
4797 pPager->journalMode = PAGER_JOURNALMODE_MEMORY;
4799 /* pPager->xBusyHandler = 0; */
4800 /* pPager->pBusyHandlerArg = 0; */
4801 pPager->xReiniter = xReinit;
4802 /* memset(pPager->aHash, 0, sizeof(pPager->aHash)); */
4803 /* pPager->szMmap = SQLITE_DEFAULT_MMAP_SIZE // will be set by btree.c */
4805 *ppPager = pPager;
4806 return SQLITE_OK;
4810 /* Verify that the database file has not be deleted or renamed out from
4811 ** under the pager. Return SQLITE_OK if the database is still were it ought
4812 ** to be on disk. Return non-zero (SQLITE_READONLY_DBMOVED or some other error
4813 ** code from sqlite3OsAccess()) if the database has gone missing.
4815 static int databaseIsUnmoved(Pager *pPager){
4816 int bHasMoved = 0;
4817 int rc;
4819 if( pPager->tempFile ) return SQLITE_OK;
4820 if( pPager->dbSize==0 ) return SQLITE_OK;
4821 assert( pPager->zFilename && pPager->zFilename[0] );
4822 rc = sqlite3OsFileControl(pPager->fd, SQLITE_FCNTL_HAS_MOVED, &bHasMoved);
4823 if( rc==SQLITE_NOTFOUND ){
4824 /* If the HAS_MOVED file-control is unimplemented, assume that the file
4825 ** has not been moved. That is the historical behavior of SQLite: prior to
4826 ** version 3.8.3, it never checked */
4827 rc = SQLITE_OK;
4828 }else if( rc==SQLITE_OK && bHasMoved ){
4829 rc = SQLITE_READONLY_DBMOVED;
4831 return rc;
4836 ** This function is called after transitioning from PAGER_UNLOCK to
4837 ** PAGER_SHARED state. It tests if there is a hot journal present in
4838 ** the file-system for the given pager. A hot journal is one that
4839 ** needs to be played back. According to this function, a hot-journal
4840 ** file exists if the following criteria are met:
4842 ** * The journal file exists in the file system, and
4843 ** * No process holds a RESERVED or greater lock on the database file, and
4844 ** * The database file itself is greater than 0 bytes in size, and
4845 ** * The first byte of the journal file exists and is not 0x00.
4847 ** If the current size of the database file is 0 but a journal file
4848 ** exists, that is probably an old journal left over from a prior
4849 ** database with the same name. In this case the journal file is
4850 ** just deleted using OsDelete, *pExists is set to 0 and SQLITE_OK
4851 ** is returned.
4853 ** This routine does not check if there is a master journal filename
4854 ** at the end of the file. If there is, and that master journal file
4855 ** does not exist, then the journal file is not really hot. In this
4856 ** case this routine will return a false-positive. The pager_playback()
4857 ** routine will discover that the journal file is not really hot and
4858 ** will not roll it back.
4860 ** If a hot-journal file is found to exist, *pExists is set to 1 and
4861 ** SQLITE_OK returned. If no hot-journal file is present, *pExists is
4862 ** set to 0 and SQLITE_OK returned. If an IO error occurs while trying
4863 ** to determine whether or not a hot-journal file exists, the IO error
4864 ** code is returned and the value of *pExists is undefined.
4866 static int hasHotJournal(Pager *pPager, int *pExists){
4867 sqlite3_vfs * const pVfs = pPager->pVfs;
4868 int rc = SQLITE_OK; /* Return code */
4869 int exists = 1; /* True if a journal file is present */
4870 int jrnlOpen = !!isOpen(pPager->jfd);
4872 assert( pPager->useJournal );
4873 assert( isOpen(pPager->fd) );
4874 assert( pPager->eState==PAGER_OPEN );
4876 assert( jrnlOpen==0 || ( sqlite3OsDeviceCharacteristics(pPager->jfd) &
4877 SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
4880 *pExists = 0;
4881 if( !jrnlOpen ){
4882 rc = sqlite3OsAccess(pVfs, pPager->zJournal, SQLITE_ACCESS_EXISTS, &exists);
4884 if( rc==SQLITE_OK && exists ){
4885 int locked = 0; /* True if some process holds a RESERVED lock */
4887 /* Race condition here: Another process might have been holding the
4888 ** the RESERVED lock and have a journal open at the sqlite3OsAccess()
4889 ** call above, but then delete the journal and drop the lock before
4890 ** we get to the following sqlite3OsCheckReservedLock() call. If that
4891 ** is the case, this routine might think there is a hot journal when
4892 ** in fact there is none. This results in a false-positive which will
4893 ** be dealt with by the playback routine. Ticket #3883.
4895 rc = sqlite3OsCheckReservedLock(pPager->fd, &locked);
4896 if( rc==SQLITE_OK && !locked ){
4897 Pgno nPage; /* Number of pages in database file */
4899 rc = pagerPagecount(pPager, &nPage);
4900 if( rc==SQLITE_OK ){
4901 /* If the database is zero pages in size, that means that either (1) the
4902 ** journal is a remnant from a prior database with the same name where
4903 ** the database file but not the journal was deleted, or (2) the initial
4904 ** transaction that populates a new database is being rolled back.
4905 ** In either case, the journal file can be deleted. However, take care
4906 ** not to delete the journal file if it is already open due to
4907 ** journal_mode=PERSIST.
4909 if( nPage==0 && !jrnlOpen ){
4910 sqlite3BeginBenignMalloc();
4911 if( pagerLockDb(pPager, RESERVED_LOCK)==SQLITE_OK ){
4912 sqlite3OsDelete(pVfs, pPager->zJournal, 0);
4913 if( !pPager->exclusiveMode ) pagerUnlockDb(pPager, SHARED_LOCK);
4915 sqlite3EndBenignMalloc();
4916 }else{
4917 /* The journal file exists and no other connection has a reserved
4918 ** or greater lock on the database file. Now check that there is
4919 ** at least one non-zero bytes at the start of the journal file.
4920 ** If there is, then we consider this journal to be hot. If not,
4921 ** it can be ignored.
4923 if( !jrnlOpen ){
4924 int f = SQLITE_OPEN_READONLY|SQLITE_OPEN_MAIN_JOURNAL;
4925 rc = sqlite3OsOpen(pVfs, pPager->zJournal, pPager->jfd, f, &f);
4927 if( rc==SQLITE_OK ){
4928 u8 first = 0;
4929 rc = sqlite3OsRead(pPager->jfd, (void *)&first, 1, 0);
4930 if( rc==SQLITE_IOERR_SHORT_READ ){
4931 rc = SQLITE_OK;
4933 if( !jrnlOpen ){
4934 sqlite3OsClose(pPager->jfd);
4936 *pExists = (first!=0);
4937 }else if( rc==SQLITE_CANTOPEN ){
4938 /* If we cannot open the rollback journal file in order to see if
4939 ** it has a zero header, that might be due to an I/O error, or
4940 ** it might be due to the race condition described above and in
4941 ** ticket #3883. Either way, assume that the journal is hot.
4942 ** This might be a false positive. But if it is, then the
4943 ** automatic journal playback and recovery mechanism will deal
4944 ** with it under an EXCLUSIVE lock where we do not need to
4945 ** worry so much with race conditions.
4947 *pExists = 1;
4948 rc = SQLITE_OK;
4955 return rc;
4959 ** This function is called to obtain a shared lock on the database file.
4960 ** It is illegal to call sqlite3PagerAcquire() until after this function
4961 ** has been successfully called. If a shared-lock is already held when
4962 ** this function is called, it is a no-op.
4964 ** The following operations are also performed by this function.
4966 ** 1) If the pager is currently in PAGER_OPEN state (no lock held
4967 ** on the database file), then an attempt is made to obtain a
4968 ** SHARED lock on the database file. Immediately after obtaining
4969 ** the SHARED lock, the file-system is checked for a hot-journal,
4970 ** which is played back if present. Following any hot-journal
4971 ** rollback, the contents of the cache are validated by checking
4972 ** the 'change-counter' field of the database file header and
4973 ** discarded if they are found to be invalid.
4975 ** 2) If the pager is running in exclusive-mode, and there are currently
4976 ** no outstanding references to any pages, and is in the error state,
4977 ** then an attempt is made to clear the error state by discarding
4978 ** the contents of the page cache and rolling back any open journal
4979 ** file.
4981 ** If everything is successful, SQLITE_OK is returned. If an IO error
4982 ** occurs while locking the database, checking for a hot-journal file or
4983 ** rolling back a journal file, the IO error code is returned.
4985 int sqlite3PagerSharedLock(Pager *pPager){
4986 int rc = SQLITE_OK; /* Return code */
4988 /* This routine is only called from b-tree and only when there are no
4989 ** outstanding pages. This implies that the pager state should either
4990 ** be OPEN or READER. READER is only possible if the pager is or was in
4991 ** exclusive access mode.
4993 assert( sqlite3PcacheRefCount(pPager->pPCache)==0 );
4994 assert( assert_pager_state(pPager) );
4995 assert( pPager->eState==PAGER_OPEN || pPager->eState==PAGER_READER );
4996 if( NEVER(MEMDB && pPager->errCode) ){ return pPager->errCode; }
4998 if( !pagerUseWal(pPager) && pPager->eState==PAGER_OPEN ){
4999 int bHotJournal = 1; /* True if there exists a hot journal-file */
5001 assert( !MEMDB );
5003 rc = pager_wait_on_lock(pPager, SHARED_LOCK);
5004 if( rc!=SQLITE_OK ){
5005 assert( pPager->eLock==NO_LOCK || pPager->eLock==UNKNOWN_LOCK );
5006 goto failed;
5009 /* If a journal file exists, and there is no RESERVED lock on the
5010 ** database file, then it either needs to be played back or deleted.
5012 if( pPager->eLock<=SHARED_LOCK ){
5013 rc = hasHotJournal(pPager, &bHotJournal);
5015 if( rc!=SQLITE_OK ){
5016 goto failed;
5018 if( bHotJournal ){
5019 if( pPager->readOnly ){
5020 rc = SQLITE_READONLY_ROLLBACK;
5021 goto failed;
5024 /* Get an EXCLUSIVE lock on the database file. At this point it is
5025 ** important that a RESERVED lock is not obtained on the way to the
5026 ** EXCLUSIVE lock. If it were, another process might open the
5027 ** database file, detect the RESERVED lock, and conclude that the
5028 ** database is safe to read while this process is still rolling the
5029 ** hot-journal back.
5031 ** Because the intermediate RESERVED lock is not requested, any
5032 ** other process attempting to access the database file will get to
5033 ** this point in the code and fail to obtain its own EXCLUSIVE lock
5034 ** on the database file.
5036 ** Unless the pager is in locking_mode=exclusive mode, the lock is
5037 ** downgraded to SHARED_LOCK before this function returns.
5039 rc = pagerLockDb(pPager, EXCLUSIVE_LOCK);
5040 if( rc!=SQLITE_OK ){
5041 goto failed;
5044 /* If it is not already open and the file exists on disk, open the
5045 ** journal for read/write access. Write access is required because
5046 ** in exclusive-access mode the file descriptor will be kept open
5047 ** and possibly used for a transaction later on. Also, write-access
5048 ** is usually required to finalize the journal in journal_mode=persist
5049 ** mode (and also for journal_mode=truncate on some systems).
5051 ** If the journal does not exist, it usually means that some
5052 ** other connection managed to get in and roll it back before
5053 ** this connection obtained the exclusive lock above. Or, it
5054 ** may mean that the pager was in the error-state when this
5055 ** function was called and the journal file does not exist.
5057 if( !isOpen(pPager->jfd) ){
5058 sqlite3_vfs * const pVfs = pPager->pVfs;
5059 int bExists; /* True if journal file exists */
5060 rc = sqlite3OsAccess(
5061 pVfs, pPager->zJournal, SQLITE_ACCESS_EXISTS, &bExists);
5062 if( rc==SQLITE_OK && bExists ){
5063 int fout = 0;
5064 int f = SQLITE_OPEN_READWRITE|SQLITE_OPEN_MAIN_JOURNAL;
5065 assert( !pPager->tempFile );
5066 rc = sqlite3OsOpen(pVfs, pPager->zJournal, pPager->jfd, f, &fout);
5067 assert( rc!=SQLITE_OK || isOpen(pPager->jfd) );
5068 if( rc==SQLITE_OK && fout&SQLITE_OPEN_READONLY ){
5069 rc = SQLITE_CANTOPEN_BKPT;
5070 sqlite3OsClose(pPager->jfd);
5075 /* Playback and delete the journal. Drop the database write
5076 ** lock and reacquire the read lock. Purge the cache before
5077 ** playing back the hot-journal so that we don't end up with
5078 ** an inconsistent cache. Sync the hot journal before playing
5079 ** it back since the process that crashed and left the hot journal
5080 ** probably did not sync it and we are required to always sync
5081 ** the journal before playing it back.
5083 if( isOpen(pPager->jfd) ){
5084 assert( rc==SQLITE_OK );
5085 rc = pagerSyncHotJournal(pPager);
5086 if( rc==SQLITE_OK ){
5087 rc = pager_playback(pPager, 1);
5088 pPager->eState = PAGER_OPEN;
5090 }else if( !pPager->exclusiveMode ){
5091 pagerUnlockDb(pPager, SHARED_LOCK);
5094 if( rc!=SQLITE_OK ){
5095 /* This branch is taken if an error occurs while trying to open
5096 ** or roll back a hot-journal while holding an EXCLUSIVE lock. The
5097 ** pager_unlock() routine will be called before returning to unlock
5098 ** the file. If the unlock attempt fails, then Pager.eLock must be
5099 ** set to UNKNOWN_LOCK (see the comment above the #define for
5100 ** UNKNOWN_LOCK above for an explanation).
5102 ** In order to get pager_unlock() to do this, set Pager.eState to
5103 ** PAGER_ERROR now. This is not actually counted as a transition
5104 ** to ERROR state in the state diagram at the top of this file,
5105 ** since we know that the same call to pager_unlock() will very
5106 ** shortly transition the pager object to the OPEN state. Calling
5107 ** assert_pager_state() would fail now, as it should not be possible
5108 ** to be in ERROR state when there are zero outstanding page
5109 ** references.
5111 pager_error(pPager, rc);
5112 goto failed;
5115 assert( pPager->eState==PAGER_OPEN );
5116 assert( (pPager->eLock==SHARED_LOCK)
5117 || (pPager->exclusiveMode && pPager->eLock>SHARED_LOCK)
5121 if( !pPager->tempFile && (
5122 pPager->pBackup
5123 || sqlite3PcachePagecount(pPager->pPCache)>0
5124 || USEFETCH(pPager)
5126 /* The shared-lock has just been acquired on the database file
5127 ** and there are already pages in the cache (from a previous
5128 ** read or write transaction). Check to see if the database
5129 ** has been modified. If the database has changed, flush the
5130 ** cache.
5132 ** Database changes is detected by looking at 15 bytes beginning
5133 ** at offset 24 into the file. The first 4 of these 16 bytes are
5134 ** a 32-bit counter that is incremented with each change. The
5135 ** other bytes change randomly with each file change when
5136 ** a codec is in use.
5138 ** There is a vanishingly small chance that a change will not be
5139 ** detected. The chance of an undetected change is so small that
5140 ** it can be neglected.
5142 Pgno nPage = 0;
5143 char dbFileVers[sizeof(pPager->dbFileVers)];
5145 rc = pagerPagecount(pPager, &nPage);
5146 if( rc ) goto failed;
5148 if( nPage>0 ){
5149 IOTRACE(("CKVERS %p %d\n", pPager, sizeof(dbFileVers)));
5150 rc = sqlite3OsRead(pPager->fd, &dbFileVers, sizeof(dbFileVers), 24);
5151 if( rc!=SQLITE_OK && rc!=SQLITE_IOERR_SHORT_READ ){
5152 goto failed;
5154 }else{
5155 memset(dbFileVers, 0, sizeof(dbFileVers));
5158 if( memcmp(pPager->dbFileVers, dbFileVers, sizeof(dbFileVers))!=0 ){
5159 pager_reset(pPager);
5161 /* Unmap the database file. It is possible that external processes
5162 ** may have truncated the database file and then extended it back
5163 ** to its original size while this process was not holding a lock.
5164 ** In this case there may exist a Pager.pMap mapping that appears
5165 ** to be the right size but is not actually valid. Avoid this
5166 ** possibility by unmapping the db here. */
5167 if( USEFETCH(pPager) ){
5168 sqlite3OsUnfetch(pPager->fd, 0, 0);
5173 /* If there is a WAL file in the file-system, open this database in WAL
5174 ** mode. Otherwise, the following function call is a no-op.
5176 rc = pagerOpenWalIfPresent(pPager);
5177 #ifndef SQLITE_OMIT_WAL
5178 assert( pPager->pWal==0 || rc==SQLITE_OK );
5179 #endif
5182 if( pagerUseWal(pPager) ){
5183 assert( rc==SQLITE_OK );
5184 rc = pagerBeginReadTransaction(pPager);
5187 if( pPager->eState==PAGER_OPEN && rc==SQLITE_OK ){
5188 rc = pagerPagecount(pPager, &pPager->dbSize);
5191 failed:
5192 if( rc!=SQLITE_OK ){
5193 assert( !MEMDB );
5194 pager_unlock(pPager);
5195 assert( pPager->eState==PAGER_OPEN );
5196 }else{
5197 pPager->eState = PAGER_READER;
5199 return rc;
5203 ** If the reference count has reached zero, rollback any active
5204 ** transaction and unlock the pager.
5206 ** Except, in locking_mode=EXCLUSIVE when there is nothing to in
5207 ** the rollback journal, the unlock is not performed and there is
5208 ** nothing to rollback, so this routine is a no-op.
5210 static void pagerUnlockIfUnused(Pager *pPager){
5211 if( pPager->nMmapOut==0 && (sqlite3PcacheRefCount(pPager->pPCache)==0) ){
5212 pagerUnlockAndRollback(pPager);
5217 ** Acquire a reference to page number pgno in pager pPager (a page
5218 ** reference has type DbPage*). If the requested reference is
5219 ** successfully obtained, it is copied to *ppPage and SQLITE_OK returned.
5221 ** If the requested page is already in the cache, it is returned.
5222 ** Otherwise, a new page object is allocated and populated with data
5223 ** read from the database file. In some cases, the pcache module may
5224 ** choose not to allocate a new page object and may reuse an existing
5225 ** object with no outstanding references.
5227 ** The extra data appended to a page is always initialized to zeros the
5228 ** first time a page is loaded into memory. If the page requested is
5229 ** already in the cache when this function is called, then the extra
5230 ** data is left as it was when the page object was last used.
5232 ** If the database image is smaller than the requested page or if a
5233 ** non-zero value is passed as the noContent parameter and the
5234 ** requested page is not already stored in the cache, then no
5235 ** actual disk read occurs. In this case the memory image of the
5236 ** page is initialized to all zeros.
5238 ** If noContent is true, it means that we do not care about the contents
5239 ** of the page. This occurs in two scenarios:
5241 ** a) When reading a free-list leaf page from the database, and
5243 ** b) When a savepoint is being rolled back and we need to load
5244 ** a new page into the cache to be filled with the data read
5245 ** from the savepoint journal.
5247 ** If noContent is true, then the data returned is zeroed instead of
5248 ** being read from the database. Additionally, the bits corresponding
5249 ** to pgno in Pager.pInJournal (bitvec of pages already written to the
5250 ** journal file) and the PagerSavepoint.pInSavepoint bitvecs of any open
5251 ** savepoints are set. This means if the page is made writable at any
5252 ** point in the future, using a call to sqlite3PagerWrite(), its contents
5253 ** will not be journaled. This saves IO.
5255 ** The acquisition might fail for several reasons. In all cases,
5256 ** an appropriate error code is returned and *ppPage is set to NULL.
5258 ** See also sqlite3PagerLookup(). Both this routine and Lookup() attempt
5259 ** to find a page in the in-memory cache first. If the page is not already
5260 ** in memory, this routine goes to disk to read it in whereas Lookup()
5261 ** just returns 0. This routine acquires a read-lock the first time it
5262 ** has to go to disk, and could also playback an old journal if necessary.
5263 ** Since Lookup() never goes to disk, it never has to deal with locks
5264 ** or journal files.
5266 int sqlite3PagerAcquire(
5267 Pager *pPager, /* The pager open on the database file */
5268 Pgno pgno, /* Page number to fetch */
5269 DbPage **ppPage, /* Write a pointer to the page here */
5270 int flags /* PAGER_GET_XXX flags */
5272 int rc = SQLITE_OK;
5273 PgHdr *pPg = 0;
5274 u32 iFrame = 0; /* Frame to read from WAL file */
5275 const int noContent = (flags & PAGER_GET_NOCONTENT);
5277 /* It is acceptable to use a read-only (mmap) page for any page except
5278 ** page 1 if there is no write-transaction open or the ACQUIRE_READONLY
5279 ** flag was specified by the caller. And so long as the db is not a
5280 ** temporary or in-memory database. */
5281 const int bMmapOk = (pgno!=1 && USEFETCH(pPager)
5282 && (pPager->eState==PAGER_READER || (flags & PAGER_GET_READONLY))
5283 #ifdef SQLITE_HAS_CODEC
5284 && pPager->xCodec==0
5285 #endif
5288 assert( pPager->eState>=PAGER_READER );
5289 assert( assert_pager_state(pPager) );
5290 assert( noContent==0 || bMmapOk==0 );
5292 if( pgno==0 ){
5293 return SQLITE_CORRUPT_BKPT;
5296 /* If the pager is in the error state, return an error immediately.
5297 ** Otherwise, request the page from the PCache layer. */
5298 if( pPager->errCode!=SQLITE_OK ){
5299 rc = pPager->errCode;
5300 }else{
5301 if( bMmapOk && pagerUseWal(pPager) ){
5302 rc = sqlite3WalFindFrame(pPager->pWal, pgno, &iFrame);
5303 if( rc!=SQLITE_OK ) goto pager_acquire_err;
5306 if( bMmapOk && iFrame==0 ){
5307 void *pData = 0;
5309 rc = sqlite3OsFetch(pPager->fd,
5310 (i64)(pgno-1) * pPager->pageSize, pPager->pageSize, &pData
5313 if( rc==SQLITE_OK && pData ){
5314 if( pPager->eState>PAGER_READER ){
5315 pPg = sqlite3PagerLookup(pPager, pgno);
5317 if( pPg==0 ){
5318 rc = pagerAcquireMapPage(pPager, pgno, pData, &pPg);
5319 }else{
5320 sqlite3OsUnfetch(pPager->fd, (i64)(pgno-1)*pPager->pageSize, pData);
5322 if( pPg ){
5323 assert( rc==SQLITE_OK );
5324 *ppPage = pPg;
5325 return SQLITE_OK;
5328 if( rc!=SQLITE_OK ){
5329 goto pager_acquire_err;
5334 sqlite3_pcache_page *pBase;
5335 pBase = sqlite3PcacheFetch(pPager->pPCache, pgno, 3);
5336 if( pBase==0 ){
5337 rc = sqlite3PcacheFetchStress(pPager->pPCache, pgno, &pBase);
5338 if( rc!=SQLITE_OK ) goto pager_acquire_err;
5340 pPg = *ppPage = sqlite3PcacheFetchFinish(pPager->pPCache, pgno, pBase);
5341 if( pPg==0 ) rc = SQLITE_NOMEM;
5345 if( rc!=SQLITE_OK ){
5346 /* Either the call to sqlite3PcacheFetch() returned an error or the
5347 ** pager was already in the error-state when this function was called.
5348 ** Set pPg to 0 and jump to the exception handler. */
5349 pPg = 0;
5350 goto pager_acquire_err;
5352 assert( (*ppPage)->pgno==pgno );
5353 assert( (*ppPage)->pPager==pPager || (*ppPage)->pPager==0 );
5355 if( (*ppPage)->pPager && !noContent ){
5356 /* In this case the pcache already contains an initialized copy of
5357 ** the page. Return without further ado. */
5358 assert( pgno<=PAGER_MAX_PGNO && pgno!=PAGER_MJ_PGNO(pPager) );
5359 pPager->aStat[PAGER_STAT_HIT]++;
5360 return SQLITE_OK;
5362 }else{
5363 /* The pager cache has created a new page. Its content needs to
5364 ** be initialized. */
5366 pPg = *ppPage;
5367 pPg->pPager = pPager;
5369 /* The maximum page number is 2^31. Return SQLITE_CORRUPT if a page
5370 ** number greater than this, or the unused locking-page, is requested. */
5371 if( pgno>PAGER_MAX_PGNO || pgno==PAGER_MJ_PGNO(pPager) ){
5372 rc = SQLITE_CORRUPT_BKPT;
5373 goto pager_acquire_err;
5376 if( MEMDB || pPager->dbSize<pgno || noContent || !isOpen(pPager->fd) ){
5377 if( pgno>pPager->mxPgno ){
5378 rc = SQLITE_FULL;
5379 goto pager_acquire_err;
5381 if( noContent ){
5382 /* Failure to set the bits in the InJournal bit-vectors is benign.
5383 ** It merely means that we might do some extra work to journal a
5384 ** page that does not need to be journaled. Nevertheless, be sure
5385 ** to test the case where a malloc error occurs while trying to set
5386 ** a bit in a bit vector.
5388 sqlite3BeginBenignMalloc();
5389 if( pgno<=pPager->dbOrigSize ){
5390 TESTONLY( rc = ) sqlite3BitvecSet(pPager->pInJournal, pgno);
5391 testcase( rc==SQLITE_NOMEM );
5393 TESTONLY( rc = ) addToSavepointBitvecs(pPager, pgno);
5394 testcase( rc==SQLITE_NOMEM );
5395 sqlite3EndBenignMalloc();
5397 memset(pPg->pData, 0, pPager->pageSize);
5398 IOTRACE(("ZERO %p %d\n", pPager, pgno));
5399 }else{
5400 if( pagerUseWal(pPager) && bMmapOk==0 ){
5401 rc = sqlite3WalFindFrame(pPager->pWal, pgno, &iFrame);
5402 if( rc!=SQLITE_OK ) goto pager_acquire_err;
5404 assert( pPg->pPager==pPager );
5405 pPager->aStat[PAGER_STAT_MISS]++;
5406 rc = readDbPage(pPg, iFrame);
5407 if( rc!=SQLITE_OK ){
5408 goto pager_acquire_err;
5411 pager_set_pagehash(pPg);
5414 return SQLITE_OK;
5416 pager_acquire_err:
5417 assert( rc!=SQLITE_OK );
5418 if( pPg ){
5419 sqlite3PcacheDrop(pPg);
5421 pagerUnlockIfUnused(pPager);
5423 *ppPage = 0;
5424 return rc;
5428 ** Acquire a page if it is already in the in-memory cache. Do
5429 ** not read the page from disk. Return a pointer to the page,
5430 ** or 0 if the page is not in cache.
5432 ** See also sqlite3PagerGet(). The difference between this routine
5433 ** and sqlite3PagerGet() is that _get() will go to the disk and read
5434 ** in the page if the page is not already in cache. This routine
5435 ** returns NULL if the page is not in cache or if a disk I/O error
5436 ** has ever happened.
5438 DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno){
5439 sqlite3_pcache_page *pPage;
5440 assert( pPager!=0 );
5441 assert( pgno!=0 );
5442 assert( pPager->pPCache!=0 );
5443 pPage = sqlite3PcacheFetch(pPager->pPCache, pgno, 0);
5444 return sqlite3PcacheFetchFinish(pPager->pPCache, pgno, pPage);
5448 ** Release a page reference.
5450 ** If the number of references to the page drop to zero, then the
5451 ** page is added to the LRU list. When all references to all pages
5452 ** are released, a rollback occurs and the lock on the database is
5453 ** removed.
5455 void sqlite3PagerUnrefNotNull(DbPage *pPg){
5456 Pager *pPager;
5457 assert( pPg!=0 );
5458 pPager = pPg->pPager;
5459 if( pPg->flags & PGHDR_MMAP ){
5460 pagerReleaseMapPage(pPg);
5461 }else{
5462 sqlite3PcacheRelease(pPg);
5464 pagerUnlockIfUnused(pPager);
5466 void sqlite3PagerUnref(DbPage *pPg){
5467 if( pPg ) sqlite3PagerUnrefNotNull(pPg);
5471 ** This function is called at the start of every write transaction.
5472 ** There must already be a RESERVED or EXCLUSIVE lock on the database
5473 ** file when this routine is called.
5475 ** Open the journal file for pager pPager and write a journal header
5476 ** to the start of it. If there are active savepoints, open the sub-journal
5477 ** as well. This function is only used when the journal file is being
5478 ** opened to write a rollback log for a transaction. It is not used
5479 ** when opening a hot journal file to roll it back.
5481 ** If the journal file is already open (as it may be in exclusive mode),
5482 ** then this function just writes a journal header to the start of the
5483 ** already open file.
5485 ** Whether or not the journal file is opened by this function, the
5486 ** Pager.pInJournal bitvec structure is allocated.
5488 ** Return SQLITE_OK if everything is successful. Otherwise, return
5489 ** SQLITE_NOMEM if the attempt to allocate Pager.pInJournal fails, or
5490 ** an IO error code if opening or writing the journal file fails.
5492 static int pager_open_journal(Pager *pPager){
5493 int rc = SQLITE_OK; /* Return code */
5494 sqlite3_vfs * const pVfs = pPager->pVfs; /* Local cache of vfs pointer */
5496 assert( pPager->eState==PAGER_WRITER_LOCKED );
5497 assert( assert_pager_state(pPager) );
5498 assert( pPager->pInJournal==0 );
5500 /* If already in the error state, this function is a no-op. But on
5501 ** the other hand, this routine is never called if we are already in
5502 ** an error state. */
5503 if( NEVER(pPager->errCode) ) return pPager->errCode;
5505 if( !pagerUseWal(pPager) && pPager->journalMode!=PAGER_JOURNALMODE_OFF ){
5506 pPager->pInJournal = sqlite3BitvecCreate(pPager->dbSize);
5507 if( pPager->pInJournal==0 ){
5508 return SQLITE_NOMEM;
5511 /* Open the journal file if it is not already open. */
5512 if( !isOpen(pPager->jfd) ){
5513 if( pPager->journalMode==PAGER_JOURNALMODE_MEMORY ){
5514 sqlite3MemJournalOpen(pPager->jfd);
5515 }else{
5516 const int flags = /* VFS flags to open journal file */
5517 SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE|
5518 (pPager->tempFile ?
5519 (SQLITE_OPEN_DELETEONCLOSE|SQLITE_OPEN_TEMP_JOURNAL):
5520 (SQLITE_OPEN_MAIN_JOURNAL)
5523 /* Verify that the database still has the same name as it did when
5524 ** it was originally opened. */
5525 rc = databaseIsUnmoved(pPager);
5526 if( rc==SQLITE_OK ){
5527 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
5528 rc = sqlite3JournalOpen(
5529 pVfs, pPager->zJournal, pPager->jfd, flags, jrnlBufferSize(pPager)
5531 #else
5532 rc = sqlite3OsOpen(pVfs, pPager->zJournal, pPager->jfd, flags, 0);
5533 #endif
5536 assert( rc!=SQLITE_OK || isOpen(pPager->jfd) );
5540 /* Write the first journal header to the journal file and open
5541 ** the sub-journal if necessary.
5543 if( rc==SQLITE_OK ){
5544 /* TODO: Check if all of these are really required. */
5545 pPager->nRec = 0;
5546 pPager->journalOff = 0;
5547 pPager->setMaster = 0;
5548 pPager->journalHdr = 0;
5549 rc = writeJournalHdr(pPager);
5553 if( rc!=SQLITE_OK ){
5554 sqlite3BitvecDestroy(pPager->pInJournal);
5555 pPager->pInJournal = 0;
5556 }else{
5557 assert( pPager->eState==PAGER_WRITER_LOCKED );
5558 pPager->eState = PAGER_WRITER_CACHEMOD;
5561 return rc;
5565 ** Begin a write-transaction on the specified pager object. If a
5566 ** write-transaction has already been opened, this function is a no-op.
5568 ** If the exFlag argument is false, then acquire at least a RESERVED
5569 ** lock on the database file. If exFlag is true, then acquire at least
5570 ** an EXCLUSIVE lock. If such a lock is already held, no locking
5571 ** functions need be called.
5573 ** If the subjInMemory argument is non-zero, then any sub-journal opened
5574 ** within this transaction will be opened as an in-memory file. This
5575 ** has no effect if the sub-journal is already opened (as it may be when
5576 ** running in exclusive mode) or if the transaction does not require a
5577 ** sub-journal. If the subjInMemory argument is zero, then any required
5578 ** sub-journal is implemented in-memory if pPager is an in-memory database,
5579 ** or using a temporary file otherwise.
5581 int sqlite3PagerBegin(Pager *pPager, int exFlag, int subjInMemory){
5582 int rc = SQLITE_OK;
5584 if( pPager->errCode ) return pPager->errCode;
5585 assert( pPager->eState>=PAGER_READER && pPager->eState<PAGER_ERROR );
5586 pPager->subjInMemory = (u8)subjInMemory;
5588 if( ALWAYS(pPager->eState==PAGER_READER) ){
5589 assert( pPager->pInJournal==0 );
5591 if( pagerUseWal(pPager) ){
5592 /* If the pager is configured to use locking_mode=exclusive, and an
5593 ** exclusive lock on the database is not already held, obtain it now.
5595 if( pPager->exclusiveMode && sqlite3WalExclusiveMode(pPager->pWal, -1) ){
5596 rc = pagerLockDb(pPager, EXCLUSIVE_LOCK);
5597 if( rc!=SQLITE_OK ){
5598 return rc;
5600 sqlite3WalExclusiveMode(pPager->pWal, 1);
5603 /* Grab the write lock on the log file. If successful, upgrade to
5604 ** PAGER_RESERVED state. Otherwise, return an error code to the caller.
5605 ** The busy-handler is not invoked if another connection already
5606 ** holds the write-lock. If possible, the upper layer will call it.
5608 rc = sqlite3WalBeginWriteTransaction(pPager->pWal);
5609 }else{
5610 /* Obtain a RESERVED lock on the database file. If the exFlag parameter
5611 ** is true, then immediately upgrade this to an EXCLUSIVE lock. The
5612 ** busy-handler callback can be used when upgrading to the EXCLUSIVE
5613 ** lock, but not when obtaining the RESERVED lock.
5615 rc = pagerLockDb(pPager, RESERVED_LOCK);
5616 if( rc==SQLITE_OK && exFlag ){
5617 rc = pager_wait_on_lock(pPager, EXCLUSIVE_LOCK);
5621 if( rc==SQLITE_OK ){
5622 /* Change to WRITER_LOCKED state.
5624 ** WAL mode sets Pager.eState to PAGER_WRITER_LOCKED or CACHEMOD
5625 ** when it has an open transaction, but never to DBMOD or FINISHED.
5626 ** This is because in those states the code to roll back savepoint
5627 ** transactions may copy data from the sub-journal into the database
5628 ** file as well as into the page cache. Which would be incorrect in
5629 ** WAL mode.
5631 pPager->eState = PAGER_WRITER_LOCKED;
5632 pPager->dbHintSize = pPager->dbSize;
5633 pPager->dbFileSize = pPager->dbSize;
5634 pPager->dbOrigSize = pPager->dbSize;
5635 pPager->journalOff = 0;
5638 assert( rc==SQLITE_OK || pPager->eState==PAGER_READER );
5639 assert( rc!=SQLITE_OK || pPager->eState==PAGER_WRITER_LOCKED );
5640 assert( assert_pager_state(pPager) );
5643 PAGERTRACE(("TRANSACTION %d\n", PAGERID(pPager)));
5644 return rc;
5648 ** Mark a single data page as writeable. The page is written into the
5649 ** main journal or sub-journal as required. If the page is written into
5650 ** one of the journals, the corresponding bit is set in the
5651 ** Pager.pInJournal bitvec and the PagerSavepoint.pInSavepoint bitvecs
5652 ** of any open savepoints as appropriate.
5654 static int pager_write(PgHdr *pPg){
5655 Pager *pPager = pPg->pPager;
5656 int rc = SQLITE_OK;
5657 int inJournal;
5659 /* This routine is not called unless a write-transaction has already
5660 ** been started. The journal file may or may not be open at this point.
5661 ** It is never called in the ERROR state.
5663 assert( pPager->eState==PAGER_WRITER_LOCKED
5664 || pPager->eState==PAGER_WRITER_CACHEMOD
5665 || pPager->eState==PAGER_WRITER_DBMOD
5667 assert( assert_pager_state(pPager) );
5668 assert( pPager->errCode==0 );
5669 assert( pPager->readOnly==0 );
5671 CHECK_PAGE(pPg);
5673 /* The journal file needs to be opened. Higher level routines have already
5674 ** obtained the necessary locks to begin the write-transaction, but the
5675 ** rollback journal might not yet be open. Open it now if this is the case.
5677 ** This is done before calling sqlite3PcacheMakeDirty() on the page.
5678 ** Otherwise, if it were done after calling sqlite3PcacheMakeDirty(), then
5679 ** an error might occur and the pager would end up in WRITER_LOCKED state
5680 ** with pages marked as dirty in the cache.
5682 if( pPager->eState==PAGER_WRITER_LOCKED ){
5683 rc = pager_open_journal(pPager);
5684 if( rc!=SQLITE_OK ) return rc;
5686 assert( pPager->eState>=PAGER_WRITER_CACHEMOD );
5687 assert( assert_pager_state(pPager) );
5689 /* Mark the page as dirty. If the page has already been written
5690 ** to the journal then we can return right away.
5692 sqlite3PcacheMakeDirty(pPg);
5693 inJournal = pageInJournal(pPager, pPg);
5694 if( inJournal && (pPager->nSavepoint==0 || !subjRequiresPage(pPg)) ){
5695 assert( !pagerUseWal(pPager) );
5696 }else{
5698 /* The transaction journal now exists and we have a RESERVED or an
5699 ** EXCLUSIVE lock on the main database file. Write the current page to
5700 ** the transaction journal if it is not there already.
5702 if( !inJournal && !pagerUseWal(pPager) ){
5703 assert( pagerUseWal(pPager)==0 );
5704 if( pPg->pgno<=pPager->dbOrigSize && isOpen(pPager->jfd) ){
5705 u32 cksum;
5706 char *pData2;
5707 i64 iOff = pPager->journalOff;
5709 /* We should never write to the journal file the page that
5710 ** contains the database locks. The following assert verifies
5711 ** that we do not. */
5712 assert( pPg->pgno!=PAGER_MJ_PGNO(pPager) );
5714 assert( pPager->journalHdr<=pPager->journalOff );
5715 CODEC2(pPager, pPg->pData, pPg->pgno, 7, return SQLITE_NOMEM, pData2);
5716 cksum = pager_cksum(pPager, (u8*)pData2);
5718 /* Even if an IO or diskfull error occurs while journalling the
5719 ** page in the block above, set the need-sync flag for the page.
5720 ** Otherwise, when the transaction is rolled back, the logic in
5721 ** playback_one_page() will think that the page needs to be restored
5722 ** in the database file. And if an IO error occurs while doing so,
5723 ** then corruption may follow.
5725 pPg->flags |= PGHDR_NEED_SYNC;
5727 rc = write32bits(pPager->jfd, iOff, pPg->pgno);
5728 if( rc!=SQLITE_OK ) return rc;
5729 rc = sqlite3OsWrite(pPager->jfd, pData2, pPager->pageSize, iOff+4);
5730 if( rc!=SQLITE_OK ) return rc;
5731 rc = write32bits(pPager->jfd, iOff+pPager->pageSize+4, cksum);
5732 if( rc!=SQLITE_OK ) return rc;
5734 IOTRACE(("JOUT %p %d %lld %d\n", pPager, pPg->pgno,
5735 pPager->journalOff, pPager->pageSize));
5736 PAGER_INCR(sqlite3_pager_writej_count);
5737 PAGERTRACE(("JOURNAL %d page %d needSync=%d hash(%08x)\n",
5738 PAGERID(pPager), pPg->pgno,
5739 ((pPg->flags&PGHDR_NEED_SYNC)?1:0), pager_pagehash(pPg)));
5741 pPager->journalOff += 8 + pPager->pageSize;
5742 pPager->nRec++;
5743 assert( pPager->pInJournal!=0 );
5744 rc = sqlite3BitvecSet(pPager->pInJournal, pPg->pgno);
5745 testcase( rc==SQLITE_NOMEM );
5746 assert( rc==SQLITE_OK || rc==SQLITE_NOMEM );
5747 rc |= addToSavepointBitvecs(pPager, pPg->pgno);
5748 if( rc!=SQLITE_OK ){
5749 assert( rc==SQLITE_NOMEM );
5750 return rc;
5752 }else{
5753 if( pPager->eState!=PAGER_WRITER_DBMOD ){
5754 pPg->flags |= PGHDR_NEED_SYNC;
5756 PAGERTRACE(("APPEND %d page %d needSync=%d\n",
5757 PAGERID(pPager), pPg->pgno,
5758 ((pPg->flags&PGHDR_NEED_SYNC)?1:0)));
5762 /* If the statement journal is open and the page is not in it,
5763 ** then write the current page to the statement journal. Note that
5764 ** the statement journal format differs from the standard journal format
5765 ** in that it omits the checksums and the header.
5767 if( pPager->nSavepoint>0 && subjRequiresPage(pPg) ){
5768 rc = subjournalPage(pPg);
5772 /* Update the database size and return.
5774 if( pPager->dbSize<pPg->pgno ){
5775 pPager->dbSize = pPg->pgno;
5777 return rc;
5781 ** This is a variant of sqlite3PagerWrite() that runs when the sector size
5782 ** is larger than the page size. SQLite makes the (reasonable) assumption that
5783 ** all bytes of a sector are written together by hardware. Hence, all bytes of
5784 ** a sector need to be journalled in case of a power loss in the middle of
5785 ** a write.
5787 ** Usually, the sector size is less than or equal to the page size, in which
5788 ** case pages can be individually written. This routine only runs in the exceptional
5789 ** case where the page size is smaller than the sector size.
5791 static SQLITE_NOINLINE int pagerWriteLargeSector(PgHdr *pPg){
5792 int rc = SQLITE_OK; /* Return code */
5793 Pgno nPageCount; /* Total number of pages in database file */
5794 Pgno pg1; /* First page of the sector pPg is located on. */
5795 int nPage = 0; /* Number of pages starting at pg1 to journal */
5796 int ii; /* Loop counter */
5797 int needSync = 0; /* True if any page has PGHDR_NEED_SYNC */
5798 Pager *pPager = pPg->pPager; /* The pager that owns pPg */
5799 Pgno nPagePerSector = (pPager->sectorSize/pPager->pageSize);
5801 /* Set the doNotSpill NOSYNC bit to 1. This is because we cannot allow
5802 ** a journal header to be written between the pages journaled by
5803 ** this function.
5805 assert( !MEMDB );
5806 assert( (pPager->doNotSpill & SPILLFLAG_NOSYNC)==0 );
5807 pPager->doNotSpill |= SPILLFLAG_NOSYNC;
5809 /* This trick assumes that both the page-size and sector-size are
5810 ** an integer power of 2. It sets variable pg1 to the identifier
5811 ** of the first page of the sector pPg is located on.
5813 pg1 = ((pPg->pgno-1) & ~(nPagePerSector-1)) + 1;
5815 nPageCount = pPager->dbSize;
5816 if( pPg->pgno>nPageCount ){
5817 nPage = (pPg->pgno - pg1)+1;
5818 }else if( (pg1+nPagePerSector-1)>nPageCount ){
5819 nPage = nPageCount+1-pg1;
5820 }else{
5821 nPage = nPagePerSector;
5823 assert(nPage>0);
5824 assert(pg1<=pPg->pgno);
5825 assert((pg1+nPage)>pPg->pgno);
5827 for(ii=0; ii<nPage && rc==SQLITE_OK; ii++){
5828 Pgno pg = pg1+ii;
5829 PgHdr *pPage;
5830 if( pg==pPg->pgno || !sqlite3BitvecTest(pPager->pInJournal, pg) ){
5831 if( pg!=PAGER_MJ_PGNO(pPager) ){
5832 rc = sqlite3PagerGet(pPager, pg, &pPage);
5833 if( rc==SQLITE_OK ){
5834 rc = pager_write(pPage);
5835 if( pPage->flags&PGHDR_NEED_SYNC ){
5836 needSync = 1;
5838 sqlite3PagerUnrefNotNull(pPage);
5841 }else if( (pPage = sqlite3PagerLookup(pPager, pg))!=0 ){
5842 if( pPage->flags&PGHDR_NEED_SYNC ){
5843 needSync = 1;
5845 sqlite3PagerUnrefNotNull(pPage);
5849 /* If the PGHDR_NEED_SYNC flag is set for any of the nPage pages
5850 ** starting at pg1, then it needs to be set for all of them. Because
5851 ** writing to any of these nPage pages may damage the others, the
5852 ** journal file must contain sync()ed copies of all of them
5853 ** before any of them can be written out to the database file.
5855 if( rc==SQLITE_OK && needSync ){
5856 assert( !MEMDB );
5857 for(ii=0; ii<nPage; ii++){
5858 PgHdr *pPage = sqlite3PagerLookup(pPager, pg1+ii);
5859 if( pPage ){
5860 pPage->flags |= PGHDR_NEED_SYNC;
5861 sqlite3PagerUnrefNotNull(pPage);
5866 assert( (pPager->doNotSpill & SPILLFLAG_NOSYNC)!=0 );
5867 pPager->doNotSpill &= ~SPILLFLAG_NOSYNC;
5868 return rc;
5872 ** Mark a data page as writeable. This routine must be called before
5873 ** making changes to a page. The caller must check the return value
5874 ** of this function and be careful not to change any page data unless
5875 ** this routine returns SQLITE_OK.
5877 ** The difference between this function and pager_write() is that this
5878 ** function also deals with the special case where 2 or more pages
5879 ** fit on a single disk sector. In this case all co-resident pages
5880 ** must have been written to the journal file before returning.
5882 ** If an error occurs, SQLITE_NOMEM or an IO error code is returned
5883 ** as appropriate. Otherwise, SQLITE_OK.
5885 int sqlite3PagerWrite(PgHdr *pPg){
5886 assert( (pPg->flags & PGHDR_MMAP)==0 );
5887 assert( pPg->pPager->eState>=PAGER_WRITER_LOCKED );
5888 assert( pPg->pPager->eState!=PAGER_ERROR );
5889 assert( assert_pager_state(pPg->pPager) );
5890 if( pPg->pPager->sectorSize > (u32)pPg->pPager->pageSize ){
5891 return pagerWriteLargeSector(pPg);
5892 }else{
5893 return pager_write(pPg);
5898 ** Return TRUE if the page given in the argument was previously passed
5899 ** to sqlite3PagerWrite(). In other words, return TRUE if it is ok
5900 ** to change the content of the page.
5902 #ifndef NDEBUG
5903 int sqlite3PagerIswriteable(DbPage *pPg){
5904 return pPg->flags&PGHDR_DIRTY;
5906 #endif
5909 ** A call to this routine tells the pager that it is not necessary to
5910 ** write the information on page pPg back to the disk, even though
5911 ** that page might be marked as dirty. This happens, for example, when
5912 ** the page has been added as a leaf of the freelist and so its
5913 ** content no longer matters.
5915 ** The overlying software layer calls this routine when all of the data
5916 ** on the given page is unused. The pager marks the page as clean so
5917 ** that it does not get written to disk.
5919 ** Tests show that this optimization can quadruple the speed of large
5920 ** DELETE operations.
5922 void sqlite3PagerDontWrite(PgHdr *pPg){
5923 Pager *pPager = pPg->pPager;
5924 if( (pPg->flags&PGHDR_DIRTY) && pPager->nSavepoint==0 ){
5925 PAGERTRACE(("DONT_WRITE page %d of %d\n", pPg->pgno, PAGERID(pPager)));
5926 IOTRACE(("CLEAN %p %d\n", pPager, pPg->pgno))
5927 pPg->flags |= PGHDR_DONT_WRITE;
5928 pager_set_pagehash(pPg);
5933 ** This routine is called to increment the value of the database file
5934 ** change-counter, stored as a 4-byte big-endian integer starting at
5935 ** byte offset 24 of the pager file. The secondary change counter at
5936 ** 92 is also updated, as is the SQLite version number at offset 96.
5938 ** But this only happens if the pPager->changeCountDone flag is false.
5939 ** To avoid excess churning of page 1, the update only happens once.
5940 ** See also the pager_write_changecounter() routine that does an
5941 ** unconditional update of the change counters.
5943 ** If the isDirectMode flag is zero, then this is done by calling
5944 ** sqlite3PagerWrite() on page 1, then modifying the contents of the
5945 ** page data. In this case the file will be updated when the current
5946 ** transaction is committed.
5948 ** The isDirectMode flag may only be non-zero if the library was compiled
5949 ** with the SQLITE_ENABLE_ATOMIC_WRITE macro defined. In this case,
5950 ** if isDirect is non-zero, then the database file is updated directly
5951 ** by writing an updated version of page 1 using a call to the
5952 ** sqlite3OsWrite() function.
5954 static int pager_incr_changecounter(Pager *pPager, int isDirectMode){
5955 int rc = SQLITE_OK;
5957 assert( pPager->eState==PAGER_WRITER_CACHEMOD
5958 || pPager->eState==PAGER_WRITER_DBMOD
5960 assert( assert_pager_state(pPager) );
5962 /* Declare and initialize constant integer 'isDirect'. If the
5963 ** atomic-write optimization is enabled in this build, then isDirect
5964 ** is initialized to the value passed as the isDirectMode parameter
5965 ** to this function. Otherwise, it is always set to zero.
5967 ** The idea is that if the atomic-write optimization is not
5968 ** enabled at compile time, the compiler can omit the tests of
5969 ** 'isDirect' below, as well as the block enclosed in the
5970 ** "if( isDirect )" condition.
5972 #ifndef SQLITE_ENABLE_ATOMIC_WRITE
5973 # define DIRECT_MODE 0
5974 assert( isDirectMode==0 );
5975 UNUSED_PARAMETER(isDirectMode);
5976 #else
5977 # define DIRECT_MODE isDirectMode
5978 #endif
5980 if( !pPager->changeCountDone && ALWAYS(pPager->dbSize>0) ){
5981 PgHdr *pPgHdr; /* Reference to page 1 */
5983 assert( !pPager->tempFile && isOpen(pPager->fd) );
5985 /* Open page 1 of the file for writing. */
5986 rc = sqlite3PagerGet(pPager, 1, &pPgHdr);
5987 assert( pPgHdr==0 || rc==SQLITE_OK );
5989 /* If page one was fetched successfully, and this function is not
5990 ** operating in direct-mode, make page 1 writable. When not in
5991 ** direct mode, page 1 is always held in cache and hence the PagerGet()
5992 ** above is always successful - hence the ALWAYS on rc==SQLITE_OK.
5994 if( !DIRECT_MODE && ALWAYS(rc==SQLITE_OK) ){
5995 rc = sqlite3PagerWrite(pPgHdr);
5998 if( rc==SQLITE_OK ){
5999 /* Actually do the update of the change counter */
6000 pager_write_changecounter(pPgHdr);
6002 /* If running in direct mode, write the contents of page 1 to the file. */
6003 if( DIRECT_MODE ){
6004 const void *zBuf;
6005 assert( pPager->dbFileSize>0 );
6006 CODEC2(pPager, pPgHdr->pData, 1, 6, rc=SQLITE_NOMEM, zBuf);
6007 if( rc==SQLITE_OK ){
6008 rc = sqlite3OsWrite(pPager->fd, zBuf, pPager->pageSize, 0);
6009 pPager->aStat[PAGER_STAT_WRITE]++;
6011 if( rc==SQLITE_OK ){
6012 /* Update the pager's copy of the change-counter. Otherwise, the
6013 ** next time a read transaction is opened the cache will be
6014 ** flushed (as the change-counter values will not match). */
6015 const void *pCopy = (const void *)&((const char *)zBuf)[24];
6016 memcpy(&pPager->dbFileVers, pCopy, sizeof(pPager->dbFileVers));
6017 pPager->changeCountDone = 1;
6019 }else{
6020 pPager->changeCountDone = 1;
6024 /* Release the page reference. */
6025 sqlite3PagerUnref(pPgHdr);
6027 return rc;
6031 ** Sync the database file to disk. This is a no-op for in-memory databases
6032 ** or pages with the Pager.noSync flag set.
6034 ** If successful, or if called on a pager for which it is a no-op, this
6035 ** function returns SQLITE_OK. Otherwise, an IO error code is returned.
6037 int sqlite3PagerSync(Pager *pPager, const char *zMaster){
6038 int rc = SQLITE_OK;
6040 if( isOpen(pPager->fd) ){
6041 void *pArg = (void*)zMaster;
6042 rc = sqlite3OsFileControl(pPager->fd, SQLITE_FCNTL_SYNC, pArg);
6043 if( rc==SQLITE_NOTFOUND ) rc = SQLITE_OK;
6045 if( rc==SQLITE_OK && !pPager->noSync ){
6046 assert( !MEMDB );
6047 rc = sqlite3OsSync(pPager->fd, pPager->syncFlags);
6049 return rc;
6053 ** This function may only be called while a write-transaction is active in
6054 ** rollback. If the connection is in WAL mode, this call is a no-op.
6055 ** Otherwise, if the connection does not already have an EXCLUSIVE lock on
6056 ** the database file, an attempt is made to obtain one.
6058 ** If the EXCLUSIVE lock is already held or the attempt to obtain it is
6059 ** successful, or the connection is in WAL mode, SQLITE_OK is returned.
6060 ** Otherwise, either SQLITE_BUSY or an SQLITE_IOERR_XXX error code is
6061 ** returned.
6063 int sqlite3PagerExclusiveLock(Pager *pPager){
6064 int rc = SQLITE_OK;
6065 assert( pPager->eState==PAGER_WRITER_CACHEMOD
6066 || pPager->eState==PAGER_WRITER_DBMOD
6067 || pPager->eState==PAGER_WRITER_LOCKED
6069 assert( assert_pager_state(pPager) );
6070 if( 0==pagerUseWal(pPager) ){
6071 rc = pager_wait_on_lock(pPager, EXCLUSIVE_LOCK);
6073 return rc;
6077 ** Sync the database file for the pager pPager. zMaster points to the name
6078 ** of a master journal file that should be written into the individual
6079 ** journal file. zMaster may be NULL, which is interpreted as no master
6080 ** journal (a single database transaction).
6082 ** This routine ensures that:
6084 ** * The database file change-counter is updated,
6085 ** * the journal is synced (unless the atomic-write optimization is used),
6086 ** * all dirty pages are written to the database file,
6087 ** * the database file is truncated (if required), and
6088 ** * the database file synced.
6090 ** The only thing that remains to commit the transaction is to finalize
6091 ** (delete, truncate or zero the first part of) the journal file (or
6092 ** delete the master journal file if specified).
6094 ** Note that if zMaster==NULL, this does not overwrite a previous value
6095 ** passed to an sqlite3PagerCommitPhaseOne() call.
6097 ** If the final parameter - noSync - is true, then the database file itself
6098 ** is not synced. The caller must call sqlite3PagerSync() directly to
6099 ** sync the database file before calling CommitPhaseTwo() to delete the
6100 ** journal file in this case.
6102 int sqlite3PagerCommitPhaseOne(
6103 Pager *pPager, /* Pager object */
6104 const char *zMaster, /* If not NULL, the master journal name */
6105 int noSync /* True to omit the xSync on the db file */
6107 int rc = SQLITE_OK; /* Return code */
6109 assert( pPager->eState==PAGER_WRITER_LOCKED
6110 || pPager->eState==PAGER_WRITER_CACHEMOD
6111 || pPager->eState==PAGER_WRITER_DBMOD
6112 || pPager->eState==PAGER_ERROR
6114 assert( assert_pager_state(pPager) );
6116 /* If a prior error occurred, report that error again. */
6117 if( NEVER(pPager->errCode) ) return pPager->errCode;
6119 PAGERTRACE(("DATABASE SYNC: File=%s zMaster=%s nSize=%d\n",
6120 pPager->zFilename, zMaster, pPager->dbSize));
6122 /* If no database changes have been made, return early. */
6123 if( pPager->eState<PAGER_WRITER_CACHEMOD ) return SQLITE_OK;
6125 if( MEMDB ){
6126 /* If this is an in-memory db, or no pages have been written to, or this
6127 ** function has already been called, it is mostly a no-op. However, any
6128 ** backup in progress needs to be restarted.
6130 sqlite3BackupRestart(pPager->pBackup);
6131 }else{
6132 if( pagerUseWal(pPager) ){
6133 PgHdr *pList = sqlite3PcacheDirtyList(pPager->pPCache);
6134 PgHdr *pPageOne = 0;
6135 if( pList==0 ){
6136 /* Must have at least one page for the WAL commit flag.
6137 ** Ticket [2d1a5c67dfc2363e44f29d9bbd57f] 2011-05-18 */
6138 rc = sqlite3PagerGet(pPager, 1, &pPageOne);
6139 pList = pPageOne;
6140 pList->pDirty = 0;
6142 assert( rc==SQLITE_OK );
6143 if( ALWAYS(pList) ){
6144 rc = pagerWalFrames(pPager, pList, pPager->dbSize, 1);
6146 sqlite3PagerUnref(pPageOne);
6147 if( rc==SQLITE_OK ){
6148 sqlite3PcacheCleanAll(pPager->pPCache);
6150 }else{
6151 /* The following block updates the change-counter. Exactly how it
6152 ** does this depends on whether or not the atomic-update optimization
6153 ** was enabled at compile time, and if this transaction meets the
6154 ** runtime criteria to use the operation:
6156 ** * The file-system supports the atomic-write property for
6157 ** blocks of size page-size, and
6158 ** * This commit is not part of a multi-file transaction, and
6159 ** * Exactly one page has been modified and store in the journal file.
6161 ** If the optimization was not enabled at compile time, then the
6162 ** pager_incr_changecounter() function is called to update the change
6163 ** counter in 'indirect-mode'. If the optimization is compiled in but
6164 ** is not applicable to this transaction, call sqlite3JournalCreate()
6165 ** to make sure the journal file has actually been created, then call
6166 ** pager_incr_changecounter() to update the change-counter in indirect
6167 ** mode.
6169 ** Otherwise, if the optimization is both enabled and applicable,
6170 ** then call pager_incr_changecounter() to update the change-counter
6171 ** in 'direct' mode. In this case the journal file will never be
6172 ** created for this transaction.
6174 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
6175 PgHdr *pPg;
6176 assert( isOpen(pPager->jfd)
6177 || pPager->journalMode==PAGER_JOURNALMODE_OFF
6178 || pPager->journalMode==PAGER_JOURNALMODE_WAL
6180 if( !zMaster && isOpen(pPager->jfd)
6181 && pPager->journalOff==jrnlBufferSize(pPager)
6182 && pPager->dbSize>=pPager->dbOrigSize
6183 && (0==(pPg = sqlite3PcacheDirtyList(pPager->pPCache)) || 0==pPg->pDirty)
6185 /* Update the db file change counter via the direct-write method. The
6186 ** following call will modify the in-memory representation of page 1
6187 ** to include the updated change counter and then write page 1
6188 ** directly to the database file. Because of the atomic-write
6189 ** property of the host file-system, this is safe.
6191 rc = pager_incr_changecounter(pPager, 1);
6192 }else{
6193 rc = sqlite3JournalCreate(pPager->jfd);
6194 if( rc==SQLITE_OK ){
6195 rc = pager_incr_changecounter(pPager, 0);
6198 #else
6199 rc = pager_incr_changecounter(pPager, 0);
6200 #endif
6201 if( rc!=SQLITE_OK ) goto commit_phase_one_exit;
6203 /* Write the master journal name into the journal file. If a master
6204 ** journal file name has already been written to the journal file,
6205 ** or if zMaster is NULL (no master journal), then this call is a no-op.
6207 rc = writeMasterJournal(pPager, zMaster);
6208 if( rc!=SQLITE_OK ) goto commit_phase_one_exit;
6210 /* Sync the journal file and write all dirty pages to the database.
6211 ** If the atomic-update optimization is being used, this sync will not
6212 ** create the journal file or perform any real IO.
6214 ** Because the change-counter page was just modified, unless the
6215 ** atomic-update optimization is used it is almost certain that the
6216 ** journal requires a sync here. However, in locking_mode=exclusive
6217 ** on a system under memory pressure it is just possible that this is
6218 ** not the case. In this case it is likely enough that the redundant
6219 ** xSync() call will be changed to a no-op by the OS anyhow.
6221 rc = syncJournal(pPager, 0);
6222 if( rc!=SQLITE_OK ) goto commit_phase_one_exit;
6224 rc = pager_write_pagelist(pPager,sqlite3PcacheDirtyList(pPager->pPCache));
6225 if( rc!=SQLITE_OK ){
6226 assert( rc!=SQLITE_IOERR_BLOCKED );
6227 goto commit_phase_one_exit;
6229 sqlite3PcacheCleanAll(pPager->pPCache);
6231 /* If the file on disk is smaller than the database image, use
6232 ** pager_truncate to grow the file here. This can happen if the database
6233 ** image was extended as part of the current transaction and then the
6234 ** last page in the db image moved to the free-list. In this case the
6235 ** last page is never written out to disk, leaving the database file
6236 ** undersized. Fix this now if it is the case. */
6237 if( pPager->dbSize>pPager->dbFileSize ){
6238 Pgno nNew = pPager->dbSize - (pPager->dbSize==PAGER_MJ_PGNO(pPager));
6239 assert( pPager->eState==PAGER_WRITER_DBMOD );
6240 rc = pager_truncate(pPager, nNew);
6241 if( rc!=SQLITE_OK ) goto commit_phase_one_exit;
6244 /* Finally, sync the database file. */
6245 if( !noSync ){
6246 rc = sqlite3PagerSync(pPager, zMaster);
6248 IOTRACE(("DBSYNC %p\n", pPager))
6252 commit_phase_one_exit:
6253 if( rc==SQLITE_OK && !pagerUseWal(pPager) ){
6254 pPager->eState = PAGER_WRITER_FINISHED;
6256 return rc;
6261 ** When this function is called, the database file has been completely
6262 ** updated to reflect the changes made by the current transaction and
6263 ** synced to disk. The journal file still exists in the file-system
6264 ** though, and if a failure occurs at this point it will eventually
6265 ** be used as a hot-journal and the current transaction rolled back.
6267 ** This function finalizes the journal file, either by deleting,
6268 ** truncating or partially zeroing it, so that it cannot be used
6269 ** for hot-journal rollback. Once this is done the transaction is
6270 ** irrevocably committed.
6272 ** If an error occurs, an IO error code is returned and the pager
6273 ** moves into the error state. Otherwise, SQLITE_OK is returned.
6275 int sqlite3PagerCommitPhaseTwo(Pager *pPager){
6276 int rc = SQLITE_OK; /* Return code */
6278 /* This routine should not be called if a prior error has occurred.
6279 ** But if (due to a coding error elsewhere in the system) it does get
6280 ** called, just return the same error code without doing anything. */
6281 if( NEVER(pPager->errCode) ) return pPager->errCode;
6283 assert( pPager->eState==PAGER_WRITER_LOCKED
6284 || pPager->eState==PAGER_WRITER_FINISHED
6285 || (pagerUseWal(pPager) && pPager->eState==PAGER_WRITER_CACHEMOD)
6287 assert( assert_pager_state(pPager) );
6289 /* An optimization. If the database was not actually modified during
6290 ** this transaction, the pager is running in exclusive-mode and is
6291 ** using persistent journals, then this function is a no-op.
6293 ** The start of the journal file currently contains a single journal
6294 ** header with the nRec field set to 0. If such a journal is used as
6295 ** a hot-journal during hot-journal rollback, 0 changes will be made
6296 ** to the database file. So there is no need to zero the journal
6297 ** header. Since the pager is in exclusive mode, there is no need
6298 ** to drop any locks either.
6300 if( pPager->eState==PAGER_WRITER_LOCKED
6301 && pPager->exclusiveMode
6302 && pPager->journalMode==PAGER_JOURNALMODE_PERSIST
6304 assert( pPager->journalOff==JOURNAL_HDR_SZ(pPager) || !pPager->journalOff );
6305 pPager->eState = PAGER_READER;
6306 return SQLITE_OK;
6309 PAGERTRACE(("COMMIT %d\n", PAGERID(pPager)));
6310 rc = pager_end_transaction(pPager, pPager->setMaster, 1);
6311 return pager_error(pPager, rc);
6315 ** If a write transaction is open, then all changes made within the
6316 ** transaction are reverted and the current write-transaction is closed.
6317 ** The pager falls back to PAGER_READER state if successful, or PAGER_ERROR
6318 ** state if an error occurs.
6320 ** If the pager is already in PAGER_ERROR state when this function is called,
6321 ** it returns Pager.errCode immediately. No work is performed in this case.
6323 ** Otherwise, in rollback mode, this function performs two functions:
6325 ** 1) It rolls back the journal file, restoring all database file and
6326 ** in-memory cache pages to the state they were in when the transaction
6327 ** was opened, and
6329 ** 2) It finalizes the journal file, so that it is not used for hot
6330 ** rollback at any point in the future.
6332 ** Finalization of the journal file (task 2) is only performed if the
6333 ** rollback is successful.
6335 ** In WAL mode, all cache-entries containing data modified within the
6336 ** current transaction are either expelled from the cache or reverted to
6337 ** their pre-transaction state by re-reading data from the database or
6338 ** WAL files. The WAL transaction is then closed.
6340 int sqlite3PagerRollback(Pager *pPager){
6341 int rc = SQLITE_OK; /* Return code */
6342 PAGERTRACE(("ROLLBACK %d\n", PAGERID(pPager)));
6344 /* PagerRollback() is a no-op if called in READER or OPEN state. If
6345 ** the pager is already in the ERROR state, the rollback is not
6346 ** attempted here. Instead, the error code is returned to the caller.
6348 assert( assert_pager_state(pPager) );
6349 if( pPager->eState==PAGER_ERROR ) return pPager->errCode;
6350 if( pPager->eState<=PAGER_READER ) return SQLITE_OK;
6352 if( pagerUseWal(pPager) ){
6353 int rc2;
6354 rc = sqlite3PagerSavepoint(pPager, SAVEPOINT_ROLLBACK, -1);
6355 rc2 = pager_end_transaction(pPager, pPager->setMaster, 0);
6356 if( rc==SQLITE_OK ) rc = rc2;
6357 }else if( !isOpen(pPager->jfd) || pPager->eState==PAGER_WRITER_LOCKED ){
6358 int eState = pPager->eState;
6359 rc = pager_end_transaction(pPager, 0, 0);
6360 if( !MEMDB && eState>PAGER_WRITER_LOCKED ){
6361 /* This can happen using journal_mode=off. Move the pager to the error
6362 ** state to indicate that the contents of the cache may not be trusted.
6363 ** Any active readers will get SQLITE_ABORT.
6365 pPager->errCode = SQLITE_ABORT;
6366 pPager->eState = PAGER_ERROR;
6367 return rc;
6369 }else{
6370 rc = pager_playback(pPager, 0);
6373 assert( pPager->eState==PAGER_READER || rc!=SQLITE_OK );
6374 assert( rc==SQLITE_OK || rc==SQLITE_FULL || rc==SQLITE_CORRUPT
6375 || rc==SQLITE_NOMEM || (rc&0xFF)==SQLITE_IOERR
6376 || rc==SQLITE_CANTOPEN
6379 /* If an error occurs during a ROLLBACK, we can no longer trust the pager
6380 ** cache. So call pager_error() on the way out to make any error persistent.
6382 return pager_error(pPager, rc);
6386 ** Return TRUE if the database file is opened read-only. Return FALSE
6387 ** if the database is (in theory) writable.
6389 u8 sqlite3PagerIsreadonly(Pager *pPager){
6390 return pPager->readOnly;
6394 ** Return the number of references to the pager.
6396 int sqlite3PagerRefcount(Pager *pPager){
6397 return sqlite3PcacheRefCount(pPager->pPCache);
6401 ** Return the approximate number of bytes of memory currently
6402 ** used by the pager and its associated cache.
6404 int sqlite3PagerMemUsed(Pager *pPager){
6405 int perPageSize = pPager->pageSize + pPager->nExtra + sizeof(PgHdr)
6406 + 5*sizeof(void*);
6407 return perPageSize*sqlite3PcachePagecount(pPager->pPCache)
6408 + sqlite3MallocSize(pPager)
6409 + pPager->pageSize;
6413 ** Return the number of references to the specified page.
6415 int sqlite3PagerPageRefcount(DbPage *pPage){
6416 return sqlite3PcachePageRefcount(pPage);
6419 #ifdef SQLITE_TEST
6421 ** This routine is used for testing and analysis only.
6423 int *sqlite3PagerStats(Pager *pPager){
6424 static int a[11];
6425 a[0] = sqlite3PcacheRefCount(pPager->pPCache);
6426 a[1] = sqlite3PcachePagecount(pPager->pPCache);
6427 a[2] = sqlite3PcacheGetCachesize(pPager->pPCache);
6428 a[3] = pPager->eState==PAGER_OPEN ? -1 : (int) pPager->dbSize;
6429 a[4] = pPager->eState;
6430 a[5] = pPager->errCode;
6431 a[6] = pPager->aStat[PAGER_STAT_HIT];
6432 a[7] = pPager->aStat[PAGER_STAT_MISS];
6433 a[8] = 0; /* Used to be pPager->nOvfl */
6434 a[9] = pPager->nRead;
6435 a[10] = pPager->aStat[PAGER_STAT_WRITE];
6436 return a;
6438 #endif
6441 ** Parameter eStat must be either SQLITE_DBSTATUS_CACHE_HIT or
6442 ** SQLITE_DBSTATUS_CACHE_MISS. Before returning, *pnVal is incremented by the
6443 ** current cache hit or miss count, according to the value of eStat. If the
6444 ** reset parameter is non-zero, the cache hit or miss count is zeroed before
6445 ** returning.
6447 void sqlite3PagerCacheStat(Pager *pPager, int eStat, int reset, int *pnVal){
6449 assert( eStat==SQLITE_DBSTATUS_CACHE_HIT
6450 || eStat==SQLITE_DBSTATUS_CACHE_MISS
6451 || eStat==SQLITE_DBSTATUS_CACHE_WRITE
6454 assert( SQLITE_DBSTATUS_CACHE_HIT+1==SQLITE_DBSTATUS_CACHE_MISS );
6455 assert( SQLITE_DBSTATUS_CACHE_HIT+2==SQLITE_DBSTATUS_CACHE_WRITE );
6456 assert( PAGER_STAT_HIT==0 && PAGER_STAT_MISS==1 && PAGER_STAT_WRITE==2 );
6458 *pnVal += pPager->aStat[eStat - SQLITE_DBSTATUS_CACHE_HIT];
6459 if( reset ){
6460 pPager->aStat[eStat - SQLITE_DBSTATUS_CACHE_HIT] = 0;
6465 ** Return true if this is an in-memory pager.
6467 int sqlite3PagerIsMemdb(Pager *pPager){
6468 return MEMDB;
6472 ** Check that there are at least nSavepoint savepoints open. If there are
6473 ** currently less than nSavepoints open, then open one or more savepoints
6474 ** to make up the difference. If the number of savepoints is already
6475 ** equal to nSavepoint, then this function is a no-op.
6477 ** If a memory allocation fails, SQLITE_NOMEM is returned. If an error
6478 ** occurs while opening the sub-journal file, then an IO error code is
6479 ** returned. Otherwise, SQLITE_OK.
6481 int sqlite3PagerOpenSavepoint(Pager *pPager, int nSavepoint){
6482 int rc = SQLITE_OK; /* Return code */
6483 int nCurrent = pPager->nSavepoint; /* Current number of savepoints */
6485 assert( pPager->eState>=PAGER_WRITER_LOCKED );
6486 assert( assert_pager_state(pPager) );
6488 if( nSavepoint>nCurrent && pPager->useJournal ){
6489 int ii; /* Iterator variable */
6490 PagerSavepoint *aNew; /* New Pager.aSavepoint array */
6492 /* Grow the Pager.aSavepoint array using realloc(). Return SQLITE_NOMEM
6493 ** if the allocation fails. Otherwise, zero the new portion in case a
6494 ** malloc failure occurs while populating it in the for(...) loop below.
6496 aNew = (PagerSavepoint *)sqlite3Realloc(
6497 pPager->aSavepoint, sizeof(PagerSavepoint)*nSavepoint
6499 if( !aNew ){
6500 return SQLITE_NOMEM;
6502 memset(&aNew[nCurrent], 0, (nSavepoint-nCurrent) * sizeof(PagerSavepoint));
6503 pPager->aSavepoint = aNew;
6505 /* Populate the PagerSavepoint structures just allocated. */
6506 for(ii=nCurrent; ii<nSavepoint; ii++){
6507 aNew[ii].nOrig = pPager->dbSize;
6508 if( isOpen(pPager->jfd) && pPager->journalOff>0 ){
6509 aNew[ii].iOffset = pPager->journalOff;
6510 }else{
6511 aNew[ii].iOffset = JOURNAL_HDR_SZ(pPager);
6513 aNew[ii].iSubRec = pPager->nSubRec;
6514 aNew[ii].pInSavepoint = sqlite3BitvecCreate(pPager->dbSize);
6515 if( !aNew[ii].pInSavepoint ){
6516 return SQLITE_NOMEM;
6518 if( pagerUseWal(pPager) ){
6519 sqlite3WalSavepoint(pPager->pWal, aNew[ii].aWalData);
6521 pPager->nSavepoint = ii+1;
6523 assert( pPager->nSavepoint==nSavepoint );
6524 assertTruncateConstraint(pPager);
6527 return rc;
6531 ** This function is called to rollback or release (commit) a savepoint.
6532 ** The savepoint to release or rollback need not be the most recently
6533 ** created savepoint.
6535 ** Parameter op is always either SAVEPOINT_ROLLBACK or SAVEPOINT_RELEASE.
6536 ** If it is SAVEPOINT_RELEASE, then release and destroy the savepoint with
6537 ** index iSavepoint. If it is SAVEPOINT_ROLLBACK, then rollback all changes
6538 ** that have occurred since the specified savepoint was created.
6540 ** The savepoint to rollback or release is identified by parameter
6541 ** iSavepoint. A value of 0 means to operate on the outermost savepoint
6542 ** (the first created). A value of (Pager.nSavepoint-1) means operate
6543 ** on the most recently created savepoint. If iSavepoint is greater than
6544 ** (Pager.nSavepoint-1), then this function is a no-op.
6546 ** If a negative value is passed to this function, then the current
6547 ** transaction is rolled back. This is different to calling
6548 ** sqlite3PagerRollback() because this function does not terminate
6549 ** the transaction or unlock the database, it just restores the
6550 ** contents of the database to its original state.
6552 ** In any case, all savepoints with an index greater than iSavepoint
6553 ** are destroyed. If this is a release operation (op==SAVEPOINT_RELEASE),
6554 ** then savepoint iSavepoint is also destroyed.
6556 ** This function may return SQLITE_NOMEM if a memory allocation fails,
6557 ** or an IO error code if an IO error occurs while rolling back a
6558 ** savepoint. If no errors occur, SQLITE_OK is returned.
6560 int sqlite3PagerSavepoint(Pager *pPager, int op, int iSavepoint){
6561 int rc = pPager->errCode; /* Return code */
6563 assert( op==SAVEPOINT_RELEASE || op==SAVEPOINT_ROLLBACK );
6564 assert( iSavepoint>=0 || op==SAVEPOINT_ROLLBACK );
6566 if( rc==SQLITE_OK && iSavepoint<pPager->nSavepoint ){
6567 int ii; /* Iterator variable */
6568 int nNew; /* Number of remaining savepoints after this op. */
6570 /* Figure out how many savepoints will still be active after this
6571 ** operation. Store this value in nNew. Then free resources associated
6572 ** with any savepoints that are destroyed by this operation.
6574 nNew = iSavepoint + (( op==SAVEPOINT_RELEASE ) ? 0 : 1);
6575 for(ii=nNew; ii<pPager->nSavepoint; ii++){
6576 sqlite3BitvecDestroy(pPager->aSavepoint[ii].pInSavepoint);
6578 pPager->nSavepoint = nNew;
6580 /* If this is a release of the outermost savepoint, truncate
6581 ** the sub-journal to zero bytes in size. */
6582 if( op==SAVEPOINT_RELEASE ){
6583 if( nNew==0 && isOpen(pPager->sjfd) ){
6584 /* Only truncate if it is an in-memory sub-journal. */
6585 if( sqlite3IsMemJournal(pPager->sjfd) ){
6586 rc = sqlite3OsTruncate(pPager->sjfd, 0);
6587 assert( rc==SQLITE_OK );
6589 pPager->nSubRec = 0;
6592 /* Else this is a rollback operation, playback the specified savepoint.
6593 ** If this is a temp-file, it is possible that the journal file has
6594 ** not yet been opened. In this case there have been no changes to
6595 ** the database file, so the playback operation can be skipped.
6597 else if( pagerUseWal(pPager) || isOpen(pPager->jfd) ){
6598 PagerSavepoint *pSavepoint = (nNew==0)?0:&pPager->aSavepoint[nNew-1];
6599 rc = pagerPlaybackSavepoint(pPager, pSavepoint);
6600 assert(rc!=SQLITE_DONE);
6604 return rc;
6608 ** Return the full pathname of the database file.
6610 ** Except, if the pager is in-memory only, then return an empty string if
6611 ** nullIfMemDb is true. This routine is called with nullIfMemDb==1 when
6612 ** used to report the filename to the user, for compatibility with legacy
6613 ** behavior. But when the Btree needs to know the filename for matching to
6614 ** shared cache, it uses nullIfMemDb==0 so that in-memory databases can
6615 ** participate in shared-cache.
6617 const char *sqlite3PagerFilename(Pager *pPager, int nullIfMemDb){
6618 return (nullIfMemDb && pPager->memDb) ? "" : pPager->zFilename;
6622 ** Return the VFS structure for the pager.
6624 const sqlite3_vfs *sqlite3PagerVfs(Pager *pPager){
6625 return pPager->pVfs;
6629 ** Return the file handle for the database file associated
6630 ** with the pager. This might return NULL if the file has
6631 ** not yet been opened.
6633 sqlite3_file *sqlite3PagerFile(Pager *pPager){
6634 return pPager->fd;
6638 ** Return the full pathname of the journal file.
6640 const char *sqlite3PagerJournalname(Pager *pPager){
6641 return pPager->zJournal;
6645 ** Return true if fsync() calls are disabled for this pager. Return FALSE
6646 ** if fsync()s are executed normally.
6648 int sqlite3PagerNosync(Pager *pPager){
6649 return pPager->noSync;
6652 #ifdef SQLITE_HAS_CODEC
6654 ** Set or retrieve the codec for this pager
6656 void sqlite3PagerSetCodec(
6657 Pager *pPager,
6658 void *(*xCodec)(void*,void*,Pgno,int),
6659 void (*xCodecSizeChng)(void*,int,int),
6660 void (*xCodecFree)(void*),
6661 void *pCodec
6663 if( pPager->xCodecFree ) pPager->xCodecFree(pPager->pCodec);
6664 pPager->xCodec = pPager->memDb ? 0 : xCodec;
6665 pPager->xCodecSizeChng = xCodecSizeChng;
6666 pPager->xCodecFree = xCodecFree;
6667 pPager->pCodec = pCodec;
6668 pagerReportSize(pPager);
6670 void *sqlite3PagerGetCodec(Pager *pPager){
6671 return pPager->pCodec;
6675 ** This function is called by the wal module when writing page content
6676 ** into the log file.
6678 ** This function returns a pointer to a buffer containing the encrypted
6679 ** page content. If a malloc fails, this function may return NULL.
6681 void *sqlite3PagerCodec(PgHdr *pPg){
6682 void *aData = 0;
6683 CODEC2(pPg->pPager, pPg->pData, pPg->pgno, 6, return 0, aData);
6684 return aData;
6688 ** Return the current pager state
6690 int sqlite3PagerState(Pager *pPager){
6691 return pPager->eState;
6693 #endif /* SQLITE_HAS_CODEC */
6695 #ifndef SQLITE_OMIT_AUTOVACUUM
6697 ** Move the page pPg to location pgno in the file.
6699 ** There must be no references to the page previously located at
6700 ** pgno (which we call pPgOld) though that page is allowed to be
6701 ** in cache. If the page previously located at pgno is not already
6702 ** in the rollback journal, it is not put there by by this routine.
6704 ** References to the page pPg remain valid. Updating any
6705 ** meta-data associated with pPg (i.e. data stored in the nExtra bytes
6706 ** allocated along with the page) is the responsibility of the caller.
6708 ** A transaction must be active when this routine is called. It used to be
6709 ** required that a statement transaction was not active, but this restriction
6710 ** has been removed (CREATE INDEX needs to move a page when a statement
6711 ** transaction is active).
6713 ** If the fourth argument, isCommit, is non-zero, then this page is being
6714 ** moved as part of a database reorganization just before the transaction
6715 ** is being committed. In this case, it is guaranteed that the database page
6716 ** pPg refers to will not be written to again within this transaction.
6718 ** This function may return SQLITE_NOMEM or an IO error code if an error
6719 ** occurs. Otherwise, it returns SQLITE_OK.
6721 int sqlite3PagerMovepage(Pager *pPager, DbPage *pPg, Pgno pgno, int isCommit){
6722 PgHdr *pPgOld; /* The page being overwritten. */
6723 Pgno needSyncPgno = 0; /* Old value of pPg->pgno, if sync is required */
6724 int rc; /* Return code */
6725 Pgno origPgno; /* The original page number */
6727 assert( pPg->nRef>0 );
6728 assert( pPager->eState==PAGER_WRITER_CACHEMOD
6729 || pPager->eState==PAGER_WRITER_DBMOD
6731 assert( assert_pager_state(pPager) );
6733 /* In order to be able to rollback, an in-memory database must journal
6734 ** the page we are moving from.
6736 if( MEMDB ){
6737 rc = sqlite3PagerWrite(pPg);
6738 if( rc ) return rc;
6741 /* If the page being moved is dirty and has not been saved by the latest
6742 ** savepoint, then save the current contents of the page into the
6743 ** sub-journal now. This is required to handle the following scenario:
6745 ** BEGIN;
6746 ** <journal page X, then modify it in memory>
6747 ** SAVEPOINT one;
6748 ** <Move page X to location Y>
6749 ** ROLLBACK TO one;
6751 ** If page X were not written to the sub-journal here, it would not
6752 ** be possible to restore its contents when the "ROLLBACK TO one"
6753 ** statement were is processed.
6755 ** subjournalPage() may need to allocate space to store pPg->pgno into
6756 ** one or more savepoint bitvecs. This is the reason this function
6757 ** may return SQLITE_NOMEM.
6759 if( pPg->flags&PGHDR_DIRTY
6760 && subjRequiresPage(pPg)
6761 && SQLITE_OK!=(rc = subjournalPage(pPg))
6763 return rc;
6766 PAGERTRACE(("MOVE %d page %d (needSync=%d) moves to %d\n",
6767 PAGERID(pPager), pPg->pgno, (pPg->flags&PGHDR_NEED_SYNC)?1:0, pgno));
6768 IOTRACE(("MOVE %p %d %d\n", pPager, pPg->pgno, pgno))
6770 /* If the journal needs to be sync()ed before page pPg->pgno can
6771 ** be written to, store pPg->pgno in local variable needSyncPgno.
6773 ** If the isCommit flag is set, there is no need to remember that
6774 ** the journal needs to be sync()ed before database page pPg->pgno
6775 ** can be written to. The caller has already promised not to write to it.
6777 if( (pPg->flags&PGHDR_NEED_SYNC) && !isCommit ){
6778 needSyncPgno = pPg->pgno;
6779 assert( pPager->journalMode==PAGER_JOURNALMODE_OFF ||
6780 pageInJournal(pPager, pPg) || pPg->pgno>pPager->dbOrigSize );
6781 assert( pPg->flags&PGHDR_DIRTY );
6784 /* If the cache contains a page with page-number pgno, remove it
6785 ** from its hash chain. Also, if the PGHDR_NEED_SYNC flag was set for
6786 ** page pgno before the 'move' operation, it needs to be retained
6787 ** for the page moved there.
6789 pPg->flags &= ~PGHDR_NEED_SYNC;
6790 pPgOld = sqlite3PagerLookup(pPager, pgno);
6791 assert( !pPgOld || pPgOld->nRef==1 );
6792 if( pPgOld ){
6793 pPg->flags |= (pPgOld->flags&PGHDR_NEED_SYNC);
6794 if( MEMDB ){
6795 /* Do not discard pages from an in-memory database since we might
6796 ** need to rollback later. Just move the page out of the way. */
6797 sqlite3PcacheMove(pPgOld, pPager->dbSize+1);
6798 }else{
6799 sqlite3PcacheDrop(pPgOld);
6803 origPgno = pPg->pgno;
6804 sqlite3PcacheMove(pPg, pgno);
6805 sqlite3PcacheMakeDirty(pPg);
6807 /* For an in-memory database, make sure the original page continues
6808 ** to exist, in case the transaction needs to roll back. Use pPgOld
6809 ** as the original page since it has already been allocated.
6811 if( MEMDB ){
6812 assert( pPgOld );
6813 sqlite3PcacheMove(pPgOld, origPgno);
6814 sqlite3PagerUnrefNotNull(pPgOld);
6817 if( needSyncPgno ){
6818 /* If needSyncPgno is non-zero, then the journal file needs to be
6819 ** sync()ed before any data is written to database file page needSyncPgno.
6820 ** Currently, no such page exists in the page-cache and the
6821 ** "is journaled" bitvec flag has been set. This needs to be remedied by
6822 ** loading the page into the pager-cache and setting the PGHDR_NEED_SYNC
6823 ** flag.
6825 ** If the attempt to load the page into the page-cache fails, (due
6826 ** to a malloc() or IO failure), clear the bit in the pInJournal[]
6827 ** array. Otherwise, if the page is loaded and written again in
6828 ** this transaction, it may be written to the database file before
6829 ** it is synced into the journal file. This way, it may end up in
6830 ** the journal file twice, but that is not a problem.
6832 PgHdr *pPgHdr;
6833 rc = sqlite3PagerGet(pPager, needSyncPgno, &pPgHdr);
6834 if( rc!=SQLITE_OK ){
6835 if( needSyncPgno<=pPager->dbOrigSize ){
6836 assert( pPager->pTmpSpace!=0 );
6837 sqlite3BitvecClear(pPager->pInJournal, needSyncPgno, pPager->pTmpSpace);
6839 return rc;
6841 pPgHdr->flags |= PGHDR_NEED_SYNC;
6842 sqlite3PcacheMakeDirty(pPgHdr);
6843 sqlite3PagerUnrefNotNull(pPgHdr);
6846 return SQLITE_OK;
6848 #endif
6851 ** Return a pointer to the data for the specified page.
6853 void *sqlite3PagerGetData(DbPage *pPg){
6854 assert( pPg->nRef>0 || pPg->pPager->memDb );
6855 return pPg->pData;
6859 ** Return a pointer to the Pager.nExtra bytes of "extra" space
6860 ** allocated along with the specified page.
6862 void *sqlite3PagerGetExtra(DbPage *pPg){
6863 return pPg->pExtra;
6867 ** Get/set the locking-mode for this pager. Parameter eMode must be one
6868 ** of PAGER_LOCKINGMODE_QUERY, PAGER_LOCKINGMODE_NORMAL or
6869 ** PAGER_LOCKINGMODE_EXCLUSIVE. If the parameter is not _QUERY, then
6870 ** the locking-mode is set to the value specified.
6872 ** The returned value is either PAGER_LOCKINGMODE_NORMAL or
6873 ** PAGER_LOCKINGMODE_EXCLUSIVE, indicating the current (possibly updated)
6874 ** locking-mode.
6876 int sqlite3PagerLockingMode(Pager *pPager, int eMode){
6877 assert( eMode==PAGER_LOCKINGMODE_QUERY
6878 || eMode==PAGER_LOCKINGMODE_NORMAL
6879 || eMode==PAGER_LOCKINGMODE_EXCLUSIVE );
6880 assert( PAGER_LOCKINGMODE_QUERY<0 );
6881 assert( PAGER_LOCKINGMODE_NORMAL>=0 && PAGER_LOCKINGMODE_EXCLUSIVE>=0 );
6882 assert( pPager->exclusiveMode || 0==sqlite3WalHeapMemory(pPager->pWal) );
6883 if( eMode>=0 && !pPager->tempFile && !sqlite3WalHeapMemory(pPager->pWal) ){
6884 pPager->exclusiveMode = (u8)eMode;
6886 return (int)pPager->exclusiveMode;
6890 ** Set the journal-mode for this pager. Parameter eMode must be one of:
6892 ** PAGER_JOURNALMODE_DELETE
6893 ** PAGER_JOURNALMODE_TRUNCATE
6894 ** PAGER_JOURNALMODE_PERSIST
6895 ** PAGER_JOURNALMODE_OFF
6896 ** PAGER_JOURNALMODE_MEMORY
6897 ** PAGER_JOURNALMODE_WAL
6899 ** The journalmode is set to the value specified if the change is allowed.
6900 ** The change may be disallowed for the following reasons:
6902 ** * An in-memory database can only have its journal_mode set to _OFF
6903 ** or _MEMORY.
6905 ** * Temporary databases cannot have _WAL journalmode.
6907 ** The returned indicate the current (possibly updated) journal-mode.
6909 int sqlite3PagerSetJournalMode(Pager *pPager, int eMode){
6910 u8 eOld = pPager->journalMode; /* Prior journalmode */
6912 #ifdef SQLITE_DEBUG
6913 /* The print_pager_state() routine is intended to be used by the debugger
6914 ** only. We invoke it once here to suppress a compiler warning. */
6915 print_pager_state(pPager);
6916 #endif
6919 /* The eMode parameter is always valid */
6920 assert( eMode==PAGER_JOURNALMODE_DELETE
6921 || eMode==PAGER_JOURNALMODE_TRUNCATE
6922 || eMode==PAGER_JOURNALMODE_PERSIST
6923 || eMode==PAGER_JOURNALMODE_OFF
6924 || eMode==PAGER_JOURNALMODE_WAL
6925 || eMode==PAGER_JOURNALMODE_MEMORY );
6927 /* This routine is only called from the OP_JournalMode opcode, and
6928 ** the logic there will never allow a temporary file to be changed
6929 ** to WAL mode.
6931 assert( pPager->tempFile==0 || eMode!=PAGER_JOURNALMODE_WAL );
6933 /* Do allow the journalmode of an in-memory database to be set to
6934 ** anything other than MEMORY or OFF
6936 if( MEMDB ){
6937 assert( eOld==PAGER_JOURNALMODE_MEMORY || eOld==PAGER_JOURNALMODE_OFF );
6938 if( eMode!=PAGER_JOURNALMODE_MEMORY && eMode!=PAGER_JOURNALMODE_OFF ){
6939 eMode = eOld;
6943 if( eMode!=eOld ){
6945 /* Change the journal mode. */
6946 assert( pPager->eState!=PAGER_ERROR );
6947 pPager->journalMode = (u8)eMode;
6949 /* When transistioning from TRUNCATE or PERSIST to any other journal
6950 ** mode except WAL, unless the pager is in locking_mode=exclusive mode,
6951 ** delete the journal file.
6953 assert( (PAGER_JOURNALMODE_TRUNCATE & 5)==1 );
6954 assert( (PAGER_JOURNALMODE_PERSIST & 5)==1 );
6955 assert( (PAGER_JOURNALMODE_DELETE & 5)==0 );
6956 assert( (PAGER_JOURNALMODE_MEMORY & 5)==4 );
6957 assert( (PAGER_JOURNALMODE_OFF & 5)==0 );
6958 assert( (PAGER_JOURNALMODE_WAL & 5)==5 );
6960 assert( isOpen(pPager->fd) || pPager->exclusiveMode );
6961 if( !pPager->exclusiveMode && (eOld & 5)==1 && (eMode & 1)==0 ){
6963 /* In this case we would like to delete the journal file. If it is
6964 ** not possible, then that is not a problem. Deleting the journal file
6965 ** here is an optimization only.
6967 ** Before deleting the journal file, obtain a RESERVED lock on the
6968 ** database file. This ensures that the journal file is not deleted
6969 ** while it is in use by some other client.
6971 sqlite3OsClose(pPager->jfd);
6972 if( pPager->eLock>=RESERVED_LOCK ){
6973 sqlite3OsDelete(pPager->pVfs, pPager->zJournal, 0);
6974 }else{
6975 int rc = SQLITE_OK;
6976 int state = pPager->eState;
6977 assert( state==PAGER_OPEN || state==PAGER_READER );
6978 if( state==PAGER_OPEN ){
6979 rc = sqlite3PagerSharedLock(pPager);
6981 if( pPager->eState==PAGER_READER ){
6982 assert( rc==SQLITE_OK );
6983 rc = pagerLockDb(pPager, RESERVED_LOCK);
6985 if( rc==SQLITE_OK ){
6986 sqlite3OsDelete(pPager->pVfs, pPager->zJournal, 0);
6988 if( rc==SQLITE_OK && state==PAGER_READER ){
6989 pagerUnlockDb(pPager, SHARED_LOCK);
6990 }else if( state==PAGER_OPEN ){
6991 pager_unlock(pPager);
6993 assert( state==pPager->eState );
6998 /* Return the new journal mode */
6999 return (int)pPager->journalMode;
7003 ** Return the current journal mode.
7005 int sqlite3PagerGetJournalMode(Pager *pPager){
7006 return (int)pPager->journalMode;
7010 ** Return TRUE if the pager is in a state where it is OK to change the
7011 ** journalmode. Journalmode changes can only happen when the database
7012 ** is unmodified.
7014 int sqlite3PagerOkToChangeJournalMode(Pager *pPager){
7015 assert( assert_pager_state(pPager) );
7016 if( pPager->eState>=PAGER_WRITER_CACHEMOD ) return 0;
7017 if( NEVER(isOpen(pPager->jfd) && pPager->journalOff>0) ) return 0;
7018 return 1;
7022 ** Get/set the size-limit used for persistent journal files.
7024 ** Setting the size limit to -1 means no limit is enforced.
7025 ** An attempt to set a limit smaller than -1 is a no-op.
7027 i64 sqlite3PagerJournalSizeLimit(Pager *pPager, i64 iLimit){
7028 if( iLimit>=-1 ){
7029 pPager->journalSizeLimit = iLimit;
7030 sqlite3WalLimit(pPager->pWal, iLimit);
7032 return pPager->journalSizeLimit;
7036 ** Return a pointer to the pPager->pBackup variable. The backup module
7037 ** in backup.c maintains the content of this variable. This module
7038 ** uses it opaquely as an argument to sqlite3BackupRestart() and
7039 ** sqlite3BackupUpdate() only.
7041 sqlite3_backup **sqlite3PagerBackupPtr(Pager *pPager){
7042 return &pPager->pBackup;
7045 #ifndef SQLITE_OMIT_VACUUM
7047 ** Unless this is an in-memory or temporary database, clear the pager cache.
7049 void sqlite3PagerClearCache(Pager *pPager){
7050 if( !MEMDB && pPager->tempFile==0 ) pager_reset(pPager);
7052 #endif
7054 #ifndef SQLITE_OMIT_WAL
7056 ** This function is called when the user invokes "PRAGMA wal_checkpoint",
7057 ** "PRAGMA wal_blocking_checkpoint" or calls the sqlite3_wal_checkpoint()
7058 ** or wal_blocking_checkpoint() API functions.
7060 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART.
7062 int sqlite3PagerCheckpoint(Pager *pPager, int eMode, int *pnLog, int *pnCkpt){
7063 int rc = SQLITE_OK;
7064 if( pPager->pWal ){
7065 rc = sqlite3WalCheckpoint(pPager->pWal, eMode,
7066 pPager->xBusyHandler, pPager->pBusyHandlerArg,
7067 pPager->ckptSyncFlags, pPager->pageSize, (u8 *)pPager->pTmpSpace,
7068 pnLog, pnCkpt
7071 return rc;
7074 int sqlite3PagerWalCallback(Pager *pPager){
7075 return sqlite3WalCallback(pPager->pWal);
7079 ** Return true if the underlying VFS for the given pager supports the
7080 ** primitives necessary for write-ahead logging.
7082 int sqlite3PagerWalSupported(Pager *pPager){
7083 const sqlite3_io_methods *pMethods = pPager->fd->pMethods;
7084 return pPager->exclusiveMode || (pMethods->iVersion>=2 && pMethods->xShmMap);
7088 ** Attempt to take an exclusive lock on the database file. If a PENDING lock
7089 ** is obtained instead, immediately release it.
7091 static int pagerExclusiveLock(Pager *pPager){
7092 int rc; /* Return code */
7094 assert( pPager->eLock==SHARED_LOCK || pPager->eLock==EXCLUSIVE_LOCK );
7095 rc = pagerLockDb(pPager, EXCLUSIVE_LOCK);
7096 if( rc!=SQLITE_OK ){
7097 /* If the attempt to grab the exclusive lock failed, release the
7098 ** pending lock that may have been obtained instead. */
7099 pagerUnlockDb(pPager, SHARED_LOCK);
7102 return rc;
7106 ** Call sqlite3WalOpen() to open the WAL handle. If the pager is in
7107 ** exclusive-locking mode when this function is called, take an EXCLUSIVE
7108 ** lock on the database file and use heap-memory to store the wal-index
7109 ** in. Otherwise, use the normal shared-memory.
7111 static int pagerOpenWal(Pager *pPager){
7112 int rc = SQLITE_OK;
7114 assert( pPager->pWal==0 && pPager->tempFile==0 );
7115 assert( pPager->eLock==SHARED_LOCK || pPager->eLock==EXCLUSIVE_LOCK );
7117 /* If the pager is already in exclusive-mode, the WAL module will use
7118 ** heap-memory for the wal-index instead of the VFS shared-memory
7119 ** implementation. Take the exclusive lock now, before opening the WAL
7120 ** file, to make sure this is safe.
7122 if( pPager->exclusiveMode ){
7123 rc = pagerExclusiveLock(pPager);
7126 /* Open the connection to the log file. If this operation fails,
7127 ** (e.g. due to malloc() failure), return an error code.
7129 if( rc==SQLITE_OK ){
7130 rc = sqlite3WalOpen(pPager->pVfs,
7131 pPager->fd, pPager->zWal, pPager->exclusiveMode,
7132 pPager->journalSizeLimit, &pPager->pWal
7135 pagerFixMaplimit(pPager);
7137 return rc;
7142 ** The caller must be holding a SHARED lock on the database file to call
7143 ** this function.
7145 ** If the pager passed as the first argument is open on a real database
7146 ** file (not a temp file or an in-memory database), and the WAL file
7147 ** is not already open, make an attempt to open it now. If successful,
7148 ** return SQLITE_OK. If an error occurs or the VFS used by the pager does
7149 ** not support the xShmXXX() methods, return an error code. *pbOpen is
7150 ** not modified in either case.
7152 ** If the pager is open on a temp-file (or in-memory database), or if
7153 ** the WAL file is already open, set *pbOpen to 1 and return SQLITE_OK
7154 ** without doing anything.
7156 int sqlite3PagerOpenWal(
7157 Pager *pPager, /* Pager object */
7158 int *pbOpen /* OUT: Set to true if call is a no-op */
7160 int rc = SQLITE_OK; /* Return code */
7162 assert( assert_pager_state(pPager) );
7163 assert( pPager->eState==PAGER_OPEN || pbOpen );
7164 assert( pPager->eState==PAGER_READER || !pbOpen );
7165 assert( pbOpen==0 || *pbOpen==0 );
7166 assert( pbOpen!=0 || (!pPager->tempFile && !pPager->pWal) );
7168 if( !pPager->tempFile && !pPager->pWal ){
7169 if( !sqlite3PagerWalSupported(pPager) ) return SQLITE_CANTOPEN;
7171 /* Close any rollback journal previously open */
7172 sqlite3OsClose(pPager->jfd);
7174 rc = pagerOpenWal(pPager);
7175 if( rc==SQLITE_OK ){
7176 pPager->journalMode = PAGER_JOURNALMODE_WAL;
7177 pPager->eState = PAGER_OPEN;
7179 }else{
7180 *pbOpen = 1;
7183 return rc;
7187 ** This function is called to close the connection to the log file prior
7188 ** to switching from WAL to rollback mode.
7190 ** Before closing the log file, this function attempts to take an
7191 ** EXCLUSIVE lock on the database file. If this cannot be obtained, an
7192 ** error (SQLITE_BUSY) is returned and the log connection is not closed.
7193 ** If successful, the EXCLUSIVE lock is not released before returning.
7195 int sqlite3PagerCloseWal(Pager *pPager){
7196 int rc = SQLITE_OK;
7198 assert( pPager->journalMode==PAGER_JOURNALMODE_WAL );
7200 /* If the log file is not already open, but does exist in the file-system,
7201 ** it may need to be checkpointed before the connection can switch to
7202 ** rollback mode. Open it now so this can happen.
7204 if( !pPager->pWal ){
7205 int logexists = 0;
7206 rc = pagerLockDb(pPager, SHARED_LOCK);
7207 if( rc==SQLITE_OK ){
7208 rc = sqlite3OsAccess(
7209 pPager->pVfs, pPager->zWal, SQLITE_ACCESS_EXISTS, &logexists
7212 if( rc==SQLITE_OK && logexists ){
7213 rc = pagerOpenWal(pPager);
7217 /* Checkpoint and close the log. Because an EXCLUSIVE lock is held on
7218 ** the database file, the log and log-summary files will be deleted.
7220 if( rc==SQLITE_OK && pPager->pWal ){
7221 rc = pagerExclusiveLock(pPager);
7222 if( rc==SQLITE_OK ){
7223 rc = sqlite3WalClose(pPager->pWal, pPager->ckptSyncFlags,
7224 pPager->pageSize, (u8*)pPager->pTmpSpace);
7225 pPager->pWal = 0;
7226 pagerFixMaplimit(pPager);
7229 return rc;
7232 #endif /* !SQLITE_OMIT_WAL */
7234 #ifdef SQLITE_ENABLE_ZIPVFS
7236 ** A read-lock must be held on the pager when this function is called. If
7237 ** the pager is in WAL mode and the WAL file currently contains one or more
7238 ** frames, return the size in bytes of the page images stored within the
7239 ** WAL frames. Otherwise, if this is not a WAL database or the WAL file
7240 ** is empty, return 0.
7242 int sqlite3PagerWalFramesize(Pager *pPager){
7243 assert( pPager->eState>=PAGER_READER );
7244 return sqlite3WalFramesize(pPager->pWal);
7246 #endif
7248 #endif /* SQLITE_OMIT_DISKIO */