Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Tweaks to the backup API documentation contained in comments. No changes to code. (CVS 6242) |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
6298bcca14bc0dd447198430af4147a3 |
User & Date: | drh 2009-02-03 18:25:13.000 |
Context
2009-02-03
| ||
18:47 | More adjustments to the backup API documentation. No changes to code. (CVS 6243) (check-in: ca650879d3 user: drh tags: trunk) | |
18:25 | Tweaks to the backup API documentation contained in comments. No changes to code. (CVS 6242) (check-in: 6298bcca14 user: drh tags: trunk) | |
16:51 | Commit first version of the 'backup' feature. (CVS 6241) (check-in: 663479b417 user: danielk1977 tags: trunk) | |
Changes
Changes to src/sqlite.h.in.
︙ | ︙ | |||
26 27 28 29 30 31 32 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** | | | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** ** @(#) $Id: sqlite.h.in,v 1.424 2009/02/03 18:25:13 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ #include <stdarg.h> /* Needed for the definition of va_list */ /* ** Make sure we can call this stuff from C++. |
︙ | ︙ | |||
6718 6719 6720 6721 6722 6723 6724 6725 6726 6727 6728 6729 6730 6731 | void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag); void (*xUnpin)(sqlite3_pcache*, void*, int discard); void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey); void (*xTruncate)(sqlite3_pcache*, unsigned iLimit); void (*xDestroy)(sqlite3_pcache*); }; /* ** CAPI3REF: Online Backup API. ** EXPERIMENTAL ** ** This API is used to overwrite the contents of one database with that ** of another. It is useful either for creating backups of databases or ** for copying in-memory databases to or from persistent files. | > > > > > > > > > > > | 6718 6719 6720 6721 6722 6723 6724 6725 6726 6727 6728 6729 6730 6731 6732 6733 6734 6735 6736 6737 6738 6739 6740 6741 6742 | void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag); void (*xUnpin)(sqlite3_pcache*, void*, int discard); void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey); void (*xTruncate)(sqlite3_pcache*, unsigned iLimit); void (*xDestroy)(sqlite3_pcache*); }; /* ** CAPI3REF: Online Backup Object ** EXPERIMENTAL ** ** The sqlite3_backup object records state information about an ongoing ** online backup operation. The sqlite3_backup object is created by ** a call to [sqlite3_backup_init()] and is destroyed by a call to ** [sqlite3_backup_finish()]. */ typedef struct sqlite3_backup sqlite3_backup; /* ** CAPI3REF: Online Backup API. ** EXPERIMENTAL ** ** This API is used to overwrite the contents of one database with that ** of another. It is useful either for creating backups of databases or ** for copying in-memory databases to or from persistent files. |
︙ | ︙ | |||
6760 6761 6762 6763 6764 6765 6766 | ** to access the source database. The values passed for the source and ** destination database handle parameters must not be the same. ** ** If an error occurs within sqlite3_backup_init(), then NULL is returned ** and an error code and error message written into the database handle ** passed as the first argument. They may be retrieved using the ** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16() functions. | | | | 6771 6772 6773 6774 6775 6776 6777 6778 6779 6780 6781 6782 6783 6784 6785 6786 | ** to access the source database. The values passed for the source and ** destination database handle parameters must not be the same. ** ** If an error occurs within sqlite3_backup_init(), then NULL is returned ** and an error code and error message written into the database handle ** passed as the first argument. They may be retrieved using the ** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16() functions. ** Otherwise, if successful, a pointer to an [sqlite3_backup] object is ** returned. This pointer may be used with the sqlite3_backup_step() and ** sqlite3_backup_finish() functions to perform the specified backup ** operation. ** ** <b>sqlite3_backup_step()</b> ** ** Function [sqlite3_backup_step()] is used to copy up to nPage pages between ** the source and destination databases, where nPage is the value of the |
︙ | ︙ | |||
6815 6816 6817 6818 6819 6820 6821 | ** database is modified by the using the same database connection as is used ** by the backup operation, then the backup database is transparently ** updated at the same time. ** ** <b>sqlite3_backup_finish()</b> ** ** Once sqlite3_backup_step() has returned SQLITE_DONE, or when the | | | | | | 6826 6827 6828 6829 6830 6831 6832 6833 6834 6835 6836 6837 6838 6839 6840 6841 6842 6843 6844 6845 6846 6847 6848 6849 6850 6851 6852 6853 6854 6855 6856 6857 6858 6859 6860 6861 6862 | ** database is modified by the using the same database connection as is used ** by the backup operation, then the backup database is transparently ** updated at the same time. ** ** <b>sqlite3_backup_finish()</b> ** ** Once sqlite3_backup_step() has returned SQLITE_DONE, or when the ** application wishes to abandon the backup operation, the [sqlite3_backup] ** object should be passed to sqlite3_backup_finish(). This releases all ** resources associated with the backup operation. If sqlite3_backup_step() ** has not yet returned SQLITE_DONE, then any active write-transaction on the ** destination database is rolled back. The [sqlite3_backup] object is invalid ** and may not be used following a call to sqlite3_backup_finish(). ** ** The value returned by sqlite3_backup_finish is SQLITE_OK if no error ** occured, regardless or whether or not sqlite3_backup_step() was called ** a sufficient number of times to complete the backup operation. Or, if ** an out-of-memory condition or IO error occured during a call to ** sqlite3_backup_step() then SQLITE_NOMEM or an SQLITE_IOERR_XXX error code ** is returned. In this case the error code and an error message are ** written to the destination database handle. ** ** A return of SQLITE_BUSY or SQLITE_LOCKED from sqlite3_backup_step() is ** not considered an error and does not affect the return value of ** sqlite3_backup_finish(). ** ** <b>sqlite3_backup_remaining(), sqlite3_backup_pagecount()</b> ** ** Each call to sqlite3_backup_step() sets two values stored internally ** by an [sqlite3_backup] object. The number of pages still to be backed ** up, which may be queried by sqlite3_backup_remaining(), and the total ** number of pages in the source database file, which may be queried by ** sqlite3_backup_pagecount(). ** ** The values returned by these functions are only updated by ** sqlite3_backup_step(). If the source database is modified during a backup ** operation, then the values are not updated to account for any extra |
︙ | ︙ | |||
6871 6872 6873 6874 6875 6876 6877 | ** Furthermore, if running in shared cache mode, the application must ** guarantee that the shared cache used by the destination database ** is not accessed while the backup is running. In practice this means ** that the application must guarantee that the file-system file being ** backed up to is not accessed by any connection within the process, ** not just the specific connection that was passed to sqlite3_backup_init(). ** | | < | 6882 6883 6884 6885 6886 6887 6888 6889 6890 6891 6892 6893 6894 6895 6896 6897 6898 6899 6900 6901 6902 | ** Furthermore, if running in shared cache mode, the application must ** guarantee that the shared cache used by the destination database ** is not accessed while the backup is running. In practice this means ** that the application must guarantee that the file-system file being ** backed up to is not accessed by any connection within the process, ** not just the specific connection that was passed to sqlite3_backup_init(). ** ** The [sqlite3_backup] object itself is partially threadsafe. Multiple ** threads may safely make multiple concurrent calls to sqlite3_backup_step(). ** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() ** APIs are not strictly speaking threadsafe. If they are invoked at the ** same time as another thread is invoking sqlite3_backup_step() it is ** possible that they return invalid values. */ sqlite3_backup *sqlite3_backup_init( sqlite3 *pDest, /* Destination database handle */ const char *zDestName, /* Destination database name */ sqlite3 *pSource, /* Source database handle */ const char *zSourceName /* Source database name */ ); int sqlite3_backup_step(sqlite3_backup *p, int nPage); |
︙ | ︙ |