From: drh Date: Tue, 3 Feb 2009 18:47:22 +0000 (+0000) Subject: More adjustments to the backup API documentation. No changes to code. (CVS 6243) X-Git-Tag: version-3.6.15~507 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=62b5d2d8e6ba2797337130b4bf9f4bd6d9582980;p=thirdparty%2Fsqlite.git More adjustments to the backup API documentation. No changes to code. (CVS 6243) FossilOrigin-Name: ca650879d3168d4475a33430300a0e8ac806facf --- diff --git a/manifest b/manifest index 4fa3e11969..48584801b9 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Tweaks\sto\sthe\sbackup\sAPI\sdocumentation\scontained\sin\scomments.\sNo\schanges\nto\scode.\s(CVS\s6242) -D 2009-02-03T18:25:13 +C More\sadjustments\sto\sthe\sbackup\sAPI\sdocumentation.\s\sNo\schanges\sto\scode.\s(CVS\s6243) +D 2009-02-03T18:47:23 F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0 F Makefile.in c7a5a30fb6852bd7839b1024e1661da8549878ee F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654 @@ -157,7 +157,7 @@ F src/resolve.c 18dc9f0df1d60048e012ce6632251063e0dd356a F src/rowset.c ba9375f37053d422dd76965a9c370a13b6e1aac4 F src/select.c ae72b604e47092521c4d9ae54e1b1cbeb872a747 F src/shell.c 8965cf0cd7a7dac39d586a43c97adb00930e025d -F src/sqlite.h.in 48e40b4115396ff7eaa1ade9fd90a59e1d8353a0 +F src/sqlite.h.in d2302ec33804193b3ae4420f0e9d8d5256d36586 F src/sqlite3ext.h 1db7d63ab5de4b3e6b83dd03d1a4e64fef6d2a17 F src/sqliteInt.h 73c1d4f9716fe21f202f9d05c4fd9e6281f2636f F src/sqliteLimit.h ffe93f5a0c4e7bd13e70cd7bf84cfb5c3465f45d @@ -700,7 +700,7 @@ F tool/speedtest16.c c8a9c793df96db7e4933f0852abb7a03d48f2e81 F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e -P 663479b417fc06ba1790a544f28694f8797cee57 -R 149ec6ea1b4cdb18000a87226a3bf85e +P 6298bcca14bc0dd447198430af4147a3673963fc +R 3f8edaab74d99aab99750110855db399 U drh -Z 1039ac561b4a6768bed916b37674a8c8 +Z 149ce33b1a3f39cb3f6bea8245a1d563 diff --git a/manifest.uuid b/manifest.uuid index 6fb37888f5..a20ed4be9b 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -6298bcca14bc0dd447198430af4147a3673963fc \ No newline at end of file +ca650879d3168d4475a33430300a0e8ac806facf \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index e884eff1fd..623f62622f 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -30,7 +30,7 @@ ** 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 $ +** @(#) $Id: sqlite.h.in,v 1.425 2009/02/03 18:47:23 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ @@ -4977,8 +4977,8 @@ int sqlite3_get_autocommit(sqlite3*); ** CAPI3REF: Find The Database Handle Of A Prepared Statement {H13120} ** ** The sqlite3_db_handle interface returns the [database connection] handle -** to which a [prepared statement] belongs. The database handle returned by -** sqlite3_db_handle is the same database handle that was the first argument +** to which a [prepared statement] belongs. The [database connection] +** returned by sqlite3_db_handle is the same [database connection] that was the first argument ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to ** create the statement in the first place. ** @@ -6750,10 +6750,11 @@ typedef struct sqlite3_backup sqlite3_backup; ** ** To perform a backup operation: **
    -**
  1. [sqlite3_backup_init()] is called once to initialize the backup, -**
  2. [sqlite3_backup_step()] is called one or more times to transfer +**
  3. sqlite3_backup_init() is called once to initialize the +** backup, +**
  4. sqlite3_backup_step() is called one or more times to transfer ** the data between the two databases, and finally -**
  5. [sqlite3_backup_finish()] is called to release all resources +**
  6. sqlite3_backup_finish() is called to release all resources ** associated with the backup operation. **
** There should be exactly one call to sqlite3_backup_finish() for each @@ -6765,16 +6766,17 @@ typedef struct sqlite3_backup sqlite3_backup; ** handle associated with the destination database and the database name ** used to attach the destination database to the handle. The database name ** is "main" for the main database, "temp" for the temporary database, or -** the name specified as part of the ATTACH statement if the destination is +** the name specified as part of the [ATTACH] statement if the destination is ** an attached database. The third and fourth arguments passed to -** sqlite3_backup_init() identify the database handle and database name used +** sqlite3_backup_init() identify the [database connection] +** and database name used ** to access the source database. The values passed for the source and -** destination database handle parameters must not be the same. +** destination [database connection] 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 +** and an error code and error message written into the [database connection] ** passed as the first argument. They may be retrieved using the -** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16() functions. +** [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 @@ -6786,26 +6788,30 @@ typedef struct sqlite3_backup sqlite3_backup; ** the source and destination databases, where nPage is the value of the ** second parameter passed to sqlite3_backup_step(). If nPage pages are ** succesfully copied, but there are still more pages to copy before the -** backup is complete, it returns SQLITE_OK. If no error occured and there -** are no more pages to copy, then SQLITE_DONE is returned. If an error -** occurs, then an SQLite error code is returned. As well as SQLITE_OK and -** SQLITE_DONE, a call to sqlite3_backup_step() may return SQLITE_READONLY, -** SQLITE_NOMEM, SQLITE_BUSY, SQLITE_LOCKED or an SQLITE_IOERR_XXX error code. +** backup is complete, it returns [SQLITE_OK]. If no error occured and there +** are no more pages to copy, then [SQLITE_DONE] is returned. If an error +** occurs, then an SQLite error code is returned. As well as [SQLITE_OK] and +** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY], +** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an +** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code. ** ** As well as the case where the destination database file was opened for -** read-only access, sqlite3_backup_step() may return SQLITE_READONLY if +** read-only access, sqlite3_backup_step() may return [SQLITE_READONLY] if ** the destination is an in-memory database with a different page size ** from the source database. ** ** If sqlite3_backup_step() cannot obtain a required file-system lock, then -** the busy-handler function is invoked (if one is specified). If the +** the [sqlite3_busy_handler | busy-handler function] +** is invoked (if one is specified). If the ** busy-handler returns non-zero before the lock is available, then -** SQLITE_BUSY is returned to the caller. In this case the call to -** sqlite3_backup_step() can be retried later. If the source database handle +** [SQLITE_BUSY] is returned to the caller. In this case the call to +** sqlite3_backup_step() can be retried later. If the source +** [database connection] ** is being used to write to the source database when sqlite3_backup_step() -** is called, then SQLITE_LOCKED is returned immediately. Again, in this +** is called, then [SQLITE_LOCKED] is returned immediately. Again, in this ** case the call to sqlite3_backup_step() can be retried later on. If -** SQLITE_IOERR_XXX, SQLITE_NOMEM or SQLITE_READONLY is returned, then +** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or +** [SQLITE_READONLY] is returned, then ** there is no point in retrying the call to sqlite3_backup_step(). These ** errors are considered fatal. At this point the application must accept ** that the backup operation has failed and pass the backup operation handle @@ -6814,8 +6820,8 @@ typedef struct sqlite3_backup sqlite3_backup; ** Following the first call to sqlite3_backup_step(), an exclusive lock is ** obtained on the destination file. It is not released until either ** sqlite3_backup_finish() is called or the backup operation is complete -** and sqlite3_backup_step() returns SQLITE_DONE. Additionally, each time -** a call to sqlite3_backup_step() is made a shared lock is obtained on +** and sqlite3_backup_step() returns [SQLITE_DONE]. Additionally, each time +** a call to sqlite3_backup_step() is made a [shared lock] is obtained on ** the source database file. This lock is released before the ** sqlite3_backup_step() call returns. Because the source database is not ** locked between calls to sqlite3_backup_step(), it may be modified mid-way @@ -6829,24 +6835,25 @@ typedef struct sqlite3_backup sqlite3_backup; ** ** sqlite3_backup_finish() ** -** Once sqlite3_backup_step() has returned SQLITE_DONE, or when the +** 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 +** 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 +** The value returned by sqlite3_backup_finish is [SQLITE_OK] if no error +** occurred, 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 +** sqlite3_backup_step() then [SQLITE_NOMEM] or an +** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] error code ** is returned. In this case the error code and an error message are -** written to the destination database handle. +** written to the destination [database connection]. ** -** 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 +** A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step() is +** not a permanent error and does not affect the return value of ** sqlite3_backup_finish(). ** ** sqlite3_backup_remaining(), sqlite3_backup_pagecount() @@ -6865,7 +6872,7 @@ typedef struct sqlite3_backup sqlite3_backup; ** ** Concurrent Usage of Database Handles ** -** The source database handle may be used by the application for other +** The source [database connection] may be used by the application for other ** purposes while a backup operation is underway or being initialized. ** If SQLite is compiled and configured to support threadsafe database ** connections, then the source database connection may be used concurrently @@ -6875,11 +6882,11 @@ typedef struct sqlite3_backup sqlite3_backup; ** connection handle is not passed to any other API (by any thread) after ** sqlite3_backup_init() is called and before the corresponding call to ** sqlite3_backup_finish(). Unfortunately SQLite does not currently check -** for this, if the application does use the destination database handle +** for this, if the application does use the destination [database connection] ** for some other purpose during a backup operation, things may appear to ** work correctly but in fact be subtly malfunctioning. ** -** Furthermore, if running in shared cache mode, the application must +** 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