Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Changes to src/sqlite3.c.

     7      7   ** of 5% are more are commonly seen when SQLite is compiled as a single
     8      8   ** translation unit.
     9      9   **
    10     10   ** This file is all you need to compile SQLite.  To use SQLite in other
    11     11   ** programs, you need this file and the "sqlite3.h" header file that defines
    12     12   ** the programming interface to the SQLite library.  (If you do not have 
    13     13   ** the "sqlite3.h" header file at hand, you will find a copy in the first
    14         -** 6736 lines past this header comment.)  Additional code files may be
           14  +** 6918 lines past this header comment.)  Additional code files may be
    15     15   ** needed if you want a wrapper to interface SQLite with your choice of
    16     16   ** programming language.  The code for the "sqlite3" command-line shell
    17     17   ** is also in a separate file.  This file contains only code for the core
    18     18   ** SQLite library.
    19     19   **
    20         -** This amalgamation was generated on 2009-02-03 16:30:31 UTC.
           20  +** This amalgamation was generated on 2009-02-03 18:21:01 UTC.
    21     21   */
    22     22   #define SQLITE_CORE 1
    23     23   #define SQLITE_AMALGAMATION 1
    24     24   #ifndef SQLITE_PRIVATE
    25     25   # define SQLITE_PRIVATE static
    26     26   #endif
    27     27   #ifndef SQLITE_API
................................................................................
    37     37   **    May you do good and not evil.
    38     38   **    May you find forgiveness for yourself and forgive others.
    39     39   **    May you share freely, never taking more than you give.
    40     40   **
    41     41   *************************************************************************
    42     42   ** Internal interface definitions for SQLite.
    43     43   **
    44         -** @(#) $Id: sqliteInt.h,v 1.830 2009/01/24 11:30:43 drh Exp $
           44  +** @(#) $Id: sqliteInt.h,v 1.831 2009/02/03 16:51:25 danielk1977 Exp $
    45     45   */
    46     46   #ifndef _SQLITEINT_H_
    47     47   #define _SQLITEINT_H_
    48     48   
    49     49   /*
    50     50   ** Include the configuration header output by 'configure' if we're using the
    51     51   ** autoconf-based build
................................................................................
   528    528   ** on how SQLite interfaces are suppose to operate.
   529    529   **
   530    530   ** The name of this file under configuration management is "sqlite.h.in".
   531    531   ** The makefile makes some minor changes to this file (such as inserting
   532    532   ** the version number) and changes its name to "sqlite3.h" as
   533    533   ** part of the build process.
   534    534   **
   535         -** @(#) $Id: sqlite.h.in,v 1.422 2009/01/23 16:45:01 danielk1977 Exp $
          535  +** @(#) $Id: sqlite.h.in,v 1.423 2009/02/03 16:51:25 danielk1977 Exp $
   536    536   */
   537    537   #ifndef _SQLITE3_H_
   538    538   #define _SQLITE3_H_
   539    539   #include <stdarg.h>     /* Needed for the definition of va_list */
   540    540   
   541    541   /*
   542    542   ** Make sure we can call this stuff from C++.
................................................................................
  7220   7220     void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
  7221   7221     void (*xUnpin)(sqlite3_pcache*, void*, int discard);
  7222   7222     void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
  7223   7223     void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
  7224   7224     void (*xDestroy)(sqlite3_pcache*);
  7225   7225   };
  7226   7226   
         7227  +/*
         7228  +** CAPI3REF: Online Backup Object
         7229  +** EXPERIMENTAL
         7230  +**
         7231  +** The sqlite3_backup object records state information about an ongoing
         7232  +** online backup operation.  The sqlite3_backup object is created by
         7233  +** a call to [sqlite3_backup_init()] and is destroyed by a call to
         7234  +** [sqlite3_backup_finish()].
         7235  +*/
         7236  +typedef struct sqlite3_backup sqlite3_backup;
         7237  +
         7238  +/*
         7239  +** CAPI3REF: Online Backup API.
         7240  +** EXPERIMENTAL
         7241  +**
         7242  +** This API is used to overwrite the contents of one database with that
         7243  +** of another. It is useful either for creating backups of databases or
         7244  +** for copying in-memory databases to or from persistent files. 
         7245  +**
         7246  +** Exclusive access is required to the destination database for the 
         7247  +** duration of the operation. However the source database is only
         7248  +** read-locked while it is actually being read, it is not locked
         7249  +** continuously for the entire operation. Thus, the backup may be
         7250  +** performed on a live database without preventing other users from
         7251  +** writing to the database for an extended period of time.
         7252  +** 
         7253  +** To perform a backup operation: 
         7254  +**   <ol>
         7255  +**     <li>[sqlite3_backup_init()] is called once to initialize the backup, 
         7256  +**     <li>[sqlite3_backup_step()] is called one or more times to transfer 
         7257  +**         the data between the two databases, and finally
         7258  +**     <li>[sqlite3_backup_finish()] is called to release all resources 
         7259  +**         associated with the backup operation. 
         7260  +**   </ol>
         7261  +** There should be exactly one call to sqlite3_backup_finish() for each
         7262  +** successful call to sqlite3_backup_init().
         7263  +**
         7264  +** <b>sqlite3_backup_init()</b>
         7265  +**
         7266  +** The first two arguments passed to [sqlite3_backup_init()] are the database
         7267  +** handle associated with the destination database and the database name 
         7268  +** used to attach the destination database to the handle. The database name
         7269  +** is "main" for the main database, "temp" for the temporary database, or
         7270  +** the name specified as part of the ATTACH statement if the destination is
         7271  +** an attached database. The third and fourth arguments passed to 
         7272  +** sqlite3_backup_init() identify the database handle and database name used
         7273  +** to access the source database. The values passed for the source and 
         7274  +** destination database handle parameters must not be the same.
         7275  +**
         7276  +** If an error occurs within sqlite3_backup_init(), then NULL is returned
         7277  +** and an error code and error message written into the database handle 
         7278  +** passed as the first argument. They may be retrieved using the
         7279  +** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16() functions.
         7280  +** Otherwise, if successful, a pointer to an [sqlite3_backup] object is
         7281  +** returned. This pointer may be used with the sqlite3_backup_step() and
         7282  +** sqlite3_backup_finish() functions to perform the specified backup 
         7283  +** operation.
         7284  +**
         7285  +** <b>sqlite3_backup_step()</b>
         7286  +**
         7287  +** Function [sqlite3_backup_step()] is used to copy up to nPage pages between 
         7288  +** the source and destination databases, where nPage is the value of the 
         7289  +** second parameter passed to sqlite3_backup_step(). If nPage pages are 
         7290  +** succesfully copied, but there are still more pages to copy before the 
         7291  +** backup is complete, it returns SQLITE_OK. If no error occured and there 
         7292  +** are no more pages to copy, then SQLITE_DONE is returned. If an error 
         7293  +** occurs, then an SQLite error code is returned. As well as SQLITE_OK and
         7294  +** SQLITE_DONE, a call to sqlite3_backup_step() may return SQLITE_READONLY,
         7295  +** SQLITE_NOMEM, SQLITE_BUSY, SQLITE_LOCKED or an SQLITE_IOERR_XXX error code.
         7296  +**
         7297  +** As well as the case where the destination database file was opened for
         7298  +** read-only access, sqlite3_backup_step() may return SQLITE_READONLY if
         7299  +** the destination is an in-memory database with a different page size
         7300  +** from the source database.
         7301  +**
         7302  +** If sqlite3_backup_step() cannot obtain a required file-system lock, then
         7303  +** the busy-handler function is invoked (if one is specified). If the 
         7304  +** busy-handler returns non-zero before the lock is available, then 
         7305  +** SQLITE_BUSY is returned to the caller. In this case the call to
         7306  +** sqlite3_backup_step() can be retried later. If the source database handle
         7307  +** is being used to write to the source database when sqlite3_backup_step()
         7308  +** is called, then SQLITE_LOCKED is returned immediately. Again, in this
         7309  +** case the call to sqlite3_backup_step() can be retried later on. If
         7310  +** SQLITE_IOERR_XXX, SQLITE_NOMEM or SQLITE_READONLY is returned, then 
         7311  +** there is no point in retrying the call to sqlite3_backup_step(). These 
         7312  +** errors are considered fatal. At this point the application must accept 
         7313  +** that the backup operation has failed and pass the backup operation handle 
         7314  +** to the sqlite3_backup_finish() to release associated resources.
         7315  +**
         7316  +** Following the first call to sqlite3_backup_step(), an exclusive lock is
         7317  +** obtained on the destination file. It is not released until either 
         7318  +** sqlite3_backup_finish() is called or the backup operation is complete 
         7319  +** and sqlite3_backup_step() returns SQLITE_DONE. Additionally, each time 
         7320  +** a call to sqlite3_backup_step() is made a shared lock is obtained on
         7321  +** the source database file. This lock is released before the
         7322  +** sqlite3_backup_step() call returns. Because the source database is not
         7323  +** locked between calls to sqlite3_backup_step(), it may be modified mid-way
         7324  +** through the backup procedure. If the source database is modified by an
         7325  +** external process or via a database connection other than the one being
         7326  +** used by the backup operation, then the backup will be transparently
         7327  +** restarted by the next call to sqlite3_backup_step(). If the source 
         7328  +** database is modified by the using the same database connection as is used
         7329  +** by the backup operation, then the backup database is transparently 
         7330  +** updated at the same time.
         7331  +**
         7332  +** <b>sqlite3_backup_finish()</b>
         7333  +**
         7334  +** Once sqlite3_backup_step() has returned SQLITE_DONE, or when the 
         7335  +** application wishes to abandon the backup operation, the [sqlite3_backup]
         7336  +** object should be passed to sqlite3_backup_finish(). This releases all
         7337  +** resources associated with the backup operation. If sqlite3_backup_step()
         7338  +** has not yet returned SQLITE_DONE, then any active write-transaction on the
         7339  +** destination database is rolled back. The [sqlite3_backup] object is invalid
         7340  +** and may not be used following a call to sqlite3_backup_finish().
         7341  +**
         7342  +** The value returned by sqlite3_backup_finish is SQLITE_OK if no error
         7343  +** occured, regardless or whether or not sqlite3_backup_step() was called
         7344  +** a sufficient number of times to complete the backup operation. Or, if
         7345  +** an out-of-memory condition or IO error occured during a call to
         7346  +** sqlite3_backup_step() then SQLITE_NOMEM or an SQLITE_IOERR_XXX error code
         7347  +** is returned. In this case the error code and an error message are
         7348  +** written to the destination database handle.
         7349  +**
         7350  +** A return of SQLITE_BUSY or SQLITE_LOCKED from sqlite3_backup_step() is
         7351  +** not considered an error and does not affect the return value of
         7352  +** sqlite3_backup_finish().
         7353  +**
         7354  +** <b>sqlite3_backup_remaining(), sqlite3_backup_pagecount()</b>
         7355  +**
         7356  +** Each call to sqlite3_backup_step() sets two values stored internally
         7357  +** by an [sqlite3_backup] object. The number of pages still to be backed
         7358  +** up, which may be queried by sqlite3_backup_remaining(), and the total
         7359  +** number of pages in the source database file, which may be queried by
         7360  +** sqlite3_backup_pagecount().
         7361  +**
         7362  +** The values returned by these functions are only updated by
         7363  +** sqlite3_backup_step(). If the source database is modified during a backup
         7364  +** operation, then the values are not updated to account for any extra
         7365  +** pages that need to be updated or the size of the source database file
         7366  +** changing.
         7367  +**
         7368  +** <b>Concurrent Usage of Database Handles</b>
         7369  +**
         7370  +** The source database handle may be used by the application for other
         7371  +** purposes while a backup operation is underway or being initialized.
         7372  +** If SQLite is compiled and configured to support threadsafe database
         7373  +** connections, then the source database connection may be used concurrently
         7374  +** from within other threads.
         7375  +**
         7376  +** However, the application must guarantee that the destination database
         7377  +** connection handle is not passed to any other API (by any thread) after 
         7378  +** sqlite3_backup_init() is called and before the corresponding call to
         7379  +** sqlite3_backup_finish(). Unfortunately SQLite does not currently check
         7380  +** for this, if the application does use the destination database handle
         7381  +** for some other purpose during a backup operation, things may appear to
         7382  +** work correctly but in fact be subtly malfunctioning.
         7383  +**
         7384  +** Furthermore, if running in shared cache mode, the application must
         7385  +** guarantee that the shared cache used by the destination database
         7386  +** is not accessed while the backup is running. In practice this means
         7387  +** that the application must guarantee that the file-system file being 
         7388  +** backed up to is not accessed by any connection within the process,
         7389  +** not just the specific connection that was passed to sqlite3_backup_init().
         7390  +**
         7391  +** The [sqlite3_backup] object itself is partially threadsafe. Multiple 
         7392  +** threads may safely make multiple concurrent calls to sqlite3_backup_step().
         7393  +** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
         7394  +** APIs are not strictly speaking threadsafe. If they are invoked at the
         7395  +** same time as another thread is invoking sqlite3_backup_step() it is
         7396  +** possible that they return invalid values.
         7397  +*/
         7398  +SQLITE_API sqlite3_backup *sqlite3_backup_init(
         7399  +  sqlite3 *pDest,                        /* Destination database handle */
         7400  +  const char *zDestName,                 /* Destination database name */
         7401  +  sqlite3 *pSource,                      /* Source database handle */
         7402  +  const char *zSourceName                /* Source database name */
         7403  +);
         7404  +SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
         7405  +SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
         7406  +SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
         7407  +SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
         7408  +
  7227   7409   /*
  7228   7410   ** Undo the hack that converts floating point types to integer for
  7229   7411   ** builds on processors without floating point support.
  7230   7412   */
  7231   7413   #ifdef SQLITE_OMIT_FLOATING_POINT
  7232   7414   # undef double
  7233   7415   #endif
................................................................................
  7805   7987   **    May you share freely, never taking more than you give.
  7806   7988   **
  7807   7989   *************************************************************************
  7808   7990   ** This header file defines the interface that the sqlite B-Tree file
  7809   7991   ** subsystem.  See comments in the source code for a detailed description
  7810   7992   ** of what each interface routine does.
  7811   7993   **
  7812         -** @(#) $Id: btree.h,v 1.107 2009/01/24 11:30:43 drh Exp $
         7994  +** @(#) $Id: btree.h,v 1.108 2009/02/03 16:51:25 danielk1977 Exp $
  7813   7995   */
  7814   7996   #ifndef _BTREE_H_
  7815   7997   #define _BTREE_H_
  7816   7998   
  7817   7999   /* TODO: This definition is just included so other modules compile. It
  7818   8000   ** needs to be revisited.
  7819   8001   */
................................................................................
  7890   8072   SQLITE_PRIVATE int sqlite3BtreeBeginStmt(Btree*);
  7891   8073   SQLITE_PRIVATE int sqlite3BtreeCommitStmt(Btree*);
  7892   8074   SQLITE_PRIVATE int sqlite3BtreeRollbackStmt(Btree*);
  7893   8075   SQLITE_PRIVATE int sqlite3BtreeCreateTable(Btree*, int*, int flags);
  7894   8076   SQLITE_PRIVATE int sqlite3BtreeIsInTrans(Btree*);
  7895   8077   SQLITE_PRIVATE int sqlite3BtreeIsInStmt(Btree*);
  7896   8078   SQLITE_PRIVATE int sqlite3BtreeIsInReadTrans(Btree*);
         8079  +SQLITE_PRIVATE int sqlite3BtreeIsInBackup(Btree*);
  7897   8080   SQLITE_PRIVATE void *sqlite3BtreeSchema(Btree *, int, void(*)(void *));
  7898   8081   SQLITE_PRIVATE int sqlite3BtreeSchemaLocked(Btree *);
  7899   8082   SQLITE_PRIVATE int sqlite3BtreeLockTable(Btree *, int, u8);
  7900   8083   SQLITE_PRIVATE int sqlite3BtreeSavepoint(Btree *, int, int);
  7901   8084   
  7902   8085   SQLITE_PRIVATE const char *sqlite3BtreeGetFilename(Btree *);
  7903   8086   SQLITE_PRIVATE const char *sqlite3BtreeGetJournalname(Btree *);
................................................................................
  8427   8610   **    May you share freely, never taking more than you give.
  8428   8611   **
  8429   8612   *************************************************************************
  8430   8613   ** This header file defines the interface that the sqlite page cache
  8431   8614   ** subsystem.  The page cache subsystem reads and writes a file a page
  8432   8615   ** at a time and provides a journal for rollback.
  8433   8616   **
  8434         -** @(#) $Id: pager.h,v 1.99 2009/01/31 14:54:07 danielk1977 Exp $
         8617  +** @(#) $Id: pager.h,v 1.100 2009/02/03 16:51:25 danielk1977 Exp $
  8435   8618   */
  8436   8619   
  8437   8620   #ifndef _PAGER_H_
  8438   8621   #define _PAGER_H_
  8439   8622   
  8440   8623   /*
  8441   8624   ** Default maximum size for persistent journal files. A negative 
................................................................................
  8514   8697   SQLITE_PRIVATE int sqlite3PagerSetPagesize(Pager*, u16*);
  8515   8698   SQLITE_PRIVATE int sqlite3PagerMaxPageCount(Pager*, int);
  8516   8699   SQLITE_PRIVATE void sqlite3PagerSetCachesize(Pager*, int);
  8517   8700   SQLITE_PRIVATE void sqlite3PagerSetSafetyLevel(Pager*,int,int);
  8518   8701   SQLITE_PRIVATE int sqlite3PagerLockingMode(Pager *, int);
  8519   8702   SQLITE_PRIVATE int sqlite3PagerJournalMode(Pager *, int);
  8520   8703   SQLITE_PRIVATE i64 sqlite3PagerJournalSizeLimit(Pager *, i64);
         8704  +sqlite3_backup **sqlite3PagerBackupPtr(Pager*);
  8521   8705   
  8522   8706   /* Functions used to obtain and release page references. */ 
  8523   8707   SQLITE_PRIVATE int sqlite3PagerAcquire(Pager *pPager, Pgno pgno, DbPage **ppPage, int clrFlag);
  8524   8708   #define sqlite3PagerGet(A,B,C) sqlite3PagerAcquire(A,B,C,0)
  8525   8709   SQLITE_PRIVATE DbPage *sqlite3PagerLookup(Pager *pPager, Pgno pgno);
  8526   8710   SQLITE_PRIVATE void sqlite3PagerRef(DbPage*);
  8527   8711   SQLITE_PRIVATE void sqlite3PagerUnref(DbPage*);
................................................................................
  8549   8733   SQLITE_PRIVATE int sqlite3PagerRefcount(Pager*);
  8550   8734   SQLITE_PRIVATE const char *sqlite3PagerFilename(Pager*);
  8551   8735   SQLITE_PRIVATE const sqlite3_vfs *sqlite3PagerVfs(Pager*);
  8552   8736   SQLITE_PRIVATE sqlite3_file *sqlite3PagerFile(Pager*);
  8553   8737   SQLITE_PRIVATE const char *sqlite3PagerJournalname(Pager*);
  8554   8738   SQLITE_PRIVATE int sqlite3PagerNosync(Pager*);
  8555   8739   SQLITE_PRIVATE void *sqlite3PagerTempSpace(Pager*);
         8740  +SQLITE_PRIVATE int sqlite3PagerIsMemdb(Pager*);
  8556   8741   
  8557   8742   /* Functions used to truncate the database file. */
  8558   8743   SQLITE_PRIVATE void sqlite3PagerTruncateImage(Pager*,Pgno);
  8559   8744   
  8560   8745   /* Used by encryption extensions. */
  8561   8746   #ifdef SQLITE_HAS_CODEC
  8562   8747   SQLITE_PRIVATE   void sqlite3PagerSetCodec(Pager*,void*(*)(void*,void*,Pgno,int),void*);
................................................................................
  8566   8751   #if !defined(NDEBUG) || defined(SQLITE_TEST)
  8567   8752   SQLITE_PRIVATE   Pgno sqlite3PagerPagenumber(DbPage*);
  8568   8753   SQLITE_PRIVATE   int sqlite3PagerIswriteable(DbPage*);
  8569   8754   #endif
  8570   8755   #ifdef SQLITE_TEST
  8571   8756   SQLITE_PRIVATE   int *sqlite3PagerStats(Pager*);
  8572   8757   SQLITE_PRIVATE   void sqlite3PagerRefdump(Pager*);
  8573         -SQLITE_PRIVATE   int sqlite3PagerIsMemdb(Pager*);
  8574   8758     void disable_simulated_io_errors(void);
  8575   8759     void enable_simulated_io_errors(void);
  8576   8760   #else
  8577   8761   # define disable_simulated_io_errors()
  8578   8762   # define enable_simulated_io_errors()
  8579   8763   #endif
  8580   8764   
................................................................................
 11064  11248   SQLITE_PRIVATE void sqlite3AlterFinishAddColumn(Parse *, Token *);
 11065  11249   SQLITE_PRIVATE void sqlite3AlterBeginAddColumn(Parse *, SrcList *);
 11066  11250   SQLITE_PRIVATE CollSeq *sqlite3GetCollSeq(sqlite3*, CollSeq *, const char *, int);
 11067  11251   SQLITE_PRIVATE char sqlite3AffinityType(const Token*);
 11068  11252   SQLITE_PRIVATE void sqlite3Analyze(Parse*, Token*, Token*);
 11069  11253   SQLITE_PRIVATE int sqlite3InvokeBusyHandler(BusyHandler*);
 11070  11254   SQLITE_PRIVATE int sqlite3FindDb(sqlite3*, Token*);
        11255  +SQLITE_PRIVATE int sqlite3FindDbName(sqlite3 *, const char *);
 11071  11256   SQLITE_PRIVATE int sqlite3AnalysisLoad(sqlite3*,int iDB);
 11072  11257   SQLITE_PRIVATE void sqlite3DefaultRowEst(Index*);
 11073  11258   SQLITE_PRIVATE void sqlite3RegisterLikeFunctions(sqlite3*, int);
 11074  11259   SQLITE_PRIVATE int sqlite3IsLikeFunction(sqlite3*,Expr*,int*,char*);
 11075  11260   SQLITE_PRIVATE void sqlite3MinimumFileFormat(Parse*, int, int);
 11076  11261   SQLITE_PRIVATE void sqlite3SchemaFree(void *);
 11077  11262   SQLITE_PRIVATE Schema *sqlite3SchemaGet(sqlite3 *, Btree *);
................................................................................
 11085  11270   
 11086  11271   SQLITE_PRIVATE void sqlite3StrAccumInit(StrAccum*, char*, int, int);
 11087  11272   SQLITE_PRIVATE void sqlite3StrAccumAppend(StrAccum*,const char*,int);
 11088  11273   SQLITE_PRIVATE char *sqlite3StrAccumFinish(StrAccum*);
 11089  11274   SQLITE_PRIVATE void sqlite3StrAccumReset(StrAccum*);
 11090  11275   SQLITE_PRIVATE void sqlite3SelectDestInit(SelectDest*,int,int);
 11091  11276   
        11277  +SQLITE_PRIVATE void sqlite3BackupRestart(sqlite3_backup *);
        11278  +SQLITE_PRIVATE void sqlite3BackupUpdate(sqlite3_backup *, Pgno, const u8 *);
        11279  +
 11092  11280   /*
 11093  11281   ** The interface to the LEMON-generated parser
 11094  11282   */
 11095  11283   SQLITE_PRIVATE void *sqlite3ParserAlloc(void*(*)(size_t));
 11096  11284   SQLITE_PRIVATE void sqlite3ParserFree(void*, void(*)(void*));
 11097  11285   SQLITE_PRIVATE void sqlite3Parser(void*, int, Token, Parse*);
 11098  11286   #ifdef YYTRACKMAXSTACKDEPTH
................................................................................
 30933  31121   ** The pager is used to access a database disk file.  It implements
 30934  31122   ** atomic commit and rollback through the use of a journal file that
 30935  31123   ** is separate from the database file.  The pager also implements file
 30936  31124   ** locking to prevent two processes from writing the same database
 30937  31125   ** file simultaneously, or one process from reading the database while
 30938  31126   ** another is writing.
 30939  31127   **
 30940         -** @(#) $Id: pager.c,v 1.561 2009/01/31 14:54:07 danielk1977 Exp $
        31128  +** @(#) $Id: pager.c,v 1.562 2009/02/03 16:51:25 danielk1977 Exp $
 30941  31129   */
 30942  31130   #ifndef SQLITE_OMIT_DISKIO
 30943  31131   
 30944  31132   /*
 30945  31133   ** Macros for troubleshooting.  Normally turned off
 30946  31134   */
 30947  31135   #if 0
................................................................................
 31220  31408   #ifdef SQLITE_HAS_CODEC
 31221  31409     void *(*xCodec)(void*,void*,Pgno,int); /* Routine for en/decoding data */
 31222  31410     void *pCodecArg;            /* First argument to xCodec() */
 31223  31411   #endif
 31224  31412     char *pTmpSpace;            /* Pager.pageSize bytes of space for tmp use */
 31225  31413     i64 journalSizeLimit;       /* Size limit for persistent journal files */
 31226  31414     PCache *pPCache;            /* Pointer to page cache object */
        31415  +  sqlite3_backup *pBackup;    /* Pointer to list of ongoing backup processes */
 31227  31416   };
 31228  31417   
 31229  31418   /*
 31230  31419   ** The following global variables hold counters used for
 31231  31420   ** testing purposes only.  These variables do not exist in
 31232  31421   ** a non-testing build.  These variables are not thread-safe.
 31233  31422   */
................................................................................
 31953  32142     (void)sqlite3PcacheFetch(pPager->pPCache, pgno, 0, &p);
 31954  32143     return p;
 31955  32144   }
 31956  32145   
 31957  32146   /*
 31958  32147   ** Unless the pager is in error-state, discard all in-memory pages. If
 31959  32148   ** the pager is in error-state, then this call is a no-op.
        32149  +**
        32150  +** TODO: Why can we not reset the pager while in error state?
 31960  32151   */
 31961  32152   static void pager_reset(Pager *pPager){
 31962  32153     if( SQLITE_OK==pPager->errCode ){
        32154  +    sqlite3BackupRestart(pPager->pBackup);
 31963  32155       sqlite3PcacheClear(pPager->pPCache);
 31964  32156     }
 31965  32157   }
 31966  32158   
 31967  32159   /*
 31968  32160   ** Free all structures in the Pager.aSavepoint[] array and set both
 31969  32161   ** Pager.aSavepoint and Pager.nSavepoint to zero. Close the sub-journal
................................................................................
 32427  32619      && isOpen(pPager->fd)
 32428  32620     ){
 32429  32621       i64 ofst = (pgno-1)*(i64)pPager->pageSize;
 32430  32622       rc = sqlite3OsWrite(pPager->fd, aData, pPager->pageSize, ofst);
 32431  32623       if( pgno>pPager->dbFileSize ){
 32432  32624         pPager->dbFileSize = pgno;
 32433  32625       }
        32626  +    sqlite3BackupUpdate(pPager->pBackup, pgno, aData);
 32434  32627     }else if( !isMainJrnl && pPg==0 ){
 32435  32628       /* If this is a rollback of a savepoint and data was not written to
 32436  32629       ** the database and the page is not in-memory, there is a potential
 32437  32630       ** problem. When the page is next fetched by the b-tree layer, it 
 32438  32631       ** will be read from the database file, which may or may not be 
 32439  32632       ** current. 
 32440  32633       **
................................................................................
 33789  33982         if( pgno==1 ){
 33790  33983           memcpy(&pPager->dbFileVers, &pData[24], sizeof(pPager->dbFileVers));
 33791  33984         }
 33792  33985         if( pgno>pPager->dbFileSize ){
 33793  33986           pPager->dbFileSize = pgno;
 33794  33987         }
 33795  33988   
        33989  +      /* Update any backup objects copying the contents of this pager. */
        33990  +      sqlite3BackupUpdate(pPager->pBackup, pgno, (u8 *)pData);
        33991  +
 33796  33992         PAGERTRACE(("STORE %d page %d hash(%08x)\n",
 33797  33993                      PAGERID(pPager), pgno, pager_pagehash(pList)));
 33798  33994         IOTRACE(("PGOUT %p %d\n", pPager, pgno));
 33799  33995         PAGER_INCR(sqlite3_pager_writedb_count);
 33800  33996         PAGER_INCR(pPager->nWrite);
 33801  33997       }else{
 33802  33998         PAGERTRACE(("NOSTORE %d page %d\n", PAGERID(pPager), pgno));
................................................................................
 34463  34659         pPager->journalHdr = 0;
 34464  34660    
 34465  34661         /* Playback and delete the journal.  Drop the database write
 34466  34662         ** lock and reacquire the read lock. Purge the cache before
 34467  34663         ** playing back the hot-journal so that we don't end up with
 34468  34664         ** an inconsistent cache.
 34469  34665         */
 34470         -      sqlite3PcacheClear(pPager->pPCache);
        34666  +      pager_reset(pPager);
 34471  34667         rc = pager_playback(pPager, 1);
 34472  34668         if( rc!=SQLITE_OK ){
 34473  34669           rc = pager_error(pPager, rc);
 34474  34670           goto failed;
 34475  34671         }
 34476  34672         assert( (pPager->state==PAGER_SHARED)
 34477  34673              || (pPager->exclusiveMode && pPager->state>PAGER_SHARED)
................................................................................
 35350  35546   
 35351  35547     PAGERTRACE(("DATABASE SYNC: File=%s zMaster=%s nSize=%d\n", 
 35352  35548         pPager->zFilename, zMaster, pPager->dbSize));
 35353  35549   
 35354  35550     /* If this is an in-memory db, or no pages have been written to, or this
 35355  35551     ** function has already been called, it is a no-op.
 35356  35552     */
 35357         -  if( pPager->state!=PAGER_SYNCED && !MEMDB && pPager->dbModified ){
        35553  +  if( MEMDB && pPager->dbModified ){
        35554  +    sqlite3BackupRestart(pPager->pBackup);
        35555  +  }else if( pPager->state!=PAGER_SYNCED && pPager->dbModified ){
 35358  35556   
 35359  35557       /* The following block updates the change-counter. Exactly how it
 35360  35558       ** does this depends on whether or not the atomic-update optimization
 35361  35559       ** was enabled at compile time, and if this transaction meets the 
 35362  35560       ** runtime criteria to use the operation: 
 35363  35561       **
 35364  35562       **    * The file-system supports the atomic-write property for
................................................................................
 35661  35859     a[6] = pPager->nHit;
 35662  35860     a[7] = pPager->nMiss;
 35663  35861     a[8] = 0;  /* Used to be pPager->nOvfl */
 35664  35862     a[9] = pPager->nRead;
 35665  35863     a[10] = pPager->nWrite;
 35666  35864     return a;
 35667  35865   }
        35866  +#endif
        35867  +
        35868  +/*
        35869  +** Return true if this is an in-memory pager.
        35870  +*/
 35668  35871   SQLITE_PRIVATE int sqlite3PagerIsMemdb(Pager *pPager){
 35669  35872     return MEMDB;
 35670  35873   }
 35671         -#endif
 35672  35874   
 35673  35875   /*
 35674  35876   ** Check that there are at least nSavepoint savepoints open. If there are
 35675  35877   ** currently less than nSavepoints open, then open one or more savepoints
 35676  35878   ** to make up the difference. If the number of savepoints is already
 35677  35879   ** equal to nSavepoint, then this function is a no-op.
 35678  35880   **
................................................................................
 36065  36267   */
 36066  36268   SQLITE_PRIVATE i64 sqlite3PagerJournalSizeLimit(Pager *pPager, i64 iLimit){
 36067  36269     if( iLimit>=-1 ){
 36068  36270       pPager->journalSizeLimit = iLimit;
 36069  36271     }
 36070  36272     return pPager->journalSizeLimit;
 36071  36273   }
        36274  +
        36275  +/*
        36276  +** Return a pointer to the pPager->pBackup variable. The backup module
        36277  +** in backup.c maintains the content of this variable. This module
        36278  +** uses it opaquely as an argument to sqlite3BackupRestart() and
        36279  +** sqlite3BackupUpdate() only.
        36280  +*/
        36281  +sqlite3_backup **sqlite3PagerBackupPtr(Pager *pPager){
        36282  +  return &pPager->pBackup;
        36283  +}
 36072  36284   
 36073  36285   #endif /* SQLITE_OMIT_DISKIO */
 36074  36286   
 36075  36287   /************** End of pager.c ***********************************************/
 36076  36288   /************** Begin file btmutex.c *****************************************/
 36077  36289   /*
 36078  36290   ** 2007 August 27
................................................................................
 36102  36314   ** a legal notice, here is a blessing:
 36103  36315   **
 36104  36316   **    May you do good and not evil.
 36105  36317   **    May you find forgiveness for yourself and forgive others.
 36106  36318   **    May you share freely, never taking more than you give.
 36107  36319   **
 36108  36320   *************************************************************************
 36109         -** $Id: btreeInt.h,v 1.41 2009/01/20 17:06:27 danielk1977 Exp $
        36321  +** $Id: btreeInt.h,v 1.42 2009/02/03 16:51:25 danielk1977 Exp $
 36110  36322   **
 36111  36323   ** This file implements a external (disk-based) database using BTrees.
 36112  36324   ** For a detailed discussion of BTrees, refer to
 36113  36325   **
 36114  36326   **     Donald E. Knuth, THE ART OF COMPUTER PROGRAMMING, Volume 3:
 36115  36327   **     "Sorting And Searching", pages 473-480. Addison-Wesley
 36116  36328   **     Publishing Company, Reading, Massachusetts.
................................................................................
 36416  36628   struct Btree {
 36417  36629     sqlite3 *db;       /* The database connection holding this btree */
 36418  36630     BtShared *pBt;     /* Sharable content of this btree */
 36419  36631     u8 inTrans;        /* TRANS_NONE, TRANS_READ or TRANS_WRITE */
 36420  36632     u8 sharable;       /* True if we can share pBt with another db */
 36421  36633     u8 locked;         /* True if db currently has pBt locked */
 36422  36634     int wantToLock;    /* Number of nested calls to sqlite3BtreeEnter() */
        36635  +  int nBackup;       /* Number of backup operations reading this btree */
 36423  36636     Btree *pNext;      /* List of other sharable Btrees from the same db */
 36424  36637     Btree *pPrev;      /* Back pointer of the same list */
 36425  36638   };
 36426  36639   
 36427  36640   /*
 36428  36641   ** Btree.inTrans may take one of the following values.
 36429  36642   **
................................................................................
 37027  37240   ** a legal notice, here is a blessing:
 37028  37241   **
 37029  37242   **    May you do good and not evil.
 37030  37243   **    May you find forgiveness for yourself and forgive others.
 37031  37244   **    May you share freely, never taking more than you give.
 37032  37245   **
 37033  37246   *************************************************************************
 37034         -** $Id: btree.c,v 1.563 2009/01/31 14:54:07 danielk1977 Exp $
        37247  +** $Id: btree.c,v 1.564 2009/02/03 16:51:25 danielk1977 Exp $
 37035  37248   **
 37036  37249   ** This file implements a external (disk-based) database using BTrees.
 37037  37250   ** See the header comment on "btreeInt.h" for additional information.
 37038  37251   ** Including a description of file format and an overview of operation.
 37039  37252   */
 37040  37253   
 37041  37254   /*
................................................................................
 44256  44469   ** open so it is safe to access without the BtShared mutex.
 44257  44470   */
 44258  44471   SQLITE_PRIVATE const char *sqlite3BtreeGetJournalname(Btree *p){
 44259  44472     assert( p->pBt->pPager!=0 );
 44260  44473     return sqlite3PagerJournalname(p->pBt->pPager);
 44261  44474   }
 44262  44475   
 44263         -#ifndef SQLITE_OMIT_VACUUM
 44264         -/*
 44265         -** Copy the complete content of pBtFrom into pBtTo.  A transaction
 44266         -** must be active for both files.
 44267         -**
 44268         -** The size of file pTo may be reduced by this operation.
 44269         -** If anything goes wrong, the transaction on pTo is rolled back. 
 44270         -**
 44271         -** If successful, CommitPhaseOne() may be called on pTo before returning. 
 44272         -** The caller should finish committing the transaction on pTo by calling
 44273         -** sqlite3BtreeCommit().
 44274         -*/
 44275         -static int btreeCopyFile(Btree *pTo, Btree *pFrom){
 44276         -  int rc = SQLITE_OK;
 44277         -  Pgno i;
 44278         -
 44279         -  Pgno nFromPage;     /* Number of pages in pFrom */
 44280         -  Pgno nToPage;       /* Number of pages in pTo */
 44281         -  Pgno nNewPage;      /* Number of pages in pTo after the copy */
 44282         -
 44283         -  Pgno iSkip;         /* Pending byte page in pTo */
 44284         -  int nToPageSize;    /* Page size of pTo in bytes */
 44285         -  int nFromPageSize;  /* Page size of pFrom in bytes */
 44286         -
 44287         -  BtShared *pBtTo = pTo->pBt;
 44288         -  BtShared *pBtFrom = pFrom->pBt;
 44289         -  pBtTo->db = pTo->db;
 44290         -  pBtFrom->db = pFrom->db;
 44291         -
 44292         -  nToPageSize = pBtTo->pageSize;
 44293         -  nFromPageSize = pBtFrom->pageSize;
 44294         -
 44295         -  assert( pTo->inTrans==TRANS_WRITE );
 44296         -  assert( pFrom->inTrans==TRANS_WRITE );
 44297         -  if( NEVER(pBtTo->pCursor) ){
 44298         -    return SQLITE_BUSY;
 44299         -  }
 44300         -
 44301         -  nToPage = pagerPagecount(pBtTo);
 44302         -  nFromPage = pagerPagecount(pBtFrom);
 44303         -  iSkip = PENDING_BYTE_PAGE(pBtTo);
 44304         -
 44305         -  /* Variable nNewPage is the number of pages required to store the
 44306         -  ** contents of pFrom using the current page-size of pTo.
 44307         -  */
 44308         -  nNewPage = (Pgno)
 44309         -     (((i64)nFromPage*(i64)nFromPageSize+(i64)nToPageSize-1)/(i64)nToPageSize);
 44310         -
 44311         -  for(i=1; rc==SQLITE_OK && (i<=nToPage || i<=nNewPage); i++){
 44312         -
 44313         -    /* Journal the original page.
 44314         -    **
 44315         -    ** iSkip is the page number of the locking page (PENDING_BYTE_PAGE)
 44316         -    ** in database *pTo (before the copy). This page is never written 
 44317         -    ** into the journal file. Unless i==iSkip or the page was not
 44318         -    ** present in pTo before the copy operation, journal page i from pTo.
 44319         -    */
 44320         -    if( i!=iSkip && i<=nToPage ){
 44321         -      DbPage *pDbPage = 0;
 44322         -      rc = sqlite3PagerGet(pBtTo->pPager, i, &pDbPage);
 44323         -      if( rc==SQLITE_OK ){
 44324         -        rc = sqlite3PagerWrite(pDbPage);
 44325         -        if( rc==SQLITE_OK && i>nFromPage ){
 44326         -          /* Yeah.  It seems wierd to call DontWrite() right after Write(). But
 44327         -          ** that is because the names of those procedures do not exactly 
 44328         -          ** represent what they do.  Write() really means "put this page in the
 44329         -          ** rollback journal and mark it as dirty so that it will be written
 44330         -          ** to the database file later."  DontWrite() undoes the second part of
 44331         -          ** that and prevents the page from being written to the database. The
 44332         -          ** page is still on the rollback journal, though.  And that is the 
 44333         -          ** whole point of this block: to put pages on the rollback journal. 
 44334         -          */
 44335         -          sqlite3PagerDontWrite(pDbPage);
 44336         -        }
 44337         -        sqlite3PagerUnref(pDbPage);
 44338         -      }
 44339         -    }
 44340         -
 44341         -    /* Overwrite the data in page i of the target database */
 44342         -    if( rc==SQLITE_OK && i!=iSkip && i<=nNewPage ){
 44343         -
 44344         -      DbPage *pToPage = 0;
 44345         -      sqlite3_int64 iOff;
 44346         -
 44347         -      rc = sqlite3PagerGet(pBtTo->pPager, i, &pToPage);
 44348         -      if( rc==SQLITE_OK ){
 44349         -        rc = sqlite3PagerWrite(pToPage);
 44350         -      }
 44351         -
 44352         -      for(
 44353         -        iOff=(i-1)*nToPageSize; 
 44354         -        rc==SQLITE_OK && iOff<i*nToPageSize; 
 44355         -        iOff += nFromPageSize
 44356         -      ){
 44357         -        DbPage *pFromPage = 0;
 44358         -        Pgno iFrom = (Pgno)(iOff/nFromPageSize)+1;
 44359         -
 44360         -        if( iFrom==PENDING_BYTE_PAGE(pBtFrom) ){
 44361         -          continue;
 44362         -        }
 44363         -
 44364         -        rc = sqlite3PagerGet(pBtFrom->pPager, iFrom, &pFromPage);
 44365         -        if( rc==SQLITE_OK ){
 44366         -          char *zTo = sqlite3PagerGetData(pToPage);
 44367         -          char *zFrom = sqlite3PagerGetData(pFromPage);
 44368         -          int nCopy;
 44369         -
 44370         -          if( nFromPageSize>=nToPageSize ){
 44371         -            zFrom += ((i-1)*nToPageSize - ((iFrom-1)*nFromPageSize));
 44372         -            nCopy = nToPageSize;
 44373         -          }else{
 44374         -            zTo += (((iFrom-1)*nFromPageSize) - (i-1)*nToPageSize);
 44375         -            nCopy = nFromPageSize;
 44376         -          }
 44377         -
 44378         -          memcpy(zTo, zFrom, nCopy);
 44379         -          sqlite3PagerUnref(pFromPage);
 44380         -        }
 44381         -      }
 44382         -
 44383         -      if( pToPage ){
 44384         -        MemPage *p = (MemPage *)sqlite3PagerGetExtra(pToPage);
 44385         -        p->isInit = 0;
 44386         -        sqlite3PagerUnref(pToPage);
 44387         -      }
 44388         -    }
 44389         -  }
 44390         -
 44391         -  /* If things have worked so far, the database file may need to be 
 44392         -  ** truncated. The complex part is that it may need to be truncated to
 44393         -  ** a size that is not an integer multiple of nToPageSize - the current
 44394         -  ** page size used by the pager associated with B-Tree pTo.
 44395         -  **
 44396         -  ** For example, say the page-size of pTo is 2048 bytes and the original 
 44397         -  ** number of pages is 5 (10 KB file). If pFrom has a page size of 1024 
 44398         -  ** bytes and 9 pages, then the file needs to be truncated to 9KB.
 44399         -  */
 44400         -  if( rc==SQLITE_OK ){
 44401         -    sqlite3_file *pFile = sqlite3PagerFile(pBtTo->pPager);
 44402         -    i64 iSize = (i64)nFromPageSize * (i64)nFromPage;
 44403         -    i64 iNow = (i64)((nToPage>nNewPage)?nToPage:nNewPage) * (i64)nToPageSize; 
 44404         -    i64 iPending = ((i64)PENDING_BYTE_PAGE(pBtTo)-1) *(i64)nToPageSize;
 44405         -
 44406         -    assert( iSize<=iNow );
 44407         -
 44408         -    /* Commit phase one syncs the journal file associated with pTo 
 44409         -    ** containing the original data. It does not sync the database file
 44410         -    ** itself. After doing this it is safe to use OsTruncate() and other
 44411         -    ** file APIs on the database file directly.
 44412         -    */
 44413         -    pBtTo->db = pTo->db;
 44414         -    if( nFromPageSize==nToPageSize ){
 44415         -      sqlite3PagerTruncateImage(pBtTo->pPager, nFromPage);
 44416         -      iNow = iSize;
 44417         -    }
 44418         -    rc = sqlite3PagerCommitPhaseOne(pBtTo->pPager, 0, 1);
 44419         -    if( iSize<iNow && rc==SQLITE_OK ){
 44420         -      rc = sqlite3OsTruncate(pFile, iSize);
 44421         -    }
 44422         -
 44423         -    /* The loop that copied data from database pFrom to pTo did not
 44424         -    ** populate the locking page of database pTo. If the page-size of
 44425         -    ** pFrom is smaller than that of pTo, this means some data will
 44426         -    ** not have been copied. 
 44427         -    **
 44428         -    ** This block copies the missing data from database pFrom to pTo 
 44429         -    ** using file APIs. This is safe because at this point we know that
 44430         -    ** all of the original data from pTo has been synced into the 
 44431         -    ** journal file. At this point it would be safe to do anything at
 44432         -    ** all to the database file except truncate it to zero bytes.
 44433         -    */
 44434         -    if( rc==SQLITE_OK && nFromPageSize<nToPageSize && iSize>iPending){
 44435         -      i64 iOff;
 44436         -      for(
 44437         -        iOff=iPending; 
 44438         -        rc==SQLITE_OK && iOff<(iPending+nToPageSize); 
 44439         -        iOff += nFromPageSize
 44440         -      ){
 44441         -        DbPage *pFromPage = 0;
 44442         -        Pgno iFrom = (Pgno)(iOff/nFromPageSize)+1;
 44443         -
 44444         -        if( iFrom==PENDING_BYTE_PAGE(pBtFrom) || iFrom>nFromPage ){
 44445         -          continue;
 44446         -        }
 44447         -
 44448         -        rc = sqlite3PagerGet(pBtFrom->pPager, iFrom, &pFromPage);
 44449         -        if( rc==SQLITE_OK ){
 44450         -          char *zFrom = sqlite3PagerGetData(pFromPage);
 44451         -          rc = sqlite3OsWrite(pFile, zFrom, nFromPageSize, iOff);
 44452         -          sqlite3PagerUnref(pFromPage);
 44453         -        }
 44454         -      }
 44455         -    }
 44456         -  }
 44457         -
 44458         -  /* Sync the database file */
 44459         -  if( rc==SQLITE_OK ){
 44460         -    rc = sqlite3PagerSync(pBtTo->pPager);
 44461         -  }
 44462         -  if( rc==SQLITE_OK ){
 44463         -    pBtTo->pageSizeFixed = 0;
 44464         -  }else{
 44465         -    sqlite3BtreeRollback(pTo);
 44466         -  }
 44467         -
 44468         -  return rc;
 44469         -}
 44470         -SQLITE_PRIVATE int sqlite3BtreeCopyFile(Btree *pTo, Btree *pFrom){
 44471         -  int rc;
 44472         -  sqlite3BtreeEnter(pTo);
 44473         -  sqlite3BtreeEnter(pFrom);
 44474         -  rc = btreeCopyFile(pTo, pFrom);
 44475         -  sqlite3BtreeLeave(pFrom);
 44476         -  sqlite3BtreeLeave(pTo);
 44477         -  return rc;
 44478         -}
 44479         -
 44480         -#endif /* SQLITE_OMIT_VACUUM */
 44481         -
 44482  44476   /*
 44483  44477   ** Return non-zero if a transaction is active.
 44484  44478   */
 44485  44479   SQLITE_PRIVATE int sqlite3BtreeIsInTrans(Btree *p){
 44486  44480     assert( p==0 || sqlite3_mutex_held(p->db->mutex) );
 44487  44481     return (p && (p->inTrans==TRANS_WRITE));
 44488  44482   }
................................................................................
 44499  44493   ** Return non-zero if a read (or write) transaction is active.
 44500  44494   */
 44501  44495   SQLITE_PRIVATE int sqlite3BtreeIsInReadTrans(Btree *p){
 44502  44496     assert( p );
 44503  44497     assert( sqlite3_mutex_held(p->db->mutex) );
 44504  44498     return p->inTrans!=TRANS_NONE;
 44505  44499   }
        44500  +
        44501  +SQLITE_PRIVATE int sqlite3BtreeIsInBackup(Btree *p){
        44502  +  assert( p );
        44503  +  assert( sqlite3_mutex_held(p->db->mutex) );
        44504  +  return p->nBackup!=0;
        44505  +}
 44506  44506   
 44507  44507   /*
 44508  44508   ** This function returns a pointer to a blob of memory associated with
 44509  44509   ** a single shared-btree. The memory is used by client code for its own
 44510  44510   ** purposes (for example, to store a high-level schema associated with 
 44511  44511   ** the shared-btree). The btree layer manages reference counting issues.
 44512  44512   **
................................................................................
 44627  44627     assert(!pCur->isIncrblobHandle);
 44628  44628     assert(!pCur->aOverflow);
 44629  44629     pCur->isIncrblobHandle = 1;
 44630  44630   }
 44631  44631   #endif
 44632  44632   
 44633  44633   /************** End of btree.c ***********************************************/
        44634  +/************** Begin file backup.c ******************************************/
        44635  +/*
        44636  +** 2009 January 28
        44637  +**
        44638  +** The author disclaims copyright to this source code.  In place of
        44639  +** a legal notice, here is a blessing:
        44640  +**
        44641  +**    May you do good and not evil.
        44642  +**    May you find forgiveness for yourself and forgive others.
        44643  +**    May you share freely, never taking more than you give.
        44644  +**
        44645  +*************************************************************************
        44646  +** This file contains the implementation of the sqlite3_backup_XXX() 
        44647  +** API functions and the related features.
        44648  +**
        44649  +** $Id: backup.c,v 1.1 2009/02/03 16:51:25 danielk1977 Exp $
        44650  +*/
        44651  +
        44652  +/* Macro to find the minimum of two numeric values.
        44653  +*/
        44654  +#ifndef MIN
        44655  +# define MIN(x,y) ((x)<(y)?(x):(y))
        44656  +#endif
        44657  +
        44658  +/*
        44659  +** Structure allocated for each backup operation.
        44660  +*/
        44661  +struct sqlite3_backup {
        44662  +  sqlite3* pDestDb;        /* Destination database handle */
        44663  +  Btree *pDest;            /* Destination b-tree file */
        44664  +  u32 iDestSchema;         /* Original schema cookie in destination */
        44665  +  int bDestLocked;         /* True once a write-transaction is open on pDest */
        44666  +
        44667  +  Pgno iNext;              /* Page number of the next source page to copy */
        44668  +  sqlite3* pSrcDb;         /* Source database handle */
        44669  +  Btree *pSrc;             /* Source b-tree file */
        44670  +
        44671  +  int rc;                  /* Backup process error code */
        44672  +
        44673  +  /* These two variables are set by every call to backup_step(). They are
        44674  +  ** read by calls to backup_remaining() and backup_pagecount().
        44675  +  */
        44676  +  Pgno nRemaining;         /* Number of pages left to copy */
        44677  +  Pgno nPagecount;         /* Total number of pages to copy */
        44678  +
        44679  +  sqlite3_backup *pNext;   /* Next backup associated with source pager */
        44680  +};
        44681  +
        44682  +/*
        44683  +** THREAD SAFETY NOTES:
        44684  +**
        44685  +**   Once it has been created using backup_init(), a single sqlite3_backup
        44686  +**   structure may be accessed via two groups of thread-safe entry points:
        44687  +**
        44688  +**     * Via the sqlite3_backup_XXX() API function backup_step() and 
        44689  +**       backup_finish(). Both these functions obtain the source database
        44690  +**       handle mutex and the mutex associated with the source BtShared 
        44691  +**       structure, in that order.
        44692  +**
        44693  +**     * Via the BackupUpdate() and BackupRestart() functions, which are
        44694  +**       invoked by the pager layer to report various state changes in
        44695  +**       the page cache associated with the source database. The mutex
        44696  +**       associated with the source database BtShared structure will always 
        44697  +**       be held when either of these functions are invoked.
        44698  +**
        44699  +**   The other sqlite3_backup_XXX() API functions, backup_remaining() and
        44700  +**   backup_pagecount() are not thread-safe functions. If they are called
        44701  +**   while some other thread is calling backup_step() or backup_finish(),
        44702  +**   the values returned may be invalid. There is no way for a call to
        44703  +**   BackupUpdate() or BackupRestart() to interfere with backup_remaining()
        44704  +**   or backup_pagecount().
        44705  +**
        44706  +**   Depending on the SQLite configuration, the database handles and/or
        44707  +**   the Btree objects may have their own mutexes that require locking.
        44708  +**   Non-sharable Btrees (in-memory databases for example), do not have
        44709  +**   associated mutexes.
        44710  +*/
        44711  +
        44712  +/*
        44713  +** Return a pointer corresponding to database zDb (i.e. "main", "temp")
        44714  +** in connection handle pDb. If such a database cannot be found, return
        44715  +** a NULL pointer and write an error message to pErrorDb.
        44716  +**
        44717  +** If the "temp" database is requested, it may need to be opened by this 
        44718  +** function. If an error occurs while doing so, return 0 and write an 
        44719  +** error message to pErrorDb.
        44720  +*/
        44721  +static Btree *findBtree(sqlite3 *pErrorDb, sqlite3 *pDb, const char *zDb){
        44722  +  int i = sqlite3FindDbName(pDb, zDb);
        44723  +
        44724  +  if( i==1 ){
        44725  +    Parse sParse;
        44726  +    memset(&sParse, 0, sizeof(sParse));
        44727  +    sParse.db = pDb;
        44728  +    if( sqlite3OpenTempDatabase(&sParse) ){
        44729  +      sqlite3ErrorClear(&sParse);
        44730  +      sqlite3Error(pErrorDb, sParse.rc, "%s", sParse.zErrMsg);
        44731  +      return 0;
        44732  +    }
        44733  +    assert( sParse.zErrMsg==0 );
        44734  +  }
        44735  +
        44736  +  if( i<0 ){
        44737  +    sqlite3Error(pErrorDb, SQLITE_ERROR, "unknown database %s", zDb);
        44738  +    return 0;
        44739  +  }
        44740  +
        44741  +  return pDb->aDb[i].pBt;
        44742  +}
        44743  +
        44744  +/*
        44745  +** Create an sqlite3_backup process to copy the contents of zSrcDb from
        44746  +** connection handle pSrcDb to zDestDb in pDestDb. If successful, return
        44747  +** a pointer to the new sqlite3_backup object.
        44748  +**
        44749  +** If an error occurs, NULL is returned and an error code and error message
        44750  +** stored in database handle pDestDb.
        44751  +*/
        44752  +SQLITE_API sqlite3_backup *sqlite3_backup_init(
        44753  +  sqlite3* pDestDb,                     /* Database to write to */
        44754  +  const char *zDestDb,                  /* Name of database within pDestDb */
        44755  +  sqlite3* pSrcDb,                      /* Database connection to read from */
        44756  +  const char *zSrcDb                    /* Name of database within pSrcDb */
        44757  +){
        44758  +  sqlite3_backup *p;                    /* Value to return */
        44759  +
        44760  +  /* Lock the source database handle. The destination database
        44761  +  ** handle is not locked. The user is required to ensure that no
        44762  +  ** other thread accesses the destination handle for the duration
        44763  +  ** of the backup operation.
        44764  +  */
        44765  +  sqlite3_mutex_enter(pSrcDb->mutex);
        44766  +
        44767  +  if( pSrcDb==pDestDb ){
        44768  +    sqlite3Error(
        44769  +        pDestDb, SQLITE_ERROR, "Source and destination handles must be distinct"
        44770  +    );
        44771  +    p = 0;
        44772  +  }else {
        44773  +    /* Allocate space for a new sqlite3_backup object */
        44774  +    p = (sqlite3_backup *)sqlite3_malloc(sizeof(sqlite3_backup));
        44775  +    if( !p ){
        44776  +      sqlite3Error(pDestDb, SQLITE_NOMEM, 0);
        44777  +    }
        44778  +  }
        44779  +
        44780  +  /* If the allocation succeeded, populate the new object. */
        44781  +  if( p ){
        44782  +    memset(p, 0, sizeof(sqlite3_backup));
        44783  +    p->pSrc = findBtree(pDestDb, pSrcDb, zSrcDb);
        44784  +    p->pDest = findBtree(pDestDb, pDestDb, zDestDb);
        44785  +    p->pDestDb = pDestDb;
        44786  +    p->pSrcDb = pSrcDb;
        44787  +    p->iNext = 1;
        44788  +
        44789  +    if( 0==p->pSrc || 0==p->pDest ){
        44790  +      /* One (or both) of the named databases did not exist. An error has
        44791  +      ** already been written into the pDestDb handle. All that is left
        44792  +      ** to do here is free the sqlite3_backup structure.
        44793  +      */
        44794  +      sqlite3_free(p);
        44795  +      p = 0;
        44796  +    }
        44797  +  }
        44798  +
        44799  +  /* If everything has gone as planned, attach the backup object to the
        44800  +  ** source pager. The source pager calls BackupUpdate() and BackupRestart()
        44801  +  ** to notify this module if the source file is modified mid-backup.
        44802  +  */
        44803  +  if( p ){
        44804  +    sqlite3_backup **pp;             /* Pointer to head of pagers backup list */
        44805  +    sqlite3BtreeEnter(p->pSrc);
        44806  +    pp = sqlite3PagerBackupPtr(sqlite3BtreePager(p->pSrc));
        44807  +    p->pNext = *pp;
        44808  +    *pp = p;
        44809  +    sqlite3BtreeLeave(p->pSrc);
        44810  +    p->pSrc->nBackup++;
        44811  +  }
        44812  +
        44813  +  sqlite3_mutex_leave(pSrcDb->mutex);
        44814  +  return p;
        44815  +}
        44816  +
        44817  +/*
        44818  +** Parameter zSrcData points to a buffer containing the data for 
        44819  +** page iSrcPg from the source database. Copy this data into the 
        44820  +** destination database.
        44821  +*/
        44822  +static int backupOnePage(sqlite3_backup *p, Pgno iSrcPg, const u8 *zSrcData){
        44823  +  Pager * const pDestPager = sqlite3BtreePager(p->pDest);
        44824  +  const int nSrcPgsz = sqlite3BtreeGetPageSize(p->pSrc);
        44825  +  int nDestPgsz = sqlite3BtreeGetPageSize(p->pDest);
        44826  +  const int nCopy = MIN(nSrcPgsz, nDestPgsz);
        44827  +  const i64 iEnd = (i64)iSrcPg*(i64)nSrcPgsz;
        44828  +
        44829  +  int rc = SQLITE_OK;
        44830  +  i64 iOff;
        44831  +
        44832  +  assert( p->bDestLocked );
        44833  +  assert( p->rc==SQLITE_OK );
        44834  +  assert( iSrcPg!=PENDING_BYTE_PAGE(p->pSrc->pBt) );
        44835  +  assert( zSrcData );
        44836  +
        44837  +  /* Catch the case where the destination is an in-memory database and the
        44838  +  ** page sizes of the source and destination differ. 
        44839  +  */
        44840  +  if( nSrcPgsz!=nDestPgsz && sqlite3PagerIsMemdb(sqlite3BtreePager(p->pDest)) ){
        44841  +    rc = SQLITE_READONLY;
        44842  +  }
        44843  +
        44844  +  /* This loop runs once for each destination page spanned by the source 
        44845  +  ** page. For each iteration, variable iOff is set to the byte offset
        44846  +  ** of the destination page.
        44847  +  */
        44848  +  for(iOff=iEnd-(i64)nSrcPgsz; rc==SQLITE_OK && iOff<iEnd; iOff+=nDestPgsz){
        44849  +    DbPage *pDestPg = 0;
        44850  +    Pgno iDest = (Pgno)(iOff/nDestPgsz)+1;
        44851  +    if( iDest==PENDING_BYTE_PAGE(p->pDest->pBt) ) continue;
        44852  +    if( SQLITE_OK==(rc = sqlite3PagerGet(pDestPager, iDest, &pDestPg))
        44853  +     && SQLITE_OK==(rc = sqlite3PagerWrite(pDestPg))
        44854  +    ){
        44855  +      const u8 *zIn = &zSrcData[iOff%nSrcPgsz];
        44856  +      u8 *zDestData = sqlite3PagerGetData(pDestPg);
        44857  +      u8 *zOut = &zDestData[iOff%nDestPgsz];
        44858  +
        44859  +      /* Copy the data from the source page into the destination page.
        44860  +      ** Then clear the Btree layer MemPage.isInit flag. Both this module
        44861  +      ** and the pager code use this trick (clearing the first byte
        44862  +      ** of the page 'extra' space to invalidate the Btree layers
        44863  +      ** cached parse of the page). MemPage.isInit is marked 
        44864  +      ** "MUST BE FIRST" for this purpose.
        44865  +      */
        44866  +      memcpy(zOut, zIn, nCopy);
        44867  +      ((u8 *)sqlite3PagerGetExtra(pDestPg))[0] = 0;
        44868  +    }
        44869  +    sqlite3PagerUnref(pDestPg);
        44870  +  }
        44871  +
        44872  +  return rc;
        44873  +}
        44874  +
        44875  +/*
        44876  +** Copy nPage pages from the source b-tree to the destination.
        44877  +*/
        44878  +SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage){
        44879  +  int rc;
        44880  +
        44881  +  sqlite3_mutex_enter(p->pSrcDb->mutex);
        44882  +  sqlite3BtreeEnter(p->pSrc);
        44883  +
        44884  +  rc = p->rc;
        44885  +  if( rc==SQLITE_OK ){
        44886  +    Pager * const pSrcPager = sqlite3BtreePager(p->pSrc);     /* Source pager */
        44887  +    Pager * const pDestPager = sqlite3BtreePager(p->pDest);   /* Dest pager */
        44888  +    int ii;                            /* Iterator variable */
        44889  +    int nSrcPage;                      /* Size of source db in pages */
        44890  +    int bCloseTrans = 0;               /* True if src db requires unlocking */
        44891  +
        44892  +    /* If the source pager is currently in a write-transaction, return
        44893  +    ** SQLITE_LOCKED immediately.
        44894  +    */
        44895  +    if( p->pDestDb && p->pSrc->pBt->inTransaction==TRANS_WRITE ){
        44896  +      rc = SQLITE_LOCKED;
        44897  +    }
        44898  +
        44899  +    /* Lock the destination database, if it is not locked already. */
        44900  +    if( SQLITE_OK==rc && p->bDestLocked==0
        44901  +     && SQLITE_OK==(rc = sqlite3BtreeBeginTrans(p->pDest, 2)) 
        44902  +    ){
        44903  +      p->bDestLocked = 1;
        44904  +      rc = sqlite3BtreeGetMeta(p->pDest, 1, &p->iDestSchema);
        44905  +    }
        44906  +
        44907  +    /* If there is no open read-transaction on the source database, open
        44908  +    ** one now. If a transaction is opened here, then it will be closed
        44909  +    ** before this function exits.
        44910  +    */
        44911  +    if( rc==SQLITE_OK && 0==sqlite3BtreeIsInReadTrans(p->pSrc) ){
        44912  +      rc = sqlite3BtreeBeginTrans(p->pSrc, 0);
        44913  +      bCloseTrans = 1;
        44914  +    }
        44915  +  
        44916  +    /* Now that there is a read-lock on the source database, query the
        44917  +    ** source pager for the number of pages in the database.
        44918  +    */
        44919  +    if( rc==SQLITE_OK ){
        44920  +      rc = sqlite3PagerPagecount(pSrcPager, &nSrcPage);
        44921  +    }
        44922  +    for(ii=0; ii<nPage && p->iNext<=nSrcPage && rc==SQLITE_OK; ii++){
        44923  +      const Pgno iSrcPg = p->iNext;                 /* Source page number */
        44924  +      if( iSrcPg!=PENDING_BYTE_PAGE(p->pSrc->pBt) ){
        44925  +        DbPage *pSrcPg;                             /* Source page object */
        44926  +        rc = sqlite3PagerGet(pSrcPager, iSrcPg, &pSrcPg);
        44927  +        if( rc==SQLITE_OK ){
        44928  +          rc = backupOnePage(p, iSrcPg, sqlite3PagerGetData(pSrcPg));
        44929  +          sqlite3PagerUnref(pSrcPg);
        44930  +        }
        44931  +      }
        44932  +      p->iNext++;
        44933  +    }
        44934  +    if( rc==SQLITE_OK ){
        44935  +      p->nPagecount = nSrcPage;
        44936  +      p->nRemaining = nSrcPage+1-p->iNext;
        44937  +      if( p->iNext>nSrcPage ){
        44938  +        rc = SQLITE_DONE;
        44939  +      }
        44940  +    }
        44941  +  
        44942  +    if( rc==SQLITE_DONE ){
        44943  +      const int nSrcPagesize = sqlite3BtreeGetPageSize(p->pSrc);
        44944  +      const int nDestPagesize = sqlite3BtreeGetPageSize(p->pDest);
        44945  +      int nDestTruncate;
        44946  +      sqlite3_file *pFile = 0;
        44947  +      i64 iSize;
        44948  +  
        44949  +      /* Update the schema version field in the destination database. This
        44950  +      ** is to make sure that the schema-version really does change in
        44951  +      ** the case where the source and destination databases have the
        44952  +      ** same schema version.
        44953  +      */
        44954  +      sqlite3BtreeUpdateMeta(p->pDest, 1, p->iDestSchema+1);
        44955  +
        44956  +      /* Set nDestTruncate to the final number of pages in the destination
        44957  +      ** database. The complication here is that the destination page
        44958  +      ** size may be different to the source page size. 
        44959  +      **
        44960  +      ** If the source page size is smaller than the destination page size, 
        44961  +      ** round up. In this case the call to sqlite3OsTruncate() below will
        44962  +      ** fix the size of the file. However it is important to call
        44963  +      ** sqlite3PagerTruncateImage() here so that any pages in the 
        44964  +      ** destination file that lie beyond the nDestTruncate page mark are
        44965  +      ** journalled by PagerCommitPhaseOne() before they are destroyed
        44966  +      ** by the file truncation.
        44967  +      */
        44968  +      if( nSrcPagesize<nDestPagesize ){
        44969  +        int ratio = nDestPagesize/nSrcPagesize;
        44970  +        nDestTruncate = (nSrcPage+ratio-1)/ratio;
        44971  +      }else{
        44972  +        nDestTruncate = nSrcPage * (nSrcPagesize/nDestPagesize);
        44973  +      }
        44974  +      sqlite3PagerTruncateImage(pDestPager, nDestTruncate);
        44975  +
        44976  +      if( nSrcPagesize<nDestPagesize ){
        44977  +        /* If the source page-size is smaller than the destination page-size,
        44978  +        ** two extra things may need to happen:
        44979  +        **
        44980  +        **   * The destination may need to be truncated, and
        44981  +        **
        44982  +        **   * Data stored on the pages immediately following the 
        44983  +        **     pending-byte page in the source database may need to be
        44984  +        **     copied into the destination database.
        44985  +        */
        44986  +        iSize = (i64)nSrcPagesize * (i64)nSrcPage;
        44987  +        pFile = sqlite3PagerFile(pDestPager);
        44988  +        assert( pFile );
        44989  +        if( SQLITE_OK==(rc = sqlite3PagerCommitPhaseOne(pDestPager, 0, 1))
        44990  +         && SQLITE_OK==(rc = sqlite3OsTruncate(pFile, iSize))
        44991  +         && SQLITE_OK==(rc = sqlite3PagerSync(pDestPager))
        44992  +        ){
        44993  +          i64 iOff;
        44994  +          i64 iEnd = MIN(PENDING_BYTE + nDestPagesize, iSize);
        44995  +          for(
        44996  +            iOff=PENDING_BYTE+nSrcPagesize; 
        44997  +            rc==SQLITE_OK && iOff<iEnd; 
        44998  +            iOff+=nSrcPagesize
        44999  +          ){
        45000  +            PgHdr *pSrcPg = 0;
        45001  +            const Pgno iSrcPg = (iOff/nSrcPagesize)+1;
        45002  +            rc = sqlite3PagerGet(pSrcPager, iSrcPg, &pSrcPg);
        45003  +            if( rc==SQLITE_OK ){
        45004  +              u8 *zData = sqlite3PagerGetData(pSrcPg);
        45005  +              rc = sqlite3OsWrite(pFile, zData, nSrcPagesize, iOff);
        45006  +            }
        45007  +            sqlite3PagerUnref(pSrcPg);
        45008  +          }
        45009  +        }
        45010  +      }else{
        45011  +        rc = sqlite3PagerCommitPhaseOne(pDestPager, 0, 0);
        45012  +      }
        45013  +  
        45014  +      /* Finish committing the transaction to the destination database. */
        45015  +      if( SQLITE_OK==rc
        45016  +       && SQLITE_OK==(rc = sqlite3BtreeCommitPhaseTwo(p->pDest))
        45017  +      ){
        45018  +        rc = SQLITE_DONE;
        45019  +      }
        45020  +    }
        45021  +  
        45022  +    /* If bCloseTrans is true, then this function opened a read transaction
        45023  +    ** on the source database. Close the read transaction here. There is
        45024  +    ** no need to check the return values of the btree methods here, as
        45025  +    ** "committing" a read-only transaction cannot fail.
        45026  +    */
        45027  +    if( bCloseTrans ){
        45028  +      TESTONLY( int rc2 );
        45029  +      TESTONLY( rc2  = ) sqlite3BtreeCommitPhaseOne(p->pSrc, 0);
        45030  +      TESTONLY( rc2 |= ) sqlite3BtreeCommitPhaseTwo(p->pSrc);
        45031  +      assert( rc2==SQLITE_OK );
        45032  +    }
        45033  +  
        45034  +    if( rc!=SQLITE_LOCKED && rc!=SQLITE_BUSY ){
        45035  +      p->rc = rc;
        45036  +    }
        45037  +  }
        45038  +  sqlite3BtreeLeave(p->pSrc);
        45039  +  sqlite3_mutex_leave(p->pSrcDb->mutex);
        45040  +  return rc;
        45041  +}
        45042  +
        45043  +/*
        45044  +** Release all resources associated with an sqlite3_backup* handle.
        45045  +*/
        45046  +SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p){
        45047  +  sqlite3_backup **pp;                 /* Ptr to head of pagers backup list */
        45048  +  sqlite3_mutex *mutex;                /* Mutex to protect source database */
        45049  +  int rc;                              /* Value to return */
        45050  +
        45051  +  /* Enter the mutexes */
        45052  +  sqlite3_mutex_enter(p->pSrcDb->mutex);
        45053  +  sqlite3BtreeEnter(p->pSrc);
        45054  +  mutex = p->pSrcDb->mutex;
        45055  +
        45056  +  /* Detach this backup from the source pager. */
        45057  +  if( p->pDestDb ){
        45058  +    pp = sqlite3PagerBackupPtr(sqlite3BtreePager(p->pSrc));
        45059  +    while( *pp!=p ){
        45060  +      pp = &(*pp)->pNext;
        45061  +    }
        45062  +    *pp = p->pNext;
        45063  +    p->pSrc->nBackup--;
        45064  +  }
        45065  +
        45066  +  /* If a transaction is still open on the Btree, roll it back. */
        45067  +  sqlite3BtreeRollback(p->pDest);
        45068  +
        45069  +  /* Set the error code of the destination database handle. */
        45070  +  rc = (p->rc==SQLITE_DONE) ? SQLITE_OK : p->rc;
        45071  +  sqlite3Error(p->pDestDb, rc, 0);
        45072  +
        45073  +  /* Exit the mutexes and free the backup context structure. */
        45074  +  sqlite3BtreeLeave(p->pSrc);
        45075  +  if( p->pDestDb ){
        45076  +    sqlite3_free(p);
        45077  +  }
        45078  +  sqlite3_mutex_leave(mutex);
        45079  +  return rc;
        45080  +}
        45081  +
        45082  +/*
        45083  +** Return the number of pages still to be backed up as of the most recent
        45084  +** call to sqlite3_backup_step().
        45085  +*/
        45086  +SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p){
        45087  +  return p->nRemaining;
        45088  +}
        45089  +
        45090  +/*
        45091  +** Return the total number of pages in the source database as of the most 
        45092  +** recent call to sqlite3_backup_step().
        45093  +*/
        45094  +SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p){
        45095  +  return p->nPagecount;
        45096  +}
        45097  +
        45098  +/*
        45099  +** This function is called after the contents of page iPage of the
        45100  +** source database have been modified. If page iPage has already been 
        45101  +** copied into the destination database, then the data written to the
        45102  +** destination is now invalidated. The destination copy of iPage needs
        45103  +** to be updated with the new data before the backup operation is
        45104  +** complete.
        45105  +**
        45106  +** It is assumed that the mutex associated with the BtShared object
        45107  +** corresponding to the source database is held when this function is
        45108  +** called.
        45109  +*/
        45110  +SQLITE_PRIVATE void sqlite3BackupUpdate(sqlite3_backup *pBackup, Pgno iPage, const u8 *aData){
        45111  +  sqlite3_backup *p;                   /* Iterator variable */
        45112  +  for(p=pBackup; p; p=p->pNext){
        45113  +    assert( sqlite3_mutex_held(p->pSrc->pBt->mutex) );
        45114  +    if( p->rc==SQLITE_OK && iPage<p->iNext ){
        45115  +      /* The backup process p has already copied page iPage. But now it
        45116  +      ** has been modified by a transaction on the source pager. Copy
        45117  +      ** the new data into the backup.
        45118  +      */
        45119  +      int rc = backupOnePage(p, iPage, aData);
        45120  +      if( rc!=SQLITE_OK ){
        45121  +        p->rc = rc;
        45122  +      }
        45123  +    }
        45124  +  }
        45125  +}
        45126  +
        45127  +/*
        45128  +** Restart the backup process. This is called when the pager layer
        45129  +** detects that the database has been modified by an external database
        45130  +** connection. In this case there is no way of knowing which of the
        45131  +** pages that have been copied into the destination database are still 
        45132  +** valid and which are not, so the entire process needs to be restarted.
        45133  +**
        45134  +** It is assumed that the mutex associated with the BtShared object
        45135  +** corresponding to the source database is held when this function is
        45136  +** called.
        45137  +*/
        45138  +SQLITE_PRIVATE void sqlite3BackupRestart(sqlite3_backup *pBackup){
        45139  +  sqlite3_backup *p;                   /* Iterator variable */
        45140  +  for(p=pBackup; p; p=p->pNext){
        45141  +    assert( sqlite3_mutex_held(p->pSrc->pBt->mutex) );
        45142  +    p->iNext = 1;
        45143  +  }
        45144  +}
        45145  +
        45146  +#ifndef SQLITE_OMIT_VACUUM
        45147  +/*
        45148  +** Copy the complete content of pBtFrom into pBtTo.  A transaction
        45149  +** must be active for both files.
        45150  +**
        45151  +** The size of file pTo may be reduced by this operation. If anything 
        45152  +** goes wrong, the transaction on pTo is rolled back. If successful, the 
        45153  +** transaction is committed before returning.
        45154  +*/
        45155  +SQLITE_PRIVATE int sqlite3BtreeCopyFile(Btree *pTo, Btree *pFrom){
        45156  +  int rc;
        45157  +  sqlite3_backup b;
        45158  +  sqlite3BtreeEnter(pTo);
        45159  +  sqlite3BtreeEnter(pFrom);
        45160  +
        45161  +  /* Set up an sqlite3_backup object. sqlite3_backup.pDestDb must be set
        45162  +  ** to 0. This is used by the implementations of sqlite3_backup_step()
        45163  +  ** and sqlite3_backup_finish() to detect that they are being called
        45164  +  ** from this function, not directly by the user.
        45165  +  */
        45166  +  memset(&b, 0, sizeof(b));
        45167  +  b.pSrcDb = pFrom->db;
        45168  +  b.pSrc = pFrom;
        45169  +  b.pDest = pTo;
        45170  +  b.iNext = 1;
        45171  +
        45172  +  /* 0x7FFFFFFF is the hard limit for the number of pages in a database
        45173  +  ** file. By passing this as the number of pages to copy to
        45174  +  ** sqlite3_backup_step(), we can guarantee that the copy finishes 
        45175  +  ** within a single call (unless an error occurs). The assert() statement
        45176  +  ** checks this assumption - (p->rc) should be set to either SQLITE_DONE 
        45177  +  ** or an error code.
        45178  +  */
        45179  +  sqlite3_backup_step(&b, 0x7FFFFFFF);
        45180  +  assert( b.rc!=SQLITE_OK );
        45181  +  rc = sqlite3_backup_finish(&b);
        45182  +  if( rc==SQLITE_OK ){
        45183  +    pTo->pBt->pageSizeFixed = 0;
        45184  +  }
        45185  +
        45186  +  sqlite3BtreeLeave(pFrom);
        45187  +  sqlite3BtreeLeave(pTo);
        45188  +  return rc;
        45189  +}
        45190  +#endif /* SQLITE_OMIT_VACUUM */
        45191  +
        45192  +
        45193  +/************** End of backup.c **********************************************/
 44634  45194   /************** Begin file vdbemem.c *****************************************/
 44635  45195   /*
 44636  45196   ** 2004 May 26
 44637  45197   **
 44638  45198   ** The author disclaims copyright to this source code.  In place of
 44639  45199   ** a legal notice, here is a blessing:
 44640  45200   **
................................................................................
 45683  46243   **
 45684  46244   *************************************************************************
 45685  46245   ** This file contains code used for creating, destroying, and populating
 45686  46246   ** a VDBE (or an "sqlite3_stmt" as it is known to the outside world.)  Prior
 45687  46247   ** to version 2.8.7, all this code was combined into the vdbe.c source file.
 45688  46248   ** But that file was getting too big so this subroutines were split out.
 45689  46249   **
 45690         -** $Id: vdbeaux.c,v 1.434 2009/01/20 17:06:27 danielk1977 Exp $
        46250  +** $Id: vdbeaux.c,v 1.435 2009/02/03 16:51:25 danielk1977 Exp $
 45691  46251   */
 45692  46252   
 45693  46253   
 45694  46254   
 45695  46255   /*
 45696  46256   ** When debugging the code generator in a symbolic debugger, one can
 45697  46257   ** set the sqlite3VdbeAddopTrace to 1 and all opcodes will be printed
................................................................................
 46965  47525     ** string, it means the main database is :memory: or a temp file.  In 
 46966  47526     ** that case we do not support atomic multi-file commits, so use the 
 46967  47527     ** simple case then too.
 46968  47528     */
 46969  47529     if( 0==sqlite3Strlen30(sqlite3BtreeGetFilename(db->aDb[0].pBt))
 46970  47530      || nTrans<=1
 46971  47531     ){
 46972         -    for(i=0; rc==SQLITE_OK && i<db->nDb; i++){ 
        47532  +    for(i=0; rc==SQLITE_OK && i<db->nDb; i++){
 46973  47533         Btree *pBt = db->aDb[i].pBt;
 46974  47534         if( pBt ){
 46975  47535           rc = sqlite3BtreeCommitPhaseOne(pBt, 0);
 46976  47536         }
 46977  47537       }
 46978  47538   
 46979  47539       /* Do the commit only if all databases successfully complete phase 1. 
................................................................................
 61249  61809   **    May you do good and not evil.
 61250  61810   **    May you find forgiveness for yourself and forgive others.
 61251  61811   **    May you share freely, never taking more than you give.
 61252  61812   **
 61253  61813   *************************************************************************
 61254  61814   ** This file contains code used to implement the ATTACH and DETACH commands.
 61255  61815   **
 61256         -** $Id: attach.c,v 1.81 2008/12/10 16:45:51 drh Exp $
        61816  +** $Id: attach.c,v 1.82 2009/02/03 16:51:25 danielk1977 Exp $
 61257  61817   */
 61258  61818   
 61259  61819   #ifndef SQLITE_OMIT_ATTACH
 61260  61820   /*
 61261  61821   ** Resolve an expression that was part of an ATTACH or DETACH statement. This
 61262  61822   ** is slightly different from resolving a normal SQL expression, because simple
 61263  61823   ** identifiers are treated as strings, not possible column names or aliases.
................................................................................
 61502  62062       goto detach_error;
 61503  62063     }
 61504  62064     if( !db->autoCommit ){
 61505  62065       sqlite3_snprintf(sizeof(zErr), zErr,
 61506  62066                        "cannot DETACH database within transaction");
 61507  62067       goto detach_error;
 61508  62068     }
 61509         -  if( sqlite3BtreeIsInReadTrans(pDb->pBt) ){
        62069  +  if( sqlite3BtreeIsInReadTrans(pDb->pBt) || sqlite3BtreeIsInBackup(pDb->pBt) ){
 61510  62070       sqlite3_snprintf(sizeof(zErr),zErr, "database %s is locked", zName);
 61511  62071       goto detach_error;
 61512  62072     }
 61513  62073   
 61514  62074     sqlite3BtreeClose(pDb->pBt);
 61515  62075     pDb->pBt = 0;
 61516  62076     pDb->pSchema = 0;
................................................................................
 62037  62597   **     CREATE INDEX
 62038  62598   **     DROP INDEX
 62039  62599   **     creating ID lists
 62040  62600   **     BEGIN TRANSACTION
 62041  62601   **     COMMIT
 62042  62602   **     ROLLBACK
 62043  62603   **
 62044         -** $Id: build.c,v 1.514 2009/02/03 15:50:34 drh Exp $
        62604  +** $Id: build.c,v 1.515 2009/02/03 16:51:25 danielk1977 Exp $
 62045  62605   */
 62046  62606   
 62047  62607   /*
 62048  62608   ** This routine is called when a new SQL statement is beginning to
 62049  62609   ** be parsed.  Initialize the pParse structure as needed.
 62050  62610   */
 62051  62611   SQLITE_PRIVATE void sqlite3BeginParse(Parse *pParse, int explainFlag){
................................................................................
 62635  63195     Vdbe *v = sqlite3GetVdbe(p);
 62636  63196     sqlite3TableLock(p, iDb, MASTER_ROOT, 1, SCHEMA_TABLE(iDb));
 62637  63197     sqlite3VdbeAddOp2(v, OP_SetNumColumns, 0, 5);/* sqlite_master has 5 columns */
 62638  63198     sqlite3VdbeAddOp3(v, OP_OpenWrite, 0, MASTER_ROOT, iDb);
 62639  63199   }
 62640  63200   
 62641  63201   /*
 62642         -** The token *pName contains the name of a database (either "main" or
 62643         -** "temp" or the name of an attached db). This routine returns the
 62644         -** index of the named database in db->aDb[], or -1 if the named db 
 62645         -** does not exist.
        63202  +** Parameter zName points to a nul-terminated buffer containing the name
        63203  +** of a database ("main", "temp" or the name of an attached db). This
        63204  +** function returns the index of the named database in db->aDb[], or
        63205  +** -1 if the named db cannot be found.
 62646  63206   */
 62647         -SQLITE_PRIVATE int sqlite3FindDb(sqlite3 *db, Token *pName){
 62648         -  int i = -1;    /* Database number */
 62649         -  int n;         /* Number of characters in the name */
 62650         -  Db *pDb;       /* A database whose name space is being searched */
 62651         -  char *zName;   /* Name we are searching for */
 62652         -
 62653         -  zName = sqlite3NameFromToken(db, pName);
        63207  +SQLITE_PRIVATE int sqlite3FindDbName(sqlite3 *db, const char *zName){
        63208  +  int i = -1;         /* Database number */
 62654  63209     if( zName ){
 62655         -    n = sqlite3Strlen30(zName);
        63210  +    Db *pDb;
        63211  +    int n = sqlite3Strlen30(zName);
 62656  63212       for(i=(db->nDb-1), pDb=&db->aDb[i]; i>=0; i--, pDb--){
 62657  63213         if( (!OMIT_TEMPDB || i!=1 ) && n==sqlite3Strlen30(pDb->zName) && 
 62658  63214             0==sqlite3StrICmp(pDb->zName, zName) ){
 62659  63215           break;
 62660  63216         }
 62661  63217       }
 62662         -    sqlite3DbFree(db, zName);
 62663  63218     }
 62664  63219     return i;
 62665  63220   }
        63221  +
        63222  +/*
        63223  +** The token *pName contains the name of a database (either "main" or
        63224  +** "temp" or the name of an attached db). This routine returns the
        63225  +** index of the named database in db->aDb[], or -1 if the named db 
        63226  +** does not exist.
        63227  +*/
        63228  +SQLITE_PRIVATE int sqlite3FindDb(sqlite3 *db, Token *pName){
        63229  +  int i;                               /* Database number */
        63230  +  char *zName;                         /* Name we are searching for */
        63231  +  zName = sqlite3NameFromToken(db, pName);
        63232  +  i = sqlite3FindDbName(db, zName);
        63233  +  sqlite3DbFree(db, zName);
        63234  +  return i;
        63235  +}
 62666  63236   
 62667  63237   /* The table or view or trigger name is passed to this routine via tokens
 62668  63238   ** pName1 and pName2. If the table name was fully qualified, for example:
 62669  63239   **
 62670  63240   ** CREATE TABLE xxx.yyy (...);
 62671  63241   ** 
 62672  63242   ** Then pName1 is set to "xxx" and pName2 "yyy". On the other hand if
................................................................................
 79208  79778   **
 79209  79779   *************************************************************************
 79210  79780   ** This file contains code used to implement the VACUUM command.
 79211  79781   **
 79212  79782   ** Most of the code in this file may be omitted by defining the
 79213  79783   ** SQLITE_OMIT_VACUUM macro.
 79214  79784   **
 79215         -** $Id: vacuum.c,v 1.85 2009/01/22 23:04:46 drh Exp $
        79785  +** $Id: vacuum.c,v 1.86 2009/02/03 16:51:25 danielk1977 Exp $
 79216  79786   */
 79217  79787   
 79218  79788   #if !defined(SQLITE_OMIT_VACUUM) && !defined(SQLITE_OMIT_ATTACH)
 79219  79789   /*
 79220  79790   ** Execute zSql on database db. Return an error code.
 79221  79791   */
 79222  79792   static int execSql(sqlite3 *db, const char *zSql){
................................................................................
 79457  80027       rc = sqlite3BtreeCopyFile(pMain, pTemp);
 79458  80028       if( rc!=SQLITE_OK ) goto end_of_vacuum;
 79459  80029       rc = sqlite3BtreeCommit(pTemp);
 79460  80030       if( rc!=SQLITE_OK ) goto end_of_vacuum;
 79461  80031   #ifndef SQLITE_OMIT_AUTOVACUUM
 79462  80032       sqlite3BtreeSetAutoVacuum(pMain, sqlite3BtreeGetAutoVacuum(pTemp));
 79463  80033   #endif
 79464         -    rc = sqlite3BtreeCommit(pMain);
 79465  80034     }
 79466  80035   
 79467  80036     if( rc==SQLITE_OK ){
 79468  80037       rc = sqlite3BtreeSetPageSize(pMain, sqlite3BtreeGetPageSize(pTemp), nRes);
 79469  80038     }
 79470  80039   
 79471  80040   end_of_vacuum:
................................................................................
 87835  88404   **
 87836  88405   *************************************************************************
 87837  88406   ** Main file for the SQLite library.  The routines in this file
 87838  88407   ** implement the programmer interface to the library.  Routines in
 87839  88408   ** other files are for internal use by SQLite and should not be
 87840  88409   ** accessed by users of the library.
 87841  88410   **
 87842         -** $Id: main.c,v 1.524 2009/02/03 15:50:34 drh Exp $
        88411  +** $Id: main.c,v 1.525 2009/02/03 16:51:25 danielk1977 Exp $
 87843  88412   */
 87844  88413   
 87845  88414   #ifdef SQLITE_ENABLE_FTS3
 87846  88415   /************** Include fts3.h in the middle of main.c ***********************/
 87847  88416   /************** Begin file fts3.h ********************************************/
 87848  88417   /*
 87849  88418   ** 2006 Oct 10
................................................................................
 88510  89079     if( db->pVdbe ){
 88511  89080       sqlite3Error(db, SQLITE_BUSY, 
 88512  89081           "Unable to close due to unfinalised statements");
 88513  89082       sqlite3_mutex_leave(db->mutex);
 88514  89083       return SQLITE_BUSY;
 88515  89084     }
 88516  89085     assert( sqlite3SafetyCheckSickOrOk(db) );
        89086  +
        89087  +  for(j=0; j<db->nDb; j++){
        89088  +    Btree *pBt = db->aDb[j].pBt;
        89089  +    if( pBt && sqlite3BtreeIsInBackup(pBt) ){
        89090  +      sqlite3Error(db, SQLITE_BUSY, 
        89091  +          "Unable to close due to unfinished backup operation");
        89092  +      sqlite3_mutex_leave(db->mutex);
        89093  +      return SQLITE_BUSY;
        89094  +    }
        89095  +  }
 88517  89096   
 88518  89097     /* Free any outstanding Savepoint structures. */
 88519  89098     sqlite3CloseSavepoints(db);
 88520  89099   
 88521  89100     for(j=0; j<db->nDb; j++){
 88522  89101       struct Db *pDb = &db->aDb[j];
 88523  89102       if( pDb->pBt ){

Changes to src/sqlite3.h.

    26     26   ** on how SQLite interfaces are suppose to operate.
    27     27   **
    28     28   ** The name of this file under configuration management is "sqlite.h.in".
    29     29   ** The makefile makes some minor changes to this file (such as inserting
    30     30   ** the version number) and changes its name to "sqlite3.h" as
    31     31   ** part of the build process.
    32     32   **
    33         -** @(#) $Id: sqlite.h.in,v 1.422 2009/01/23 16:45:01 danielk1977 Exp $
           33  +** @(#) $Id: sqlite.h.in,v 1.423 2009/02/03 16:51:25 danielk1977 Exp $
    34     34   */
    35     35   #ifndef _SQLITE3_H_
    36     36   #define _SQLITE3_H_
    37     37   #include <stdarg.h>     /* Needed for the definition of va_list */
    38     38   
    39     39   /*
    40     40   ** Make sure we can call this stuff from C++.
................................................................................
  6718   6718     void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
  6719   6719     void (*xUnpin)(sqlite3_pcache*, void*, int discard);
  6720   6720     void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
  6721   6721     void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
  6722   6722     void (*xDestroy)(sqlite3_pcache*);
  6723   6723   };
  6724   6724   
         6725  +/*
         6726  +** CAPI3REF: Online Backup Object
         6727  +** EXPERIMENTAL
         6728  +**
         6729  +** The sqlite3_backup object records state information about an ongoing
         6730  +** online backup operation.  The sqlite3_backup object is created by
         6731  +** a call to [sqlite3_backup_init()] and is destroyed by a call to
         6732  +** [sqlite3_backup_finish()].
         6733  +*/
         6734  +typedef struct sqlite3_backup sqlite3_backup;
         6735  +
         6736  +/*
         6737  +** CAPI3REF: Online Backup API.
         6738  +** EXPERIMENTAL
         6739  +**
         6740  +** This API is used to overwrite the contents of one database with that
         6741  +** of another. It is useful either for creating backups of databases or
         6742  +** for copying in-memory databases to or from persistent files. 
         6743  +**
         6744  +** Exclusive access is required to the destination database for the 
         6745  +** duration of the operation. However the source database is only
         6746  +** read-locked while it is actually being read, it is not locked
         6747  +** continuously for the entire operation. Thus, the backup may be
         6748  +** performed on a live database without preventing other users from
         6749  +** writing to the database for an extended period of time.
         6750  +** 
         6751  +** To perform a backup operation: 
         6752  +**   <ol>
         6753  +**     <li>[sqlite3_backup_init()] is called once to initialize the backup, 
         6754  +**     <li>[sqlite3_backup_step()] is called one or more times to transfer 
         6755  +**         the data between the two databases, and finally
         6756  +**     <li>[sqlite3_backup_finish()] is called to release all resources 
         6757  +**         associated with the backup operation. 
         6758  +**   </ol>
         6759  +** There should be exactly one call to sqlite3_backup_finish() for each
         6760  +** successful call to sqlite3_backup_init().
         6761  +**
         6762  +** <b>sqlite3_backup_init()</b>
         6763  +**
         6764  +** The first two arguments passed to [sqlite3_backup_init()] are the database
         6765  +** handle associated with the destination database and the database name 
         6766  +** used to attach the destination database to the handle. The database name
         6767  +** is "main" for the main database, "temp" for the temporary database, or
         6768  +** the name specified as part of the ATTACH statement if the destination is
         6769  +** an attached database. The third and fourth arguments passed to 
         6770  +** sqlite3_backup_init() identify the database handle and database name used
         6771  +** to access the source database. The values passed for the source and 
         6772  +** destination database handle parameters must not be the same.
         6773  +**
         6774  +** If an error occurs within sqlite3_backup_init(), then NULL is returned
         6775  +** and an error code and error message written into the database handle 
         6776  +** passed as the first argument. They may be retrieved using the
         6777  +** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16() functions.
         6778  +** Otherwise, if successful, a pointer to an [sqlite3_backup] object is
         6779  +** returned. This pointer may be used with the sqlite3_backup_step() and
         6780  +** sqlite3_backup_finish() functions to perform the specified backup 
         6781  +** operation.
         6782  +**
         6783  +** <b>sqlite3_backup_step()</b>
         6784  +**
         6785  +** Function [sqlite3_backup_step()] is used to copy up to nPage pages between 
         6786  +** the source and destination databases, where nPage is the value of the 
         6787  +** second parameter passed to sqlite3_backup_step(). If nPage pages are 
         6788  +** succesfully copied, but there are still more pages to copy before the 
         6789  +** backup is complete, it returns SQLITE_OK. If no error occured and there 
         6790  +** are no more pages to copy, then SQLITE_DONE is returned. If an error 
         6791  +** occurs, then an SQLite error code is returned. As well as SQLITE_OK and
         6792  +** SQLITE_DONE, a call to sqlite3_backup_step() may return SQLITE_READONLY,
         6793  +** SQLITE_NOMEM, SQLITE_BUSY, SQLITE_LOCKED or an SQLITE_IOERR_XXX error code.
         6794  +**
         6795  +** As well as the case where the destination database file was opened for
         6796  +** read-only access, sqlite3_backup_step() may return SQLITE_READONLY if
         6797  +** the destination is an in-memory database with a different page size
         6798  +** from the source database.
         6799  +**
         6800  +** If sqlite3_backup_step() cannot obtain a required file-system lock, then
         6801  +** the busy-handler function is invoked (if one is specified). If the 
         6802  +** busy-handler returns non-zero before the lock is available, then 
         6803  +** SQLITE_BUSY is returned to the caller. In this case the call to
         6804  +** sqlite3_backup_step() can be retried later. If the source database handle
         6805  +** is being used to write to the source database when sqlite3_backup_step()
         6806  +** is called, then SQLITE_LOCKED is returned immediately. Again, in this
         6807  +** case the call to sqlite3_backup_step() can be retried later on. If
         6808  +** SQLITE_IOERR_XXX, SQLITE_NOMEM or SQLITE_READONLY is returned, then 
         6809  +** there is no point in retrying the call to sqlite3_backup_step(). These 
         6810  +** errors are considered fatal. At this point the application must accept 
         6811  +** that the backup operation has failed and pass the backup operation handle 
         6812  +** to the sqlite3_backup_finish() to release associated resources.
         6813  +**
         6814  +** Following the first call to sqlite3_backup_step(), an exclusive lock is
         6815  +** obtained on the destination file. It is not released until either 
         6816  +** sqlite3_backup_finish() is called or the backup operation is complete 
         6817  +** and sqlite3_backup_step() returns SQLITE_DONE. Additionally, each time 
         6818  +** a call to sqlite3_backup_step() is made a shared lock is obtained on
         6819  +** the source database file. This lock is released before the
         6820  +** sqlite3_backup_step() call returns. Because the source database is not
         6821  +** locked between calls to sqlite3_backup_step(), it may be modified mid-way
         6822  +** through the backup procedure. If the source database is modified by an
         6823  +** external process or via a database connection other than the one being
         6824  +** used by the backup operation, then the backup will be transparently
         6825  +** restarted by the next call to sqlite3_backup_step(). If the source 
         6826  +** database is modified by the using the same database connection as is used
         6827  +** by the backup operation, then the backup database is transparently 
         6828  +** updated at the same time.
         6829  +**
         6830  +** <b>sqlite3_backup_finish()</b>
         6831  +**
         6832  +** Once sqlite3_backup_step() has returned SQLITE_DONE, or when the 
         6833  +** application wishes to abandon the backup operation, the [sqlite3_backup]
         6834  +** object should be passed to sqlite3_backup_finish(). This releases all
         6835  +** resources associated with the backup operation. If sqlite3_backup_step()
         6836  +** has not yet returned SQLITE_DONE, then any active write-transaction on the
         6837  +** destination database is rolled back. The [sqlite3_backup] object is invalid
         6838  +** and may not be used following a call to sqlite3_backup_finish().
         6839  +**
         6840  +** The value returned by sqlite3_backup_finish is SQLITE_OK if no error
         6841  +** occured, regardless or whether or not sqlite3_backup_step() was called
         6842  +** a sufficient number of times to complete the backup operation. Or, if
         6843  +** an out-of-memory condition or IO error occured during a call to
         6844  +** sqlite3_backup_step() then SQLITE_NOMEM or an SQLITE_IOERR_XXX error code
         6845  +** is returned. In this case the error code and an error message are
         6846  +** written to the destination database handle.
         6847  +**
         6848  +** A return of SQLITE_BUSY or SQLITE_LOCKED from sqlite3_backup_step() is
         6849  +** not considered an error and does not affect the return value of
         6850  +** sqlite3_backup_finish().
         6851  +**
         6852  +** <b>sqlite3_backup_remaining(), sqlite3_backup_pagecount()</b>
         6853  +**
         6854  +** Each call to sqlite3_backup_step() sets two values stored internally
         6855  +** by an [sqlite3_backup] object. The number of pages still to be backed
         6856  +** up, which may be queried by sqlite3_backup_remaining(), and the total
         6857  +** number of pages in the source database file, which may be queried by
         6858  +** sqlite3_backup_pagecount().
         6859  +**
         6860  +** The values returned by these functions are only updated by
         6861  +** sqlite3_backup_step(). If the source database is modified during a backup
         6862  +** operation, then the values are not updated to account for any extra
         6863  +** pages that need to be updated or the size of the source database file
         6864  +** changing.
         6865  +**
         6866  +** <b>Concurrent Usage of Database Handles</b>
         6867  +**
         6868  +** The source database handle may be used by the application for other
         6869  +** purposes while a backup operation is underway or being initialized.
         6870  +** If SQLite is compiled and configured to support threadsafe database
         6871  +** connections, then the source database connection may be used concurrently
         6872  +** from within other threads.
         6873  +**
         6874  +** However, the application must guarantee that the destination database
         6875  +** connection handle is not passed to any other API (by any thread) after 
         6876  +** sqlite3_backup_init() is called and before the corresponding call to
         6877  +** sqlite3_backup_finish(). Unfortunately SQLite does not currently check
         6878  +** for this, if the application does use the destination database handle
         6879  +** for some other purpose during a backup operation, things may appear to
         6880  +** work correctly but in fact be subtly malfunctioning.
         6881  +**
         6882  +** Furthermore, if running in shared cache mode, the application must
         6883  +** guarantee that the shared cache used by the destination database
         6884  +** is not accessed while the backup is running. In practice this means
         6885  +** that the application must guarantee that the file-system file being 
         6886  +** backed up to is not accessed by any connection within the process,
         6887  +** not just the specific connection that was passed to sqlite3_backup_init().
         6888  +**
         6889  +** The [sqlite3_backup] object itself is partially threadsafe. Multiple 
         6890  +** threads may safely make multiple concurrent calls to sqlite3_backup_step().
         6891  +** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
         6892  +** APIs are not strictly speaking threadsafe. If they are invoked at the
         6893  +** same time as another thread is invoking sqlite3_backup_step() it is
         6894  +** possible that they return invalid values.
         6895  +*/
         6896  +sqlite3_backup *sqlite3_backup_init(
         6897  +  sqlite3 *pDest,                        /* Destination database handle */
         6898  +  const char *zDestName,                 /* Destination database name */
         6899  +  sqlite3 *pSource,                      /* Source database handle */
         6900  +  const char *zSourceName                /* Source database name */
         6901  +);
         6902  +int sqlite3_backup_step(sqlite3_backup *p, int nPage);
         6903  +int sqlite3_backup_finish(sqlite3_backup *p);
         6904  +int sqlite3_backup_remaining(sqlite3_backup *p);
         6905  +int sqlite3_backup_pagecount(sqlite3_backup *p);
         6906  +
  6725   6907   /*
  6726   6908   ** Undo the hack that converts floating point types to integer for
  6727   6909   ** builds on processors without floating point support.
  6728   6910   */
  6729   6911   #ifdef SQLITE_OMIT_FLOATING_POINT
  6730   6912   # undef double
  6731   6913   #endif
  6732   6914   
  6733   6915   #ifdef __cplusplus
  6734   6916   }  /* End of the 'extern "C"' block */
  6735   6917   #endif
  6736   6918   #endif