From fddfa2d863fcf8f7f00d153ff39fc32d0d53857d Mon Sep 17 00:00:00 2001 From: drh Date: Wed, 5 Dec 2007 18:05:16 +0000 Subject: [PATCH] Begin adding requirements numbers to the C/C++ interface documentation. (CVS 4593) FossilOrigin-Name: ae1936aadf00bec91750d41be7507cf1b81fc411 --- manifest | 12 +- manifest.uuid | 2 +- src/sqlite.h.in | 1360 ++++++++++++++++++++++++----------------------- 3 files changed, 709 insertions(+), 665 deletions(-) diff --git a/manifest b/manifest index aabdb57ed0..d00e840a20 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Add\sthe\sability\sto\schange\sthe\sautovacuum\sstatus\sof\san\sexisting\sdatabase\nby\ssetting\sthe\sauto_vacuum\spragma\sthen\srunning\sthe\sVACUUM\scommand.\s(CVS\s4592) -D 2007-12-05T01:38:23 +C Begin\sadding\srequirements\snumbers\sto\sthe\sC/C++\sinterface\sdocumentation.\s(CVS\s4593) +D 2007-12-05T18:05:16 F Makefile.arm-wince-mingw32ce-gcc ac5f7b2cef0cd850d6f755ba6ee4ab961b1fadf7 F Makefile.in 30789bf70614bad659351660d76b8e533f3340e9 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654 @@ -134,7 +134,7 @@ F src/random.c 4a22746501bf36b0a088c66e38dde5daba6a35da F src/select.c 7c0ab94b8f287eb94fdb1eb101be603832ecfc34 F src/server.c 087b92a39d883e3fa113cae259d64e4c7438bc96 F src/shell.c c97be281cfc3dcb14902f45e4b16f20038eb83ff -F src/sqlite.h.in 28e78e9191a655fd2aa728c1f55d35e9f644103a +F src/sqlite.h.in b886a911e1e72e3f79fb1d66553ce5c717042267 F src/sqlite3ext.h a93f59cdee3638dc0c9c086f80df743a4e68c3cb F src/sqliteInt.h a941ccf797b45c27bc0face4e75935b5cc019202 F src/sqliteLimit.h 15ffe2116746c27ace2b428a26a4fcd6dba6fa65 @@ -597,7 +597,7 @@ F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5 -P bf34284ff0c60ae6e735e09bb29cd48b158e8dce -R 268cf574fbaadd8f08b72bad36ab32de +P bdfc19e838b369a8c5d5d23663fad690f55ba3d7 +R 9ef2020d3fc9ded9ecb9c3353fddc20a U drh -Z 01b4baedd2f51b7c9bd419e3c44b8fa2 +Z d0c1d862b6e3beefc5bad47c02091c37 diff --git a/manifest.uuid b/manifest.uuid index acc41c0ef2..dd0ae2debf 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -bdfc19e838b369a8c5d5d23663fad690f55ba3d7 \ No newline at end of file +ae1936aadf00bec91750d41be7507cf1b81fc411 \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index 6a8f14e311..b2186892ac 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -30,20 +30,7 @@ ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** -** This file is also used to generate some (but not all) of the formal -** requirements for SQLite. To this end, "shall" language is used. -** Requirements are specified as follows: -** -** {F00000} ... shall .... {EX} commentary {END} -** -** The requirement number comes first and is enclosed in curly -** braces. The F prefix identifies functional requirements. -** The requirement consists of all text up through the next -** {...} mark or until the end of the comment. Text following -** {EX} is an explanatory amplification of the preceding requirement. -** Both the {EX} and the {END} are optional. -** -** @(#) $Id: sqlite.h.in,v 1.274 2007/12/04 13:22:44 drh Exp $ +** @(#) $Id: sqlite.h.in,v 1.275 2007/12/05 18:05:16 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ @@ -76,14 +63,16 @@ extern "C" { #endif /* -** CAPI3REF: Compile-Time Library Version Numbers {F10100} +** CAPI3REF: Compile-Time Library Version Numbers {F10010} +** +** {F10011} The version of the SQLite library is contained in the sqlite3.h +** header file in a #define named SQLITE_VERSION. {F10012} The SQLITE_VERSION +** macro resolves to a string constant. ** -** {F10101} The SQLITE_VERSION #define in the sqlite3.h header file -** shall resolve to a string constant that identifies the SQLite library -** version in the format "X.Y.Z", where -** X is the major version number, Y is the minor version number, and Z -** is the release number or the release number followed by text "alpha" -** or "beta". {EX} +** {F10013} The format of the version string is "X.Y.Z", where +** X is the major version number, Y is the minor version number and Z +** is the release number. The X.Y.Z might be followed by "alpha" or "beta". +** For example "3.1.1beta". {END} ** ** The X value is always 3 in SQLite. The X value only changes when ** backwards compatibility is broken and we intend to never break @@ -92,14 +81,11 @@ extern "C" { ** but not backwards compatible. The Z value is incremented with ** each release but resets back to 0 when Y is incremented. ** -** {F10104} The #define named SQLITE_VERSION_NUMBER shall resolve to -** an integer constant with -** the value (X*1000000 + Y*1000 + Z) where X, Y and Z are same as in -** the SQLITE_VERSION #define, though without the optional "alpha" -** or "beta" text on the end of Z. {EX} For example, for version "3.5.3", -** SQLITE_VERSION_NUMBER is set to 3005003. A test like -** (SQLITE_VERSION_NUMBER>=3005003) can be used to verify at -** compile-time that the SQLite version is 3.5.3 or later. {END} +** {F10014} The SQLITE_VERSION_NUMBER is an integer with the value +** (X*1000000 + Y*1000 + Z). For example, for version "3.1.1beta", +** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using +** version 3.1.1 or greater at compile time, programs may use the test +** (SQLITE_VERSION_NUMBER>=3001001). {END} ** ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()]. */ @@ -107,49 +93,50 @@ extern "C" { #define SQLITE_VERSION_NUMBER --VERSION-NUMBER-- /* -** CAPI3REF: Run-Time Library Version Numbers {F10110} +** CAPI3REF: Run-Time Library Version Numbers {F10020} ** -** {F10111} The sqlite3_libversion_number() interface shall return -** the value SQLITE_VERSION_NUMBER. {EX} -** Cautious programmers may want to put add code to -** their application that compares the value returned from -** sqlite3_libversion_number() against SQLITE_VERSION_NUMBER from -** the header, in order to insure that the library and header file -** are from the same release. +** {F10021} These routines return values equivalent to the header constants +** [SQLITE_VERSION] and [SQLITE_VERSION_NUMBER]. {END} The values returned +** by this routines should only be different from the header values +** if the application is compiled using an sqlite3.h header from a +** different version of SQLite than library. Cautious programmers might +** include a check in their application to verify that +** sqlite3_libversion_number() always returns the value +** [SQLITE_VERSION_NUMBER]. ** -** {F10112} The sqlite3_version[] string constant shall contain the text -** of the [SQLITE_VERSION] #define. {F10113} The sqlite3_libversion() -** function shall return a pointer to the sqlite3_version[] string -** constant. {EX} The sqlite3_libversion() function is provided for -** DLL users who can only access functions and not constants within -** the DLL and thus cannot access the sqlite3_version[] string directly. +** {F10022} The sqlite3_version[] string constant contains the text of the +** [SQLITE_VERSION] string. {F10023} The sqlite3_libversion() function returns +** a poiner to the sqlite3_version[] string constant. {END} The function +** is provided for DLL users who can only access functions and not +** constants within the DLL. */ SQLITE_EXTERN const char sqlite3_version[]; const char *sqlite3_libversion(void); int sqlite3_libversion_number(void); /* -** CAPI3REF: Test To See If The Library Is Threadsafe {F10200} +** CAPI3REF: Test To See If The Library Is Threadsafe {F10100} ** -** {F10201} The sqlite3_threadsafe() routine shall return TRUE (nonzero) -** if SQLite was compiled its mutexes enabled and FALSE (zero) if -** mutexes are disabled. {EX} +** {F10101} This routine returns TRUE (nonzero) if SQLite was compiled with +** all of its mutexes enabled and is thus threadsafe. {F10102} It returns +** zero if the particular build is for single-threaded operation +** only. {END} ** -** Really all this routine does is return true if SQLite was compiled -** with the -DSQLITE_THREADSAFE=1 option and false if -** compiled with -DSQLITE_THREADSAFE=0. If SQLite uses an +** {F10103} Really all this routine does is return true if SQLite was +** compiled with the -DSQLITE_THREADSAFE=1 option and false if +** compiled with -DSQLITE_THREADSAFE=0. {U10104} If SQLite uses an ** application-defined mutex subsystem, malloc subsystem, collating ** sequence, VFS, SQL function, progress callback, commit hook, ** extension, or other accessories and these add-ons are not ** threadsafe, then clearly the combination will not be threadsafe -** either. Hence, this routine never reports that the library +** either. {END} Hence, this routine never reports that the library ** is guaranteed to be threadsafe, only when it is guaranteed not -** to be. {END} +** to be. */ int sqlite3_threadsafe(void); /* -** CAPI3REF: Database Connection Handle {F11000} +** CAPI3REF: Database Connection Handle {F12000} ** ** Each open SQLite database is represented by pointer to an instance of the ** opaque structure named "sqlite3". It is useful to think of an sqlite3 @@ -164,20 +151,17 @@ typedef struct sqlite3 sqlite3; /* -** CAPI3REF: 64-Bit Integer Types {F10300} +** CAPI3REF: 64-Bit Integer Types {F10200} ** -** Some compilers do not support the "long long" datatype. So we have -** to do compiler-specific typedefs for 64-bit signed and unsigned integers. +** Because there is no cross-platform way to specify such types +** SQLite includes typedefs for 64-bit signed and unsigned integers. +** {F10201} The sqlite_int64 and sqlite3_int64 types specify a +** 64-bit signed integer. {F10202} The sqlite_uint64 and +** sqlite3_uint64 types specify a 64-bit unsigned integer. {END} ** -** Many SQLite interface functions require a 64-bit integer arguments. -** Those interfaces are declared using this typedef. -** -** {F10301} Values of type sqlite_int64 or sqlite3_int64 shall be -** 64-bit twos-complement integers. {F10302} Values of type -** sqlite_uint64 or sqlite3_uint64 shall be 64-bit unsigned integers. {END} -** The sqlite3_int64 and sqlite3_uint64 typedefs are preferred. -** The sqlite_int64 and sqlite_uint64 typedefs are maintained for -** backwards compatibility only. +** The sqlite3_int64 and sqlite3_uint64 are the preferred type +** definitions. The sqlite_int64 and sqlite_uint64 types are +** supported for backwards compatibility only. */ #ifdef SQLITE_INT64_TYPE typedef SQLITE_INT64_TYPE sqlite_int64; @@ -201,30 +185,23 @@ typedef sqlite_uint64 sqlite3_uint64; #endif /* -** CAPI3REF: Closing A Database Connection {F11100} +** CAPI3REF: Closing A Database Connection {F12010} ** -** The sqlite3_close() interface is the destructor for the [sqlite3] object. -** {F11101} A successful call to sqlite3_close() shall return SQLITE_OK. -** {F11102} A successful call to sqlite3_close() shall cause all database -** files associated with the [sqlite3] object to be closed and shall -** cause resources -** associated with the [sqlite3] object to be released. -** {F11103} A successful call to sqlite3_close() -** shall cause any pending transaction on the [sqlite3] object to be -** rolled back. {END} +** {F12010} Call this function with a pointer to a structure that was +** previously returned from [sqlite3_open()], [sqlite3_open16()], or +** [sqlite3_open_v2()] and the corresponding database will by +** closed. {END} ** -** All SQL statements prepared using [sqlite3_prepare_v2()] or +** {F12011} All SQL statements prepared using [sqlite3_prepare_v2()] or ** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()] -** before sqlite3_close() is called. {F11104} If sqlite3_close() is -** called on a connection that has unfinalized [sqlite3_stmt] objects -** then sqlite3_close() shall return SQLITE_BUSY and the database -** connection shall remain open. {END} +** before this routine is called. Otherwise, SQLITE_BUSY is returned and the +** database connection remains open. {END} ** -** {U11105} Calling sqlite3_close() on a database connection that has -** already been closed results in undefined behavior. {U11106} If -** other interfaces that reference the same database connection are -** pending (either in the same thread or in different threads) when -** sqlite3_close() is called, then the behavior is undefined. +** {U12012} Passing this routine a database connection that has already been +** closed results in undefined behavior. {U12013} If other interfaces that +** reference the same database connection are pending (either in the +** same thread or in different threads) when this routine is called, +** then the behavior is undefined and is almost certainly undesirable. */ int sqlite3_close(sqlite3 *); @@ -236,74 +213,55 @@ int sqlite3_close(sqlite3 *); typedef int (*sqlite3_callback)(void*,int,char**, char**); /* -** CAPI3REF: One-Step Query Execution Interface {F11200} -** -** The sqlite3_exec() interface runs zero or more SQL statements -** passed as the 2nd parameter. The optional callback in the third parameter -** is invoked once for each row of result generated by the SQL statements. -** If an error occurs, sqlite3_exec() returns an appropriate error code -** and writes an error message into *errmsg if errmsg is not NULL. -** -** Details: -** -** {F11201} The sqlite3_exec() interface shall evaluate semicolon separated -** UTF-8 encoded SQL statements passed in as the second argument, -** in order, until either all statements have been evaluated -** or until an error or interrupt occurs. -** {EX} The statements are prepared one by one using [sqlite3_prepare()], -** evaluated using [sqlite3_step()], then destroyed using [sqlite3_finalize()]. -** {F11202} The sqlite3_exec() interface shall evaluate SQL statements using -** the database connection passed in as the first parameter. -** -** {F11203} The sqlite3_exec() interface shall retry statements -** that give an SQLITE_SCHEMA error and shall proceed normally -** if the retry works, or shall halt and return SQLITE_SCHEMA if -** the retry fails. -** -** {F11204} If the 3rd parameter to sqlite3_exec() is not NULL then -** sqlite3_exec() shall invoke the callback function specified by -** that parameter once for each row in the result set of every query -** that sqlite3_exec() evaluates. {END} This callback -** should normally return 0. {F11205} If the callback on -** sqlite3_exec() returns a non-zero value then the query being -** evaluated shall abort and all subsequent SQL statements in the -** 2nd parameter to sqlite3_exec() shall be -** skipped and the sqlite3_exec() function shall return the [SQLITE_ABORT]. -** -** {F11206} The sqlite3_exec() interface shall pass its 4th -** parameter through as the 1st parameter to its callback function. -** -** {F11207} The sqlite3_exec() routine shall cause the 2nd parameter -** to its callback function to be the number of columns in the current -** row of the query result. -** {F11206} The sqlite3_exec() routine shall cause the 3rd parameter to -** its callback function to be an array of N pointers where each pointers -** is the return value of [sqlite3_column_text()] for the corresponding -** result column. {F11207} The sqlite3_exec() routine shall cause -** the 4th parameter to its callback function to be an array of N pointers -** where the value of each element of the array pointer returned -** by [sqlite3_column_name()] for the corresponding column. {END} -** -** The sqlite3_exec() callback function may be NULL, even for -** queries. A NULL callback is not an error. It just means that no callback -** will be invoked. -** -** {F11209} If sqlite3_exec() encounters an error while parsing or evaluating -** the SQL and if the 5th parameter to sqlite3_exec() is not NULL, -** then an appropriate error message shall be written into memory obtained -** from [sqlite3_malloc()] and *errmsg shall be made to point to that -** message. {EX} The calling function +** CAPI3REF: One-Step Query Execution Interface {F12100} +** +** {F12101} The sqlite3_exec() interface evaluates zero or more +** UTF-8 encoded, semicolon-separated SQL +** statements provided as its second argument. {F12102} The SQL +** statements are evaluated in the context of the database connection +** provided in the first argument. +** {F12103} SQL statements are prepared one by one using +** [sqlite3_prepare()] or the equivalent, evaluated +** using one or more calls to [sqlite3_step()], then destroyed +** using [sqlite3_finalize()]. {F12104} The return value of +** sqlite3_exec() is SQLITE_OK if all SQL statement run +** successfully. +** +** {F12105} If one or more of the SQL statements handed to +** sqlite3_exec() are queries, then +** the callback function specified by the 3rd parameter is +** invoked once for each row of the query result. {F12106} +** If the callback returns a non-zero value then the query +** is aborted, all subsequent SQL statements +** are skipped and the sqlite3_exec() function returns the [SQLITE_ABORT]. +** +** {F12107} The 4th parameter to sqlite3_exec() is an arbitrary pointer +** that is passed through to the callback function as its first parameter. +** +** {F12108} The 2nd parameter to the callback function is the number of +** columns in the query result. {F12109} The 3rd parameter to the callback +** is an array of pointers to strings holding the values for each column +** as extracted using [sqlite3_column_text()]. NULL values in the result +** set result in a NULL pointer. All other value are in their UTF-8 +** string representation. {F12110} +** The 4th parameter to the callback is an array of strings +** obtained using [sqlite3_column_name()] and holding +** the names of each column, also in UTF-8. +** +** {F12110} The callback function may be NULL, even for queries. A NULL +** callback is not an error. It just means that no callback +** will be invoked. +** +** {F12112} If an error occurs while parsing or evaluating the SQL +** then an appropriate error message is written into memory obtained +** from [sqlite3_malloc()] and *errmsg is made to point to that message +** assuming errmsg is not NULL. {U12113} The calling function ** is responsible for freeing the memory using [sqlite3_free()]. -** If errmsg==NULL, then no error message is ever written. -** This processing apply only to error that occur during statement -** process, not to error that may occur within the callback routine itself. -** {F11210} If the call to [sqlite3_malloc()] fails while attempting to -** construct an error message for the 5th parameter of sqlite3_exec() -** then the *errmsg value is left unchanged. +** {F12114} If errmsg==NULL, then no error message is ever written. ** -** {F11211} The return value from sqlite3_exec() shall be SQLITE_OK if there -** are no errors. {EX} Some other [SQLITE_OK | return code] if there is -** an error. The particular return value depends on the type of error. +** {F12115} The return value is is SQLITE_OK if there are no errors and +** some other [SQLITE_OK | return code] if there is an error. +** The particular return value depends on the type of error. {END} */ int sqlite3_exec( sqlite3*, /* An open database */ @@ -314,16 +272,16 @@ int sqlite3_exec( ); /* -** CAPI3REF: Result Codes {F10120} +** CAPI3REF: Result Codes {F10210} ** KEYWORDS: SQLITE_OK ** ** Many SQLite functions return an integer result code from the set shown ** above in order to indicates success or failure. ** -** The result codes above are the only ones returned by SQLite in its -** default configuration. However, the [sqlite3_extended_result_codes()] -** API can be used to set a database connectoin to return more detailed -** result codes. +** {F10211} The result codes above are the only ones returned by SQLite in its +** default configuration. {F10212} However, the +** [sqlite3_extended_result_codes()] API can be used to set a database +** connectoin to return more detailed result codes. {END} ** ** See also: [SQLITE_IOERR_READ | extended result codes] ** @@ -361,28 +319,29 @@ int sqlite3_exec( /* end-of-error-codes */ /* -** CAPI3REF: Extended Result Codes {F10121} +** CAPI3REF: Extended Result Codes {F10220} ** ** In its default configuration, SQLite API routines return one of 26 integer -** result codes described at result-codes. However, experience has shown that +** [result codes]. However, experience has shown that ** many of these result codes are too course-grained. They do not provide as ** much information about problems as users might like. In an effort to ** address this, newer versions of SQLite (version 3.3.8 and later) include ** support for additional result codes that provide more detailed information -** about errors. The extended result codes are enabled (or disabled) for -** each database -** connection using the [sqlite3_extended_result_codes()] API. +** about errors. {F10221} The extended result codes are enabled or disabled +** for each database connection using the [sqlite3_extended_result_codes()] +** API. {END} ** -** Some of the available extended result codes are listed here. +** Some of the available extended result codes are listed above. ** We expect the number of extended result codes will be expand -** over time. Software that uses extended result codes should expect -** to see new result codes in future releases of SQLite. +** over time. {U10422} Software that uses extended result codes should expect +** to see new result codes in future releases of SQLite. {END} ** -** The symbolic name for an extended result code always contains a related -** primary result code as a prefix. Primary result codes contain a single -** "_" character. Extended result codes contain two or more "_" characters. -** The numeric value of an extended result code can be converted to its -** corresponding primary result code by masking off the lower 8 bytes. +** {F10223} The symbolic name for an extended result code always contains +** a related primary result code as a prefix. {F10224} Primary result +** codes contain a single "_" character. {F10225} Extended result codes +** contain two or more "_" characters. {F10226} The numeric value of an +** extended result code can be converted to its +** corresponding primary result code by masking off the lower 8 bytes. {END} ** ** The SQLITE_OK result code will never be extended. It will always ** be exactly zero. @@ -401,13 +360,12 @@ int sqlite3_exec( #define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) /* -** CAPI3REF: Flags For File Open Operations {F10122} +** CAPI3REF: Flags For File Open Operations {F10230} ** -** Combination of the following bit values are used as the +** {F10231} Some combination of the these bit values are used as the ** third argument to the [sqlite3_open_v2()] interface and ** as fourth argument to the xOpen method of the ** [sqlite3_vfs] object. -** */ #define SQLITE_OPEN_READONLY 0x00000001 #define SQLITE_OPEN_READWRITE 0x00000002 @@ -423,22 +381,22 @@ int sqlite3_exec( #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* -** CAPI3REF: Device Characteristics {F10123} +** CAPI3REF: Device Characteristics {F10240} ** -** The xDeviceCapabilities method of the [sqlite3_io_methods] -** object returns an integer which is a vector of the following +** {F10241} The xDeviceCapabilities method of the [sqlite3_io_methods] +** object returns an integer which is a vector of the these ** bit values expressing I/O characteristics of the mass storage ** device that holds the file that the [sqlite3_io_methods] -** refers to. +** refers to. {END} ** -** The SQLITE_IOCAP_ATOMIC property means that all writes of -** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values +** {F10242} The SQLITE_IOCAP_ATOMIC property means that all writes of +** any size are atomic. {F10243} The SQLITE_IOCAP_ATOMICnnn values ** mean that writes of blocks that are nnn bytes in size and ** are aligned to an address which is an integer multiple of -** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means +** nnn are atomic. {F10244} The SQLITE_IOCAP_SAFE_APPEND value means ** that when data is appended to a file, the data is appended ** first then the size of the file is extended, never the other -** way around. The SQLITE_IOCAP_SEQUENTIAL property means that +** way around. {F10245} The SQLITE_IOCAP_SEQUENTIAL property means that ** information is written to disk in the same order as calls ** to xWrite(). */ @@ -455,11 +413,11 @@ int sqlite3_exec( #define SQLITE_IOCAP_SEQUENTIAL 0x00000400 /* -** CAPI3REF: File Locking Levels {F10124} +** CAPI3REF: File Locking Levels {F10250} ** -** SQLite uses one of the following integer values as the second +** {F10251} SQLite uses one of the following integer values as the second ** argument to calls it makes to the xLock() and xUnlock() methods -** of an [sqlite3_io_methods] object. +** of an [sqlite3_io_methods] object. {END} */ #define SQLITE_LOCK_NONE 0 #define SQLITE_LOCK_SHARED 1 @@ -468,16 +426,16 @@ int sqlite3_exec( #define SQLITE_LOCK_EXCLUSIVE 4 /* -** CAPI3REF: Synchronization Type Flags {F10125} +** CAPI3REF: Synchronization Type Flags {F10260} ** -** When SQLite invokes the xSync() method of an [sqlite3_io_methods] -** object it uses a combination of the following integer values as -** the second argument. +** {F10261} When SQLite invokes the xSync() method of an +** [sqlite3_io_methods] object it uses a combination of the +** these integer values as the second argument. ** -** When the SQLITE_SYNC_DATAONLY flag is used, it means that the +** {F10262} When the SQLITE_SYNC_DATAONLY flag is used, it means that the ** sync operation only needs to flush data to mass storage. Inode -** information need not be flushed. The SQLITE_SYNC_NORMAL means -** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means +** information need not be flushed. {F10263} The SQLITE_SYNC_NORMAL means +** to use normal fsync() semantics. {F10264} The SQLITE_SYNC_FULL flag means ** to use Mac OS-X style fullsync instead of fsync(). */ #define SQLITE_SYNC_NORMAL 0x00002 @@ -486,7 +444,7 @@ int sqlite3_exec( /* -** CAPI3REF: OS Interface Open File Handle {F14100} +** CAPI3REF: OS Interface Open File Handle {F11110} ** ** An [sqlite3_file] object represents an open file in the OS ** interface layer. Individual OS interface implementations will @@ -501,23 +459,18 @@ struct sqlite3_file { }; /* -** CAPI3REF: OS Interface File Virtual Methods Object {F14110} +** CAPI3REF: OS Interface File Virtual Methods Object {F11120} ** -** Every file opened by the [sqlite3_vfs] xOpen method -** contains a pointer to an instance of the the sqlite3_io_methods object. -** This object defines the +** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to +** an instance of the this object. This object defines the ** methods used to perform various operations against the open file. ** -** {F14111} Whenever the SQLite library invokes the xSync method of -** an [sqlite3_io_methods] object, it shall supply a flags argument -** which is one of [SQLITE_SYNC_NORMAL] or [SQLITE_SYNC_FULL] optionally -** ORed with [SQLITE_SYNC_DATA]. {EX} -** [SQLITE_SYNC_NORMAL] requests a normal fsync(). [SQLITE_SYNC_FULL] -** requests an OS-X style fullsync. The [SQLITE_SYNC_DATA] flag -** indicates that only the data of the file and not its inode needs to be -** synced. These flags serve as optimization hints to the underlying -** VFS and can be ignored by the VFS if they are not applicable to the -** specific application. {END} +** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or +** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). +* The second choice is an +** OS-X style fullsync. The SQLITE_SYNC_DATA flag may be ORed in to +** indicate that only the data of the file and not its inode needs to be +** synced. ** ** The integer values to xLock() and xUnlock() are one of **