src/backup.c

   1 /*
   2 ** 2009 January 28
   3 **
   4 ** The author disclaims copyright to this source code.  In place of
   5 ** a legal notice, here is a blessing:
   6 **
   7 **    May you do good and not evil.
   8 **    May you find forgiveness for yourself and forgive others.
   9 **    May you share freely, never taking more than you give.
  10 **
  11 *************************************************************************
  12 ** This file contains the implementation of the sqlite3_backup_XXX()
  13 ** API functions and the related features.
  14 */
  15 #include "sqliteInt.h"
  16 #include "btreeInt.h"
  17
  18 /*
  19 ** Structure allocated for each backup operation.
  20 */
  21 struct sqlite3_backup {
  22   sqlite3* pDestDb;        /* Destination database handle */
  23   Btree *pDest;            /* Destination b-tree file */
  24   u32 iDestSchema;         /* Original schema cookie in destination */
  25   int bDestLocked;         /* True once a write-transaction is open on pDest */
  26
  27   Pgno iNext;              /* Page number of the next source page to copy */
  28   sqlite3* pSrcDb;         /* Source database handle */
  29   Btree *pSrc;             /* Source b-tree file */
  30
  31   int rc;                  /* Backup process error code */
  32
  33   /* These two variables are set by every call to backup_step(). They are
  34   ** read by calls to backup_remaining() and backup_pagecount().
  35   */
  36   Pgno nRemaining;         /* Number of pages left to copy */
  37   Pgno nPagecount;         /* Total number of pages to copy */
  38
  39   int isAttached;          /* True once backup has been registered with pager */
  40   sqlite3_backup *pNext;   /* Next backup associated with source pager */
  41 };
  42
  43 /*
  44 ** THREAD SAFETY NOTES:
  45 **
  46 **   Once it has been created using backup_init(), a single sqlite3_backup
  47 **   structure may be accessed via two groups of thread-safe entry points:
  48 **
  49 **     * Via the sqlite3_backup_XXX() API function backup_step() and
  50 **       backup_finish(). Both these functions obtain the source database
  51 **       handle mutex and the mutex associated with the source BtShared
  52 **       structure, in that order.
  53 **
  54 **     * Via the BackupUpdate() and BackupRestart() functions, which are
  55 **       invoked by the pager layer to report various state changes in
  56 **       the page cache associated with the source database. The mutex
  57 **       associated with the source database BtShared structure will always
  58 **       be held when either of these functions are invoked.
  59 **
  60 **   The other sqlite3_backup_XXX() API functions, backup_remaining() and
  61 **   backup_pagecount() are not thread-safe functions. If they are called
  62 **   while some other thread is calling backup_step() or backup_finish(),
  63 **   the values returned may be invalid. There is no way for a call to
  64 **   BackupUpdate() or BackupRestart() to interfere with backup_remaining()
  65 **   or backup_pagecount().
  66 **
  67 **   Depending on the SQLite configuration, the database handles and/or
  68 **   the Btree objects may have their own mutexes that require locking.
  69 **   Non-sharable Btrees (in-memory databases for example), do not have
  70 **   associated mutexes.
  71 */
  72
  73 /*
  74 ** Return a pointer corresponding to database zDb (i.e. "main", "temp")
  75 ** in connection handle pDb. If such a database cannot be found, return
  76 ** a NULL pointer and write an error message to pErrorDb.
  77 **
  78 ** If the "temp" database is requested, it may need to be opened by this
  79 ** function. If an error occurs while doing so, return 0 and write an
  80 ** error message to pErrorDb.
  81 */
  82 static Btree *findBtree(sqlite3 *pErrorDb, sqlite3 *pDb, const char *zDb){
  83   int i = sqlite3FindDbName(pDb, zDb);
  84
  85   if( i==1 ){
  86     Parse sParse;
  87     int rc = 0;
  88     sqlite3ParseObjectInit(&sParse,pDb);
  89     if( sqlite3OpenTempDatabase(&sParse) ){
  90       sqlite3ErrorWithMsg(pErrorDb, sParse.rc, "%s", sParse.zErrMsg);
  91       rc = SQLITE_ERROR;
  92     }
  93     sqlite3DbFree(pErrorDb, sParse.zErrMsg);
  94     sqlite3ParseObjectReset(&sParse);
  95     if( rc ){
  96       return 0;
  97     }
  98   }
  99
 100   if( i<0 ){
 101     sqlite3ErrorWithMsg(pErrorDb, SQLITE_ERROR, "unknown database %s", zDb);
 102     return 0;
 103   }
 104
 105   return pDb->aDb[i].pBt;
 106 }
 107
 108 /*
 109 ** Attempt to set the page size of the destination to match the page size
 110 ** of the source.
 111 */
 112 static int setDestPgsz(sqlite3_backup *p){
 113   int rc;
 114   rc = sqlite3BtreeSetPageSize(p->pDest,sqlite3BtreeGetPageSize(p->pSrc),0,0);
 115   return rc;
 116 }
 117
 118 /*
 119 ** Check that there is no open read-transaction on the b-tree passed as the
 120 ** second argument. If there is not, return SQLITE_OK. Otherwise, if there
 121 ** is an open read-transaction, return SQLITE_ERROR and leave an error
 122 ** message in database handle db.
 123 */
 124 static int checkReadTransaction(sqlite3 *db, Btree *p){
 125   if( sqlite3BtreeTxnState(p)!=SQLITE_TXN_NONE ){
 126     sqlite3ErrorWithMsg(db, SQLITE_ERROR, "destination database is in use");
 127     return SQLITE_ERROR;
 128   }
 129   return SQLITE_OK;
 130 }
 131
 132 /*
 133 ** Create an sqlite3_backup process to copy the contents of zSrcDb from
 134 ** connection handle pSrcDb to zDestDb in pDestDb. If successful, return
 135 ** a pointer to the new sqlite3_backup object.
 136 **
 137 ** If an error occurs, NULL is returned and an error code and error message
 138 ** stored in database handle pDestDb.
 139 */
 140 sqlite3_backup *sqlite3_backup_init(
 141   sqlite3* pDestDb,                     /* Database to write to */
 142   const char *zDestDb,                  /* Name of database within pDestDb */
 143   sqlite3* pSrcDb,                      /* Database connection to read from */
 144   const char *zSrcDb                    /* Name of database within pSrcDb */
 145 ){
 146   sqlite3_backup *p;                    /* Value to return */
 147
 148 #ifdef SQLITE_ENABLE_API_ARMOR
 149   if( !sqlite3SafetyCheckOk(pSrcDb)||!sqlite3SafetyCheckOk(pDestDb) ){
 150     (void)SQLITE_MISUSE_BKPT;
 151     return 0;
 152   }
 153 #endif
 154
 155   /* Lock the source database handle. The destination database
 156   ** handle is not locked in this routine, but it is locked in
 157   ** sqlite3_backup_step(). The user is required to ensure that no
 158   ** other thread accesses the destination handle for the duration
 159   ** of the backup operation.  Any attempt to use the destination
 160   ** database connection while a backup is in progress may cause
 161   ** a malfunction or a deadlock.
 162   */
 163   sqlite3_mutex_enter(pSrcDb->mutex);
 164   sqlite3_mutex_enter(pDestDb->mutex);
 165
 166   if( pSrcDb==pDestDb ){
 167     sqlite3ErrorWithMsg(
 168         pDestDb, SQLITE_ERROR, "source and destination must be distinct"
 169     );
 170     p = 0;
 171   }else {
 172     /* Allocate space for a new sqlite3_backup object...
 173     ** EVIDENCE-OF: R-64852-21591 The sqlite3_backup object is created by a
 174     ** call to sqlite3_backup_init() and is destroyed by a call to
 175     ** sqlite3_backup_finish(). */
 176     p = (sqlite3_backup *)sqlite3MallocZero(sizeof(sqlite3_backup));
 177     if( !p ){
 178       sqlite3Error(pDestDb, SQLITE_NOMEM_BKPT);
 179     }
 180   }
 181
 182   /* If the allocation succeeded, populate the new object. */
 183   if( p ){
 184     p->pSrc = findBtree(pDestDb, pSrcDb, zSrcDb);
 185     p->pDest = findBtree(pDestDb, pDestDb, zDestDb);
 186     p->pDestDb = pDestDb;
 187     p->pSrcDb = pSrcDb;
 188     p->iNext = 1;
 189     p->isAttached = 0;
 190
 191     if( 0==p->pSrc || 0==p->pDest
 192      || checkReadTransaction(pDestDb, p->pDest)!=SQLITE_OK
 193      ){
 194       /* One (or both) of the named databases did not exist or an OOM
 195       ** error was hit. Or there is a transaction open on the destination
 196       ** database. The error has already been written into the pDestDb
 197       ** handle. All that is left to do here is free the sqlite3_backup
 198       ** structure.  */
 199       sqlite3_free(p);
 200       p = 0;
 201     }
 202   }
 203   if( p ){
 204     p->pSrc->nBackup++;
 205   }
 206
 207   sqlite3_mutex_leave(pDestDb->mutex);
 208   sqlite3_mutex_leave(pSrcDb->mutex);
 209   return p;
 210 }
 211
 212 /*
 213 ** Argument rc is an SQLite error code. Return true if this error is
 214 ** considered fatal if encountered during a backup operation. All errors
 215 ** are considered fatal except for SQLITE_BUSY and SQLITE_LOCKED.
 216 */
 217 static int isFatalError(int rc){
 218   return (rc!=SQLITE_OK && rc!=SQLITE_BUSY && ALWAYS(rc!=SQLITE_LOCKED));
 219 }
 220
 221 /*
 222 ** Parameter zSrcData points to a buffer containing the data for
 223 ** page iSrcPg from the source database. Copy this data into the
 224 ** destination database.
 225 */
 226 static int backupOnePage(
 227   sqlite3_backup *p,              /* Backup handle */
 228   Pgno iSrcPg,                    /* Source database page to backup */
 229   const u8 *zSrcData,             /* Source database page data */
 230   int bUpdate                     /* True for an update, false otherwise */
 231 ){
 232   Pager * const pDestPager = sqlite3BtreePager(p->pDest);
 233   const int nSrcPgsz = sqlite3BtreeGetPageSize(p->pSrc);
 234   int nDestPgsz = sqlite3BtreeGetPageSize(p->pDest);
 235   const int nCopy = MIN(nSrcPgsz, nDestPgsz);
 236   const i64 iEnd = (i64)iSrcPg*(i64)nSrcPgsz;
 237   int rc = SQLITE_OK;
 238   i64 iOff;
 239
 240   assert( sqlite3BtreeGetReserveNoMutex(p->pSrc)>=0 );
 241   assert( p->bDestLocked );
 242   assert( !isFatalError(p->rc) );
 243   assert( iSrcPg!=PENDING_BYTE_PAGE(p->pSrc->pBt) );
 244   assert( zSrcData );
 245   assert( nSrcPgsz==nDestPgsz || sqlite3PagerIsMemdb(pDestPager)==0 );
 246
 247   /* This loop runs once for each destination page spanned by the source
 248   ** page. For each iteration, variable iOff is set to the byte offset
 249   ** of the destination page.
 250   */
 251   for(iOff=iEnd-(i64)nSrcPgsz; rc==SQLITE_OK && iOff<iEnd; iOff+=nDestPgsz){
 252     DbPage *pDestPg = 0;
 253     Pgno iDest = (Pgno)(iOff/nDestPgsz)+1;
 254     if( iDest==PENDING_BYTE_PAGE(p->pDest->pBt) ) continue;
 255     if( SQLITE_OK==(rc = sqlite3PagerGet(pDestPager, iDest, &pDestPg, 0))
 256      && SQLITE_OK==(rc = sqlite3PagerWrite(pDestPg))
 257     ){
 258       const u8 *zIn = &zSrcData[iOff%nSrcPgsz];
 259       u8 *zDestData = sqlite3PagerGetData(pDestPg);
 260       u8 *zOut = &zDestData[iOff%nDestPgsz];
 261
 262       /* Copy the data from the source page into the destination page.
 263       ** Then clear the Btree layer MemPage.isInit flag. Both this module
 264       ** and the pager code use this trick (clearing the first byte
 265       ** of the page 'extra' space to invalidate the Btree layers
 266       ** cached parse of the page). MemPage.isInit is marked
 267       ** "MUST BE FIRST" for this purpose.
 268       */
 269       memcpy(zOut, zIn, nCopy);
 270       ((u8 *)sqlite3PagerGetExtra(pDestPg))[0] = 0;
 271       if( iOff==0 && bUpdate==0 ){
 272         sqlite3Put4byte(&zOut[28], sqlite3BtreeLastPage(p->pSrc));
 273       }
 274     }
 275     sqlite3PagerUnref(pDestPg);
 276   }
 277
 278   return rc;
 279 }
 280
 281 /*
 282 ** If pFile is currently larger than iSize bytes, then truncate it to
 283 ** exactly iSize bytes. If pFile is not larger than iSize bytes, then
 284 ** this function is a no-op.
 285 **
 286 ** Return SQLITE_OK if everything is successful, or an SQLite error
 287 ** code if an error occurs.
 288 */
 289 static int backupTruncateFile(sqlite3_file *pFile, i64 iSize){
 290   i64 iCurrent;
 291   int rc = sqlite3OsFileSize(pFile, &iCurrent);
 292   if( rc==SQLITE_OK && iCurrent>iSize ){
 293     rc = sqlite3OsTruncate(pFile, iSize);
 294   }
 295   return rc;
 296 }
 297
 298 /*
 299 ** Register this backup object with the associated source pager for
 300 ** callbacks when pages are changed or the cache invalidated.
 301 */
 302 static void attachBackupObject(sqlite3_backup *p){
 303   sqlite3_backup **pp;
 304   assert( sqlite3BtreeHoldsMutex(p->pSrc) );
 305   pp = sqlite3PagerBackupPtr(sqlite3BtreePager(p->pSrc));
 306   p->pNext = *pp;
 307   *pp = p;
 308   p->isAttached = 1;
 309 }
 310
 311 /*
 312 ** Copy nPage pages from the source b-tree to the destination.
 313 */
 314 int sqlite3_backup_step(sqlite3_backup *p, int nPage){
 315   int rc;
 316   int destMode;       /* Destination journal mode */
 317   int pgszSrc = 0;    /* Source page size */
 318   int pgszDest = 0;   /* Destination page size */
 319
 320 #ifdef SQLITE_ENABLE_API_ARMOR
 321   if( p==0 ) return SQLITE_MISUSE_BKPT;
 322 #endif
 323   sqlite3_mutex_enter(p->pSrcDb->mutex);
 324   sqlite3BtreeEnter(p->pSrc);
 325   if( p->pDestDb ){
 326     sqlite3_mutex_enter(p->pDestDb->mutex);
 327   }
 328
 329   rc = p->rc;
 330   if( !isFatalError(rc) ){
 331     Pager * const pSrcPager = sqlite3BtreePager(p->pSrc);     /* Source pager */
 332     Pager * const pDestPager = sqlite3BtreePager(p->pDest);   /* Dest pager */
 333     int ii;                            /* Iterator variable */
 334     int nSrcPage = -1;                 /* Size of source db in pages */
 335     int bCloseTrans = 0;               /* True if src db requires unlocking */
 336
 337     /* If the source pager is currently in a write-transaction, return
 338     ** SQLITE_BUSY immediately.
 339     */
 340     if( p->pDestDb && p->pSrc->pBt->inTransaction==TRANS_WRITE ){
 341       rc = SQLITE_BUSY;
 342     }else{
 343       rc = SQLITE_OK;
 344     }
 345
 346     /* If there is no open read-transaction on the source database, open
 347     ** one now. If a transaction is opened here, then it will be closed
 348     ** before this function exits.
 349     */
 350     if( rc==SQLITE_OK && SQLITE_TXN_NONE==sqlite3BtreeTxnState(p->pSrc) ){
 351       rc = sqlite3BtreeBeginTrans(p->pSrc, 0, 0);
 352       bCloseTrans = 1;
 353     }
 354
 355     /* If the destination database has not yet been locked (i.e. if this
 356     ** is the first call to backup_step() for the current backup operation),
 357     ** try to set its page size to the same as the source database. This
 358     ** is especially important on ZipVFS systems, as in that case it is
 359     ** not possible to create a database file that uses one page size by
 360     ** writing to it with another.  */
 361     if( p->bDestLocked==0 && rc==SQLITE_OK && setDestPgsz(p)==SQLITE_NOMEM ){
 362       rc = SQLITE_NOMEM;
 363     }
 364
 365     /* Lock the destination database, if it is not locked already. */
 366     if( SQLITE_OK==rc && p->bDestLocked==0
 367      && SQLITE_OK==(rc = sqlite3BtreeBeginTrans(p->pDest, 2,
 368                                                 (int*)&p->iDestSchema))
 369     ){
 370       p->bDestLocked = 1;
 371     }
 372
 373     /* Do not allow backup if the destination database is in WAL mode
 374     ** and the page sizes are different between source and destination */
 375     pgszSrc = sqlite3BtreeGetPageSize(p->pSrc);
 376     pgszDest = sqlite3BtreeGetPageSize(p->pDest);
 377     destMode = sqlite3PagerGetJournalMode(sqlite3BtreePager(p->pDest));
 378     if( SQLITE_OK==rc
 379      && (destMode==PAGER_JOURNALMODE_WAL || sqlite3PagerIsMemdb(pDestPager))
 380      && pgszSrc!=pgszDest
 381     ){
 382       rc = SQLITE_READONLY;
 383     }
 384
 385     /* Now that there is a read-lock on the source database, query the
 386     ** source pager for the number of pages in the database.
 387     */
 388     nSrcPage = (int)sqlite3BtreeLastPage(p->pSrc);
 389     assert( nSrcPage>=0 );
 390     for(ii=0; (nPage<0 || ii<nPage) && p->iNext<=(Pgno)nSrcPage && !rc; ii++){
 391       const Pgno iSrcPg = p->iNext;                 /* Source page number */
 392       if( iSrcPg!=PENDING_BYTE_PAGE(p->pSrc->pBt) ){
 393         DbPage *pSrcPg;                             /* Source page object */
 394         rc = sqlite3PagerGet(pSrcPager, iSrcPg, &pSrcPg,PAGER_GET_READONLY);
 395         if( rc==SQLITE_OK ){
 396           rc = backupOnePage(p, iSrcPg, sqlite3PagerGetData(pSrcPg), 0);
 397           sqlite3PagerUnref(pSrcPg);
 398         }
 399       }
 400       p->iNext++;
 401     }
 402     if( rc==SQLITE_OK ){
 403       p->nPagecount = nSrcPage;
 404       p->nRemaining = nSrcPage+1-p->iNext;
 405       if( p->iNext>(Pgno)nSrcPage ){
 406         rc = SQLITE_DONE;
 407       }else if( !p->isAttached ){
 408         attachBackupObject(p);
 409       }
 410     }
 411
 412     /* Update the schema version field in the destination database. This
 413     ** is to make sure that the schema-version really does change in
 414     ** the case where the source and destination databases have the
 415     ** same schema version.
 416     */
 417     if( rc==SQLITE_DONE ){
 418       if( nSrcPage==0 ){
 419         rc = sqlite3BtreeNewDb(p->pDest);
 420         nSrcPage = 1;
 421       }
 422       if( rc==SQLITE_OK || rc==SQLITE_DONE ){
 423         rc = sqlite3BtreeUpdateMeta(p->pDest,1,p->iDestSchema+1);
 424       }
 425       if( rc==SQLITE_OK ){
 426         if( p->pDestDb ){
 427           sqlite3ResetAllSchemasOfConnection(p->pDestDb);
 428         }
 429         if( destMode==PAGER_JOURNALMODE_WAL ){
 430           rc = sqlite3BtreeSetVersion(p->pDest, 2);
 431         }
 432       }
 433       if( rc==SQLITE_OK ){
 434         int nDestTruncate;
 435         /* Set nDestTruncate to the final number of pages in the destination
 436         ** database. The complication here is that the destination page
 437         ** size may be different to the source page size.
 438         **
 439         ** If the source page size is smaller than the destination page size,
 440         ** round up. In this case the call to sqlite3OsTruncate() below will
 441         ** fix the size of the file. However it is important to call
 442         ** sqlite3PagerTruncateImage() here so that any pages in the
 443         ** destination file that lie beyond the nDestTruncate page mark are
 444         ** journalled by PagerCommitPhaseOne() before they are destroyed
 445         ** by the file truncation.
 446         */
 447         assert( pgszSrc==sqlite3BtreeGetPageSize(p->pSrc) );
 448         assert( pgszDest==sqlite3BtreeGetPageSize(p->pDest) );
 449         if( pgszSrc<pgszDest ){
 450           int ratio = pgszDest/pgszSrc;
 451           nDestTruncate = (nSrcPage+ratio-1)/ratio;
 452           if( nDestTruncate==(int)PENDING_BYTE_PAGE(p->pDest->pBt) ){
 453             nDestTruncate--;
 454           }
 455         }else{
 456           nDestTruncate = nSrcPage * (pgszSrc/pgszDest);
 457         }
 458         assert( nDestTruncate>0 );
 459
 460         if( pgszSrc<pgszDest ){
 461           /* If the source page-size is smaller than the destination page-size,
 462           ** two extra things may need to happen:
 463           **
 464           **   * The destination may need to be truncated, and
 465           **
 466           **   * Data stored on the pages immediately following the
 467           **     pending-byte page in the source database may need to be
 468           **     copied into the destination database.
 469           */
 470           const i64 iSize = (i64)pgszSrc * (i64)nSrcPage;
 471           sqlite3_file * const pFile = sqlite3PagerFile(pDestPager);
 472           Pgno iPg;
 473           int nDstPage;
 474           i64 iOff;
 475           i64 iEnd;
 476
 477           assert( pFile );
 478           assert( nDestTruncate==0
 479               || (i64)nDestTruncate*(i64)pgszDest >= iSize || (
 480                 nDestTruncate==(int)(PENDING_BYTE_PAGE(p->pDest->pBt)-1)
 481              && iSize>=PENDING_BYTE && iSize<=PENDING_BYTE+pgszDest
 482           ));
 483
 484           /* This block ensures that all data required to recreate the original
 485           ** database has been stored in the journal for pDestPager and the
 486           ** journal synced to disk. So at this point we may safely modify
 487           ** the database file in any way, knowing that if a power failure
 488           ** occurs, the original database will be reconstructed from the
 489           ** journal file.  */
 490           sqlite3PagerPagecount(pDestPager, &nDstPage);
 491           for(iPg=nDestTruncate; rc==SQLITE_OK && iPg<=(Pgno)nDstPage; iPg++){
 492             if( iPg!=PENDING_BYTE_PAGE(p->pDest->pBt) ){
 493               DbPage *pPg;
 494               rc = sqlite3PagerGet(pDestPager, iPg, &pPg, 0);
 495               if( rc==SQLITE_OK ){
 496                 rc = sqlite3PagerWrite(pPg);
 497                 sqlite3PagerUnref(pPg);
 498               }
 499             }
 500           }
 501           if( rc==SQLITE_OK ){
 502             rc = sqlite3PagerCommitPhaseOne(pDestPager, 0, 1);
 503           }
 504
 505           /* Write the extra pages and truncate the database file as required */
 506           iEnd = MIN(PENDING_BYTE + pgszDest, iSize);
 507           for(
 508             iOff=PENDING_BYTE+pgszSrc;
 509             rc==SQLITE_OK && iOff<iEnd;
 510             iOff+=pgszSrc
 511           ){
 512             PgHdr *pSrcPg = 0;
 513             const Pgno iSrcPg = (Pgno)((iOff/pgszSrc)+1);
 514             rc = sqlite3PagerGet(pSrcPager, iSrcPg, &pSrcPg, 0);
 515             if( rc==SQLITE_OK ){
 516               u8 *zData = sqlite3PagerGetData(pSrcPg);
 517               rc = sqlite3OsWrite(pFile, zData, pgszSrc, iOff);
 518             }
 519             sqlite3PagerUnref(pSrcPg);
 520           }
 521           if( rc==SQLITE_OK ){
 522             rc = backupTruncateFile(pFile, iSize);
 523           }
 524
 525           /* Sync the database file to disk. */
 526           if( rc==SQLITE_OK ){
 527             rc = sqlite3PagerSync(pDestPager, 0);
 528           }
 529         }else{
 530           sqlite3PagerTruncateImage(pDestPager, nDestTruncate);
 531           rc = sqlite3PagerCommitPhaseOne(pDestPager, 0, 0);
 532         }
 533
 534         /* Finish committing the transaction to the destination database. */
 535         if( SQLITE_OK==rc
 536          && SQLITE_OK==(rc = sqlite3BtreeCommitPhaseTwo(p->pDest, 0))
 537         ){
 538           rc = SQLITE_DONE;
 539         }
 540       }
 541     }
 542
 543     /* If bCloseTrans is true, then this function opened a read transaction
 544     ** on the source database. Close the read transaction here. There is
 545     ** no need to check the return values of the btree methods here, as
 546     ** "committing" a read-only transaction cannot fail.
 547     */
 548     if( bCloseTrans ){
 549       TESTONLY( int rc2 );
 550       TESTONLY( rc2  = ) sqlite3BtreeCommitPhaseOne(p->pSrc, 0);
 551       TESTONLY( rc2 |= ) sqlite3BtreeCommitPhaseTwo(p->pSrc, 0);
 552       assert( rc2==SQLITE_OK );
 553     }
 554
 555     if( rc==SQLITE_IOERR_NOMEM ){
 556       rc = SQLITE_NOMEM_BKPT;
 557     }
 558     p->rc = rc;
 559   }
 560   if( p->pDestDb ){
 561     sqlite3_mutex_leave(p->pDestDb->mutex);
 562   }
 563   sqlite3BtreeLeave(p->pSrc);
 564   sqlite3_mutex_leave(p->pSrcDb->mutex);
 565   return rc;
 566 }
 567
 568 /*
 569 ** Release all resources associated with an sqlite3_backup* handle.
 570 */
 571 int sqlite3_backup_finish(sqlite3_backup *p){
 572   sqlite3_backup **pp;                 /* Ptr to head of pagers backup list */
 573   sqlite3 *pSrcDb;                     /* Source database connection */
 574   int rc;                              /* Value to return */
 575
 576   /* Enter the mutexes */
 577   if( p==0 ) return SQLITE_OK;
 578   pSrcDb = p->pSrcDb;
 579   sqlite3_mutex_enter(pSrcDb->mutex);
 580   sqlite3BtreeEnter(p->pSrc);
 581   if( p->pDestDb ){
 582     sqlite3_mutex_enter(p->pDestDb->mutex);
 583   }
 584
 585   /* Detach this backup from the source pager. */
 586   if( p->pDestDb ){
 587     p->pSrc->nBackup--;
 588   }
 589   if( p->isAttached ){
 590     pp = sqlite3PagerBackupPtr(sqlite3BtreePager(p->pSrc));
 591     assert( pp!=0 );
 592     while( *pp!=p ){
 593       pp = &(*pp)->pNext;
 594       assert( pp!=0 );
 595     }
 596     *pp = p->pNext;
 597   }
 598
 599   /* If a transaction is still open on the Btree, roll it back. */
 600   sqlite3BtreeRollback(p->pDest, SQLITE_OK, 0);
 601
 602   /* Set the error code of the destination database handle. */
 603   rc = (p->rc==SQLITE_DONE) ? SQLITE_OK : p->rc;
 604   if( p->pDestDb ){
 605     sqlite3Error(p->pDestDb, rc);
 606
 607     /* Exit the mutexes and free the backup context structure. */
 608     sqlite3LeaveMutexAndCloseZombie(p->pDestDb);
 609   }
 610   sqlite3BtreeLeave(p->pSrc);
 611   if( p->pDestDb ){
 612     /* EVIDENCE-OF: R-64852-21591 The sqlite3_backup object is created by a
 613     ** call to sqlite3_backup_init() and is destroyed by a call to
 614     ** sqlite3_backup_finish(). */
 615     sqlite3_free(p);
 616   }
 617   sqlite3LeaveMutexAndCloseZombie(pSrcDb);
 618   return rc;
 619 }
 620
 621 /*
 622 ** Return the number of pages still to be backed up as of the most recent
 623 ** call to sqlite3_backup_step().
 624 */
 625 int sqlite3_backup_remaining(sqlite3_backup *p){
 626 #ifdef SQLITE_ENABLE_API_ARMOR
 627   if( p==0 ){
 628     (void)SQLITE_MISUSE_BKPT;
 629     return 0;
 630   }
 631 #endif
 632   return p->nRemaining;
 633 }
 634
 635 /*
 636 ** Return the total number of pages in the source database as of the most
 637 ** recent call to sqlite3_backup_step().
 638 */
 639 int sqlite3_backup_pagecount(sqlite3_backup *p){
 640 #ifdef SQLITE_ENABLE_API_ARMOR
 641   if( p==0 ){
 642     (void)SQLITE_MISUSE_BKPT;
 643     return 0;
 644   }
 645 #endif
 646   return p->nPagecount;
 647 }
 648
 649 /*
 650 ** This function is called after the contents of page iPage of the
 651 ** source database have been modified. If page iPage has already been
 652 ** copied into the destination database, then the data written to the
 653 ** destination is now invalidated. The destination copy of iPage needs
 654 ** to be updated with the new data before the backup operation is
 655 ** complete.
 656 **
 657 ** It is assumed that the mutex associated with the BtShared object
 658 ** corresponding to the source database is held when this function is
 659 ** called.
 660 */
 661 static SQLITE_NOINLINE void backupUpdate(
 662   sqlite3_backup *p,
 663   Pgno iPage,
 664   const u8 *aData
 665 ){
 666   assert( p!=0 );
 667   do{
 668     assert( sqlite3_mutex_held(p->pSrc->pBt->mutex) );
 669     if( !isFatalError(p->rc) && iPage<p->iNext ){
 670       /* The backup process p has already copied page iPage. But now it
 671       ** has been modified by a transaction on the source pager. Copy
 672       ** the new data into the backup.
 673       */
 674       int rc;
 675       assert( p->pDestDb );
 676       sqlite3_mutex_enter(p->pDestDb->mutex);
 677       rc = backupOnePage(p, iPage, aData, 1);
 678       sqlite3_mutex_leave(p->pDestDb->mutex);
 679       assert( rc!=SQLITE_BUSY && rc!=SQLITE_LOCKED );
 680       if( rc!=SQLITE_OK ){
 681         p->rc = rc;
 682       }
 683     }
 684   }while( (p = p->pNext)!=0 );
 685 }
 686 void sqlite3BackupUpdate(sqlite3_backup *pBackup, Pgno iPage, const u8 *aData){
 687   if( pBackup ) backupUpdate(pBackup, iPage, aData);
 688 }
 689
 690 /*
 691 ** Restart the backup process. This is called when the pager layer
 692 ** detects that the database has been modified by an external database
 693 ** connection. In this case there is no way of knowing which of the
 694 ** pages that have been copied into the destination database are still
 695 ** valid and which are not, so the entire process needs to be restarted.
 696 **
 697 ** It is assumed that the mutex associated with the BtShared object
 698 ** corresponding to the source database is held when this function is
 699 ** called.
 700 */
 701 void sqlite3BackupRestart(sqlite3_backup *pBackup){
 702   sqlite3_backup *p;                   /* Iterator variable */
 703   for(p=pBackup; p; p=p->pNext){
 704     assert( sqlite3_mutex_held(p->pSrc->pBt->mutex) );
 705     p->iNext = 1;
 706   }
 707 }
 708
 709 #ifndef SQLITE_OMIT_VACUUM
 710 /*
 711 ** Copy the complete content of pBtFrom into pBtTo.  A transaction
 712 ** must be active for both files.
 713 **
 714 ** The size of file pTo may be reduced by this operation. If anything
 715 ** goes wrong, the transaction on pTo is rolled back. If successful, the
 716 ** transaction is committed before returning.
 717 */
 718 int sqlite3BtreeCopyFile(Btree *pTo, Btree *pFrom){
 719   int rc;
 720   sqlite3_file *pFd;              /* File descriptor for database pTo */
 721   sqlite3_backup b;
 722   sqlite3BtreeEnter(pTo);
 723   sqlite3BtreeEnter(pFrom);
 724
 725   assert( sqlite3BtreeTxnState(pTo)==SQLITE_TXN_WRITE );
 726   pFd = sqlite3PagerFile(sqlite3BtreePager(pTo));
 727   if( pFd->pMethods ){
 728     i64 nByte = sqlite3BtreeGetPageSize(pFrom)*(i64)sqlite3BtreeLastPage(pFrom);
 729     rc = sqlite3OsFileControl(pFd, SQLITE_FCNTL_OVERWRITE, &nByte);
 730     if( rc==SQLITE_NOTFOUND ) rc = SQLITE_OK;
 731     if( rc ) goto copy_finished;
 732   }
 733
 734   /* Set up an sqlite3_backup object. sqlite3_backup.pDestDb must be set
 735   ** to 0. This is used by the implementations of sqlite3_backup_step()
 736   ** and sqlite3_backup_finish() to detect that they are being called
 737   ** from this function, not directly by the user.
 738   */
 739   memset(&b, 0, sizeof(b));
 740   b.pSrcDb = pFrom->db;
 741   b.pSrc = pFrom;
 742   b.pDest = pTo;
 743   b.iNext = 1;
 744
 745   /* 0x7FFFFFFF is the hard limit for the number of pages in a database
 746   ** file. By passing this as the number of pages to copy to
 747   ** sqlite3_backup_step(), we can guarantee that the copy finishes
 748   ** within a single call (unless an error occurs). The assert() statement
 749   ** checks this assumption - (p->rc) should be set to either SQLITE_DONE
 750   ** or an error code.  */
 751   sqlite3_backup_step(&b, 0x7FFFFFFF);
 752   assert( b.rc!=SQLITE_OK );
 753
 754   rc = sqlite3_backup_finish(&b);
 755   if( rc==SQLITE_OK ){
 756     pTo->pBt->btsFlags &= ~BTS_PAGESIZE_FIXED;
 757   }else{
 758     sqlite3PagerClearCache(sqlite3BtreePager(b.pDest));
 759   }
 760
 761   assert( sqlite3BtreeTxnState(pTo)!=SQLITE_TXN_WRITE );
 762 copy_finished:
 763   sqlite3BtreeLeave(pFrom);
 764   sqlite3BtreeLeave(pTo);
 765   return rc;
 766 }
 767 #endif /* SQLITE_OMIT_VACUUM */