000001  /*
000002  ** 2009 January 28
000003  **
000004  ** The author disclaims copyright to this source code.  In place of
000005  ** a legal notice, here is a blessing:
000006  **
000007  **    May you do good and not evil.
000008  **    May you find forgiveness for yourself and forgive others.
000009  **    May you share freely, never taking more than you give.
000010  **
000011  *************************************************************************
000012  ** This file contains the implementation of the sqlite3_backup_XXX() 
000013  ** API functions and the related features.
000014  */
000015  #include "sqliteInt.h"
000016  #include "btreeInt.h"
000017  
000018  /*
000019  ** Structure allocated for each backup operation.
000020  */
000021  struct sqlite3_backup {
000022    sqlite3* pDestDb;        /* Destination database handle */
000023    Btree *pDest;            /* Destination b-tree file */
000024    u32 iDestSchema;         /* Original schema cookie in destination */
000025    int bDestLocked;         /* True once a write-transaction is open on pDest */
000026  
000027    Pgno iNext;              /* Page number of the next source page to copy */
000028    sqlite3* pSrcDb;         /* Source database handle */
000029    Btree *pSrc;             /* Source b-tree file */
000030  
000031    int rc;                  /* Backup process error code */
000032  
000033    /* These two variables are set by every call to backup_step(). They are
000034    ** read by calls to backup_remaining() and backup_pagecount().
000035    */
000036    Pgno nRemaining;         /* Number of pages left to copy */
000037    Pgno nPagecount;         /* Total number of pages to copy */
000038  
000039    int isAttached;          /* True once backup has been registered with pager */
000040    sqlite3_backup *pNext;   /* Next backup associated with source pager */
000041  };
000042  
000043  /*
000044  ** THREAD SAFETY NOTES:
000045  **
000046  **   Once it has been created using backup_init(), a single sqlite3_backup
000047  **   structure may be accessed via two groups of thread-safe entry points:
000048  **
000049  **     * Via the sqlite3_backup_XXX() API function backup_step() and 
000050  **       backup_finish(). Both these functions obtain the source database
000051  **       handle mutex and the mutex associated with the source BtShared 
000052  **       structure, in that order.
000053  **
000054  **     * Via the BackupUpdate() and BackupRestart() functions, which are
000055  **       invoked by the pager layer to report various state changes in
000056  **       the page cache associated with the source database. The mutex
000057  **       associated with the source database BtShared structure will always 
000058  **       be held when either of these functions are invoked.
000059  **
000060  **   The other sqlite3_backup_XXX() API functions, backup_remaining() and
000061  **   backup_pagecount() are not thread-safe functions. If they are called
000062  **   while some other thread is calling backup_step() or backup_finish(),
000063  **   the values returned may be invalid. There is no way for a call to
000064  **   BackupUpdate() or BackupRestart() to interfere with backup_remaining()
000065  **   or backup_pagecount().
000066  **
000067  **   Depending on the SQLite configuration, the database handles and/or
000068  **   the Btree objects may have their own mutexes that require locking.
000069  **   Non-sharable Btrees (in-memory databases for example), do not have
000070  **   associated mutexes.
000071  */
000072  
000073  /*
000074  ** Return a pointer corresponding to database zDb (i.e. "main", "temp")
000075  ** in connection handle pDb. If such a database cannot be found, return
000076  ** a NULL pointer and write an error message to pErrorDb.
000077  **
000078  ** If the "temp" database is requested, it may need to be opened by this 
000079  ** function. If an error occurs while doing so, return 0 and write an 
000080  ** error message to pErrorDb.
000081  */
000082  static Btree *findBtree(sqlite3 *pErrorDb, sqlite3 *pDb, const char *zDb){
000083    int i = sqlite3FindDbName(pDb, zDb);
000084  
000085    if( i==1 ){
000086      Parse sParse;
000087      int rc = 0;
000088      memset(&sParse, 0, sizeof(sParse));
000089      sParse.db = pDb;
000090      if( sqlite3OpenTempDatabase(&sParse) ){
000091        sqlite3ErrorWithMsg(pErrorDb, sParse.rc, "%s", sParse.zErrMsg);
000092        rc = SQLITE_ERROR;
000093      }
000094      sqlite3DbFree(pErrorDb, sParse.zErrMsg);
000095      sqlite3ParserReset(&sParse);
000096      if( rc ){
000097        return 0;
000098      }
000099    }
000100  
000101    if( i<0 ){
000102      sqlite3ErrorWithMsg(pErrorDb, SQLITE_ERROR, "unknown database %s", zDb);
000103      return 0;
000104    }
000105  
000106    return pDb->aDb[i].pBt;
000107  }
000108  
000109  /*
000110  ** Attempt to set the page size of the destination to match the page size
000111  ** of the source.
000112  */
000113  static int setDestPgsz(sqlite3_backup *p){
000114    int rc;
000115    rc = sqlite3BtreeSetPageSize(p->pDest,sqlite3BtreeGetPageSize(p->pSrc),-1,0);
000116    return rc;
000117  }
000118  
000119  /*
000120  ** Check that there is no open read-transaction on the b-tree passed as the
000121  ** second argument. If there is not, return SQLITE_OK. Otherwise, if there
000122  ** is an open read-transaction, return SQLITE_ERROR and leave an error 
000123  ** message in database handle db.
000124  */
000125  static int checkReadTransaction(sqlite3 *db, Btree *p){
000126    if( sqlite3BtreeIsInReadTrans(p) ){
000127      sqlite3ErrorWithMsg(db, SQLITE_ERROR, "destination database is in use");
000128      return SQLITE_ERROR;
000129    }
000130    return SQLITE_OK;
000131  }
000132  
000133  /*
000134  ** Create an sqlite3_backup process to copy the contents of zSrcDb from
000135  ** connection handle pSrcDb to zDestDb in pDestDb. If successful, return
000136  ** a pointer to the new sqlite3_backup object.
000137  **
000138  ** If an error occurs, NULL is returned and an error code and error message
000139  ** stored in database handle pDestDb.
000140  */
000141  sqlite3_backup *sqlite3_backup_init(
000142    sqlite3* pDestDb,                     /* Database to write to */
000143    const char *zDestDb,                  /* Name of database within pDestDb */
000144    sqlite3* pSrcDb,                      /* Database connection to read from */
000145    const char *zSrcDb                    /* Name of database within pSrcDb */
000146  ){
000147    sqlite3_backup *p;                    /* Value to return */
000148  
000149  #ifdef SQLITE_ENABLE_API_ARMOR
000150    if( !sqlite3SafetyCheckOk(pSrcDb)||!sqlite3SafetyCheckOk(pDestDb) ){
000151      (void)SQLITE_MISUSE_BKPT;
000152      return 0;
000153    }
000154  #endif
000155  
000156    /* Lock the source database handle. The destination database
000157    ** handle is not locked in this routine, but it is locked in
000158    ** sqlite3_backup_step(). The user is required to ensure that no
000159    ** other thread accesses the destination handle for the duration
000160    ** of the backup operation.  Any attempt to use the destination
000161    ** database connection while a backup is in progress may cause
000162    ** a malfunction or a deadlock.
000163    */
000164    sqlite3_mutex_enter(pSrcDb->mutex);
000165    sqlite3_mutex_enter(pDestDb->mutex);
000166  
000167    if( pSrcDb==pDestDb ){
000168      sqlite3ErrorWithMsg(
000169          pDestDb, SQLITE_ERROR, "source and destination must be distinct"
000170      );
000171      p = 0;
000172    }else {
000173      /* Allocate space for a new sqlite3_backup object...
000174      ** EVIDENCE-OF: R-64852-21591 The sqlite3_backup object is created by a
000175      ** call to sqlite3_backup_init() and is destroyed by a call to
000176      ** sqlite3_backup_finish(). */
000177      p = (sqlite3_backup *)sqlite3MallocZero(sizeof(sqlite3_backup));
000178      if( !p ){
000179        sqlite3Error(pDestDb, SQLITE_NOMEM_BKPT);
000180      }
000181    }
000182  
000183    /* If the allocation succeeded, populate the new object. */
000184    if( p ){
000185      p->pSrc = findBtree(pDestDb, pSrcDb, zSrcDb);
000186      p->pDest = findBtree(pDestDb, pDestDb, zDestDb);
000187      p->pDestDb = pDestDb;
000188      p->pSrcDb = pSrcDb;
000189      p->iNext = 1;
000190      p->isAttached = 0;
000191  
000192      if( 0==p->pSrc || 0==p->pDest 
000193       || checkReadTransaction(pDestDb, p->pDest)!=SQLITE_OK 
000194       ){
000195        /* One (or both) of the named databases did not exist or an OOM
000196        ** error was hit. Or there is a transaction open on the destination
000197        ** database. The error has already been written into the pDestDb 
000198        ** handle. All that is left to do here is free the sqlite3_backup 
000199        ** structure.  */
000200        sqlite3_free(p);
000201        p = 0;
000202      }
000203    }
000204    if( p ){
000205      p->pSrc->nBackup++;
000206    }
000207  
000208    sqlite3_mutex_leave(pDestDb->mutex);
000209    sqlite3_mutex_leave(pSrcDb->mutex);
000210    return p;
000211  }
000212  
000213  /*
000214  ** Argument rc is an SQLite error code. Return true if this error is 
000215  ** considered fatal if encountered during a backup operation. All errors
000216  ** are considered fatal except for SQLITE_BUSY and SQLITE_LOCKED.
000217  */
000218  static int isFatalError(int rc){
000219    return (rc!=SQLITE_OK && rc!=SQLITE_BUSY && ALWAYS(rc!=SQLITE_LOCKED));
000220  }
000221  
000222  /*
000223  ** Parameter zSrcData points to a buffer containing the data for 
000224  ** page iSrcPg from the source database. Copy this data into the 
000225  ** destination database.
000226  */
000227  static int backupOnePage(
000228    sqlite3_backup *p,              /* Backup handle */
000229    Pgno iSrcPg,                    /* Source database page to backup */
000230    const u8 *zSrcData,             /* Source database page data */
000231    int bUpdate                     /* True for an update, false otherwise */
000232  ){
000233    Pager * const pDestPager = sqlite3BtreePager(p->pDest);
000234    const int nSrcPgsz = sqlite3BtreeGetPageSize(p->pSrc);
000235    int nDestPgsz = sqlite3BtreeGetPageSize(p->pDest);
000236    const int nCopy = MIN(nSrcPgsz, nDestPgsz);
000237    const i64 iEnd = (i64)iSrcPg*(i64)nSrcPgsz;
000238  #ifdef SQLITE_HAS_CODEC
000239    /* Use BtreeGetReserveNoMutex() for the source b-tree, as although it is
000240    ** guaranteed that the shared-mutex is held by this thread, handle
000241    ** p->pSrc may not actually be the owner.  */
000242    int nSrcReserve = sqlite3BtreeGetReserveNoMutex(p->pSrc);
000243    int nDestReserve = sqlite3BtreeGetOptimalReserve(p->pDest);
000244  #endif
000245    int rc = SQLITE_OK;
000246    i64 iOff;
000247  
000248    assert( sqlite3BtreeGetReserveNoMutex(p->pSrc)>=0 );
000249    assert( p->bDestLocked );
000250    assert( !isFatalError(p->rc) );
000251    assert( iSrcPg!=PENDING_BYTE_PAGE(p->pSrc->pBt) );
000252    assert( zSrcData );
000253  
000254    /* Catch the case where the destination is an in-memory database and the
000255    ** page sizes of the source and destination differ. 
000256    */
000257    if( nSrcPgsz!=nDestPgsz && sqlite3PagerIsMemdb(pDestPager) ){
000258      rc = SQLITE_READONLY;
000259    }
000260  
000261  #ifdef SQLITE_HAS_CODEC
000262    /* Backup is not possible if the page size of the destination is changing
000263    ** and a codec is in use.
000264    */
000265    if( nSrcPgsz!=nDestPgsz && sqlite3PagerGetCodec(pDestPager)!=0 ){
000266      rc = SQLITE_READONLY;
000267    }
000268  
000269    /* Backup is not possible if the number of bytes of reserve space differ
000270    ** between source and destination.  If there is a difference, try to
000271    ** fix the destination to agree with the source.  If that is not possible,
000272    ** then the backup cannot proceed.
000273    */
000274    if( nSrcReserve!=nDestReserve ){
000275      u32 newPgsz = nSrcPgsz;
000276      rc = sqlite3PagerSetPagesize(pDestPager, &newPgsz, nSrcReserve);
000277      if( rc==SQLITE_OK && newPgsz!=nSrcPgsz ) rc = SQLITE_READONLY;
000278    }
000279  #endif
000280  
000281    /* This loop runs once for each destination page spanned by the source 
000282    ** page. For each iteration, variable iOff is set to the byte offset
000283    ** of the destination page.
000284    */
000285    for(iOff=iEnd-(i64)nSrcPgsz; rc==SQLITE_OK && iOff<iEnd; iOff+=nDestPgsz){
000286      DbPage *pDestPg = 0;
000287      Pgno iDest = (Pgno)(iOff/nDestPgsz)+1;
000288      if( iDest==PENDING_BYTE_PAGE(p->pDest->pBt) ) continue;
000289      if( SQLITE_OK==(rc = sqlite3PagerGet(pDestPager, iDest, &pDestPg, 0))
000290       && SQLITE_OK==(rc = sqlite3PagerWrite(pDestPg))
000291      ){
000292        const u8 *zIn = &zSrcData[iOff%nSrcPgsz];
000293        u8 *zDestData = sqlite3PagerGetData(pDestPg);
000294        u8 *zOut = &zDestData[iOff%nDestPgsz];
000295  
000296        /* Copy the data from the source page into the destination page.
000297        ** Then clear the Btree layer MemPage.isInit flag. Both this module
000298        ** and the pager code use this trick (clearing the first byte
000299        ** of the page 'extra' space to invalidate the Btree layers
000300        ** cached parse of the page). MemPage.isInit is marked 
000301        ** "MUST BE FIRST" for this purpose.
000302        */
000303        memcpy(zOut, zIn, nCopy);
000304        ((u8 *)sqlite3PagerGetExtra(pDestPg))[0] = 0;
000305        if( iOff==0 && bUpdate==0 ){
000306          sqlite3Put4byte(&zOut[28], sqlite3BtreeLastPage(p->pSrc));
000307        }
000308      }
000309      sqlite3PagerUnref(pDestPg);
000310    }
000311  
000312    return rc;
000313  }
000314  
000315  /*
000316  ** If pFile is currently larger than iSize bytes, then truncate it to
000317  ** exactly iSize bytes. If pFile is not larger than iSize bytes, then
000318  ** this function is a no-op.
000319  **
000320  ** Return SQLITE_OK if everything is successful, or an SQLite error 
000321  ** code if an error occurs.
000322  */
000323  static int backupTruncateFile(sqlite3_file *pFile, i64 iSize){
000324    i64 iCurrent;
000325    int rc = sqlite3OsFileSize(pFile, &iCurrent);
000326    if( rc==SQLITE_OK && iCurrent>iSize ){
000327      rc = sqlite3OsTruncate(pFile, iSize);
000328    }
000329    return rc;
000330  }
000331  
000332  /*
000333  ** Register this backup object with the associated source pager for
000334  ** callbacks when pages are changed or the cache invalidated.
000335  */
000336  static void attachBackupObject(sqlite3_backup *p){
000337    sqlite3_backup **pp;
000338    assert( sqlite3BtreeHoldsMutex(p->pSrc) );
000339    pp = sqlite3PagerBackupPtr(sqlite3BtreePager(p->pSrc));
000340    p->pNext = *pp;
000341    *pp = p;
000342    p->isAttached = 1;
000343  }
000344  
000345  /*
000346  ** Copy nPage pages from the source b-tree to the destination.
000347  */
000348  int sqlite3_backup_step(sqlite3_backup *p, int nPage){
000349    int rc;
000350    int destMode;       /* Destination journal mode */
000351    int pgszSrc = 0;    /* Source page size */
000352    int pgszDest = 0;   /* Destination page size */
000353  
000354  #ifdef SQLITE_ENABLE_API_ARMOR
000355    if( p==0 ) return SQLITE_MISUSE_BKPT;
000356  #endif
000357    sqlite3_mutex_enter(p->pSrcDb->mutex);
000358    sqlite3BtreeEnter(p->pSrc);
000359    if( p->pDestDb ){
000360      sqlite3_mutex_enter(p->pDestDb->mutex);
000361    }
000362  
000363    rc = p->rc;
000364    if( !isFatalError(rc) ){
000365      Pager * const pSrcPager = sqlite3BtreePager(p->pSrc);     /* Source pager */
000366      Pager * const pDestPager = sqlite3BtreePager(p->pDest);   /* Dest pager */
000367      int ii;                            /* Iterator variable */
000368      int nSrcPage = -1;                 /* Size of source db in pages */
000369      int bCloseTrans = 0;               /* True if src db requires unlocking */
000370  
000371      /* If the source pager is currently in a write-transaction, return
000372      ** SQLITE_BUSY immediately.
000373      */
000374      if( p->pDestDb && p->pSrc->pBt->inTransaction==TRANS_WRITE ){
000375        rc = SQLITE_BUSY;
000376      }else{
000377        rc = SQLITE_OK;
000378      }
000379  
000380      /* If there is no open read-transaction on the source database, open
000381      ** one now. If a transaction is opened here, then it will be closed
000382      ** before this function exits.
000383      */
000384      if( rc==SQLITE_OK && 0==sqlite3BtreeIsInReadTrans(p->pSrc) ){
000385        rc = sqlite3BtreeBeginTrans(p->pSrc, 0, 0);
000386        bCloseTrans = 1;
000387      }
000388  
000389      /* If the destination database has not yet been locked (i.e. if this
000390      ** is the first call to backup_step() for the current backup operation),
000391      ** try to set its page size to the same as the source database. This
000392      ** is especially important on ZipVFS systems, as in that case it is
000393      ** not possible to create a database file that uses one page size by
000394      ** writing to it with another.  */
000395      if( p->bDestLocked==0 && rc==SQLITE_OK && setDestPgsz(p)==SQLITE_NOMEM ){
000396        rc = SQLITE_NOMEM;
000397      }
000398  
000399      /* Lock the destination database, if it is not locked already. */
000400      if( SQLITE_OK==rc && p->bDestLocked==0
000401       && SQLITE_OK==(rc = sqlite3BtreeBeginTrans(p->pDest, 2,
000402                                                  (int*)&p->iDestSchema)) 
000403      ){
000404        p->bDestLocked = 1;
000405      }
000406  
000407      /* Do not allow backup if the destination database is in WAL mode
000408      ** and the page sizes are different between source and destination */
000409      pgszSrc = sqlite3BtreeGetPageSize(p->pSrc);
000410      pgszDest = sqlite3BtreeGetPageSize(p->pDest);
000411      destMode = sqlite3PagerGetJournalMode(sqlite3BtreePager(p->pDest));
000412      if( SQLITE_OK==rc && destMode==PAGER_JOURNALMODE_WAL && pgszSrc!=pgszDest ){
000413        rc = SQLITE_READONLY;
000414      }
000415    
000416      /* Now that there is a read-lock on the source database, query the
000417      ** source pager for the number of pages in the database.
000418      */
000419      nSrcPage = (int)sqlite3BtreeLastPage(p->pSrc);
000420      assert( nSrcPage>=0 );
000421      for(ii=0; (nPage<0 || ii<nPage) && p->iNext<=(Pgno)nSrcPage && !rc; ii++){
000422        const Pgno iSrcPg = p->iNext;                 /* Source page number */
000423        if( iSrcPg!=PENDING_BYTE_PAGE(p->pSrc->pBt) ){
000424          DbPage *pSrcPg;                             /* Source page object */
000425          rc = sqlite3PagerGet(pSrcPager, iSrcPg, &pSrcPg,PAGER_GET_READONLY);
000426          if( rc==SQLITE_OK ){
000427            rc = backupOnePage(p, iSrcPg, sqlite3PagerGetData(pSrcPg), 0);
000428            sqlite3PagerUnref(pSrcPg);
000429          }
000430        }
000431        p->iNext++;
000432      }
000433      if( rc==SQLITE_OK ){
000434        p->nPagecount = nSrcPage;
000435        p->nRemaining = nSrcPage+1-p->iNext;
000436        if( p->iNext>(Pgno)nSrcPage ){
000437          rc = SQLITE_DONE;
000438        }else if( !p->isAttached ){
000439          attachBackupObject(p);
000440        }
000441      }
000442    
000443      /* Update the schema version field in the destination database. This
000444      ** is to make sure that the schema-version really does change in
000445      ** the case where the source and destination databases have the
000446      ** same schema version.
000447      */
000448      if( rc==SQLITE_DONE ){
000449        if( nSrcPage==0 ){
000450          rc = sqlite3BtreeNewDb(p->pDest);
000451          nSrcPage = 1;
000452        }
000453        if( rc==SQLITE_OK || rc==SQLITE_DONE ){
000454          rc = sqlite3BtreeUpdateMeta(p->pDest,1,p->iDestSchema+1);
000455        }
000456        if( rc==SQLITE_OK ){
000457          if( p->pDestDb ){
000458            sqlite3ResetAllSchemasOfConnection(p->pDestDb);
000459          }
000460          if( destMode==PAGER_JOURNALMODE_WAL ){
000461            rc = sqlite3BtreeSetVersion(p->pDest, 2);
000462          }
000463        }
000464        if( rc==SQLITE_OK ){
000465          int nDestTruncate;
000466          /* Set nDestTruncate to the final number of pages in the destination
000467          ** database. The complication here is that the destination page
000468          ** size may be different to the source page size. 
000469          **
000470          ** If the source page size is smaller than the destination page size, 
000471          ** round up. In this case the call to sqlite3OsTruncate() below will
000472          ** fix the size of the file. However it is important to call
000473          ** sqlite3PagerTruncateImage() here so that any pages in the 
000474          ** destination file that lie beyond the nDestTruncate page mark are
000475          ** journalled by PagerCommitPhaseOne() before they are destroyed
000476          ** by the file truncation.
000477          */
000478          assert( pgszSrc==sqlite3BtreeGetPageSize(p->pSrc) );
000479          assert( pgszDest==sqlite3BtreeGetPageSize(p->pDest) );
000480          if( pgszSrc<pgszDest ){
000481            int ratio = pgszDest/pgszSrc;
000482            nDestTruncate = (nSrcPage+ratio-1)/ratio;
000483            if( nDestTruncate==(int)PENDING_BYTE_PAGE(p->pDest->pBt) ){
000484              nDestTruncate--;
000485            }
000486          }else{
000487            nDestTruncate = nSrcPage * (pgszSrc/pgszDest);
000488          }
000489          assert( nDestTruncate>0 );
000490  
000491          if( pgszSrc<pgszDest ){
000492            /* If the source page-size is smaller than the destination page-size,
000493            ** two extra things may need to happen:
000494            **
000495            **   * The destination may need to be truncated, and
000496            **
000497            **   * Data stored on the pages immediately following the 
000498            **     pending-byte page in the source database may need to be
000499            **     copied into the destination database.
000500            */
000501            const i64 iSize = (i64)pgszSrc * (i64)nSrcPage;
000502            sqlite3_file * const pFile = sqlite3PagerFile(pDestPager);
000503            Pgno iPg;
000504            int nDstPage;
000505            i64 iOff;
000506            i64 iEnd;
000507  
000508            assert( pFile );
000509            assert( nDestTruncate==0 
000510                || (i64)nDestTruncate*(i64)pgszDest >= iSize || (
000511                  nDestTruncate==(int)(PENDING_BYTE_PAGE(p->pDest->pBt)-1)
000512               && iSize>=PENDING_BYTE && iSize<=PENDING_BYTE+pgszDest
000513            ));
000514  
000515            /* This block ensures that all data required to recreate the original
000516            ** database has been stored in the journal for pDestPager and the
000517            ** journal synced to disk. So at this point we may safely modify
000518            ** the database file in any way, knowing that if a power failure
000519            ** occurs, the original database will be reconstructed from the 
000520            ** journal file.  */
000521            sqlite3PagerPagecount(pDestPager, &nDstPage);
000522            for(iPg=nDestTruncate; rc==SQLITE_OK && iPg<=(Pgno)nDstPage; iPg++){
000523              if( iPg!=PENDING_BYTE_PAGE(p->pDest->pBt) ){
000524                DbPage *pPg;
000525                rc = sqlite3PagerGet(pDestPager, iPg, &pPg, 0);
000526                if( rc==SQLITE_OK ){
000527                  rc = sqlite3PagerWrite(pPg);
000528                  sqlite3PagerUnref(pPg);
000529                }
000530              }
000531            }
000532            if( rc==SQLITE_OK ){
000533              rc = sqlite3PagerCommitPhaseOne(pDestPager, 0, 1);
000534            }
000535  
000536            /* Write the extra pages and truncate the database file as required */
000537            iEnd = MIN(PENDING_BYTE + pgszDest, iSize);
000538            for(
000539              iOff=PENDING_BYTE+pgszSrc; 
000540              rc==SQLITE_OK && iOff<iEnd; 
000541              iOff+=pgszSrc
000542            ){
000543              PgHdr *pSrcPg = 0;
000544              const Pgno iSrcPg = (Pgno)((iOff/pgszSrc)+1);
000545              rc = sqlite3PagerGet(pSrcPager, iSrcPg, &pSrcPg, 0);
000546              if( rc==SQLITE_OK ){
000547                u8 *zData = sqlite3PagerGetData(pSrcPg);
000548                rc = sqlite3OsWrite(pFile, zData, pgszSrc, iOff);
000549              }
000550              sqlite3PagerUnref(pSrcPg);
000551            }
000552            if( rc==SQLITE_OK ){
000553              rc = backupTruncateFile(pFile, iSize);
000554            }
000555  
000556            /* Sync the database file to disk. */
000557            if( rc==SQLITE_OK ){
000558              rc = sqlite3PagerSync(pDestPager, 0);
000559            }
000560          }else{
000561            sqlite3PagerTruncateImage(pDestPager, nDestTruncate);
000562            rc = sqlite3PagerCommitPhaseOne(pDestPager, 0, 0);
000563          }
000564      
000565          /* Finish committing the transaction to the destination database. */
000566          if( SQLITE_OK==rc
000567           && SQLITE_OK==(rc = sqlite3BtreeCommitPhaseTwo(p->pDest, 0))
000568          ){
000569            rc = SQLITE_DONE;
000570          }
000571        }
000572      }
000573    
000574      /* If bCloseTrans is true, then this function opened a read transaction
000575      ** on the source database. Close the read transaction here. There is
000576      ** no need to check the return values of the btree methods here, as
000577      ** "committing" a read-only transaction cannot fail.
000578      */
000579      if( bCloseTrans ){
000580        TESTONLY( int rc2 );
000581        TESTONLY( rc2  = ) sqlite3BtreeCommitPhaseOne(p->pSrc, 0);
000582        TESTONLY( rc2 |= ) sqlite3BtreeCommitPhaseTwo(p->pSrc, 0);
000583        assert( rc2==SQLITE_OK );
000584      }
000585    
000586      if( rc==SQLITE_IOERR_NOMEM ){
000587        rc = SQLITE_NOMEM_BKPT;
000588      }
000589      p->rc = rc;
000590    }
000591    if( p->pDestDb ){
000592      sqlite3_mutex_leave(p->pDestDb->mutex);
000593    }
000594    sqlite3BtreeLeave(p->pSrc);
000595    sqlite3_mutex_leave(p->pSrcDb->mutex);
000596    return rc;
000597  }
000598  
000599  /*
000600  ** Release all resources associated with an sqlite3_backup* handle.
000601  */
000602  int sqlite3_backup_finish(sqlite3_backup *p){
000603    sqlite3_backup **pp;                 /* Ptr to head of pagers backup list */
000604    sqlite3 *pSrcDb;                     /* Source database connection */
000605    int rc;                              /* Value to return */
000606  
000607    /* Enter the mutexes */
000608    if( p==0 ) return SQLITE_OK;
000609    pSrcDb = p->pSrcDb;
000610    sqlite3_mutex_enter(pSrcDb->mutex);
000611    sqlite3BtreeEnter(p->pSrc);
000612    if( p->pDestDb ){
000613      sqlite3_mutex_enter(p->pDestDb->mutex);
000614    }
000615  
000616    /* Detach this backup from the source pager. */
000617    if( p->pDestDb ){
000618      p->pSrc->nBackup--;
000619    }
000620    if( p->isAttached ){
000621      pp = sqlite3PagerBackupPtr(sqlite3BtreePager(p->pSrc));
000622      while( *pp!=p ){
000623        pp = &(*pp)->pNext;
000624      }
000625      *pp = p->pNext;
000626    }
000627  
000628    /* If a transaction is still open on the Btree, roll it back. */
000629    sqlite3BtreeRollback(p->pDest, SQLITE_OK, 0);
000630  
000631    /* Set the error code of the destination database handle. */
000632    rc = (p->rc==SQLITE_DONE) ? SQLITE_OK : p->rc;
000633    if( p->pDestDb ){
000634      sqlite3Error(p->pDestDb, rc);
000635  
000636      /* Exit the mutexes and free the backup context structure. */
000637      sqlite3LeaveMutexAndCloseZombie(p->pDestDb);
000638    }
000639    sqlite3BtreeLeave(p->pSrc);
000640    if( p->pDestDb ){
000641      /* EVIDENCE-OF: R-64852-21591 The sqlite3_backup object is created by a
000642      ** call to sqlite3_backup_init() and is destroyed by a call to
000643      ** sqlite3_backup_finish(). */
000644      sqlite3_free(p);
000645    }
000646    sqlite3LeaveMutexAndCloseZombie(pSrcDb);
000647    return rc;
000648  }
000649  
000650  /*
000651  ** Return the number of pages still to be backed up as of the most recent
000652  ** call to sqlite3_backup_step().
000653  */
000654  int sqlite3_backup_remaining(sqlite3_backup *p){
000655  #ifdef SQLITE_ENABLE_API_ARMOR
000656    if( p==0 ){
000657      (void)SQLITE_MISUSE_BKPT;
000658      return 0;
000659    }
000660  #endif
000661    return p->nRemaining;
000662  }
000663  
000664  /*
000665  ** Return the total number of pages in the source database as of the most 
000666  ** recent call to sqlite3_backup_step().
000667  */
000668  int sqlite3_backup_pagecount(sqlite3_backup *p){
000669  #ifdef SQLITE_ENABLE_API_ARMOR
000670    if( p==0 ){
000671      (void)SQLITE_MISUSE_BKPT;
000672      return 0;
000673    }
000674  #endif
000675    return p->nPagecount;
000676  }
000677  
000678  /*
000679  ** This function is called after the contents of page iPage of the
000680  ** source database have been modified. If page iPage has already been 
000681  ** copied into the destination database, then the data written to the
000682  ** destination is now invalidated. The destination copy of iPage needs
000683  ** to be updated with the new data before the backup operation is
000684  ** complete.
000685  **
000686  ** It is assumed that the mutex associated with the BtShared object
000687  ** corresponding to the source database is held when this function is
000688  ** called.
000689  */
000690  static SQLITE_NOINLINE void backupUpdate(
000691    sqlite3_backup *p,
000692    Pgno iPage,
000693    const u8 *aData
000694  ){
000695    assert( p!=0 );
000696    do{
000697      assert( sqlite3_mutex_held(p->pSrc->pBt->mutex) );
000698      if( !isFatalError(p->rc) && iPage<p->iNext ){
000699        /* The backup process p has already copied page iPage. But now it
000700        ** has been modified by a transaction on the source pager. Copy
000701        ** the new data into the backup.
000702        */
000703        int rc;
000704        assert( p->pDestDb );
000705        sqlite3_mutex_enter(p->pDestDb->mutex);
000706        rc = backupOnePage(p, iPage, aData, 1);
000707        sqlite3_mutex_leave(p->pDestDb->mutex);
000708        assert( rc!=SQLITE_BUSY && rc!=SQLITE_LOCKED );
000709        if( rc!=SQLITE_OK ){
000710          p->rc = rc;
000711        }
000712      }
000713    }while( (p = p->pNext)!=0 );
000714  }
000715  void sqlite3BackupUpdate(sqlite3_backup *pBackup, Pgno iPage, const u8 *aData){
000716    if( pBackup ) backupUpdate(pBackup, iPage, aData);
000717  }
000718  
000719  /*
000720  ** Restart the backup process. This is called when the pager layer
000721  ** detects that the database has been modified by an external database
000722  ** connection. In this case there is no way of knowing which of the
000723  ** pages that have been copied into the destination database are still 
000724  ** valid and which are not, so the entire process needs to be restarted.
000725  **
000726  ** It is assumed that the mutex associated with the BtShared object
000727  ** corresponding to the source database is held when this function is
000728  ** called.
000729  */
000730  void sqlite3BackupRestart(sqlite3_backup *pBackup){
000731    sqlite3_backup *p;                   /* Iterator variable */
000732    for(p=pBackup; p; p=p->pNext){
000733      assert( sqlite3_mutex_held(p->pSrc->pBt->mutex) );
000734      p->iNext = 1;
000735    }
000736  }
000737  
000738  #ifndef SQLITE_OMIT_VACUUM
000739  /*
000740  ** Copy the complete content of pBtFrom into pBtTo.  A transaction
000741  ** must be active for both files.
000742  **
000743  ** The size of file pTo may be reduced by this operation. If anything 
000744  ** goes wrong, the transaction on pTo is rolled back. If successful, the 
000745  ** transaction is committed before returning.
000746  */
000747  int sqlite3BtreeCopyFile(Btree *pTo, Btree *pFrom){
000748    int rc;
000749    sqlite3_file *pFd;              /* File descriptor for database pTo */
000750    sqlite3_backup b;
000751    sqlite3BtreeEnter(pTo);
000752    sqlite3BtreeEnter(pFrom);
000753  
000754    assert( sqlite3BtreeIsInTrans(pTo) );
000755    pFd = sqlite3PagerFile(sqlite3BtreePager(pTo));
000756    if( pFd->pMethods ){
000757      i64 nByte = sqlite3BtreeGetPageSize(pFrom)*(i64)sqlite3BtreeLastPage(pFrom);
000758      rc = sqlite3OsFileControl(pFd, SQLITE_FCNTL_OVERWRITE, &nByte);
000759      if( rc==SQLITE_NOTFOUND ) rc = SQLITE_OK;
000760      if( rc ) goto copy_finished;
000761    }
000762  
000763    /* Set up an sqlite3_backup object. sqlite3_backup.pDestDb must be set
000764    ** to 0. This is used by the implementations of sqlite3_backup_step()
000765    ** and sqlite3_backup_finish() to detect that they are being called
000766    ** from this function, not directly by the user.
000767    */
000768    memset(&b, 0, sizeof(b));
000769    b.pSrcDb = pFrom->db;
000770    b.pSrc = pFrom;
000771    b.pDest = pTo;
000772    b.iNext = 1;
000773  
000774  #ifdef SQLITE_HAS_CODEC
000775    sqlite3PagerAlignReserve(sqlite3BtreePager(pTo), sqlite3BtreePager(pFrom));
000776  #endif
000777  
000778    /* 0x7FFFFFFF is the hard limit for the number of pages in a database
000779    ** file. By passing this as the number of pages to copy to
000780    ** sqlite3_backup_step(), we can guarantee that the copy finishes 
000781    ** within a single call (unless an error occurs). The assert() statement
000782    ** checks this assumption - (p->rc) should be set to either SQLITE_DONE 
000783    ** or an error code.  */
000784    sqlite3_backup_step(&b, 0x7FFFFFFF);
000785    assert( b.rc!=SQLITE_OK );
000786  
000787    rc = sqlite3_backup_finish(&b);
000788    if( rc==SQLITE_OK ){
000789      pTo->pBt->btsFlags &= ~BTS_PAGESIZE_FIXED;
000790    }else{
000791      sqlite3PagerClearCache(sqlite3BtreePager(b.pDest));
000792    }
000793  
000794    assert( sqlite3BtreeIsInTrans(pTo)==0 );
000795  copy_finished:
000796    sqlite3BtreeLeave(pFrom);
000797    sqlite3BtreeLeave(pTo);
000798    return rc;
000799  }
000800  #endif /* SQLITE_OMIT_VACUUM */