/ Check-in [0b8b5c2e]
Login

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

Overview
Comment:Improvements to the API documentation found in comments in the sqlite.h.in source file. (CVS 4755)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 0b8b5c2e833c90aec1c14d16c12334e01b50f35f
User & Date: drh 2008-01-30 16:16:14
Context
2008-01-31
12:26
Additional API documentation updates in sqlite.h.in. (CVS 4756) check-in: 9b6ab9fa user: drh tags: trunk
2008-01-30
16:16
Improvements to the API documentation found in comments in the sqlite.h.in source file. (CVS 4755) check-in: 0b8b5c2e user: drh tags: trunk
16:14
Disable the likely() and unlikely() macros as they do not work some older versions of GCC. (CVS 4754) check-in: e01f9ed9 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

    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.278 2007/12/13 21:54:11 drh Exp $
           33  +** @(#) $Id: sqlite.h.in,v 1.279 2008/01/30 16:16:14 drh 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++.
................................................................................
    61     61   #ifdef SQLITE_VERSION_NUMBER
    62     62   # undef SQLITE_VERSION_NUMBER
    63     63   #endif
    64     64   
    65     65   /*
    66     66   ** CAPI3REF: Compile-Time Library Version Numbers {F10010}
    67     67   **
    68         -** {F10011} The #define in the sqlite3.h header file named
    69         -** SQLITE_VERSION resolves to a string literal that identifies
    70         -** the version of the SQLite library in the format "X.Y.Z", where
    71         -** X is the major version number, Y is the minor version number and Z
    72         -** is the release number.  The X.Y.Z might be followed by "alpha" or "beta".
    73         -** {END} For example "3.1.1beta".
           68  +** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in
           69  +** the sqlite3.h file specify the version of SQLite with which
           70  +** that header file is associated.
    74     71   **
    75         -** The X value is always 3 in SQLite.  The X value only changes when
    76         -** backwards compatibility is broken and we intend to never break
    77         -** backwards compatibility.  The Y value only changes when
           72  +** The "version" of SQLite is a strong of the form "X.Y.Z".
           73  +** The phrase "alpha" or "beta" might be appended after the Z.
           74  +** The X value is major version number always 3 in SQLite3.
           75  +** The X value only changes when  backwards compatibility is
           76  +** broken and we intend to never break
           77  +** backwards compatibility.  The Y value is the minor version
           78  +** number and only changes when
    78     79   ** there are major feature enhancements that are forwards compatible
    79         -** but not backwards compatible.  The Z value is incremented with
           80  +** but not backwards compatible.  The Z value is release number
           81  +** and is incremented with
    80     82   ** each release but resets back to 0 when Y is incremented.
    81     83   **
    82         -** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer
    83         -** with the value  (X*1000000 + Y*1000 + Z) where X, Y, and Z are as
    84         -** with SQLITE_VERSION. {END} For example, for version "3.1.1beta", 
    85         -** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using 
    86         -** version 3.1.1 or greater at compile time, programs may use the test 
    87         -** (SQLITE_VERSION_NUMBER>=3001001).
    88         -**
    89     84   ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
           85  +**
           86  +** INVARIANTS:
           87  +**
           88  +** {F10011} The SQLITE_VERSION #define in the sqlite3.h header file
           89  +**          evaluates to a string literal that is the SQLite version
           90  +**          with which the header file is associated.
           91  +**
           92  +** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer
           93  +**          with the value  (X*1000000 + Y*1000 + Z) where X, Y, and
           94  +**          Z are the major version, minor version, and release number.
    90     95   */
    91     96   #define SQLITE_VERSION         "--VERS--"
    92     97   #define SQLITE_VERSION_NUMBER --VERSION-NUMBER--
    93     98   
    94     99   /*
    95    100   ** CAPI3REF: Run-Time Library Version Numbers {F10020}
          101  +** KEYWORDS: sqlite3_version
    96    102   **
    97         -** {F10021} The sqlite3_libversion_number() interface returns an integer
    98         -** equal to [SQLITE_VERSION_NUMBER].  {END} The value returned
    99         -** by this routine should only be different from the header values
   100         -** if the application is compiled using an sqlite3.h header from a
   101         -** different version of SQLite than library.  Cautious programmers might
          103  +** These features provide the same information as the [SQLITE_VERSION]
          104  +** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated
          105  +** with the library instead of the header file.  Cautious programmers might
   102    106   ** include a check in their application to verify that 
   103    107   ** sqlite3_libversion_number() always returns the value 
   104    108   ** [SQLITE_VERSION_NUMBER].
   105    109   **
   106         -** {F10022} The sqlite3_version[] string constant contains the text of the
   107         -** [SQLITE_VERSION] string. {F10023} The sqlite3_libversion() function returns
   108         -** a pointer to the sqlite3_version[] string constant. {END} The 
   109         -** sqlite3_libversion() function
   110         -** is provided for DLL users who can only access functions and not
          110  +** The sqlite3_libversion() function returns the same information as is
          111  +** in the sqlite3_version[] string constant.  The function is provided
          112  +** for use in DLLs since DLL users usually do not have direct access to string
   111    113   ** constants within the DLL.
          114  +**
          115  +** INVARIANTS:
          116  +**
          117  +** {F10021} The [sqlite3_libversion_number()] interface returns an integer
          118  +**          equal to [SQLITE_VERSION_NUMBER]. 
          119  +**
          120  +** {F10022} The [sqlite3_version] string constant contains the text of the
          121  +**          [SQLITE_VERSION] string. 
          122  +**
          123  +** {F10023} The [sqlite3_libversion()] function returns
          124  +**          a pointer to the [sqlite3_version] string constant.
   112    125   */
   113    126   SQLITE_EXTERN const char sqlite3_version[];
   114    127   const char *sqlite3_libversion(void);
   115    128   int sqlite3_libversion_number(void);
   116    129   
   117    130   /*
   118    131   ** CAPI3REF: Test To See If The Library Is Threadsafe {F10100}
   119    132   **
   120         -** {F10101} The sqlite3_threadsafe() routine returns nonzero
   121         -** if SQLite was compiled with its mutexes enabled or zero if
   122         -** SQLite was compiled with mutexes disabled. {END}  If this
   123         -** routine returns false, then it is not safe for simultaneously
   124         -** running threads to both invoke SQLite interfaces.
          133  +** SQLite can be compiled with or without mutexes.  When
          134  +** the SQLITE_THREADSAFE C preprocessor macro is true, mutexes
          135  +** are enabled and SQLite is threadsafe.  When that macro os false,
          136  +** the mutexes are omitted.  Without the mutexes, it is not safe
          137  +** to use SQLite from more than one thread.
   125    138   **
   126         -** Really all this routine does is return true if SQLite was
   127         -** compiled with the -DSQLITE_THREADSAFE=1 option and false if
   128         -** compiled with -DSQLITE_THREADSAFE=0.  If SQLite uses an
   129         -** application-defined mutex subsystem, malloc subsystem, collating
   130         -** sequence, VFS, SQL function, progress callback, commit hook,
   131         -** extension, or other accessories and these add-ons are not
   132         -** threadsafe, then clearly the combination will not be threadsafe
   133         -** either.  Hence, this routine never reports that the library
   134         -** is guaranteed to be threadsafe, only when it is guaranteed not
   135         -** to be.
          139  +** There is a measurable performance penalty for enabling mutexes.
          140  +** So if speed is of utmost importance, it makes sense to disable
          141  +** the mutexes.  But for maximum safety, mutexes should be enabled.
          142  +** The default behavior is for mutexes to be enabled.
          143  +**
          144  +** This interface can be used by a program to make sure that the
          145  +** version of SQLite that it is linking against was compiled with
          146  +** the desired setting of the SQLITE_THREADSAFE macro.
          147  +**
          148  +** INVARIANTS:
          149  +**
          150  +** {F10101} The [sqlite3_threadsafe()] function returns nonzero if
          151  +**          SQLite was compiled with its mutexes enabled or zero
          152  +**          if SQLite was compiled with mutexes disabled.
   136    153   */
   137    154   int sqlite3_threadsafe(void);
   138    155   
   139    156   /*
   140    157   ** CAPI3REF: Database Connection Handle {F12000}
          158  +** KEYWORDS: {database connection}
   141    159   **
   142    160   ** Each open SQLite database is represented by pointer to an instance of the
   143    161   ** opaque structure named "sqlite3".  It is useful to think of an sqlite3
   144    162   ** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and
   145    163   ** [sqlite3_open_v2()] interfaces are its constructors
   146    164   ** and [sqlite3_close()] is its destructor.  There are many other interfaces
   147    165   ** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and
................................................................................
   149    167   ** object.
   150    168   */
   151    169   typedef struct sqlite3 sqlite3;
   152    170   
   153    171   
   154    172   /*
   155    173   ** CAPI3REF: 64-Bit Integer Types {F10200}
          174  +** KEYWORDS: sqlite_int64 sqlite_uint64
   156    175   **
   157         -** Because there is no cross-platform way to specify such types
          176  +** Because there is no cross-platform way to specify 64-bit integer types
   158    177   ** SQLite includes typedefs for 64-bit signed and unsigned integers.
   159         -** {F10201} The sqlite_int64 and sqlite3_int64 types specify a
   160         -** 64-bit signed integer. {F10202} The sqlite_uint64 and
   161         -** sqlite3_uint64 types specify a 64-bit unsigned integer. {END}
   162    178   **
   163    179   ** The sqlite3_int64 and sqlite3_uint64 are the preferred type
   164    180   ** definitions.  The sqlite_int64 and sqlite_uint64 types are
   165    181   ** supported for backwards compatibility only.
          182  +**
          183  +** INVARIANTS:
          184  +**
          185  +** {F10201} The [sqlite_int64] and [sqlite3_int64] types specify a
          186  +**          64-bit signed integer.
          187  +**
          188  +** {F10202} The [sqlite_uint64] and [sqlite3_uint64] types specify
          189  +**          a 64-bit unsigned integer.
   166    190   */
   167    191   #ifdef SQLITE_INT64_TYPE
   168    192     typedef SQLITE_INT64_TYPE sqlite_int64;
   169    193     typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
   170    194   #elif defined(_MSC_VER) || defined(__BORLANDC__)
   171    195     typedef __int64 sqlite_int64;
   172    196     typedef unsigned __int64 sqlite_uint64;
................................................................................
   184    208   #ifdef SQLITE_OMIT_FLOATING_POINT
   185    209   # define double sqlite3_int64
   186    210   #endif
   187    211   
   188    212   /*
   189    213   ** CAPI3REF: Closing A Database Connection {F12010}
   190    214   **
   191         -** {F12011} The sqlite3_close() interfaces destroys an [sqlite3] object
   192         -** allocated by a prior call to [sqlite3_open()], [sqlite3_open16()], or
   193         -** [sqlite3_open_v2()]. {F12012} Sqlite3_close() releases all
   194         -** memory used by the connection and closes all open files. {END}.
          215  +** This routine is the destructor for the [sqlite3] object.  
          216  +**
          217  +** Applications should [sqlite3_finalize | finalize] all
          218  +** [prepared statements] and
          219  +** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs] 
          220  +** associated with the [sqlite3] object prior
          221  +** to attempting to close the [sqlite3] object.
          222  +**
          223  +** <todo>What happens to pending transactions?  Are they
          224  +** rolled back, or abandoned?</todo>
          225  +**
          226  +** INVARIANTS:
          227  +**
          228  +** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object
          229  +**          allocated by a prior call to [sqlite3_open()],
          230  +**          [sqlite3_open16()], or [sqlite3_open_v2()].
          231  +**
          232  +** {F12012} The [sqlite3_close()] function releases all memory used by the
          233  +**          connection and closes all open files.
   195    234   **
   196    235   ** {F12013} If the database connection contains
   197         -** [sqlite3_stmt | prepared statements] that have not been finalized
   198         -** by [sqlite3_finalize()], then sqlite3_close() returns SQLITE_BUSY
   199         -** and leaves the connection open.  {F12014} Giving sqlite3_close()
   200         -** a NULL pointer is a harmless no-op. {END}
          236  +**          [prepared statements] that have not been
          237  +**          finalized by [sqlite3_finalize()], then [sqlite3_close()]
          238  +**          returns [SQLITE_BUSY] and leaves the connection open.
   201    239   **
   202         -** {U12015} Passing this routine a database connection that has already been
   203         -** closed results in undefined behavior. {U12016} If other interfaces that
   204         -** reference the same database connection are pending (either in the
   205         -** same thread or in different threads) when this routine is called,
   206         -** then the behavior is undefined and is almost certainly undesirable.
          240  +** {F12014} Giving sqlite3_close() a NULL pointer is a harmless no-op.
          241  +**
          242  +** LIMITATIONS:
          243  +**
          244  +** {U12015} The parameter to [sqlite3_close()] must be an [sqlite3] object
          245  +**          pointer previously obtained from [sqlite3_open()] or the 
          246  +**          equivalent, or NULL.
          247  +**
          248  +** {U12016} The parameter to [sqlite3_close()] must not have been previously
          249  +**          closed.
   207    250   */
   208    251   int sqlite3_close(sqlite3 *);
   209    252   
   210    253   /*
   211    254   ** The type for a callback function.
   212    255   ** This is legacy and deprecated.  It is included for historical
   213    256   ** compatibility and is not documented.
   214    257   */
   215    258   typedef int (*sqlite3_callback)(void*,int,char**, char**);
   216    259   
   217    260   /*
   218    261   ** CAPI3REF: One-Step Query Execution Interface {F12100}
   219    262   **
   220         -** {F12101} The sqlite3_exec() interface evaluates zero or more 
   221         -** UTF-8 encoded, semicolon-separated SQL statements in the zero-terminated
   222         -** string of its second argument.  {F12102} The SQL
   223         -** statements are evaluated in the context of the database connection
   224         -** specified by in the first argument.
   225         -** {F12103} SQL statements are prepared one by one using
   226         -** [sqlite3_prepare()] or the equivalent, evaluated
   227         -** using one or more calls to [sqlite3_step()], then destroyed
   228         -** using [sqlite3_finalize()]. {F12104} The return value of
   229         -** sqlite3_exec() is SQLITE_OK if all SQL statement run
   230         -** successfully.
   231         -**
   232         -** {F12105} If one or more of the SQL statements handed to
   233         -** sqlite3_exec() are queries, then
   234         -** the callback function specified by the 3rd parameter is
   235         -** invoked once for each row of the query result. {F12106}
   236         -** If the callback returns a non-zero value then the query
   237         -** is aborted, all subsequent SQL statements
   238         -** are skipped and the sqlite3_exec() function returns the [SQLITE_ABORT].
   239         -**
   240         -** {F12107} The 4th parameter to sqlite3_exec() is an arbitrary pointer
   241         -** that is passed through to the callback function as its first parameter.
   242         -**
   243         -** {F12108} The 2nd parameter to the callback function is the number of
   244         -** columns in the query result.  {F12109} The 3rd parameter to the callback
   245         -** is an array of pointers to strings holding the values for each column
   246         -** as extracted using [sqlite3_column_text()].  NULL values in the result
   247         -** set result in a NULL pointer.  All other value are in their UTF-8
   248         -** string representation. {F12117}
   249         -** The 4th parameter to the callback is an array of strings
   250         -** obtained using [sqlite3_column_name()] and holding
   251         -** the names of each column, also in UTF-8.
   252         -**
   253         -** {F12110} The callback function may be NULL, even for queries.  A NULL
   254         -** callback is not an error.  It just means that no callback
   255         -** will be invoked. 
   256         -**
   257         -** {F12112} If an error occurs while parsing or evaluating the SQL
   258         -** then an appropriate error message is written into memory obtained
   259         -** from [sqlite3_malloc()] and *errmsg is made to point to that message
   260         -** assuming errmsg is not NULL.  
   261         -** {U12113} The calling function is responsible for freeing the memory
   262         -** using [sqlite3_free()].
   263         -** {F12116} If [sqlite3_malloc()] fails while attempting to generate
   264         -** the error message, *errmsg is set to NULL.
   265         -** {F12114} If errmsg is NULL then no attempt is made to generate an
   266         -** error message. <todo>Is the return code SQLITE_NOMEM or the original
   267         -** error code?</todo> <todo>What happens if there are multiple errors?
   268         -** Do we get code for the first error, or is the choice of reported
   269         -** error arbitrary?</todo>
   270         -**
   271         -** {F12115} The return value is is SQLITE_OK if there are no errors and
   272         -** some other [SQLITE_OK | return code] if there is an error.  
   273         -** The particular return value depends on the type of error.  {END}
          263  +** The sqlite3_exec() interface is a convenient way of running
          264  +** one or more SQL statements without a lot of C code.  The
          265  +** SQL statements are passed in as the second parameter to
          266  +** sqlite3_exec().  The statements are evaluated one by one
          267  +** until either an error or an interrupt is encountered or
          268  +** until they are all done.  The 3rd parameter is an optional
          269  +** callback that is invoked once for each row of any query results
          270  +** produced by the SQL statements.  The 5th parameter tells where
          271  +** to write any error messages.
          272  +**
          273  +** The sqlite3_exec() interface is implemented in terms of
          274  +** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
          275  +** The sqlite3_exec() routine does nothing that cannot be done
          276  +** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
          277  +** The sqlite3_exec() is just a convenient wrapper.
          278  +**
          279  +** INVARIANTS:
          280  +** 
          281  +** {F12101} The [sqlite3_exec()] interface evaluates zero or more UTF-8
          282  +**          encoded, semicolon-separated, SQL statements in the
          283  +**          zero-terminated string of its 2nd parameter within the
          284  +**          context of the [sqlite3] object given in the 1st parameter.
          285  +**
          286  +** {F12104} The return value of [sqlite3_exec()] is SQLITE_OK if all
          287  +**          SQL statements run successfully.
          288  +**
          289  +** {F12105} The return value of [sqlite3_exec()] is an appropriate 
          290  +**          non-zero error code if any SQL statement fails.
          291  +**
          292  +** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()]
          293  +**          return results and the 3rd parameter is not NULL, then
          294  +**          the callback function specified by the 3rd parameter is
          295  +**          invoked once for each row of result.
          296  +**
          297  +** {F12110} If the callback returns a non-zero value then [sqlite3_exec()]
          298  +**          will aborted the SQL statement it is currently evaluating,
          299  +**          skip all subsequent SQL statements, and return [SQLITE_ABORT].
          300  +**          <todo>What happens to *errmsg here?  Does the result code for
          301  +**          sqlite3_errcode() get set?</todo>
          302  +**
          303  +** {F12113} The [sqlite3_exec()] routine will pass its 4th parameter through
          304  +**          as the 1st parameter of the callback.
          305  +**
          306  +** {F12116} The [sqlite3_exec()] routine sets the 2nd parameter of its
          307  +**          callback to be the number of columns in the current row of
          308  +**          result.
          309  +**
          310  +** {F12119} The [sqlite3_exec()] routine sets the 3rd parameter of its 
          311  +**          callback to be an array of pointers to strings holding the
          312  +**          values for each column in the current result set row as
          313  +**          obtained from [sqlite3_column_text()].
          314  +**
          315  +** {F12122} The [sqlite3_exec()] routine sets the 4th parameter of its
          316  +**          callback to be an array of pointers to strings holding the
          317  +**          names of result columns as obtained from [sqlite3_column_name()].
          318  +**
          319  +** {F12125} If the 3rd parameter to [sqlite3_exec()] is NULL then
          320  +**          [sqlite3_exec()] never invokes a callback.  All query
          321  +**          results are silently discarded.
          322  +**
          323  +** {F12128} If an error occurs while parsing or evaluating any of the SQL
          324  +**          statements handed to [sqlite3_exec()] then [sqlite3_exec()] will
          325  +**          return an [error code] other than [SQLITE_OK].
          326  +**
          327  +** {F12131} If an error occurs while parsing or evaluating any of the SQL
          328  +**          handed to [sqlite3_exec()] and if the 5th parameter (errmsg)
          329  +**          to [sqlite3_exec()] is not NULL, then an error message is
          330  +**          allocated using the equivalent of [sqlite3_mprintf()] and
          331  +**          *errmsg is made to point to that message.
          332  +**
          333  +** {F12134} The [sqlite3_exec()] routine does not change the value of
          334  +**          *errmsg if errmsg is NULL or if there are no errors.
          335  +**
          336  +** {F12137} The [sqlite3_exec()] function sets the error code and message
          337  +**          accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
          338  +**
          339  +** LIMITATIONS:
          340  +**
          341  +** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open
          342  +**          [database connection].
          343  +**
          344  +** {U12142} The database connection must not be closed while
          345  +**          [sqlite3_exec()] is running.
          346  +** 
          347  +** {U12143} The calling function is should use [sqlite3_free()] to free
          348  +**          the memory that *errmsg is left pointing at once the error
          349  +**          message is no longer needed.
          350  +**
          351  +** {U12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()]
          352  +**          must remain unchanged while [sqlite3_exec()] is running.
   274    353   */
   275    354   int sqlite3_exec(
   276    355     sqlite3*,                                  /* An open database */
   277    356     const char *sql,                           /* SQL to be evaluted */
   278    357     int (*callback)(void*,int,char**,char**),  /* Callback function */
   279    358     void *,                                    /* 1st argument to callback */
   280    359     char **errmsg                              /* Error msg written here */
   281    360   );
   282    361   
   283    362   /*
   284    363   ** CAPI3REF: Result Codes {F10210}
   285         -** KEYWORDS: SQLITE_OK
          364  +** KEYWORDS: SQLITE_OK {error code} {error codes}
   286    365   **
   287    366   ** Many SQLite functions return an integer result code from the set shown
   288         -** above in order to indicates success or failure.
   289         -**
   290         -** {F10211} The result codes shown here are the only ones returned 
   291         -** by SQLite in its default configuration. {F10212} However, the
   292         -** [sqlite3_extended_result_codes()] API can be used to set a database
   293         -** connectoin to return more detailed result codes. {END}
          367  +** here in order to indicates success or failure.
   294    368   **
   295    369   ** See also: [SQLITE_IOERR_READ | extended result codes]
   296         -**
   297    370   */
   298    371   #define SQLITE_OK           0   /* Successful result */
   299    372   /* beginning-of-error-codes */
   300    373   #define SQLITE_ERROR        1   /* SQL error or missing database */
   301    374   #define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
   302    375   #define SQLITE_PERM         3   /* Access permission denied */
   303    376   #define SQLITE_ABORT        4   /* Callback routine requested an abort */
................................................................................
   325    398   #define SQLITE_NOTADB      26   /* File opened that is not a database file */
   326    399   #define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
   327    400   #define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
   328    401   /* end-of-error-codes */
   329    402   
   330    403   /*
   331    404   ** CAPI3REF: Extended Result Codes {F10220}
          405  +** KEYWORDS: {extended error code} {extended error codes}
          406  +** KEYWORDS: {extended result codes}
   332    407   **
   333    408   ** In its default configuration, SQLite API routines return one of 26 integer
   334    409   ** [SQLITE_OK | result codes].  However, experience has shown that
   335    410   ** many of these result codes are too course-grained.  They do not provide as
   336    411   ** much information about problems as programmers might like.  In an effort to
   337    412   ** address this, newer versions of SQLite (version 3.3.8 and later) include
   338    413   ** support for additional result codes that provide more detailed information
   339         -** about errors. {F10221} The extended result codes are enabled or disabled
          414  +** about errors. The extended result codes are enabled or disabled
   340    415   ** for each database connection using the [sqlite3_extended_result_codes()]
   341         -** API. {END}
          416  +** API.
   342    417   ** 
   343         -** Some of the available extended result codes are listed above.
   344         -** We expect the number of extended result codes will be expand
   345         -** over time.  {U10422} Software that uses extended result codes should expect
   346         -** to see new result codes in future releases of SQLite. {END}
   347         -** 
   348         -** {F10223} The symbolic name for an extended result code always contains
   349         -** a related primary result code as a prefix. {F10224} Primary result
   350         -** codes contain a single "_" character.  {F10225} Extended result codes
   351         -** contain two or more "_" characters. {F10226} The numeric value of an
   352         -** extended result code can be converted to its
   353         -** corresponding primary result code by masking off the lower 8 bytes. {END}
          418  +** Some of the available extended result codes are listed here.
          419  +** One may expect the number of extended result codes will be expand
          420  +** over time.  Software that uses extended result codes should expect
          421  +** to see new result codes in future releases of SQLite.
   354    422   **
   355    423   ** The SQLITE_OK result code will never be extended.  It will always
   356    424   ** be exactly zero.
          425  +** 
          426  +** INVARIANTS:
          427  +**
          428  +** {F10223} The symbolic name for an extended result code always contains
          429  +**          a related primary result code as a prefix.
          430  +**
          431  +** {F10224} Primary result code names contain a single "_" character.
          432  +**
          433  +** {F10225} Extended result code names contain two or more "_" characters.
          434  +**
          435  +** {F10226} The numeric value of an extended result code contains the
          436  +**          numeric value of its corresponding primary result code it
          437  +**          its least significant 8 bits.
   357    438   */
   358    439   #define SQLITE_IOERR_READ          (SQLITE_IOERR | (1<<8))
   359    440   #define SQLITE_IOERR_SHORT_READ    (SQLITE_IOERR | (2<<8))
   360    441   #define SQLITE_IOERR_WRITE         (SQLITE_IOERR | (3<<8))
   361    442   #define SQLITE_IOERR_FSYNC         (SQLITE_IOERR | (4<<8))
   362    443   #define SQLITE_IOERR_DIR_FSYNC     (SQLITE_IOERR | (5<<8))
   363    444   #define SQLITE_IOERR_TRUNCATE      (SQLITE_IOERR | (6<<8))
................................................................................
   367    448   #define SQLITE_IOERR_DELETE        (SQLITE_IOERR | (10<<8))
   368    449   #define SQLITE_IOERR_BLOCKED       (SQLITE_IOERR | (11<<8))
   369    450   #define SQLITE_IOERR_NOMEM         (SQLITE_IOERR | (12<<8))
   370    451   
   371    452   /*
   372    453   ** CAPI3REF: Flags For File Open Operations {F10230}
   373    454   **
   374         -** {F10231} Some combination of the these bit values are used as the
   375         -** third argument to the [sqlite3_open_v2()] interface and
   376         -** as fourth argument to the xOpen method of the
          455  +** These bit values are intended for use in then
          456  +** 3rd parameter to the [sqlite3_open_v2()] interface and
          457  +** in the 4th parameter to the xOpen method of the
   377    458   ** [sqlite3_vfs] object.
   378    459   */
   379    460   #define SQLITE_OPEN_READONLY         0x00000001
   380    461   #define SQLITE_OPEN_READWRITE        0x00000002
   381    462   #define SQLITE_OPEN_CREATE           0x00000004
   382    463   #define SQLITE_OPEN_DELETEONCLOSE    0x00000008
   383    464   #define SQLITE_OPEN_EXCLUSIVE        0x00000010
................................................................................
   388    469   #define SQLITE_OPEN_TEMP_JOURNAL     0x00001000
   389    470   #define SQLITE_OPEN_SUBJOURNAL       0x00002000
   390    471   #define SQLITE_OPEN_MASTER_JOURNAL   0x00004000
   391    472   
   392    473   /*
   393    474   ** CAPI3REF: Device Characteristics {F10240}
   394    475   **
   395         -** {F10241} The xDeviceCapabilities method of the [sqlite3_io_methods]
          476  +** The xDeviceCapabilities method of the [sqlite3_io_methods]
   396    477   ** object returns an integer which is a vector of the these
   397    478   ** bit values expressing I/O characteristics of the mass storage
   398    479   ** device that holds the file that the [sqlite3_io_methods]
   399         -** refers to. {END}
          480  +** refers to.
   400    481   **
   401         -** {F10242} The SQLITE_IOCAP_ATOMIC property means that all writes of
   402         -** any size are atomic.  {F10243} The SQLITE_IOCAP_ATOMICnnn values
          482  +** The SQLITE_IOCAP_ATOMIC property means that all writes of
          483  +** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
   403    484   ** mean that writes of blocks that are nnn bytes in size and
   404    485   ** are aligned to an address which is an integer multiple of
   405         -** nnn are atomic.  {F10244} The SQLITE_IOCAP_SAFE_APPEND value means
          486  +** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
   406    487   ** that when data is appended to a file, the data is appended
   407    488   ** first then the size of the file is extended, never the other
   408         -** way around.  {F10245} The SQLITE_IOCAP_SEQUENTIAL property means that
          489  +** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
   409    490   ** information is written to disk in the same order as calls
   410    491   ** to xWrite().
   411    492   */
   412    493   #define SQLITE_IOCAP_ATOMIC          0x00000001
   413    494   #define SQLITE_IOCAP_ATOMIC512       0x00000002
   414    495   #define SQLITE_IOCAP_ATOMIC1K        0x00000004
   415    496   #define SQLITE_IOCAP_ATOMIC2K        0x00000008
................................................................................
   420    501   #define SQLITE_IOCAP_ATOMIC64K       0x00000100
   421    502   #define SQLITE_IOCAP_SAFE_APPEND     0x00000200
   422    503   #define SQLITE_IOCAP_SEQUENTIAL      0x00000400
   423    504   
   424    505   /*
   425    506   ** CAPI3REF: File Locking Levels {F10250}
   426    507   **
   427         -** {F10251} SQLite uses one of the following integer values as the second
          508  +** SQLite uses one of these integer values as the second
   428    509   ** argument to calls it makes to the xLock() and xUnlock() methods
   429         -** of an [sqlite3_io_methods] object. {END}
          510  +** of an [sqlite3_io_methods] object.
   430    511   */
   431    512   #define SQLITE_LOCK_NONE          0
   432    513   #define SQLITE_LOCK_SHARED        1
   433    514   #define SQLITE_LOCK_RESERVED      2
   434    515   #define SQLITE_LOCK_PENDING       3
   435    516   #define SQLITE_LOCK_EXCLUSIVE     4
   436    517   
   437    518   /*
   438    519   ** CAPI3REF: Synchronization Type Flags {F10260}
   439    520   **
   440         -** {F10261} When SQLite invokes the xSync() method of an
          521  +** When SQLite invokes the xSync() method of an
   441    522   ** [sqlite3_io_methods] object it uses a combination of the
   442    523   ** these integer values as the second argument.
   443    524   **
   444         -** {F10262} When the SQLITE_SYNC_DATAONLY flag is used, it means that the
          525  +** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
   445    526   ** sync operation only needs to flush data to mass storage.  Inode
   446         -** information need not be flushed. {F10263} The SQLITE_SYNC_NORMAL means 
   447         -** to use normal fsync() semantics. {F10264} The SQLITE_SYNC_FULL flag means 
          527  +** information need not be flushed. The SQLITE_SYNC_NORMAL means 
          528  +** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means 
   448    529   ** to use Mac OS-X style fullsync instead of fsync().
   449    530   */
   450    531   #define SQLITE_SYNC_NORMAL        0x00002
   451    532   #define SQLITE_SYNC_FULL          0x00003
   452    533   #define SQLITE_SYNC_DATAONLY      0x00010
   453    534   
   454    535   
................................................................................
   564    645   /*
   565    646   ** CAPI3REF: Standard File Control Opcodes {F11310}
   566    647   **
   567    648   ** These integer constants are opcodes for the xFileControl method
   568    649   ** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()]
   569    650   ** interface.
   570    651   **
   571         -** {F11311} The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
          652  +** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
   572    653   ** opcode cases the xFileControl method to write the current state of
   573    654   ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
   574    655   ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
   575         -** into an integer that the pArg argument points to. {F11312} This capability
          656  +** into an integer that the pArg argument points to. This capability
   576    657   ** is used during testing and only needs to be supported when SQLITE_TEST
   577    658   ** is defined.
   578    659   */
   579    660   #define SQLITE_FCNTL_LOCKSTATE        1
   580    661   
   581    662   /*
   582    663   ** CAPI3REF: Mutex Handle {F17110}
   583    664   **
   584    665   ** The mutex module within SQLite defines [sqlite3_mutex] to be an
   585         -** abstract type for a mutex object.  {F17111} The SQLite core never looks
   586         -** at the internal representation of an [sqlite3_mutex]. {END} It only
          666  +** abstract type for a mutex object.  The SQLite core never looks
          667  +** at the internal representation of an [sqlite3_mutex].  It only
   587    668   ** deals with pointers to the [sqlite3_mutex] object.
   588    669   **
   589    670   ** Mutexes are created using [sqlite3_mutex_alloc()].
   590    671   */
   591    672   typedef struct sqlite3_mutex sqlite3_mutex;
   592    673   
   593    674   /*
................................................................................
   652    733   ** that does not care about crash recovery or rollback, might make
   653    734   ** the open of a journal file a no-op.  Writes to this journal are
   654    735   ** also a no-op.  Any attempt to read the journal return SQLITE_IOERR.
   655    736   ** Or the implementation might recognize the a database file will
   656    737   ** be doing page-aligned sector reads and writes in a random order
   657    738   ** and set up its I/O subsystem accordingly.
   658    739   ** 
   659         -** {F11144} SQLite might also add one of the following flags to the xOpen
          740  +** SQLite might also add one of the following flags to the xOpen
   660    741   ** method:
   661    742   ** 
   662    743   ** <ul>
   663    744   ** <li> [SQLITE_OPEN_DELETEONCLOSE]
   664    745   ** <li> [SQLITE_OPEN_EXCLUSIVE]
   665    746   ** </ul>
   666    747   ** 
................................................................................
   743    824   #define SQLITE_ACCESS_EXISTS    0
   744    825   #define SQLITE_ACCESS_READWRITE 1
   745    826   #define SQLITE_ACCESS_READ      2
   746    827   
   747    828   /*
   748    829   ** CAPI3REF: Enable Or Disable Extended Result Codes {F12200}
   749    830   **
   750         -** {F12201} The sqlite3_extended_result_codes() routine enables or disables the
   751         -** [SQLITE_IOERR_READ | extended result codes] feature on a database
   752         -** connection if its 2nd parameter is
   753         -** non-zero or zero, respectively. {F12202}
   754         -** By default, SQLite API routines return one of only 26 integer
   755         -** [SQLITE_OK | result codes].  {F12203} When extended result codes
   756         -** are enabled by this routine, the repetoire of result codes can be
   757         -** much larger and can (hopefully) provide more detailed information
   758         -** about the cause of an error.
          831  +** The sqlite3_extended_result_codes() routine enables or disables the
          832  +** [SQLITE_IOERR_READ | extended result codes] feature of SQLite.
          833  +** The extended result codes are disabled by default for historical
          834  +** compatibility.
   759    835   **
   760         -** {F12204} The second argument is a boolean value that turns extended result
   761         -** codes on and off. {F12205} Extended result codes are off by default for
   762         -** backwards compatibility with older versions of SQLite.
          836  +** INVARIANTS:
          837  +**
          838  +** {F12201} Each new [database connection] has the 
          839  +**          [extended result codes] feature
          840  +**          disabled by default.
          841  +**
          842  +** {F12202} The [sqlite3_extended_result_codes(D,F)] interface will enable
          843  +**          [extended result codes] for the 
          844  +**          [database connection] D if the F parameter
          845  +**          is true, or disable them if F is false.
   763    846   */
   764    847   int sqlite3_extended_result_codes(sqlite3*, int onoff);
   765    848   
   766    849   /*
   767    850   ** CAPI3REF: Last Insert Rowid {F12220}
   768    851   **
   769         -** {F12221} Each entry in an SQLite table has a unique 64-bit signed
   770         -** integer key called the "rowid".  {F12222} The rowid is always available
          852  +** Each entry in an SQLite table has a unique 64-bit signed
          853  +** integer key called the "rowid". The rowid is always available
   771    854   ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
   772         -** names are not also used by explicitly declared columns. {F12223} If
          855  +** names are not also used by explicitly declared columns. If
   773    856   ** the table has a column of type INTEGER PRIMARY KEY then that column
   774    857   ** is another an alias for the rowid.
   775    858   **
   776         -** {F12224} This routine returns the rowid of the most recent
          859  +** This routine returns the rowid of the most recent
   777    860   ** successful INSERT into the database from the database connection
   778         -** shown in the first argument.  {F12225} If no successful inserts
          861  +** shown in the first argument.  If no successful inserts
   779    862   ** have ever occurred on this database connection, zero is returned.
   780    863   **
   781         -** {F12226} If an INSERT occurs within a trigger, then the rowid of the
          864  +** If an INSERT occurs within a trigger, then the rowid of the
   782    865   ** inserted row is returned by this routine as long as the trigger
   783         -** is running.  {F12227} But once the trigger terminates, the value returned
          866  +** is running.  But once the trigger terminates, the value returned
   784    867   ** by this routine reverts to the last value inserted before the
   785    868   ** trigger fired.
   786    869   **
   787         -** {F12228} An INSERT that fails due to a constraint violation is not a
          870  +** An INSERT that fails due to a constraint violation is not a
   788    871   ** successful insert and does not change the value returned by this
   789         -** routine.  {F12229} Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
          872  +** routine.  Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
   790    873   ** and INSERT OR ABORT make no changes to the return value of this
   791         -** routine when their insertion fails.  {F12231} When INSERT OR REPLACE 
          874  +** routine when their insertion fails.  When INSERT OR REPLACE 
   792    875   ** encounters a constraint violation, it does not fail.  The
   793    876   ** INSERT continues to completion after deleting rows that caused
   794    877   ** the constraint problem so INSERT OR REPLACE will always change
   795    878   ** the return value of this interface. 
   796    879   **
   797         -** {UF12232} If another thread does a new insert on the same database connection
   798         -** while this routine is running and thus changes the last insert rowid,
   799         -** then the return value of this routine is undefined.
          880  +** For the purposes of this routine, an insert is considered to
          881  +** be successful even if it is subsequently rolled back.
          882  +**
          883  +** INVARIANTS:
          884  +**
          885  +** {F12221} The [sqlite3_last_insert_rowid()] function returns the
          886  +**          rowid of the most recent successful insert done
          887  +**          on the same database connection and within the same
          888  +**          trigger context, or zero if there have
          889  +**          been no qualifying inserts on that connection.
          890  +**
          891  +** {F12223} The [sqlite3_last_insert_rowid()] function returns
          892  +**          same value when called from the same trigger context
          893  +**          immediately before and after a ROLLBACK.
          894  +**
          895  +** LIMITATIONS:
          896  +**
          897  +** {U12232} If separate thread does a new insert on the same
          898  +**          database connection while the [sqlite3_last_insert_rowid()]
          899  +**          function is running and thus changes the last insert rowid,
          900  +**          then the value returned by [sqlite3_last_insert_rowid()] is
          901  +**          unpredictable and might not equal either the old or the new
          902  +**          last insert rowid.
   800    903   */
   801    904   sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
   802    905   
   803    906   /*
   804    907   ** CAPI3REF: Count The Number Of Rows Modified {F12240}
   805    908   **
   806         -** {F12241} This function returns the number of database rows that were changed
          909  +** This function returns the number of database rows that were changed
   807    910   ** or inserted or deleted by the most recently completed SQL statement
   808         -** on the connection specified by the first parameter. {F12242} Only
          911  +** on the connection specified by the first parameter.  Only
   809    912   ** changes that are directly specified by the INSERT, UPDATE, or
   810    913   ** DELETE statement are counted.  Auxiliary changes caused by
   811         -** triggers are not counted. {F12243} Use the [sqlite3_total_changes()] function
          914  +** triggers are not counted. Use the [sqlite3_total_changes()] function
   812    915   ** to find the total number of changes including changes caused by triggers.
   813    916   **
   814         -** {F12244} Within the body of a trigger, the sqlite3_changes() interface
          917  +** A "row changes" is a change to a single row of a single table
          918  +** caused by an INSERT, DELETE, or UPDATE statement.  Rows that
          919  +** are changed as side effects of REPLACE constraint resolution,
          920  +** rollback, ABORT processing, DROP TABLE, or by any other
          921  +** mechanisms do not count as direct row changes.
          922  +**
          923  +** A "trigger context" is a scope of execution that begins and
          924  +** ends with the script of a trigger.  Most SQL statements are
          925  +** evaluated outside of any trigger.  This is the "top level"
          926  +** trigger context.  If a trigger fires from the top level, a
          927  +** new trigger context is entered for the duration of that one
          928  +** trigger.  Subtriggers create subcontexts for their duration.
          929  +**
          930  +** Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
          931  +** not create a new trigger context.
          932  +**
          933  +** This function returns the number of direct row changes in the
          934  +** most recent INSERT, UPDATE, or DELETE statement within the same
          935  +** trigger context.
          936  +**
          937  +** So when called from the top level, this function returns the
          938  +** number of changes in the most recent INSERT, UPDATE, or DELETE
          939  +** that also occurred at the top level.
          940  +** Within the body of a trigger, the sqlite3_changes() interface
   815    941   ** can be called to find the number of
   816    942   ** changes in the most recently completed INSERT, UPDATE, or DELETE
   817    943   ** statement within the body of the same trigger.
          944  +** However, the number returned does not include in changes
          945  +** caused by subtriggers since they have their own context.
   818    946   **
   819         -** {F12245} All changes are counted, even if they are later undone by a
   820         -** ROLLBACK or ABORT.  {F12246} Except, changes associated with creating and
   821         -** dropping tables are not counted.
   822         -**
   823         -** {F12247} If a callback invokes [sqlite3_exec()] or [sqlite3_step()]
   824         -** recursively, then the changes in the inner, recursive call are
   825         -** counted together with the changes in the outer call.
   826         -**
   827         -** {F12248} SQLite implements the command "DELETE FROM table" without
          947  +** SQLite implements the command "DELETE FROM table" without
   828    948   ** a WHERE clause by dropping and recreating the table.  (This is much
   829    949   ** faster than going through and deleting individual elements from the
   830         -** table.)  Because of this optimization, the change count for 
   831         -** "DELETE FROM table" will be zero regardless of the number of elements
   832         -** that were originally in the table. {F12251} To get an accurate count
   833         -** of the number of rows deleted, use
          950  +** table.)  Because of this optimization, the deletions in
          951  +** "DELETE FROM table" are not row changes and will not be counted
          952  +** by the sqlite3_changes() or [sqlite3_total_changes()] functions.
          953  +** To get an accurate count of the number of rows deleted, use
   834    954   ** "DELETE FROM table WHERE 1" instead.
   835    955   **
   836         -** {UF12252} If another thread makes changes on the same database connection
   837         -** while this routine is running then the return value of this routine
   838         -** is undefined.
          956  +** INVARIANTS:
          957  +**
          958  +** {F12241} The [sqlite3_changes()] function returns the number of
          959  +**          row changes caused by the most recent INSERT, UPDATE,
          960  +**          or DELETE statement on the same database connection and
          961  +**          within the same trigger context, or zero if there have
          962  +**          not been any qualifying row changes.
          963  +**
          964  +** LIMITATIONS:
          965  +**
          966  +** {U12252} If a separate thread makes changes on the same database connection
          967  +**          while [sqlite3_changes()] is running then the value returned
          968  +**          is unpredictable and unmeaningful.
   839    969   */
   840    970   int sqlite3_changes(sqlite3*);
   841    971   
   842    972   /*
   843    973   ** CAPI3REF: Total Number Of Rows Modified {F12260}
   844    974   ***
   845         -** {F12261} This function returns the number of database rows that have been
   846         -** modified by INSERT, UPDATE or DELETE statements since the database handle
   847         -** was opened. {F12262} The count includes UPDATE, INSERT and DELETE 
   848         -** statements executed as part of trigger programs.  {F12263} All changes
          975  +** This function returns the number of row changes caused
          976  +** by INSERT, UPDATE or DELETE statements since the database handle
          977  +** was opened.  The count includes all changes from all trigger
          978  +** contexts.  But the count does not include changes used to
          979  +** implement REPLACE constraints, do rollbacks or ABORT processing,
          980  +** or DROP table processing.
          981  +** The changes
   849    982   ** are counted as soon as the statement that makes them is completed 
   850    983   ** (when the statement handle is passed to [sqlite3_reset()] or 
   851         -** [sqlite3_finalize()]). {END}
          984  +** [sqlite3_finalize()]).
   852    985   **
   853         -** See also the [sqlite3_change()] interface.
   854         -**
   855         -** {F12265} SQLite implements the command "DELETE FROM table" without
          986  +** SQLite implements the command "DELETE FROM table" without
   856    987   ** a WHERE clause by dropping and recreating the table.  (This is much
   857    988   ** faster than going
   858    989   ** through and deleting individual elements form the table.)  Because of
   859    990   ** this optimization, the change count for "DELETE FROM table" will be
   860    991   ** zero regardless of the number of elements that were originally in the
   861    992   ** table. To get an accurate count of the number of rows deleted, use
   862    993   ** "DELETE FROM table WHERE 1" instead.
   863    994   **
   864         -** {U12264} If another thread makes changes on the same database connection
   865         -** while this routine is running then the return value of this routine
   866         -** is undefined. {END}
          995  +** See also the [sqlite3_changes()] interface.
          996  +**
          997  +** INVARIANTS:
          998  +** 
          999  +** {F12261} The [sqlite3_total_changes()] returns the total number
         1000  +**          of row changes caused by INSERT, UPDATE, and/or DELETE
         1001  +**          statements on the same [database connection], in any
         1002  +**          trigger context, since the database connection was
         1003  +**          created.
         1004  +**
         1005  +** LIMITATIONS:
         1006  +**
         1007  +** {U12264} If a separate thread makes changes on the same database connection
         1008  +**          while [sqlite3_total_changes()] is running then the value 
         1009  +**          returned is unpredictable and unmeaningful.
   867   1010   */
   868   1011   int sqlite3_total_changes(sqlite3*);
   869   1012   
   870   1013   /*
   871   1014   ** CAPI3REF: Interrupt A Long-Running Query {F12270}
   872   1015   **
   873         -** {F12271} This function causes any pending database operation to abort and
   874         -** return at its earliest opportunity. {END} This routine is typically
         1016  +** This function causes any pending database operation to abort and
         1017  +** return at its earliest opportunity. This routine is typically
   875   1018   ** called in response to a user action such as pressing "Cancel"
   876   1019   ** or Ctrl-C where the user wants a long query operation to halt
   877   1020   ** immediately.
   878   1021   **
   879         -** {F12272} It is safe to call this routine from a thread different from the
   880         -** thread that is currently running the database operation. {U12273} But it
         1022  +** It is safe to call this routine from a thread different from the
         1023  +** thread that is currently running the database operation.  But it
   881   1024   ** is not safe to call this routine with a database connection that
   882   1025   ** is closed or might close before sqlite3_interrupt() returns.
   883   1026   **
   884   1027   ** If an SQL is very nearly finished at the time when sqlite3_interrupt()
   885   1028   ** is called, then it might not have an opportunity to be interrupted.
   886   1029   ** It might continue to completion.
   887         -** {F12274} The SQL operation that is interrupted will return
   888         -** [SQLITE_INTERRUPT].  {F12275} If the interrupted SQL operation is an
         1030  +** An SQL operation that is interrupted will return
         1031  +** [SQLITE_INTERRUPT].  If the interrupted SQL operation is an
   889   1032   ** INSERT, UPDATE, or DELETE that is inside an explicit transaction, 
   890   1033   ** then the entire transaction will be rolled back automatically.
   891         -** {F12276} A call to sqlite3_interrupt() has no effect on SQL statements
         1034  +** A call to sqlite3_interrupt() has no effect on SQL statements
   892   1035   ** that are started after sqlite3_interrupt() returns.
         1036  +**
         1037  +** INVARIANTS:
         1038  +**
         1039  +** {F12271} The [sqlite3_interrupt()] interface will force all running
         1040  +**          SQL statements associated with the same database connection
         1041  +**          to halt after processing at most one additional row of
         1042  +**          data.
         1043  +**
         1044  +** {F12272} Any SQL statement that is interrupted by [sqlite3_interrupt()]
         1045  +**          will return [SQLITE_INTERRUPT].
         1046  +**
         1047  +** LIMITATIONS:
         1048  +**
         1049  +** {U12279} If the database connection closes while [sqlite3_interrupt()]
         1050  +**          is running then bad things will likely happen.
   893   1051   */
   894   1052   void sqlite3_interrupt(sqlite3*);
   895   1053   
   896   1054   /*
   897   1055   ** CAPI3REF: Determine If An SQL Statement Is Complete {F10510}
   898   1056   **
   899   1057   ** These routines are useful for command-line input to determine if the
   900   1058   ** currently entered text seems to form complete a SQL statement or
   901   1059   ** if additional input is needed before sending the text into
   902   1060   ** SQLite for parsing.  These routines return true if the input string
   903   1061   ** appears to be a complete SQL statement.  A statement is judged to be
   904         -** complete if it ends with a semicolon and is not a fragment of a
   905         -** CREATE TRIGGER statement.  These routines do not parse the SQL and
         1062  +** complete if it ends with a semicolon token and is not a fragment of a
         1063  +** CREATE TRIGGER statement.  Semicolons that are embedded within
         1064  +** string literals or quoted identifier names or comments are not
         1065  +** independent tokens (they are part of the token in which they are
         1066  +** embedded) and thus do not count as a statement terminator.
         1067  +**
         1068  +** These routines do not parse the SQL and
   906   1069   ** so will not detect syntactically incorrect SQL.
   907   1070   **
   908         -** {F10511} These functions return true if the given input string 
   909         -** ends with a semicolon optionally followed by whitespace or
   910         -** comments. {F10512} For sqlite3_complete(),
   911         -** the parameter must be a zero-terminated UTF-8 string. {F10513} For
   912         -** sqlite3_complete16(), a zero-terminated machine byte order UTF-16 string
   913         -** is required.  {F10514} These routines return false if the terminal
   914         -** semicolon is within a comment, a string literal or a quoted identifier
   915         -** (in other words if the final semicolon is not really a separate token
   916         -** but part of a larger token) or if the final semicolon is
   917         -** in between the BEGIN and END keywords of a CREATE TRIGGER statement.
   918         -** {END}
         1071  +** INVARIANTS:
         1072  +**
         1073  +** {F10511} The sqlite3_complete() and sqlite3_complete16() functions
         1074  +**          return true (non-zero) if and only if the last
         1075  +**          non-whitespace token in their input is a semicolon that
         1076  +**          is not in between the BEGIN and END of a CREATE TRIGGER
         1077  +**          statement.
         1078  +**
         1079  +** LIMITATIONS:
         1080  +**
         1081  +** {U10512} The input to sqlite3_complete() must be a zero-terminated
         1082  +**          UTF-8 string.
         1083  +**
         1084  +** {U10513} The input to sqlite3_complete16() must be a zero-terminated
         1085  +**          UTF-16 string in native byte order.
   919   1086   */
   920   1087   int sqlite3_complete(const char *sql);
   921   1088   int sqlite3_complete16(const void *sql);
   922   1089   
   923   1090   /*
   924   1091   ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {F12310}
   925   1092   **
   926         -** {F12311} This routine identifies a callback function that might be
         1093  +** This routine identifies a callback function that might be
   927   1094   ** invoked whenever an attempt is made to open a database table 
   928   1095   ** that another thread or process has locked.
   929         -** {F12312} If the busy callback is NULL, then [SQLITE_BUSY]
         1096  +** If the busy callback is NULL, then [SQLITE_BUSY]
   930   1097   ** or [SQLITE_IOERR_BLOCKED]
   931   1098   ** is returned immediately upon encountering the lock.
   932         -** {F12313} If the busy callback is not NULL, then the
   933         -** callback will be invoked with two arguments.  {F12314} The
         1099  +** If the busy callback is not NULL, then the
         1100  +** callback will be invoked with two arguments.  The
   934   1101   ** first argument to the handler is a copy of the void* pointer which
   935         -** is the third argument to this routine.  {F12315} The second argument to
         1102  +** is the third argument to this routine.  The second argument to
   936   1103   ** the handler is the number of times that the busy handler has
   937         -** been invoked for this locking event.  {F12316} If the
         1104  +** been invoked for this locking event.   If the
   938   1105   ** busy callback returns 0, then no additional attempts are made to
   939   1106   ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
   940         -** {F12317} If the callback returns non-zero, then another attempt
         1107  +** If the callback returns non-zero, then another attempt
   941   1108   ** is made to open the database for reading and the cycle repeats.
   942   1109   **
   943   1110   ** The presence of a busy handler does not guarantee that
   944         -** it will be invoked when there is lock contention. {F12319}
         1111  +** it will be invoked when there is lock contention.
   945   1112   ** If SQLite determines that invoking the busy handler could result in
   946   1113   ** a deadlock, it will go ahead and return [SQLITE_BUSY] or
   947   1114   ** [SQLITE_IOERR_BLOCKED] instead of invoking the
   948         -** busy handler. {END}
         1115  +** busy handler.
   949   1116   ** Consider a scenario where one process is holding a read lock that
   950   1117   ** it is trying to promote to a reserved lock and
   951   1118   ** a second process is holding a reserved lock that it is trying
   952   1119   ** to promote to an exclusive lock.  The first process cannot proceed
   953   1120   ** because it is blocked by the second and the second process cannot
   954   1121   ** proceed because it is blocked by the first.  If both processes
   955   1122   ** invoke the busy handlers, neither will make any progress.  Therefore,
   956   1123   ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
   957   1124   ** will induce the first process to release its read lock and allow
   958   1125   ** the second process to proceed.
   959   1126   **
   960         -** {F12321} The default busy callback is NULL. {END}
         1127  +** The default busy callback is NULL.
   961   1128   **
   962         -** {F12322} The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
         1129  +** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
   963   1130   ** when SQLite is in the middle of a large transaction where all the
   964         -** changes will not fit into the in-memory cache.  {F12323} SQLite will
         1131  +** changes will not fit into the in-memory cache.  SQLite will
   965   1132   ** already hold a RESERVED lock on the database file, but it needs
   966   1133   ** to promote this lock to EXCLUSIVE so that it can spill cache
   967   1134   ** pages into the database file without harm to concurrent
   968         -** readers.  {F12324} If it is unable to promote the lock, then the in-memory
         1135  +** readers.  If it is unable to promote the lock, then the in-memory
   969   1136   ** cache will be left in an inconsistent state and so the error
   970   1137   ** code is promoted from the relatively benign [SQLITE_BUSY] to
   971         -** the more severe [SQLITE_IOERR_BLOCKED].  {F12325} This error code promotion
   972         -** forces an automatic rollback of the changes. {END} See the
         1138  +** the more severe [SQLITE_IOERR_BLOCKED].  This error code promotion
         1139  +** forces an automatic rollback of the changes.  See the
   973   1140   ** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
   974   1141   ** CorruptionFollowingBusyError</a> wiki page for a discussion of why
   975   1142   ** this is important.
   976   1143   **	
   977         -** {F12326} Sqlite is re-entrant, so the busy handler may start a new
   978         -** query. {END} (It is not clear why anyone would every want to do this,
   979         -** but it is allowed, in theory.) {U12327} But the busy handler may not
   980         -** close the database.  Closing the database from a busy handler will delete 
   981         -** data structures out from under the executing query and will 
   982         -** probably result in a segmentation fault or other runtime error. {END}
   983         -**
   984         -** {F12328} There can only be a single busy handler defined for each database
         1144  +** There can only be a single busy handler defined for each database
   985   1145   ** connection.  Setting a new busy handler clears any previous one. 
   986         -** {F12329} Note that calling [sqlite3_busy_timeout()] will also set or clear
         1146  +** Note that calling [sqlite3_busy_timeout()] will also set or clear
   987   1147   ** the busy handler.
   988   1148   **
   989         -** {F12331} When operating in [sqlite3_enable_shared_cache | shared cache mode],
   990         -** only a single busy handler can be defined for each database file.
   991         -** So if two database connections share a single cache, then changing
   992         -** the busy handler on one connection will also change the busy
   993         -** handler in the other connection.  {F12332} The busy handler is invoked
   994         -** in the thread that was running when the lock contention occurs.
         1149  +** INVARIANTS:
         1150  +**
         1151  +** {F12311} The [sqlite3_busy_handler()] function replaces the busy handler
         1152  +**          callback in the database connection identified by the 1st
         1153  +**          parameter with a new busy handler identified by the 2nd and 3rd
         1154  +**          parameters.
         1155  +**
         1156  +** {F12312} The default busy handler for new database connections is NULL.
         1157  +**
         1158  +** {F12314} When two or more database connection share a common cache,
         1159  +**          the busy handler for the database connection currently using
         1160  +**          the cache is invoked when the cache encounters a lock.
         1161  +**
         1162  +** {F12316} If a busy handler callback returns zero, then the SQLite
         1163  +**          interface that provoked the locking event will return
         1164  +**          [SQLITE_BUSY].
         1165  +**
         1166  +** {F12318} SQLite will invokes the busy handler with two argument which
         1167  +**          are a copy of the pointer supplied by the 3rd parameter to
         1168  +**          [sqlite3_busy_handler()] and a count of the number of prior
         1169  +**          invocations of the busy handler for the same locking event.
         1170  +**
         1171  +** LIMITATIONS:
         1172  +**
         1173  +** {U12319} A busy handler should not call close the database connection
         1174  +**          or prepared statement that invoked the busy handler.
   995   1175   */
   996   1176   int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
   997   1177   
   998   1178   /*
   999   1179   ** CAPI3REF: Set A Busy Timeout {F12340}
  1000   1180   **
  1001         -** {F12341} This routine sets a [sqlite3_busy_handler | busy handler]
         1181  +** This routine sets a [sqlite3_busy_handler | busy handler]
  1002   1182   ** that sleeps for a while when a
  1003         -** table is locked.  {F12342} The handler will sleep multiple times until 
         1183  +** table is locked.  The handler will sleep multiple times until 
  1004   1184   ** at least "ms" milliseconds of sleeping have been done. {F12343} After
  1005   1185   ** "ms" milliseconds of sleeping, the handler returns 0 which
  1006   1186   ** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
  1007   1187   **
  1008         -** {F12344} Calling this routine with an argument less than or equal to zero
         1188  +** Calling this routine with an argument less than or equal to zero
  1009   1189   ** turns off all busy handlers.
  1010   1190   **
  1011         -** {F12345} There can only be a single busy handler for a particular database
         1191  +** There can only be a single busy handler for a particular database
  1012   1192   ** connection.  If another busy handler was defined  
  1013   1193   ** (using [sqlite3_busy_handler()]) prior to calling
  1014   1194   ** this routine, that other busy handler is cleared.
         1195  +**
         1196  +** INVARIANTS:
         1197  +**
         1198  +** {F12341} The [sqlite3_busy_timeout()] function overrides any prior
         1199  +**          [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting
         1200  +**          on the same database connection.
         1201  +**
         1202  +** {F12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than
         1203  +**          or equal to zero, then the busy handler is cleared so that
         1204  +**          all subsequent locking events immediately return [SQLITE_BUSY].
         1205  +**
         1206  +** {F12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive
         1207  +**          number N, then a busy handler is set that repeatedly calls
         1208  +**          the xSleep() method in the VFS interface until either the
         1209  +**          lock clears or until the cumulative sleep time reported back
         1210  +**          by xSleep() exceeds N milliseconds.
  1015   1211   */
  1016   1212   int sqlite3_busy_timeout(sqlite3*, int ms);
  1017   1213   
  1018   1214   /*
  1019   1215   ** CAPI3REF: Convenience Routines For Running Queries {F12370}
  1020   1216   **
  1021         -** This next routine is a convenience wrapper around [sqlite3_exec()].
  1022         -** {F12371} Instead of invoking a user-supplied callback for each row of the
  1023         -** result, this routine remembers each row of the result in memory
  1024         -** obtained from [sqlite3_malloc()], then returns all of the result after the
  1025         -** query has finished. {F12372}
         1217  +** Definition: A <b>result table</b> is memory data structure created by the
         1218  +** [sqlite3_get_table()] interface.  A result table records the
         1219  +** complete query results from one or more queries.
  1026   1220   **
  1027         -** As an example, suppose the query result where this table:
         1221  +** The table conceptually has a number of rows and columns.  But
         1222  +** these numbers are not part of the result table itself.  These
         1223  +** numbers are obtained separately.  Let N be the number of rows
         1224  +** and M be the number of columns.
         1225  +**
         1226  +** A result table is an array of pointers to zero-terminated
         1227  +** UTF-8 strings.  There are (N+1)*M elements in the array.  
         1228  +** The first M pointers point to zero-terminated strings that 
         1229  +** contain the names of the columns.
         1230  +** The remaining entries all point to query results.  NULL
         1231  +** values are give a NULL pointer.  All other values are in
         1232  +** their UTF-8 zero-terminated string representation as returned by
         1233  +** [sqlite3_column_text()].
         1234  +**
         1235  +** A result table might consists of one or more memory allocations.
         1236  +** It is not safe to pass a result table directly to [sqlite3_free()].
         1237  +** A result table should be deallocated using [sqlite3_free_table()].
         1238  +**
         1239  +** As an example of the result table format, suppose a query result
         1240  +** is as follows:
  1028   1241   **
  1029   1242   ** <blockquote><pre>
  1030   1243   **        Name        | Age
  1031   1244   **        -----------------------
  1032   1245   **        Alice       | 43
  1033   1246   **        Bob         | 28
  1034   1247   **        Cindy       | 21
  1035   1248   ** </pre></blockquote>
  1036   1249   **
  1037         -** If the 3rd argument were &azResult then after the function returns
  1038         -** azResult will contain the following data:
         1250  +** There are two column (M==2) and three rows (N==3).  Thus the
         1251  +** result table has 8 entries.  Suppose the result table is stored
         1252  +** in an array names azResult.  Then azResult holds this content:
  1039   1253   **
  1040   1254   ** <blockquote><pre>
  1041   1255   **        azResult&#91;0] = "Name";
  1042   1256   **        azResult&#91;1] = "Age";
  1043   1257   **        azResult&#91;2] = "Alice";
  1044   1258   **        azResult&#91;3] = "43";
  1045   1259   **        azResult&#91;4] = "Bob";
  1046   1260   **        azResult&#91;5] = "28";
  1047   1261   **        azResult&#91;6] = "Cindy";
  1048   1262   **        azResult&#91;7] = "21";
  1049   1263   ** </pre></blockquote>
  1050   1264   **
  1051         -** Notice that there is an extra row of data containing the column
  1052         -** headers.  But the *nrow return value is still 3.  *ncolumn is
  1053         -** set to 2.  In general, the number of values inserted into azResult
  1054         -** will be ((*nrow) + 1)*(*ncolumn).
         1265  +** The sqlite3_get_table() function evaluates one or more
         1266  +** semicolon-separated SQL statements in the zero-terminated UTF-8
         1267  +** string of its 2nd parameter.  It returns a result table to the
         1268  +** pointer given in its 3rd parameter.
  1055   1269   **
  1056         -** {U12374} After the calling function has finished using the result, it should 
  1057         -** pass the result data pointer to sqlite3_free_table() in order to 
         1270  +** After the calling function has finished using the result, it should 
         1271  +** pass the pointer to the result table to sqlite3_free_table() in order to 
  1058   1272   ** release the memory that was malloc-ed.  Because of the way the 
  1059         -** [sqlite3_malloc()] happens, the calling function must not try to call 
  1060         -** [sqlite3_free()] directly.  Only [sqlite3_free_table()] is able to release 
  1061         -** the memory properly and safely. {END}
         1273  +** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
         1274  +** function must not try to call [sqlite3_free()] directly.  Only 
         1275  +** [sqlite3_free_table()] is able to release the memory properly and safely.
  1062   1276   **
  1063         -** {F12373} The return value of this routine is the same as
  1064         -** from [sqlite3_exec()].
         1277  +** The sqlite3_get_table() interface is implemented as a wrapper around
         1278  +** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access
         1279  +** to any internal data structures of SQLite.  It uses only the public
         1280  +** interface defined here.  As a consequence, errors that occur in the
         1281  +** wrapper layer outside of the internal [sqlite3_exec()] call are not
         1282  +** reflected in subsequent calls to [sqlite3_errcode()] or
         1283  +** [sqlite3_errmsg()].
         1284  +**
         1285  +** INVARIANTS:
         1286  +**
         1287  +** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then
         1288  +**          it frees the result table under construction, aborts the
         1289  +**          query in process, skips any subsequent queries, sets the
         1290  +**          *resultp output pointer to NULL and returns [SQLITE_NOMEM].
         1291  +**
         1292  +** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL
         1293  +**          then [sqlite3_get_table()] write the number of columns in the
         1294  +**          result set of the query into *ncolumn if the query is
         1295  +**          successful (if the function returns SQLITE_OK).
         1296  +**
         1297  +** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL
         1298  +**          then [sqlite3_get_table()] write the number of rows in the
         1299  +**          result set of the query into *nrow if the query is
         1300  +**          successful (if the function returns SQLITE_OK).
         1301  +**
         1302  +** {F12373} The [sqlite3_get_table()] function sets its *ncolumn value
         1303  +**          to the number of columns in the result set of the query in the
         1304  +**          sql parameter, or to zero if the query in sql has an empty
         1305  +**          result set.
  1065   1306   */
  1066   1307   int sqlite3_get_table(
  1067         -  sqlite3*,              /* An open database */
  1068         -  const char *sql,       /* SQL to be executed */
  1069         -  char ***resultp,       /* Result written to a char *[]  that this points to */
  1070         -  int *nrow,             /* Number of result rows written here */
  1071         -  int *ncolumn,          /* Number of result columns written here */
  1072         -  char **errmsg          /* Error msg written here */
         1308  +  sqlite3*,             /* An open database */
         1309  +  const char *sql,      /* SQL to be evaluated */
         1310  +  char ***pResult,      /* Results of the query */
         1311  +  int *nrow,            /* Number of result rows written here */
         1312  +  int *ncolumn,         /* Number of result columns written here */
         1313  +  char **errmsg         /* Error msg written here */
  1073   1314   );
  1074   1315   void sqlite3_free_table(char **result);
  1075   1316   
  1076   1317   /*
  1077   1318   ** CAPI3REF: Formatted String Printing Functions {F17400}
  1078   1319   **
  1079   1320   ** These routines are workalikes of the "printf()" family of functions
  1080   1321   ** from the standard C library.
  1081   1322   **
  1082         -** {F17401} The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
         1323  +** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
  1083   1324   ** results into memory obtained from [sqlite3_malloc()].
  1084         -** {U17402} The strings returned by these two routines should be
  1085         -** released by [sqlite3_free()]. {F17403}  Both routines return a
         1325  +** The strings returned by these two routines should be
         1326  +** released by [sqlite3_free()].   Both routines return a
  1086   1327   ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
  1087   1328   ** memory to hold the resulting string.
  1088   1329   **
  1089         -** {F17404} In sqlite3_snprintf() routine is similar to "snprintf()" from
         1330  +** In sqlite3_snprintf() routine is similar to "snprintf()" from
  1090   1331   ** the standard C library.  The result is written into the
  1091   1332   ** buffer supplied as the second parameter whose size is given by
  1092         -** the first parameter. {END} Note that the order of the
         1333  +** the first parameter. Note that the order of the
  1093   1334   ** first two parameters is reversed from snprintf().  This is an
  1094   1335   ** historical accident that cannot be fixed without breaking
  1095         -** backwards compatibility.  {F17405} Note also that sqlite3_snprintf()
         1336  +** backwards compatibility.  Note also that sqlite3_snprintf()
  1096   1337   ** returns a pointer to its buffer instead of the number of
  1097         -** characters actually written into the buffer. {END} We admit that
         1338  +** characters actually written into the buffer.  We admit that
  1098   1339   ** the number of characters written would be a more useful return
  1099   1340   ** value but we cannot change the implementation of sqlite3_snprintf()
  1100   1341   ** now without breaking compatibility.
  1101   1342   **
  1102         -** {F17406} As long as the buffer size is greater than zero, sqlite3_snprintf()
  1103         -** guarantees that the buffer is always zero-terminated. {F17407} The first
         1343  +** As long as the buffer size is greater than zero, sqlite3_snprintf()
         1344  +** guarantees that the buffer is always zero-terminated.  The first
  1104   1345   ** parameter "n" is the total size of the buffer, including space for
  1105         -** the zero terminator.  {END} So the longest string that can be completely
         1346  +** the zero terminator.  So the longest string that can be completely
  1106   1347   ** written will be n-1 characters.
  1107   1348   **
  1108   1349   ** These routines all implement some additional formatting
  1109   1350   ** options that are useful for constructing SQL statements.
  1110   1351   ** All of the usual printf formatting options apply.  In addition, there
  1111   1352   ** is are "%q", "%Q", and "%z" options.
  1112   1353   **
  1113         -** {F17410} The %q option works like %s in that it substitutes a null-terminated
         1354  +** The %q option works like %s in that it substitutes a null-terminated
  1114   1355   ** string from the argument list.  But %q also doubles every '\'' character.
  1115         -** %q is designed for use inside a string literal. {END} By doubling each '\''
         1356  +** %q is designed for use inside a string literal.  By doubling each '\''
  1116   1357   ** character it escapes that character and allows it to be inserted into
  1117   1358   ** the string.
  1118   1359   **
  1119   1360   ** For example, so some string variable contains text as follows:
  1120   1361   **
  1121   1362   ** <blockquote><pre>
  1122   1363   **  char *zText = "It's a happy day!";
................................................................................
  1144   1385   **  INSERT INTO table1 VALUES('It's a happy day!');
  1145   1386   ** </pre></blockquote>
  1146   1387   **
  1147   1388   ** This second example is an SQL syntax error.  As a general rule you
  1148   1389   ** should always use %q instead of %s when inserting text into a string 
  1149   1390   ** literal.
  1150   1391   **
  1151         -** {F17411} The %Q option works like %q except it also adds single quotes around
         1392  +** The %Q option works like %q except it also adds single quotes around
  1152   1393   ** the outside of the total string.  Or if the parameter in the argument
  1153   1394   ** list is a NULL pointer, %Q substitutes the text "NULL" (without single
  1154   1395   ** quotes) in place of the %Q option. {END}  So, for example, one could say:
  1155   1396   **
  1156   1397   ** <blockquote><pre>
  1157   1398   **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
  1158   1399   **  sqlite3_exec(db, zSQL, 0, 0, 0);
  1159   1400   **  sqlite3_free(zSQL);
  1160   1401   ** </pre></blockquote>
  1161   1402   **
  1162   1403   ** The code above will render a correct SQL statement in the zSQL
  1163   1404   ** variable even if the zText variable is a NULL pointer.
  1164   1405   **
  1165         -** {F17412} The "%z" formatting option works exactly like "%s" with the
         1406  +** The "%z" formatting option works exactly like "%s" with the
  1166   1407   ** addition that after the string has been read and copied into
  1167   1408   ** the result, [sqlite3_free()] is called on the input string. {END}
         1409  +**
         1410  +** INVARIANTS:
         1411  +**
         1412  +** {F17403}  The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces
         1413  +**           return either pointers to zero-terminated UTF-8 strings held in
         1414  +**           memory obtained from [sqlite3_malloc()] or NULL pointers if
         1415  +**           a call to [sqlite3_malloc()] fails.
         1416  +**
         1417  +** {F17406}  The [sqlite3_snprintf()] interface writes a zero-terminated
         1418  +**           UTF-8 string into the buffer pointed to by the second parameter
         1419  +**           provided that the first parameter is greater than zero.
         1420  +**
         1421  +** {F17407}  The [sqlite3_snprintf()] interface does not writes slots of
         1422  +**           its output buffer (the second parameter) outside the range
         1423  +**           of 0 through N-1 (where N is the first parameter)
         1424  +**           regardless of the length of the string
         1425  +**           requested by the format specification.
         1426  +**   
  1168   1427   */
  1169   1428   char *sqlite3_mprintf(const char*,...);
  1170   1429   char *sqlite3_vmprintf(const char*, va_list);
  1171   1430   char *sqlite3_snprintf(int,char*,const char*, ...);
  1172   1431   
  1173   1432   /*
  1174   1433   ** CAPI3REF: Memory Allocation Subsystem {F17300}
  1175   1434   **
  1176         -** {F17301} The SQLite core  uses these three routines for all of its own
  1177         -** internal memory allocation needs. {END}  "Core" in the previous sentence
         1435  +** The SQLite core  uses these three routines for all of its own
         1436  +** internal memory allocation needs. "Core" in the previous sentence
  1178   1437   ** does not include operating-system specific VFS implementation.  The
  1179   1438   ** windows VFS uses native malloc and free for some operations.
  1180   1439   **
  1181         -** {F17302} The sqlite3_malloc() routine returns a pointer to a block
         1440  +** The sqlite3_malloc() routine returns a pointer to a block
  1182   1441   ** of memory at least N bytes in length, where N is the parameter.
  1183         -** {F17303} If sqlite3_malloc() is unable to obtain sufficient free
  1184         -** memory, it returns a NULL pointer.  {F17304} If the parameter N to
         1442  +** If sqlite3_malloc() is unable to obtain sufficient free
         1443  +** memory, it returns a NULL pointer.  If the parameter N to
  1185   1444   ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
  1186   1445   ** a NULL pointer.
  1187   1446   **
  1188         -** {F17305} Calling sqlite3_free() with a pointer previously returned
         1447  +** Calling sqlite3_free() with a pointer previously returned
  1189   1448   ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
  1190         -** that it might be reused.  {F17306} The sqlite3_free() routine is
         1449  +** that it might be reused.  The sqlite3_free() routine is
  1191   1450   ** a no-op if is called with a NULL pointer.  Passing a NULL pointer
  1192         -** to sqlite3_free() is harmless.  {U17307} After being freed, memory
         1451  +** to sqlite3_free() is harmless.  After being freed, memory
  1193   1452   ** should neither be read nor written.  Even reading previously freed
  1194   1453   ** memory might result in a segmentation fault or other severe error.
  1195         -** {U17309} Memory corruption, a segmentation fault, or other severe error
         1454  +** Memory corruption, a segmentation fault, or other severe error
  1196   1455   ** might result if sqlite3_free() is called with a non-NULL pointer that
  1197   1456   ** was not obtained from sqlite3_malloc() or sqlite3_free().
  1198   1457   **
  1199         -** {F17310} The sqlite3_realloc() interface attempts to resize a
         1458  +** The sqlite3_realloc() interface attempts to resize a
  1200   1459   ** prior memory allocation to be at least N bytes, where N is the
  1201   1460   ** second parameter.  The memory allocation to be resized is the first
  1202         -** parameter.  {F17311} If the first parameter to sqlite3_realloc()
         1461  +** parameter.  If the first parameter to sqlite3_realloc()
  1203   1462   ** is a NULL pointer then its behavior is identical to calling
  1204   1463   ** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
  1205         -** {F17312} If the second parameter to sqlite3_realloc() is zero or
         1464  +** If the second parameter to sqlite3_realloc() is zero or
  1206   1465   ** negative then the behavior is exactly the same as calling
  1207   1466   ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
  1208         -** {F17313} Sqlite3_realloc() returns a pointer to a memory allocation
         1467  +** Sqlite3_realloc() returns a pointer to a memory allocation
  1209   1468   ** of at least N bytes in size or NULL if sufficient memory is unavailable.
  1210         -** {F17314} If M is the size of the prior allocation, then min(N,M) bytes
         1469  +** If M is the size of the prior allocation, then min(N,M) bytes
  1211   1470   ** of the prior allocation are copied into the beginning of buffer returned
  1212   1471   ** by sqlite3_realloc() and the prior allocation is freed.
  1213         -** {F17315} If sqlite3_realloc() returns NULL, then the prior allocation
         1472  +** If sqlite3_realloc() returns NULL, then the prior allocation
  1214   1473   ** is not freed.
  1215   1474   **
  1216         -** {F17316} The memory returned by sqlite3_malloc() and sqlite3_realloc()
         1475  +** The memory returned by sqlite3_malloc() and sqlite3_realloc()
  1217   1476   ** is always aligned to at least an 8 byte boundary. {END}
  1218   1477   **
  1219         -** {F17381} The default implementation
         1478  +** The default implementation
  1220   1479   ** of the memory allocation subsystem uses the malloc(), realloc()
  1221   1480   ** and free() provided by the standard C library. {F17382} However, if 
  1222   1481   ** SQLite is compiled with the following C preprocessor macro
  1223   1482   **
  1224   1483   ** <blockquote> SQLITE_MEMORY_SIZE=<i>NNN</i> </blockquote>
  1225   1484   **
  1226   1485   ** where <i>NNN</i> is an integer, then SQLite create a static
................................................................................
  1237   1496   ** The windows OS interface layer calls
  1238   1497   ** the system malloc() and free() directly when converting
  1239   1498   ** filenames between the UTF-8 encoding used by SQLite
  1240   1499   ** and whatever filename encoding is used by the particular windows
  1241   1500   ** installation.  Memory allocation errors are detected, but
  1242   1501   ** they are reported back as [SQLITE_CANTOPEN] or
  1243   1502   ** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
         1503  +**
         1504  +** INVARIANTS:
         1505  +**
         1506  +** {F17303}  The [sqlite3_malloc(N)] interface returns either a pointer to 
         1507  +**           newly checked-out block of at least N bytes of memory
         1508  +**           that is 8-byte aligned, 
         1509  +**           or it returns NULL if it is unable to fulfill the request.
         1510  +**
         1511  +** {F17304}  The [sqlite3_malloc(N)] interface returns a NULL pointer if
         1512  +**           N is less than or equal to zero.
         1513  +**
         1514  +** {F17305}  The [sqlite3_free(P)] interface releases memory previously
         1515  +**           returned from [sqlite3_malloc()] or [sqlite3_realloc()],
         1516  +**           making it available for reuse.
         1517  +**
         1518  +** {F17306}  A call to [sqlite3_free(NULL)] is a harmless no-op.
         1519  +**
         1520  +** {F17310}  A call to [sqlite3_realloc(0,N)] is equivalent to a call
         1521  +**           to [sqlite3_malloc(N)].
         1522  +**
         1523  +** {F17312}  A call to [sqlite3_realloc(P,0)] is equivalent to a call
         1524  +**           to [sqlite3_free(P)].
         1525  +**
         1526  +** {F17315}  The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()],
         1527  +**           and [sqlite3_free()] for all of its memory allocation and
         1528  +**           deallocation needs.
         1529  +**
         1530  +** {F17318}  The [sqlite3_realloc(P,N)] interface returns either a pointer
         1531  +**           to a block of checked-out memory of at least N bytes in size
         1532  +**           that is 8-byte aligned, or a NULL pointer.
         1533  +**
         1534  +** {F17321}  When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
         1535  +**           copies the first K bytes of content from P into the newly allocated
         1536  +**           where K is the lessor of N and the size of the buffer P.
         1537  +**
         1538  +** {F17322}  When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
         1539  +**           releases the buffer P.
         1540  +**
         1541  +** {F17323}  When [sqlite3_realloc(P,N)] returns NULL, the buffer P is
         1542  +**           not modified or released.
         1543  +**
         1544  +** LIMITATIONS:
         1545  +**
         1546  +** {U17350}  The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
         1547  +**           must be either NULL or else a pointer obtained from a prior
         1548  +**           invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that has
         1549  +**           not been released.
         1550  +**
         1551  +** {U17351}  The application must not read or write any part of 
         1552  +**           a block of memory after it has been released using
         1553  +**           [sqlite3_free()] or [sqlite3_realloc()].
         1554  +**
  1244   1555   */
  1245   1556   void *sqlite3_malloc(int);
  1246   1557   void *sqlite3_realloc(void*, int);
  1247   1558   void sqlite3_free(void*);
  1248   1559   
  1249   1560   /*
  1250   1561   ** CAPI3REF: Memory Allocator Statistics {F17370}
  1251   1562   **
  1252         -** In addition to the basic three allocation routines 
  1253         -** [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()],
  1254         -** the memory allocation subsystem included with the SQLite
  1255         -** sources provides the interfaces shown here.
  1256         -**
  1257         -** {F17371} The sqlite3_memory_used() routine returns the
  1258         -** number of bytes of memory currently outstanding (malloced but not freed).
  1259         -** {F17372} The value returned by sqlite3_memory_used() includes
  1260         -** any overhead added by SQLite, but not overhead added by the
  1261         -** library malloc() that backs the sqlite3_malloc() implementation.
  1262         -** {F17373} The sqlite3_memory_highwater() routines returns the
  1263         -** maximum number of bytes that have been outstanding at any time
  1264         -** since the highwater mark was last reset.
  1265         -** {F17374} The byte count returned by sqlite3_memory_highwater()
  1266         -** uses the same byte counting rules as sqlite3_memory_used(). {END}
  1267         -** In other words, overhead added internally by SQLite is counted,
  1268         -** but overhead from the underlying system malloc is not.
  1269         -** {F17375} If the parameter to sqlite3_memory_highwater() is true,
  1270         -** then the highwater mark is reset to the current value of
  1271         -** sqlite3_memory_used() and the prior highwater mark (before the
  1272         -** reset) is returned.  {F17376}  If the parameter to 
  1273         -** sqlite3_memory_highwater() is zero, then the highwater mark is
  1274         -** unchanged.
         1563  +** SQLite provides these two interfaces for reporting on the status
         1564  +** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
         1565  +** the memory allocation subsystem included within the SQLite.
         1566  +**
         1567  +** INVARIANTS:
         1568  +**
         1569  +** {F17371} The [sqlite3_memory_used()] routine returns the
         1570  +**          number of bytes of memory currently outstanding 
         1571  +**          (malloced but not freed).
         1572  +**
         1573  +** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum
         1574  +**          value of [sqlite3_memory_used()] 
         1575  +**          since the highwater mark was last reset.
         1576  +**
         1577  +** {F17374} The values returned by [sqlite3_memory_used()] and
         1578  +**          [sqlite3_memory_highwater()] include any overhead
         1579  +**          added by SQLite in its implementation of [sqlite3_malloc()],
         1580  +**          but not overhead added by the any underlying system library
         1581  +**          routines that [sqlite3_malloc()] may call.
         1582  +** 
         1583  +** {F17375} The memory highwater mark is reset to the current value of
         1584  +**          [sqlite3_memory_used()] if and only if the parameter to
         1585  +**          [sqlite3_memory_highwater()] is true.  The value returned
         1586  +**          by [sqlite3_memory_highwater(1)] is the highwater mark
         1587  +**          prior to the reset.
  1275   1588   */
  1276   1589   sqlite3_int64 sqlite3_memory_used(void);
  1277   1590   sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
  1278   1591   
  1279   1592   /*
  1280   1593   ** CAPI3REF: Compile-Time Authorization Callbacks {F12500}
  1281   1594   **
  1282         -** {F12501} This routine registers a authorizer callback with a particular
  1283         -** database connection, supplied in the first argument. {F12502}
         1595  +** This routine registers a authorizer callback with a particular
         1596  +** database connection, supplied in the first argument.
  1284   1597   ** The authorizer callback is invoked as SQL statements are being compiled
  1285   1598   ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
  1286         -** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  {F12503} At various
         1599  +** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  At various
  1287   1600   ** points during the compilation process, as logic is being created
  1288   1601   ** to perform various actions, the authorizer callback is invoked to
  1289   1602   ** see if those actions are allowed.  The authorizer callback should
  1290   1603   ** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the
  1291   1604   ** specific action but allow the SQL statement to continue to be
  1292   1605   ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
  1293         -** rejected with an error.  {F12504} If the authorizer callback returns
         1606  +** rejected with an error.   If the authorizer callback returns
  1294   1607   ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
  1295   1608   ** then [sqlite3_prepare_v2()] or equivalent call that triggered
  1296         -** the authorizer shall
  1297         -** fail with an SQLITE_ERROR error code and an appropriate error message. {END}
         1609  +** the authorizer will fail with an error message.
  1298   1610   **
  1299   1611   ** When the callback returns [SQLITE_OK], that means the operation
  1300         -** requested is ok.  {F12505} When the callback returns [SQLITE_DENY], the
         1612  +** requested is ok.  When the callback returns [SQLITE_DENY], the
  1301   1613   ** [sqlite3_prepare_v2()] or equivalent call that triggered the
  1302         -** authorizer shall fail
  1303         -** with an SQLITE_ERROR error code and an error message explaining that
  1304         -** access is denied. {F12506} If the authorizer code (the 2nd parameter
  1305         -** to the authorizer callback is anything other than [SQLITE_READ], then
  1306         -** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY]. 
  1307         -** If the authorizer code is [SQLITE_READ] and the callback returns
  1308         -** [SQLITE_IGNORE] then the prepared statement is constructed to
  1309         -** insert a NULL value in place of the table column that would have
  1310         -** been read if [SQLITE_OK] had been returned. {END}
         1614  +** authorizer will fail with an error message explaining that
         1615  +** access is denied.  If the authorizer code is [SQLITE_READ]
         1616  +** and the callback returns [SQLITE_IGNORE] then the prepared
         1617  +** statement is constructed to insert a NULL value in place of
         1618  +** the table column that would have
         1619  +** been read if [SQLITE_OK] had been returned.  The [SQLITE_IGNORE]
         1620  +** return can be used to deny an untrusted user access to individual
         1621  +** columns of a table.
  1311   1622   **
  1312         -** {F12510} The first parameter to the authorizer callback is a copy of
         1623  +** The first parameter to the authorizer callback is a copy of
  1313   1624   ** the third parameter to the sqlite3_set_authorizer() interface.
  1314         -** {F12511} The second parameter to the callback is an integer 
         1625  +** The second parameter to the callback is an integer 
  1315   1626   ** [SQLITE_COPY | action code] that specifies the particular action
  1316         -** to be authorized. {END} The available action codes are
  1317         -** [SQLITE_COPY | documented separately].  {F12512} The third through sixth
         1627  +** to be authorized. The third through sixth
  1318   1628   ** parameters to the callback are zero-terminated strings that contain 
  1319         -** additional details about the action to be authorized. {END}
         1629  +** additional details about the action to be authorized.
  1320   1630   **
  1321   1631   ** An authorizer is used when preparing SQL statements from an untrusted
  1322   1632   ** source, to ensure that the SQL statements do not try to access data
  1323   1633   ** that they are not allowed to see, or that they do not try to
  1324   1634   ** execute malicious statements that damage the database.  For
  1325   1635   ** example, an application may allow a user to enter arbitrary
  1326   1636   ** SQL queries for evaluation by a database.  But the application does
  1327   1637   ** not want the user to be able to make arbitrary changes to the
  1328   1638   ** database.  An authorizer could then be put in place while the
  1329   1639   ** user-entered SQL is being prepared that disallows everything
  1330   1640   ** except SELECT statements.  
  1331   1641   **
  1332         -** {F12520} Only a single authorizer can be in place on a database connection
         1642  +** Only a single authorizer can be in place on a database connection
  1333   1643   ** at a time.  Each call to sqlite3_set_authorizer overrides the
  1334         -** previous call. {F12521}  A NULL authorizer means that no authorization
  1335         -** callback is invoked.  {F12522} The default authorizer is NULL. {END}
         1644  +** previous call.  Disable the authorizer by installing a NULL callback.
         1645  +** The authorizer is disabled by default.
  1336   1646   **
  1337   1647   ** Note that the authorizer callback is invoked only during 
  1338         -** [sqlite3_prepare()] or its variants.  {F12523} Authorization is not
  1339         -** performed during statement evaluation in [sqlite3_step()]. {END}
         1648  +** [sqlite3_prepare()] or its variants.  Authorization is not
         1649  +** performed during statement evaluation in [sqlite3_step()].
         1650  +**
         1651  +** INVARIANTS:
         1652  +**
         1653  +** {F12501} The [sqlite3_set_authorizer(D,...)] interface registers a
         1654  +**          authorizer callback with database connection D.
         1655  +**
         1656  +** {F12502} The authorizer callback is invoked as SQL statements are
         1657  +**          being compiled
         1658  +**
         1659  +** {F12503} If the authorizer callback returns any value other than
         1660  +**          [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] then
         1661  +**          the [sqlite3_prepare_v2()] or equivalent call that caused
         1662  +**          the authorizer callback to run shall fail with an
         1663  +**          [SQLITE_ERROR] error code and an appropriate error message.
         1664  +**
         1665  +** {F12504} When the authorizer callback returns [SQLITE_OK], the operation
         1666  +**          described is coded normally.
         1667  +**
         1668  +** {F12505} When the authorizer callback returns [SQLITE_DENY], the
         1669  +**          [sqlite3_prepare_v2()] or equivalent call that caused the
         1670  +**          authorizer callback to run shall fail
         1671  +**          with an [SQLITE_ERROR] error code and an error message
         1672  +**          explaining that access is denied.
         1673  +**
         1674  +** {F12506} If the authorizer code (the 2nd parameter to the authorizer
         1675  +**          callback) is [SQLITE_READ] and the authorizer callback returns
         1676  +**          [SQLITE_IGNORE] then the prepared statement is constructed to
         1677  +**          insert a NULL value in place of the table column that would have
         1678  +**          been read if [SQLITE_OK] had been returned.
         1679  +**
         1680  +** {F12507} If the authorizer code (the 2nd parameter to the authorizer
         1681  +**          callback) is anything other than [SQLITE_READ], then
         1682  +**          a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY]. 
         1683  +**
         1684  +** {F12510} The first parameter to the authorizer callback is a copy of
         1685  +**          the third parameter to the [sqlite3_set_authorizer()] interface.
         1686  +**
         1687  +** {F12511} The second parameter to the callback is an integer 
         1688  +**          [SQLITE_COPY | action code] that specifies the particular action
         1689  +**          to be authorized.
         1690  +**
         1691  +** {F12512} The third through sixth parameters to the callback are
         1692  +**          zero-terminated strings that contain 
         1693  +**          additional details about the action to be authorized.
         1694  +**
         1695  +** {F12520} Each call to [sqlite3_set_authorizer()] overrides the
         1696  +**          any previously installed authorizer.
         1697  +**
         1698  +** {F12521} A NULL authorizer means that no authorization
         1699  +**          callback is invoked.
         1700  +**
         1701  +** {F12522} The default authorizer is NULL.
  1340   1702   */
  1341   1703   int sqlite3_set_authorizer(
  1342   1704     sqlite3*,
  1343   1705     int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
  1344   1706     void *pUserData
  1345   1707   );
  1346   1708   
................................................................................
  1356   1718   #define SQLITE_DENY   1   /* Abort the SQL statement with an error */
  1357   1719   #define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
  1358   1720   
  1359   1721   /*
  1360   1722   ** CAPI3REF: Authorizer Action Codes {F12550}
  1361   1723   **
  1362   1724   ** The [sqlite3_set_authorizer()] interface registers a callback function
  1363         -** that is invoked to authorizer certain SQL statement actions.  {F12551} The
         1725  +** that is invoked to authorizer certain SQL statement actions.  The
  1364   1726   ** second parameter to the callback is an integer code that specifies
  1365   1727   ** what action is being authorized.  These are the integer action codes that
  1366         -** the authorizer callback may be passed. {END}
         1728  +** the authorizer callback may be passed.
  1367   1729   **
  1368   1730   ** These action code values signify what kind of operation is to be 
  1369         -** authorized.  {F12552} The 3rd and 4th parameters to the authorization
         1731  +** authorized.  The 3rd and 4th parameters to the authorization
  1370   1732   ** callback function will be parameters or NULL depending on which of these
  1371         -** codes is used as the second parameter. {F12553} The 5th parameter to the
         1733  +** codes is used as the second parameter.  The 5th parameter to the
  1372   1734   ** authorizer callback is the name of the database ("main", "temp", 
  1373         -** etc.) if applicable. {F12554} The 6th parameter to the authorizer callback
         1735  +** etc.) if applicable.  The 6th parameter to the authorizer callback
  1374   1736   ** is the name of the inner-most trigger or view that is responsible for
  1375   1737   ** the access attempt or NULL if this access attempt is directly from 
  1376   1738   ** top-level SQL code.
         1739  +**
         1740  +** INVARIANTS:
         1741  +**
         1742  +** {F12551} The second parameter to an 
         1743  +**          [sqlite3_set_authorizer | authorizer callback is always an integer
         1744  +**          [SQLITE_COPY | authorizer code] that specifies what action
         1745  +**          is being authorized.
         1746  +**
         1747  +** {F12552} The 3rd and 4th parameters to the 
         1748  +**          [sqlite3_set_authorizer | authorization callback function]
         1749  +**          will be parameters or NULL depending on which 
         1750  +**          [SQLITE_COPY | authorizer code] is used as the second parameter.
         1751  +**
         1752  +** {F12553} The 5th parameter to the
         1753  +**          [sqlite3_set_authorizer | authorizer callback] is the name
         1754  +**          of the database (example: "main", "temp", etc.) if applicable.
         1755  +**
         1756  +** {F12554} The 6th parameter to the
         1757  +**          [sqlite3_set_authorizer | authorizer callback] is the name
         1758  +**          of the inner-most trigger or view that is responsible for
         1759  +**          the access attempt or NULL if this access attempt is directly from 
         1760  +**          top-level SQL code.
  1377   1761   */
  1378   1762   /******************************************* 3rd ************ 4th ***********/
  1379   1763   #define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
  1380   1764   #define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
  1381   1765   #define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
  1382   1766   #define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
  1383   1767   #define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
................................................................................
  1411   1795   
  1412   1796   /*
  1413   1797   ** CAPI3REF: Tracing And Profiling Functions {F12280}
  1414   1798   **
  1415   1799   ** These routines register callback functions that can be used for
  1416   1800   ** tracing and profiling the execution of SQL statements.
  1417   1801   **
  1418         -** {F12281} The callback function registered by sqlite3_trace() is invoked
  1419         -** at the first [sqlite3_step()] for the evaluation of an SQL statement.
  1420         -** {F12282} Only a single trace callback can be registered at a time.
  1421         -** Each call to sqlite3_trace() overrides the previous.  {F12283} A
  1422         -** NULL callback for sqlite3_trace() disables tracing.  {F12284} The
  1423         -** first argument to the trace callback is a copy of the pointer which
  1424         -** was the 3rd argument to sqlite3_trace.  {F12285} The second argument
  1425         -** to the trace callback is a zero-terminated UTF8 string containing
  1426         -** the original text of the SQL statement as it was passed into
  1427         -** [sqlite3_prepare_v2()] or the equivalent. {END}  Note that the
  1428         -** host parameter are not expanded in the SQL statement text.
  1429         -**
  1430         -** {F12287} The callback function registered by sqlite3_profile() is invoked
  1431         -** as each SQL statement finishes.  {F12288} The first parameter to the
  1432         -** profile callback is a copy of the 3rd parameter to sqlite3_profile().
  1433         -** {F12289} The second parameter to the profile callback is a
  1434         -** zero-terminated UTF-8 string that contains the complete text of
  1435         -** the SQL statement as it was processed by [sqlite3_prepare_v2()] or
  1436         -** the equivalent.  {F12290} The third parameter to the profile 
  1437         -** callback is an estimate of the number of nanoseconds of
  1438         -** wall-clock time required to run the SQL statement from start
  1439         -** to finish. {END}  
         1802  +** The callback function registered by sqlite3_trace() is invoked at
         1803  +** various times when an SQL statement is being run by [sqlite3_step()].
         1804  +** The callback returns a UTF-8 rendering of the SQL statement text
         1805  +** as the statement first begins executing.  Additional callbacks occur
         1806  +** as each triggersubprogram is entered.  The callbacks for triggers
         1807  +** contain a UTF-8 SQL comment that identifies the trigger.
         1808  +** 
         1809  +** The callback function registered by sqlite3_profile() is invoked
         1810  +** as each SQL statement finishes.  The profile callback contains
         1811  +** the original statement text and an estimate of wall-clock time
         1812  +** of how long that statement took to run.
  1440   1813   **
  1441   1814   ** The sqlite3_profile() API is currently considered experimental and
  1442         -** is subject to change.
         1815  +** is subject to change or removal in a future release.
         1816  +**
         1817  +** The trigger reporting feature of the trace callback is considered
         1818  +** experimental and is subject to change or removal in future releases.
         1819  +** Future versions of SQLite might also add new trace callback 
         1820  +** invocations.
         1821  +**
         1822  +** INVARIANTS:
         1823  +**
         1824  +** {F12281} The callback function registered by [sqlite3_trace()] is
         1825  +**          whenever an SQL statement first begins to execute and
         1826  +**          whenever a trigger subprogram first begins to run.
         1827  +**
         1828  +** {F12282} Each call to [sqlite3_trace()] overrides the previously
         1829  +**          registered trace callback.
         1830  +**
         1831  +** {F12283} A NULL trace callback disables tracing.
         1832  +**
         1833  +** {F12284} The first argument to the trace callback is a copy of
         1834  +**          the pointer which was the 3rd argument to [sqlite3_trace()].
         1835  +**
         1836  +** {F12285} The second argument to the trace callback is a
         1837  +**          zero-terminated UTF8 string containing the original text
         1838  +**          of the SQL statement as it was passed into [sqlite3_prepare_v2()]
         1839  +**          or the equivalent, or an SQL comment indicating the beginning
         1840  +**          of a trigger subprogram.
         1841  +**
         1842  +** {F12287} The callback function registered by [sqlite3_profile()] is invoked
         1843  +**          as each SQL statement finishes.
         1844  +**
         1845  +** {F12288} The first parameter to the profile callback is a copy of
         1846  +**          the 3rd parameter to [sqlite3_profile()].
         1847  +**
         1848  +** {F12289} The second parameter to the profile callback is a
         1849  +**          zero-terminated UTF-8 string that contains the complete text of
         1850  +**          the SQL statement as it was processed by [sqlite3_prepare_v2()]
         1851  +**          or the equivalent.
         1852  +**
         1853  +** {F12290} The third parameter to the profile  callback is an estimate
         1854  +**          of the number of nanoseconds of wall-clock time required to
         1855  +**          run the SQL statement from start to finish.
  1443   1856   */
  1444   1857   void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
  1445   1858   void *sqlite3_profile(sqlite3*,
  1446   1859      void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
  1447   1860   
  1448   1861   /*
  1449   1862   ** CAPI3REF: Query Progress Callbacks {F12910}
  1450   1863   **
  1451         -** {F12911} This routine configures a callback function - the
         1864  +** This routine configures a callback function - the
  1452   1865   ** progress callback - that is invoked periodically during long
  1453   1866   ** running calls to [sqlite3_exec()], [sqlite3_step()] and
  1454         -** [sqlite3_get_table()]. {END}  An example use for this 
         1867  +** [sqlite3_get_table()].   An example use for this 
  1455   1868   ** interface is to keep a GUI updated during a large query.
         1869  +**
         1870  +** If the progress callback returns non-zero, the opertion is
         1871  +** interrupted.  This feature can be used to implement a
         1872  +** "Cancel" button on a GUI dialog box.
         1873  +**
         1874  +** INVARIANTS:
         1875  +**
         1876  +** {F12911} The callback function registered by [sqlite3_progress_handler()]
         1877  +**          is invoked periodically during long running calls to
         1878  +**          [sqlite3_step()].
  1456   1879   **
  1457   1880   ** {F12912} The progress callback is invoked once for every N virtual
  1458         -** machine opcodes, where N is the second argument to this function.
         1881  +**          machine opcodes, where N is the second argument to 
         1882  +**          the [sqlite3_progress_handler()] call that registered
         1883  +**          the callback.  <todo>What if N is less than 1?</todo>
         1884  +**
  1459   1885   ** {F12913} The progress callback itself is identified by the third
  1460         -** argument to this function. {F12914} The fourth argument to this
  1461         -** function is a void pointer passed to the progress callback
  1462         -** function each time it is invoked. {END}
         1886  +**          argument to [sqlite3_progress_handler()].
  1463   1887   **
  1464         -** {F12915} If a call to [sqlite3_exec()], [sqlite3_step()], or
  1465         -** [sqlite3_get_table()] results in fewer than N opcodes being executed,
  1466         -** then the progress callback is never invoked. {END}
         1888  +** {F12914} The fourth argument [sqlite3_progress_handler()] is a
         1889  +***         void pointer passed to the progress callback
         1890  +**          function each time it is invoked.
         1891  +**
         1892  +** {F12915} If a call to [sqlite3_step()] results in fewer than
         1893  +**          N opcodes being executed,
         1894  +**          then the progress callback is never invoked. {END}
  1467   1895   ** 
  1468         -** {F12916} Only a single progress callback function may be registered for each
  1469         -** open database connection.  Every call to sqlite3_progress_handler()
  1470         -** overwrites the results of the previous call. {F12917}
  1471         -** To remove the progress callback altogether, pass NULL as the third
  1472         -** argument to this function. {END}
         1896  +** {F12916} Every call to [sqlite3_progress_handler()]
         1897  +**          overwrites any previously registere progress handler.
         1898  +**
         1899  +** {F12917} If the progress handler callback is NULL then no progress
         1900  +**          handler is invoked.
  1473   1901   **
  1474   1902   ** {F12918} If the progress callback returns a result other than 0, then
  1475         -** the current query is immediately terminated and any database changes
  1476         -** rolled back. {F12919}
  1477         -** The containing [sqlite3_exec()], [sqlite3_step()], or
  1478         -** [sqlite3_get_table()] call returns SQLITE_INTERRUPT. {END}  This feature
  1479         -** can be used, for example, to implement the "Cancel" button on a
  1480         -** progress dialog box in a GUI.
         1903  +**          the behavior is a if [sqlite3_interrupt()] had been called.
  1481   1904   */
  1482   1905   void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
  1483   1906   
  1484   1907   /*
  1485   1908   ** CAPI3REF: Opening A New Database Connection {F12700}
  1486   1909   **
  1487         -** {F12701} These routines open an SQLite database file whose name
         1910  +** These routines open an SQLite database file whose name
  1488   1911   ** is given by the filename argument.
  1489         -** {F12702} The filename argument is interpreted as UTF-8
         1912  +** The filename argument is interpreted as UTF-8
  1490   1913   ** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16
  1491   1914   ** in the native byte order for [sqlite3_open16()].
  1492         -** {F12703} An [sqlite3*] handle is returned in *ppDb, even
  1493         -** if an error occurs.  {F12723} (Exception: if SQLite is unable
         1915  +** An [sqlite3*] handle is usually returned in *ppDb, even
         1916  +** if an error occurs.  The only exception is if SQLite is unable
  1494   1917   ** to allocate memory to hold the [sqlite3] object, a NULL will
  1495         -** be written into *ppDb instead of a pointer to the [sqlite3] object.)
  1496         -** {F12704} If the database is opened (and/or created)
  1497         -** successfully, then [SQLITE_OK] is returned.  {F12705} Otherwise an
  1498         -** error code is returned.  {F12706} The
         1918  +** be written into *ppDb instead of a pointer to the [sqlite3] object.
         1919  +** If the database is opened (and/or created)
         1920  +** successfully, then [SQLITE_OK] is returned.  Otherwise an
         1921  +** error code is returned.  The
  1499   1922   ** [sqlite3_errmsg()] or [sqlite3_errmsg16()]  routines can be used to obtain
  1500   1923   ** an English language description of the error.
  1501   1924   **
  1502         -** {F12707} The default encoding for the database will be UTF-8 if
         1925  +** The default encoding for the database will be UTF-8 if
  1503   1926   ** [sqlite3_open()] or [sqlite3_open_v2()] is called and
  1504   1927   ** UTF-16 in the native byte order if [sqlite3_open16()] is used.
  1505   1928   **
  1506         -** {F12708} Whether or not an error occurs when it is opened, resources
         1929  +** Whether or not an error occurs when it is opened, resources
  1507   1930   ** associated with the [sqlite3*] handle should be released by passing it
  1508   1931   ** to [sqlite3_close()] when it is no longer required.
  1509   1932   **
  1510         -** {F12709} The [sqlite3_open_v2()] interface works like [sqlite3_open()] 
         1933  +** The [sqlite3_open_v2()] interface works like [sqlite3_open()] 
  1511   1934   ** except that it acccepts two additional parameters for additional control
  1512         -** over the new database connection.  {F12710} The flags parameter can be
         1935  +** over the new database connection.  The flags parameter can be
  1513   1936   ** one of:
  1514   1937   **
  1515   1938   ** <ol>
  1516   1939   ** <li>  [SQLITE_OPEN_READONLY]
  1517   1940   ** <li>  [SQLITE_OPEN_READWRITE]
  1518   1941   ** <li>  [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]
  1519   1942   ** </ol>
  1520   1943   **
  1521         -** {F12711} The first value opens the database read-only. 
  1522         -** {F12712} If the database does not previously exist, an error is returned.
  1523         -** {F12713} The second option opens
         1944  +** The first value opens the database read-only. 
         1945  +** If the database does not previously exist, an error is returned.
         1946  +** The second option opens
  1524   1947   ** the database for reading and writing if possible, or reading only if
  1525         -** if the file is write protected.  {F12714} In either case the database
  1526         -** must already exist or an error is returned.  {F12715} The third option
         1948  +** if the file is write protected.  In either case the database
         1949  +** must already exist or an error is returned.  The third option
  1527   1950   ** opens the database for reading and writing and creates it if it does
  1528         -** not already exist. {F12716}
         1951  +** not already exist.
  1529   1952   ** The third options is behavior that is always used for [sqlite3_open()]
  1530   1953   ** and [sqlite3_open16()].
  1531   1954   **
  1532         -** {F12717} If the filename is ":memory:", then an private
  1533         -** in-memory database is created for the connection. {F12718} This in-memory
  1534         -** database will vanish when the database connection is closed. {END}  Future
         1955  +** If the filename is ":memory:", then an private
         1956  +** in-memory database is created for the connection.  This in-memory
         1957  +** database will vanish when the database connection is closed.  Future
  1535   1958   ** version of SQLite might make use of additional special filenames
  1536   1959   ** that begin with the ":" character.  It is recommended that 
  1537   1960   ** when a database filename really does begin with
  1538   1961   ** ":" that you prefix the filename with a pathname like "./" to
  1539   1962   ** avoid ambiguity.
  1540   1963   **
  1541         -** {F12719} If the filename is an empty string, then a private temporary
  1542         -** on-disk database will be created.  {F12720} This private database will be
         1964  +** If the filename is an empty string, then a private temporary
         1965  +** on-disk database will be created.  This private database will be
  1543   1966   ** automatically deleted as soon as the database connection is closed.
  1544   1967   **
  1545         -** {F12721} The fourth parameter to sqlite3_open_v2() is the name of the
         1968  +** The fourth parameter to sqlite3_open_v2() is the name of the
  1546   1969   ** [sqlite3_vfs] object that defines the operating system 
  1547         -** interface that the new database connection should use.  {F12722} If the
         1970  +** interface that the new database connection should use.  If the
  1548   1971   ** fourth parameter is a NULL pointer then the default [sqlite3_vfs]
  1549         -** object is used. {END}
         1972  +** object is used.
  1550   1973   **
  1551   1974   ** <b>Note to windows users:</b>  The encoding used for the filename argument
  1552   1975   ** of [sqlite3_open()] and [sqlite3_open_v2()] must be UTF-8, not whatever
  1553   1976   ** codepage is currently defined.  Filenames containing international
  1554   1977   ** characters must be converted to UTF-8 prior to passing them into
  1555   1978   ** [sqlite3_open()] or [sqlite3_open_v2()].
         1979  +**
         1980  +** INVARIANTS:
         1981  +**
         1982  +** {F12701} The [sqlite3_open()], [sqlite3_open16()], and
         1983  +**          [sqlite3_open_v2()] interfaces create a new
         1984  +**          [database connection] associated with
         1985  +**          the database file given in their first parameter.
         1986  +**
         1987  +** {F12702} The filename argument is interpreted as UTF-8
         1988  +**          for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16
         1989  +**          in the native byte order for [sqlite3_open16()].
         1990  +**
         1991  +** {F12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()], 
         1992  +**          or [sqlite3_open_v2()] writes a pointer to a new
         1993  +**          [database connection] into *ppDb.
         1994  +**
         1995  +** {F12704} The [sqlite3_open()], [sqlite3_open16()], and
         1996  +**          [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success,
         1997  +**          or an appropriate [error code] on failure.
         1998  +**
         1999  +** {F12706} The default text encoding for a new database created using
         2000  +**          [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8.
         2001  +**
         2002  +** {F12707} The default text encoding for a new database created using
         2003  +**          [sqlite3_open16()] will be UTF-16.
         2004  +**
         2005  +** {F12709} The [sqlite3_open(F,D)] interface is equivalent to
         2006  +**          [sqlite3_open_v2(F,D,G,0)] where the G parameter is
         2007  +**          [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE].
         2008  +**
         2009  +** {F12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
         2010  +**          bit value [SQLITE_OPEN_READONLY] then the database is opened
         2011  +**          for reading only.
         2012  +**
         2013  +** {F12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
         2014  +**          bit value [SQLITE_OPEN_READWRITE] then the database is opened
         2015  +**          reading and writing if possible, or for reading only if the
         2016  +**          file is write protected by the operating system.
         2017  +**
         2018  +** {F12713} If the G parameter to [sqlite3_open(v2(F,D,G,V)] omits the
         2019  +**          bit value [SQLITE_OPEN_CREATE] and the database does not
         2020  +**          previously exist, an error is returned.
         2021  +**
         2022  +** {F12714} If the G parameter to [sqlite3_open(v2(F,D,G,V)] contains the
         2023  +**          bit value [SQLITE_OPEN_CREATE] and the database does not
         2024  +**          previously exist, then an attempt is made to create and
         2025  +**          initialize the database.
         2026  +**
         2027  +** {F12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()],
         2028  +**          or [sqlite3_open_v2()] is ":memory:", then an private,
         2029  +**          ephemeral, in-memory database is created for the connection.
         2030  +**          <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
         2031  +**          in sqlite3_open_v2()?</todo>
         2032  +**
         2033  +** {F12719} If the filename is an empty string, then a private, ephermeral
         2034  +**          on-disk database will be created.
         2035  +**          <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
         2036  +**          in sqlite3_open_v2()?</todo>
         2037  +**
         2038  +** {F12721} The [database connection] created by 
         2039  +**          [sqlite3_open_v2(F,D,G,V)] will use the
         2040  +**          [sqlite3_vfs] object identified by the V parameter, or
         2041  +**          the default [sqlite3_vfs] object is V is a NULL pointer.
  1556   2042   */
  1557   2043   int sqlite3_open(
  1558   2044     const char *filename,   /* Database filename (UTF-8) */
  1559   2045     sqlite3 **ppDb          /* OUT: SQLite db handle */
  1560   2046   );
  1561   2047   int sqlite3_open16(
  1562   2048     const void *filename,   /* Database filename (UTF-16) */
................................................................................
  1568   2054     int flags,              /* Flags */
  1569   2055     const char *zVfs        /* Name of VFS module to use */
  1570   2056   );
  1571   2057   
  1572   2058   /*
  1573   2059   ** CAPI3REF: Error Codes And Messages {F12800}
  1574   2060   **
  1575         -** {F12801} The sqlite3_errcode() interface returns the numeric
         2061  +** The sqlite3_errcode() interface returns the numeric
  1576   2062   ** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code]
  1577   2063   ** for the most recent failed sqlite3_* API call associated
  1578         -** with [sqlite3] handle 'db'. {U12802} If a prior API call failed but the
         2064  +** with [sqlite3] handle 'db'. If a prior API call failed but the
  1579   2065   ** most recent API call succeeded, the return value from sqlite3_errcode()
  1580         -** is undefined. {END}
         2066  +** is undefined.
  1581   2067   **
  1582         -** {F12803} The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
         2068  +** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
  1583   2069   ** text that describes the error, as either UTF8 or UTF16 respectively.
  1584         -** {F12804} Memory to hold the error message string is managed internally.
  1585         -** {U12805} The 
  1586         -** string may be overwritten or deallocated by subsequent calls to SQLite
  1587         -** interface functions. {END}
  1588         -**
  1589         -** {F12806} Calls to many sqlite3_* functions set the error code and
  1590         -** string returned by [sqlite3_errcode()], [sqlite3_errmsg()], and
  1591         -** [sqlite3_errmsg16()] overwriting the previous values.  {F12807}
  1592         -** Except, calls to [sqlite3_errcode()],
  1593         -** [sqlite3_errmsg()], and [sqlite3_errmsg16()] themselves do not affect the
  1594         -** results of future invocations.  {F12808} Calls to API routines that
  1595         -** do not return an error code (example: [sqlite3_data_count()]) do not
  1596         -** change the error code returned by this routine.  {F12809} Interfaces that
  1597         -** are not associated with a specific database connection (examples:
  1598         -** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()] do not change
  1599         -** the return code. {END}
  1600         -**
  1601         -** {F12810} Assuming no other intervening sqlite3_* API calls are made,
  1602         -** the error code returned by this function is associated with the same
  1603         -** error as the strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()].
         2070  +** Memory to hold the error message string is managed internally.
         2071  +** The application does not need to worry with freeing the result.
         2072  +** However, the error string might be overwritten or deallocated b
         2073  +** subsequent calls to other SQLite interface functions.
         2074  +**
         2075  +** INVARIANTS:
         2076  +**
         2077  +** {F12801} The [sqlite3_errcode(D)] interface returns the numeric
         2078  +**          [SQLITE_OK | result code] or
         2079  +**          [SQLITE_IOERR_READ | extended result code]
         2080  +**          for the most recent failed interface call associated
         2081  +**          with [sqlite3] handle D.
         2082  +**
         2083  +** {U12802} If a prior API call failed but the most recent API call
         2084  +**          succeeded, the return value from [sqlite3_errcode()],
         2085  +**          [sqlite3_errmsg()], and [sqlite3_errmsg16()] are undefined.
         2086  +**
         2087  +** {F12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)]
         2088  +**          interfaces return English-language text that describes
         2089  +**          the error in the mostly recently failed interface call,
         2090  +**          encoded as either UTF8 or UTF16 respectively.
         2091  +**
         2092  +** {U12804} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]
         2093  +**          are only valid until the next SQLite interface call.
         2094  +**
         2095  +** {F12807} Calls to [sqlite3_errcode()], [sqlite3_errmsg()], and
         2096  +**          [sqlite3_errmsg16()] themselves do not affect the
         2097  +**          results of future invocations of these routines.
         2098  +**
         2099  +** {F12808} Calls to API routines that do not return an error code
         2100  +**          (example: [sqlite3_data_count()]) do not
         2101  +**          change the error code or message returned by
         2102  +**          [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
         2103  +**
         2104  +** {F12809} Interfaces that are not associated with a specific
         2105  +**          [database connection] (examples:
         2106  +**          [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()]
         2107  +**          do not change the values returned by
         2108  +**          [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
  1604   2109   */
  1605   2110   int sqlite3_errcode(sqlite3 *db);
  1606   2111   const char *sqlite3_errmsg(sqlite3*);
  1607   2112   const void *sqlite3_errmsg16(sqlite3*);
  1608   2113   
  1609   2114   /*
  1610   2115   ** CAPI3REF: SQL Statement Object {F13000}
         2116  +** KEYWORDS: {prepared statement} {prepared statements}
  1611   2117   **
  1612   2118   ** An instance of this object represent single SQL statements.  This
  1613   2119   ** object is variously known as a "prepared statement" or a 
  1614   2120   ** "compiled SQL statement" or simply as a "statement".
  1615   2121   ** 
  1616   2122   ** The life of a statement object goes something like this:
  1617   2123   **
................................................................................
  1633   2139   
  1634   2140   /*
  1635   2141   ** CAPI3REF: Compiling An SQL Statement {F13010}
  1636   2142   **
  1637   2143   ** To execute an SQL query, it must first be compiled into a byte-code
  1638   2144   ** program using one of these routines. 
  1639   2145   **
  1640         -** {F13011} The first argument "db" is an [sqlite3 | SQLite database handle] 
         2146  +** The first argument "db" is an [database connection] 
  1641   2147   ** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()]
  1642         -** or [sqlite3_open16()]. {F13012}
         2148  +** or [sqlite3_open16()]. 
  1643   2149   ** The second argument "zSql" is the statement to be compiled, encoded
  1644   2150   ** as either UTF-8 or UTF-16.  The sqlite3_prepare() and sqlite3_prepare_v2()
  1645   2151   ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2()
  1646   2152   ** use UTF-16. {END}
  1647   2153   **
  1648         -** {F13013} If the nByte argument is less
         2154  +** If the nByte argument is less
  1649   2155   ** than zero, then zSql is read up to the first zero terminator.
  1650         -** {F13014} If nByte is non-negative, then it is the maximum number of 
         2156  +** If nByte is non-negative, then it is the maximum number of 
  1651   2157   ** bytes read from zSql.  When nByte is non-negative, the
  1652   2158   ** zSql string ends at either the first '\000' or '\u0000' character or 
  1653   2159   ** until the nByte-th byte, whichever comes first. {END}
  1654   2160   **
  1655         -** {F13015} *pzTail is made to point to the first byte past the end of the
         2161  +** *pzTail is made to point to the first byte past the end of the
  1656   2162   ** first SQL statement in zSql.  These routines only compiles the first
  1657   2163   ** statement in zSql, so *pzTail is left pointing to what remains
  1658         -** uncompiled. {END}
         2164  +** uncompiled.
  1659   2165   **
  1660         -** {F13016} *ppStmt is left pointing to a compiled 
  1661         -** [sqlite3_stmt | SQL statement structure] that can be
         2166  +** *ppStmt is left pointing to a compiled [prepared statement] that can be
  1662   2167   ** executed using [sqlite3_step()].  Or if there is an error, *ppStmt may be
  1663         -** set to NULL.  {F13017} If the input text contains no SQL (if the input
         2168  +** set to NULL.  If the input text contains no SQL (if the input
  1664   2169   ** is and empty string or a comment) then *ppStmt is set to NULL.
  1665   2170   ** {U13018} The calling procedure is responsible for deleting the
  1666   2171   ** compiled SQL statement
  1667   2172   ** using [sqlite3_finalize()] after it has finished with it.
  1668   2173   **
  1669         -** {F13019} On success, [SQLITE_OK] is returned.  Otherwise an 
  1670         -** [SQLITE_ERROR | error code] is returned. {END}
         2174  +** On success, [SQLITE_OK] is returned.  Otherwise an 
         2175  +** [error code] is returned.
  1671   2176   **
  1672   2177   ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
  1673   2178   ** recommended for all new programs. The two older interfaces are retained
  1674   2179   ** for backwards compatibility, but their use is discouraged.
  1675         -** {F13020} In the "v2" interfaces, the prepared statement
         2180  +** In the "v2" interfaces, the prepared statement
  1676   2181   ** that is returned (the [sqlite3_stmt] object) contains a copy of the 
  1677   2182   ** original SQL text. {END} This causes the [sqlite3_step()] interface to
  1678   2183   ** behave a differently in two ways:
  1679   2184   **
  1680   2185   ** <ol>
  1681         -** <li>{F13022}
         2186  +** <li>
  1682   2187   ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
  1683   2188   ** always used to do, [sqlite3_step()] will automatically recompile the SQL
  1684         -** statement and try to run it again. {F12023} If the schema has changed in
         2189  +** statement and try to run it again.  If the schema has changed in
  1685   2190   ** a way that makes the statement no longer valid, [sqlite3_step()] will still
  1686         -** return [SQLITE_SCHEMA].  {END} But unlike the legacy behavior, 
  1687         -** [SQLITE_SCHEMA] is now a fatal error.  {F12024} Calling
         2191  +** return [SQLITE_SCHEMA].  But unlike the legacy behavior, 
         2192  +** [SQLITE_SCHEMA] is now a fatal error.  Calling
  1688   2193   ** [sqlite3_prepare_v2()] again will not make the
  1689         -** error go away.  {F12025} Note: use [sqlite3_errmsg()] to find the text
         2194  +** error go away.  Note: use [sqlite3_errmsg()] to find the text
  1690   2195   ** of the parsing error that results in an [SQLITE_SCHEMA] return. {END}
  1691   2196   ** </li>
  1692   2197   **
  1693   2198   ** <li>
  1694         -** {F13030} When an error occurs, 
         2199  +** When an error occurs, 
  1695   2200   ** [sqlite3_step()] will return one of the detailed 
  1696         -** [SQLITE_ERROR | result codes] or
  1697         -** [SQLITE_IOERR_READ | extended result codes].  {F13031}
         2201  +** [error codes] or [extended error codes]. 
  1698   2202   ** The legacy behavior was that [sqlite3_step()] would only return a generic
  1699   2203   ** [SQLITE_ERROR] result code and you would have to make a second call to
  1700   2204   ** [sqlite3_reset()] in order to find the underlying cause of the problem.
  1701         -** {F13032}
  1702   2205   ** With the "v2" prepare interfaces, the underlying reason for the error is
  1703         -** returned immediately. {END}
         2206  +** returned immediately.
  1704   2207   ** </li>
  1705   2208   ** </ol>
         2209  +**
         2210  +** INVARIANTS:
         2211  +**
         2212  +** {F13011} The [sqlite3_prepare(db,zSql,...)] and
         2213  +**          [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the
         2214  +**          text in their zSql parameter as UTF-8.
         2215  +**
         2216  +** {F13012} The [sqlite3_prepare16(db,zSql,...)] and
         2217  +**          [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the
         2218  +**          text in their zSql parameter as UTF-16 in the native byte order.
         2219  +**
         2220  +** {F13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
         2221  +**          and its variants is less than zero, then SQL text is
         2222  +**          read from zSql is read up to the first zero terminator.
         2223  +**
         2224  +** {F13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
         2225  +**          and its variants is non-negative, then nBytes bytes
         2226  +**          SQL text is read from zSql.
         2227  +**
         2228  +** {F13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants
         2229  +**          if the zSql input text contains more than one SQL statement
         2230  +**          and pzTail is not NULL, then *pzTail is made to point to the
         2231  +**          first byte past the end of the first SQL statement in zSql.
         2232  +**          <todo>What does *pzTail point to if there is one statement?</todo>
         2233  +**
         2234  +** {F13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)]
         2235  +**          or one of its variants writes into *ppStmt a pointer to a new
         2236  +**          [prepared statement] or a pointer to NULL
         2237  +**          if zSql contains nothing other than whitespace or comments. 
         2238  +**
         2239  +** {F13019} The [sqlite3_prepare_v2()] interface and its variants return
         2240  +**          [SQLITE_OK] or an appropriate [error code] upon failure.
  1706   2241   */
  1707   2242   int sqlite3_prepare(
  1708   2243     sqlite3 *db,            /* Database handle */
  1709   2244     const char *zSql,       /* SQL statement, UTF-8 encoded */
  1710   2245     int nByte,              /* Maximum length of zSql in bytes. */
  1711   2246     sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  1712   2247     const char **pzTail     /* OUT: Pointer to unused portion of zSql */
................................................................................
  1732   2267     sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  1733   2268     const void **pzTail     /* OUT: Pointer to unused portion of zSql */
  1734   2269   );
  1735   2270   
  1736   2271   /*
  1737   2272   ** CAPIREF: Retrieving Statement SQL {F13100}
  1738   2273   **
  1739         -** {F13101} If the compiled SQL statement passed as an argument was
  1740         -** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()],
  1741         -** then this function returns a pointer to a zero-terminated string
  1742         -** containing a copy of the original SQL statement. {F13102} The
  1743         -** pointer is valid until the statement
  1744         -** is deleted using sqlite3_finalize().
  1745         -** {F13103} The string returned by sqlite3_sql() is always UTF8 even
  1746         -** if a UTF16 string was originally entered using [sqlite3_prepare16_v2()]
  1747         -** or the equivalent.
         2274  +** This intereface can be used to retrieve a saved copy of the original
         2275  +** SQL text used to create a [prepared statement].
  1748   2276   **
  1749         -** {F13104} If the statement was compiled using either of the legacy
  1750         -** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this
  1751         -** function returns NULL.
         2277  +** INVARIANTS:
         2278  +**
         2279  +** {F13101} If the [prepared statement] passed as 
         2280  +**          the an argument to [sqlite3_sql()] was compiled
         2281  +**          compiled using either [sqlite3_prepare_v2()] or
         2282  +**          [sqlite3_prepare16_v2()],
         2283  +**          then [sqlite3_sql()] function returns a pointer to a
         2284  +**          zero-terminated string containing a UTF-8 rendering
         2285  +**          of the original SQL statement.
         2286  +**
         2287  +** {F13102} If the [prepared statement] passed as 
         2288  +**          the an argument to [sqlite3_sql()] was compiled
         2289  +**          compiled using either [sqlite3_prepare()] or
         2290  +**          [sqlite3_prepare16()],
         2291  +**          then [sqlite3_sql()] function returns a NULL pointer.
         2292  +**
         2293  +** {F13103} The string returned by [sqlite3_sql(S)] is valid until the
         2294  +**          [prepared statement] S is deleted using [sqlite3_finalize(S)].
  1752   2295   */
  1753   2296   const char *sqlite3_sql(sqlite3_stmt *pStmt);
  1754   2297   
  1755   2298   /*
  1756   2299   ** CAPI3REF:  Dynamically Typed Value Object  {F15000}
  1757   2300   **
  1758         -** {F15001} SQLite uses the sqlite3_value object to represent all values
  1759         -** that are or can be stored in a database table. {END}
         2301  +** SQLite uses the sqlite3_value object to represent all values
         2302  +** that are or can be stored in a database table.
  1760   2303   ** SQLite uses dynamic typing for the values it stores.  
  1761         -** {F15002} Values stored in sqlite3_value objects can be
         2304  +** Values stored in sqlite3_value objects can be
  1762   2305   ** be integers, floating point values, strings, BLOBs, or NULL.
  1763   2306   */
  1764   2307   typedef struct Mem sqlite3_value;
  1765   2308   
  1766   2309   /*
  1767   2310   ** CAPI3REF:  SQL Function Context Object {F16001}
  1768   2311   **
  1769   2312   ** The context in which an SQL function executes is stored in an
  1770         -** sqlite3_context object.  {F16002} A pointer to an sqlite3_context
         2313  +** sqlite3_context object.  A pointer to an sqlite3_context
  1771   2314   ** object is always first parameter to application-defined SQL functions.
  1772   2315   */
  1773   2316   typedef struct sqlite3_context sqlite3_context;
  1774   2317   
  1775   2318   /*
  1776   2319   ** CAPI3REF:  Binding Values To Prepared Statements {F13500}
  1777   2320   **
  1778         -** {F13501} In the SQL strings input to [sqlite3_prepare_v2()] and its
         2321  +** In the SQL strings input to [sqlite3_prepare_v2()] and its
  1779   2322   ** variants, literals may be replace by a parameter in one
  1780   2323   ** of these forms:
  1781   2324   **
  1782   2325   ** <ul>
  1783   2326   ** <li>  ?
  1784   2327   ** <li>  ?NNN
  1785         -** <li>  :AAA
  1786         -** <li>  @AAA
         2328  +** <li>  :VVV
         2329  +** <li>  @VVV
  1787   2330   ** <li>  $VVV
  1788   2331   ** </ul>
  1789   2332   **
  1790   2333   ** In the parameter forms shown above NNN is an integer literal,
  1791         -** AAA is an alphanumeric identifier and VVV is a variable name according
  1792         -** to the syntax rules of the TCL programming language. {END}
  1793         -** The values of these parameters (also called "host parameter names")
         2334  +** VVV alpha-numeric parameter name.
         2335  +** The values of these parameters (also called "host parameter names"
         2336  +** or "SQL parameters")
  1794   2337   ** can be set using the sqlite3_bind_*() routines defined here.
  1795   2338   **
  1796         -** {F13502} The first argument to the sqlite3_bind_*() routines always
         2339  +** The first argument to the sqlite3_bind_*() routines always
  1797   2340   ** is a pointer to the [sqlite3_stmt] object returned from
  1798         -** [sqlite3_prepare_v2()] or its variants.  {F13503} The second
  1799         -** argument is the index of the parameter to be set.  {F13504} The
  1800         -** first parameter has an index of 1.  {F13505} When the same named
         2341  +** [sqlite3_prepare_v2()] or its variants. The second
         2342  +** argument is the index of the parameter to be set. The
         2343  +** first parameter has an index of 1.  When the same named
  1801   2344   ** parameter is used more than once, second and subsequent
  1802   2345   ** occurrences have the same index as the first occurrence. 
  1803         -** {F13506} The index for named parameters can be looked up using the
  1804         -** [sqlite3_bind_parameter_name()] API if desired.  {F13507} The index
         2346  +** The index for named parameters can be looked up using the
         2347  +** [sqlite3_bind_parameter_name()] API if desired.  The index
  1805   2348   ** for "?NNN" parameters is the value of NNN.
  1806         -** {F13508} The NNN value must be between 1 and the compile-time
  1807         -** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). {END}
         2349  +** The NNN value must be between 1 and the compile-time
         2350  +** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999).
  1808   2351   ** See <a href="limits.html">limits.html</a> for additional information.
  1809   2352   **
  1810         -** {F13509} The third argument is the value to bind to the parameter. {END}
         2353  +** The third argument is the value to bind to the parameter.
  1811   2354   **
  1812         -** {F13510} In those
         2355  +** In those
  1813   2356   ** routines that have a fourth argument, its value is the number of bytes
  1814         -** in the parameter.  To be clear: the value is the number of bytes in the
  1815         -** string, not the number of characters. {F13511}  The number
         2357  +** in the parameter.  To be clear: the value is the number of <u>bytes</u>
         2358  +** in the value, not the number of characters.   The number
  1816   2359   ** of bytes does not include the zero-terminator at the end of strings.
  1817         -** {F13512}
  1818   2360   ** If the fourth parameter is negative, the length of the string is
  1819         -** number of bytes up to the first zero terminator. {END}
         2361  +** number of bytes up to the first zero terminator.
  1820   2362   **
  1821         -** {F13513}
  1822   2363   ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
  1823   2364   ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
  1824         -** text after SQLite has finished with it. {F13514} If the fifth argument is
  1825         -** the special value [SQLITE_STATIC], then the library assumes that the
         2365  +** string after SQLite has finished with it. If the fifth argument is
         2366  +** the special value [SQLITE_STATIC], then SQLite assumes that the
  1826   2367   ** information is in static, unmanaged space and does not need to be freed.
  1827         -** {F13515} If the fifth argument has the value [SQLITE_TRANSIENT], then
         2368  +** If the fifth argument has the value [SQLITE_TRANSIENT], then
  1828   2369   ** SQLite makes its own private copy of the data immediately, before
  1829         -** the sqlite3_bind_*() routine returns. {END}
         2370  +** the sqlite3_bind_*() routine returns.
  1830   2371   **
  1831         -** {F13520} The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
  1832         -** is filled with zeros.  {F13521} A zeroblob uses a fixed amount of memory
  1833         -** (just an integer to hold it size) while it is being processed. {END}
         2372  +** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
         2373  +** is filled with zeros.  A zeroblob uses a fixed amount of memory
         2374  +** (just an integer to hold it size) while it is being processed.
  1834   2375   ** Zeroblobs are intended to serve as place-holders for BLOBs whose
  1835   2376   ** content is later written using 
  1836         -** [sqlite3_blob_open | increment BLOB I/O] routines. {F13522} A negative
  1837         -** value for the zeroblob results in a zero-length BLOB. {END}
         2377  +** [sqlite3_blob_open | increment BLOB I/O] routines. A negative
         2378  +** value for the zeroblob results in a zero-length BLOB.
  1838   2379   **
  1839         -** {F13530} The sqlite3_bind_*() routines must be called after
         2380  +** The sqlite3_bind_*() routines must be called after
  1840   2381   ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
  1841         -** before [sqlite3_step()]. {F13531}
         2382  +** before [sqlite3_step()].
  1842   2383   ** Bindings are not cleared by the [sqlite3_reset()] routine.
  1843         -** {F13532} Unbound parameters are interpreted as NULL. {END}
         2384  +** Unbound parameters are interpreted as NULL.
  1844   2385   **
  1845         -** {F13540} These routines return [SQLITE_OK] on success or an error code if
  1846         -** anything goes wrong.  {F13541} [SQLITE_RANGE] is returned if the parameter
  1847         -** index is out of range.  {F13542} [SQLITE_NOMEM] is returned if malloc fails.
  1848         -** {F13543} [SQLITE_MISUSE] is returned if these routines are called on a
         2386  +** These routines return [SQLITE_OK] on success or an error code if
         2387  +** anything goes wrong.  [SQLITE_RANGE] is returned if the parameter
         2388  +** index is out of range.  [SQLITE_NOMEM] is returned if malloc fails.
         2389  +** [SQLITE_MISUSE] might be returned if these routines are called on a
  1849   2390   ** virtual machine that is the wrong state or which has already been finalized.
         2391  +** Detection of misuse is unreliable.  Applications should not depend
         2392  +** on SQLITE_MISUSE returns.  SQLITE_MISUSE is intended to indicate a
         2393  +** a logic error in the application.  Future versions of SQLite might
         2394  +** panic rather than return SQLITE_MISUSE.
         2395  +**
         2396  +** See also: [sqlite3_bind_parameter_count()],
         2397  +** [sqlite3_bind_parameter_name()], and
         2398  +** [sqlite3_bind_parameter_index()].
         2399  +**
         2400  +** INVARIANTS:
         2401  +**
         2402  +** {F13506} The [sqlite3_prepare | SQL statement compiler] recognizes
         2403  +**          tokens of the forms "?", "?NNN", "$VVV", ":VVV", and "@VVV"
         2404  +**          as SQL parameters, where NNN is any sequence of one or more
         2405  +**          digits and where VVV is any sequence of one or more 
         2406  +**          alphanumeric characters or "::" optionally followed by
         2407  +**          a string containing no spaces and contained within parentheses.
         2408  +**
         2409  +** {F13509} The initial value of an SQL parameter is NULL.
         2410  +**
         2411  +** {F13512} The index of an "?" SQL parameter is one larger than the
         2412  +**          largest index of SQL parameter to the left, or 1 if
         2413  +**          the "?" is the leftmost SQL parameter.
         2414  +**
         2415  +** {F13515} The index of an "?NNN" SQL parameter is the integer NNN.
         2416  +**
         2417  +** {F13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is
         2418  +**          the same as the index of leftmost occurances of the same
         2419  +**          parameter, or one more than the largest index over all
         2420  +**          parameters to the left if this is the first occurrance
         2421  +**          of this parameter, or 1 if this is the leftmost parameter.
         2422  +**
         2423  +** {F13521} The [sqlite3_prepare | SQL statement compiler] fail with
         2424  +**          an [SQLITE_RANGE] error if the index of an SQL parameter
         2425  +**          is less than 1 or greater than SQLITE_MAX_VARIABLE_NUMBER.
         2426  +**
         2427  +** {F13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)]
         2428  +**          associate the value V with all SQL parameters having an
         2429  +**          index of N in the [prepared statement] S.
         2430  +**
         2431  +** {F13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)]
         2432  +**          override prior calls with the same values of S and N.
         2433  +**
         2434  +** {F13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)]
         2435  +**          persist across calls to [sqlite3_reset(S)].
         2436  +**
         2437  +** {F13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
         2438  +**          [sqlite3_bind_text(S,N,V,L,D)], or
         2439  +**          [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L
         2440  +**          bytes of the blob or string pointed to by V, when L
         2441  +**          is non-negative.
         2442  +**
         2443  +** {F13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or
         2444  +**          [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters
         2445  +**          from V through the first zero character when L is negative.
         2446  +**
         2447  +** {F13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
         2448  +**          [sqlite3_bind_text(S,N,V,L,D)], or
         2449  +**          [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
         2450  +**          constant [SQLITE_STATIC], SQLite assumes that the value V
         2451  +**          is held in static unmanaged space that will not change
         2452  +**          during the lifetime of the binding.
         2453  +**
         2454  +** {F13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
         2455  +**          [sqlite3_bind_text(S,N,V,L,D)], or
         2456  +**          [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
         2457  +**          constant [SQLITE_TRANSIENT], the routine makes a 
         2458  +**          private copy of V value before it returns.
         2459  +**
         2460  +** {F13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
         2461  +**          [sqlite3_bind_text(S,N,V,L,D)], or
         2462  +**          [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to
         2463  +**          a function, SQLite invokes that function to destroy the
         2464  +**          V value after it has finished using the V value.
         2465  +**
         2466  +** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound
         2467  +**          is a blob of L bytes, or a zero-length blob if L is negative.
  1850   2468   */
  1851   2469   int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
  1852   2470   int sqlite3_bind_double(sqlite3_stmt*, int, double);
  1853   2471   int sqlite3_bind_int(sqlite3_stmt*, int, int);
  1854   2472   int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
  1855   2473   int sqlite3_bind_null(sqlite3_stmt*, int);
  1856   2474   int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
  1857   2475   int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
  1858   2476   int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
  1859   2477   int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
  1860   2478   
  1861   2479   /*
  1862         -** CAPI3REF: Number Of Host Parameters {F13600}
  1863         -**
  1864         -** {F13601} Return the largest host parameter index in the precompiled
  1865         -** statement given as the argument. {F13602} When the host parameters
  1866         -** are of the forms like ":AAA", "$VVV", "@AAA", or "?",
  1867         -** then they are assigned sequential increasing numbers beginning
  1868         -** with one, so the value returned is the number of parameters.
  1869         -** {F13603} However
  1870         -** if the same host parameter name is used multiple times, each occurrance
  1871         -** is given the same number, so the value returned in that case is the number
  1872         -** of unique host parameter names. {F13604} If host parameters of the
  1873         -** form "?NNN" are used (where NNN is an integer) then there might be
  1874         -** gaps in the numbering and the value returned by this interface is
  1875         -** the index of the host parameter with the largest index value. {END}
  1876         -**
  1877         -** {U13605} The prepared statement must not be [sqlite3_finalize | finalized]
  1878         -** prior to this routine returning.  Otherwise the results are undefined
  1879         -** and probably undesirable.
         2480  +** CAPI3REF: Number Of SQL Parameters {F13600}
         2481  +**
         2482  +** This routine can be used to find the number of SQL parameters
         2483  +** in a prepared statement.  SQL parameters are tokens of the
         2484  +** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
         2485  +** place-holders for values that are [sqlite3_bind_blob | bound]
         2486  +** to the parameters at a later time.
         2487  +**
         2488  +** This routine actually returns the index of the largest parameter.
         2489  +** For all forms except ?NNN, this will correspond to the number of
         2490  +** unique parameters.  If parameters of the ?NNN are used, there may
         2491  +** be gaps in the list.
         2492  +**
         2493  +** See also: [sqlite3_bind_blob|sqlite3_bind()],
         2494  +** [sqlite3_bind_parameter_name()], and
         2495  +** [sqlite3_bind_parameter_index()].
         2496  +**
         2497  +** INVARIANTS:
         2498  +**
         2499  +** {F13601} The [sqlite3_bind_parameter_count(S)] interface returns
         2500  +**          the largest index of all SQL parameters in the
         2501  +**          [prepared statement] S, or 0 if S
         2502  +**          contains no SQL parameters.
  1880   2503   */
  1881   2504   int sqlite3_bind_parameter_count(sqlite3_stmt*);
  1882   2505   
  1883   2506   /*
  1884   2507   ** CAPI3REF: Name Of A Host Parameter {F13620}
  1885   2508   **
  1886         -** {F13621} This routine returns a pointer to the name of the n-th
  1887         -** parameter in a [sqlite3_stmt | prepared statement]. {F13622}
  1888         -** Host parameters of the form ":AAA" or "@AAA" or "$VVV" have a name
         2509  +** This routine returns a pointer to the name of the n-th
         2510  +** SQL parameter in a [prepared statement].
         2511  +** SQL parameters of the form ":AAA" or "@AAA" or "$AAA" have a name
  1889   2512   ** which is the string ":AAA" or "@AAA" or "$VVV". 
  1890   2513   ** In other words, the initial ":" or "$" or "@"
  1891         -** is included as part of the name.  {F13626}
         2514  +** is included as part of the name.
  1892   2515   ** Parameters of the form "?" or "?NNN" have no name.
  1893   2516   **
  1894         -** {F13623} The first host parameter has an index of 1, not 0.
         2517  +** The first host parameter has an index of 1, not 0.
  1895   2518   **
  1896         -** {F13624} If the value n is out of range or if the n-th parameter is
  1897         -** nameless, then NULL is returned.  {F13625} The returned string is
         2519  +** If the value n is out of range or if the n-th parameter is
         2520  +** nameless, then NULL is returned.  The returned string is
  1898   2521   ** always in the UTF-8 encoding even if the named parameter was
  1899   2522   ** originally specified as UTF-16 in [sqlite3_prepare16()] or
  1900   2523   ** [sqlite3_prepare16_v2()].
         2524  +**
         2525  +** See also: [sqlite3_bind_blob|sqlite3_bind()],
         2526  +** [sqlite3_bind_parameter_count()], and
         2527  +** [sqlite3_bind_parameter_index()].
         2528  +**
         2529  +** INVARIANTS:
         2530  +**
         2531  +** {F13621} The [sqlite3_bind_parameter_name(S,N)] interface returns
         2532  +**          a UTF-8 rendering of the name of the SQL parameter in
         2533  +**          [prepared statement] S having index N, or
         2534  +**          NULL if there is no SQL parameter with index N or if the
         2535  +**          parameter with index N is an anonymous parameter "?" or
         2536  +**          a numbered parameter "?NNN".
  1901   2537   */
  1902   2538   const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
  1903   2539   
  1904   2540   /*
  1905   2541   ** CAPI3REF: Index Of A Parameter With A Given Name {F13640}
  1906   2542   **
  1907         -** {F13641} This routine returns the index of a host parameter with the
  1908         -** given name.  {F13642} The name must match exactly.  {F13643}
  1909         -** If no parameter with the given name is found, return 0.
  1910         -** {F13644} Parameter names must be UTF8.
         2543  +** Return the index of an SQL parameter given its name.  The
         2544  +** index value returned is suitable for use as the second
         2545  +** parameter to [sqlite3_bind_blob|sqlite3_bind()].  A zero
         2546  +** is returned if no matching parameter is found.  The parameter
         2547  +** name must be given in UTF-8 even if the original statement
         2548  +** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
         2549  +**
         2550  +** See also: [sqlite3_bind_blob|sqlite3_bind()],
         2551  +** [sqlite3_bind_parameter_count()], and
         2552  +** [sqlite3_bind_parameter_index()].
         2553  +**
         2554  +** INVARIANTS:
         2555  +**
         2556  +** {F13641} The [sqlite3_bind_parameter_index(S,N)] interface returns
         2557  +**          the index of SQL parameter in [prepared statement]
         2558  +**          S whose name matches the UTF-8 string N, or 0 if there is
         2559  +**          no match.
  1911   2560   */
  1912   2561   int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
  1913   2562   
  1914   2563   /*
  1915   2564   ** CAPI3REF: Reset All Bindings On A Prepared Statement {F13660}
  1916   2565   **
  1917         -** {F13661} Contrary to the intuition of many, [sqlite3_reset()] does not
         2566  +** Contrary to the intuition of many, [sqlite3_reset()] does not
  1918   2567   ** reset the [sqlite3_bind_blob | bindings] on a 
  1919         -** [sqlite3_stmt | prepared statement]. {F13662} Use this routine to
         2568  +** [prepared statement].  Use this routine to
  1920   2569   ** reset all host parameters to NULL.
         2570  +**
         2571  +** INVARIANTS:
         2572  +**
         2573  +** {F13661} The [sqlite3_clear_bindings(S)] interface resets all
         2574  +**          SQL parameter bindings in [prepared statement] S
         2575  +**          back to NULL.
  1921   2576   */
  1922   2577   int sqlite3_clear_bindings(sqlite3_stmt*);
  1923   2578   
  1924   2579   /*
  1925   2580   ** CAPI3REF: Number Of Columns In A Result Set {F13710}
  1926   2581   **
  1927         -** {F13711} Return the number of columns in the result set returned by the 
  1928         -** [sqlite3_stmt | compiled SQL statement]. {F13712} This routine returns 0
         2582  +** Return the number of columns in the result set returned by the 
         2583  +** [prepared statement]. This routine returns 0
  1929   2584   ** if pStmt is an SQL statement that does not return data (for 
  1930   2585   ** example an UPDATE).
         2586  +**
         2587  +** INVARIANTS:
         2588  +**
         2589  +** {F13711} The [sqlite3_column_count(S)] interface returns the number of
         2590  +**          columns in the result set generated by the
         2591  +**          [prepared statement] S, or 0 if S does not generate
         2592  +**          a result set.
  1931   2593   */
  1932   2594   int sqlite3_column_count(sqlite3_stmt *pStmt);
  1933   2595   
  1934   2596   /*
  1935   2597   ** CAPI3REF: Column Names In A Result Set {F13720}
  1936   2598   **
  1937         -** {F13721} These routines return the name assigned to a particular column
  1938         -** in the result set of a SELECT statement.  {F13722} The sqlite3_column_name()
         2599  +** These routines return the name assigned to a particular column
         2600  +** in the result set of a SELECT statement.  The sqlite3_column_name()
  1939   2601   ** interface returns a pointer to a zero-terminated UTF8 string
  1940   2602   ** and sqlite3_column_name16() returns a pointer to a zero-terminated
  1941         -** UTF16 string. {F13723}  The first parameter is the
  1942         -** [sqlite3_stmt | prepared statement] that implements the SELECT statement.
         2603  +** UTF16 string.  The first parameter is the
         2604  +** [prepared statement] that implements the SELECT statement.
  1943   2605   ** The second parameter is the column number.  The left-most column is
  1944   2606   ** number 0.
  1945   2607   **
  1946         -** {F13724} The returned string pointer is valid until either the 
  1947         -** [sqlite3_stmt | prepared statement] is destroyed by [sqlite3_finalize()]
         2608  +** The returned string pointer is valid until either the 
         2609  +** [prepared statement] is destroyed by [sqlite3_finalize()]
  1948   2610   ** or until the next call sqlite3_column_name() or sqlite3_column_name16()
  1949   2611   ** on the same column.
  1950   2612   **
  1951         -** {F13725} If sqlite3_malloc() fails during the processing of either routine
         2613  +** If sqlite3_malloc() fails during the processing of either routine
  1952   2614   ** (for example during a conversion from UTF-8 to UTF-16) then a
  1953   2615   ** NULL pointer is returned.
         2616  +**
         2617  +** The name of a result column is the value of the "AS" clause for
         2618  +** that column, if there is an AS clause.  If there is no AS clause
         2619  +** then the name of the column is unspecified and may change from
         2620  +** one release of SQLite to the next.
         2621  +**
         2622  +** INVARIANTS:
         2623  +**
         2624  +** {F13721} A successful invocation of the [sqlite3_column_name(S,N)]
         2625  +**          interface returns the name
         2626  +**          of the Nth column (where 0 is the left-most column) for the
         2627  +**          result set of [prepared statement] S as a
         2628  +**          zero-terminated UTF-8 string.
         2629  +**
         2630  +** {F13723} A successful invocation of the [sqlite3_column_name16(S,N)]
         2631  +**          interface returns the name
         2632  +**          of the Nth column (where 0 is the left-most column) for the
         2633  +**          result set of [prepared statement] S as a
         2634  +**          zero-terminated UTF-16 string in the native byte order.
         2635  +**
         2636  +** {F13724} The [sqlite3_column_name()] and [sqlite3_column_name16()]
         2637  +**          interfaces return a NULL pointer if they are unable to
         2638  +**          allocate memory memory to hold there normal return strings.
         2639  +**
         2640  +** {F13725} If the N parameter to [sqlite3_column_name(S,N)] or
         2641  +**          [sqlite3_column_name16(S,N)] is out of range, then the
         2642  +**          interfaces returns a NULL pointer.
         2643  +** 
         2644  +** {F13726} The strings returned by [sqlite3_column_name(S,N)] and
         2645  +**          [sqlite3_column_name16(S,N)] are valid until the next
         2646  +**          call to either routine with the same S and N parameters
         2647  +**          or until [sqlite3_finalize(S)] is called.
         2648  +**
         2649  +** {F13727} When a result column of a [SELECT] statement contains
         2650  +**          an AS clause, the name of that column is the indentifier
         2651  +**          to the right of the AS keyword.
  1954   2652   */
  1955   2653   const char *sqlite3_column_name(sqlite3_stmt*, int N);
  1956   2654   const void *sqlite3_column_name16(sqlite3_stmt*, int N);
  1957   2655   
  1958   2656   /*
  1959   2657   ** CAPI3REF: Source Of Data In A Query Result {F13740}
  1960   2658   **
  1961         -** {F13741} These routines provide a means to determine what column of what
         2659  +** These routines provide a means to determine what column of what
  1962   2660   ** table in which database a result of a SELECT statement comes from.
  1963         -** {F13742} The name of the database or table or column can be returned as
  1964         -** either a UTF8 or UTF16 string.  {F13743} The _database_ routines return
         2661  +** The name of the database or table or column can be returned as
         2662  +** either a UTF8 or UTF16 string.  The _database_ routines return
  1965   2663   ** the database name, the _table_ routines return the table name, and
  1966         -** the origin_ routines return the column name. {F13744}
         2664  +** the origin_ routines return the column name.
  1967   2665   ** The returned string is valid until
  1968         -** the [sqlite3_stmt | prepared statement] is destroyed using
         2666  +** the [prepared statement] is destroyed using
  1969   2667   ** [sqlite3_finalize()] or until the same information is requested
  1970   2668   ** again in a different encoding.
  1971   2669   **
  1972         -** {F13745} The names returned are the original un-aliased names of the
         2670  +** The names returned are the original un-aliased names of the
  1973   2671   ** database, table, and column.
  1974   2672   **
  1975         -** {F13746} The first argument to the following calls is a 
  1976         -** [sqlite3_stmt | compiled SQL statement].
  1977         -** {F13747} These functions return information about the Nth column returned by 
         2673  +** The first argument to the following calls is a [prepared statement].
         2674  +** These functions return information about the Nth column returned by 
  1978   2675   ** the statement, where N is the second function argument.
  1979   2676   **
  1980         -** {F13748} If the Nth column returned by the statement is an expression
         2677  +** If the Nth column returned by the statement is an expression
  1981   2678   ** or subquery and is not a column value, then all of these functions
  1982         -** return NULL.  {F13749} Otherwise, they return the 
         2679  +** return NULL.  These routine might also return NULL if a memory
         2680  +** allocation error occurs.  Otherwise, they return the 
  1983   2681   ** name of the attached database, table and column that query result
  1984   2682   ** column was extracted from.
  1985   2683   **
  1986         -** {F13750} As with all other SQLite APIs, those postfixed with "16" return
         2684  +** As with all other SQLite APIs, those postfixed with "16" return
  1987   2685   ** UTF-16 encoded strings, the other functions return UTF-8. {END}
  1988   2686   **
  1989   2687   ** These APIs are only available if the library was compiled with the 
  1990   2688   ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
  1991   2689   **
  1992   2690   ** {U13751}
  1993   2691   ** If two or more threads call one or more of these routines against the same
  1994   2692   ** prepared statement and column at the same time then the results are
  1995   2693   ** undefined.
         2694  +**
         2695  +** INVARIANTS:
         2696  +**
         2697  +** {F13741} The [sqlite3_column_database_name(S,N)] interface returns either
         2698  +**          the UTF-8 zero-terminated name of the database from which the 
         2699  +**          Nth result column of [prepared statement] S 
         2700  +**          is extracted, or NULL if the the Nth column of S is a
         2701  +**          general expression or if unable to allocate memory
         2702  +**          to store the name.
         2703  +**          
         2704  +** {F13742} The [sqlite3_column_database_name16(S,N)] interface returns either
         2705  +**          the UTF-16 native byte order
         2706  +**          zero-terminated name of the database from which the 
         2707  +**          Nth result column of [prepared statement] S 
         2708  +**          is extracted, or NULL if the the Nth column of S is a
         2709  +**          general expression or if unable to allocate memory
         2710  +**          to store the name.
         2711  +**          
         2712  +** {F13743} The [sqlite3_column_table_name(S,N)] interface returns either
         2713  +**          the UTF-8 zero-terminated name of the table from which the 
         2714  +**          Nth result column of [prepared statement] S 
         2715  +**          is extracted, or NULL if the the Nth column of S is a
         2716  +**          general expression or if unable to allocate memory
         2717  +**          to store the name.
         2718  +**          
         2719  +** {F13744} The [sqlite3_column_table_name16(S,N)] interface returns either
         2720  +**          the UTF-16 native byte order
         2721  +**          zero-terminated name of the table from which the 
         2722  +**          Nth result column of [prepared statement] S 
         2723  +**          is extracted, or NULL if the the Nth column of S is a
         2724  +**          general expression or if unable to allocate memory
         2725  +**          to store the name.
         2726  +**          
         2727  +** {F13745} The [sqlite3_column_origin_name(S,N)] interface returns either
         2728  +**          the UTF-8 zero-terminated name of the table column from which the 
         2729  +**          Nth result column of [prepared statement] S 
         2730  +**          is extracted, or NULL if the the Nth column of S is a
         2731  +**          general expression or if unable to allocate memory
         2732  +**          to store the name.
         2733  +**          
         2734  +** {F13746} The [sqlite3_column_origin_name16(S,N)] interface returns either
         2735  +**          the UTF-16 native byte order
         2736  +**          zero-terminated name of the table column from which the 
         2737  +**          Nth result column of [prepared statement] S 
         2738  +**          is extracted, or NULL if the the Nth column of S is a
         2739  +**          general expression or if unable to allocate memory
         2740  +**          to store the name.
         2741  +**          
         2742  +** {F13748} The return values from
         2743  +**          [sqlite3_column_database_name|column metadata interfaces]
         2744  +**          are valid
         2745  +**          for the lifetime of the [prepared statement]
         2746  +**          or until the encoding is changed by another metadata
         2747  +**          interface call for the same prepared statement and column.
         2748  +**
         2749  +** LIMITATIONS:
         2750  +**
         2751  +** {U13751} If two or more threads call one or more
         2752  +**          [sqlite3_column_database_name|column metadata interfaces]
         2753  +**          the same [prepared statement] and result column
         2754  +**          at the same time then the results are undefined.
  1996   2755   */
  1997   2756   const char *sqlite3_column_database_name(sqlite3_stmt*,int);
  1998   2757   const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
  1999   2758   const char *sqlite3_column_table_name(sqlite3_stmt*,int);
  2000   2759   const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
  2001   2760   const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
  2002   2761   const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
  2003   2762   
  2004   2763   /*
  2005   2764   ** CAPI3REF: Declared Datatype Of A Query Result {F13760}
  2006   2765   **
  2007         -** The first parameter is a [sqlite3_stmt | compiled SQL statement]. 
  2008         -** {F13761} If this statement is a SELECT statement and the Nth column of the 
         2766  +** The first parameter is a [prepared statement]. 
         2767  +** If this statement is a SELECT statement and the Nth column of the 
  2009   2768   ** returned result set of that SELECT is a table column (not an
  2010   2769   ** expression or subquery) then the declared type of the table
  2011         -** column is returned.  {F13762} If the Nth column of the result set is an
         2770  +** column is returned.  If the Nth column of the result set is an
  2012   2771   ** expression or subquery, then a NULL pointer is returned.
  2013         -** {F13763} The returned string is always UTF-8 encoded.  {END} 
         2772  +** The returned string is always UTF-8 encoded.  {END} 
  2014   2773   ** For example, in the database schema:
  2015   2774   **
  2016   2775   ** CREATE TABLE t1(c1 VARIANT);
  2017   2776   **
  2018   2777   ** And the following statement compiled:
  2019   2778   **
  2020   2779   ** SELECT c1 + 1, c1 FROM t1;
................................................................................
  2025   2784   **
  2026   2785   ** SQLite uses dynamic run-time typing.  So just because a column
  2027   2786   ** is declared to contain a particular type does not mean that the
  2028   2787   ** data stored in that column is of the declared type.  SQLite is
  2029   2788   ** strongly typed, but the typing is dynamic not static.  Type
  2030   2789   ** is associated with individual values, not with the containers
  2031   2790   ** used to hold those values.
         2791  +**
         2792  +** INVARIANTS:
         2793  +**
         2794  +** {F13761}  A successful call to [sqlite3_column_decltype(S,N)]
         2795  +**           returns a zero-terminated UTF-8 string containing the
         2796  +**           the declared datatype of the table column that appears
         2797  +**           as the Nth column (numbered from 0) of the result set to the
         2798  +**           [prepared statement] S.
         2799  +**
         2800  +** {F13762}  A successful call to [sqlite3_column_decltype16(S,N)]
         2801  +**           returns a zero-terminated UTF-16 native byte order string
         2802  +**           containing the declared datatype of the table column that appears
         2803  +**           as the Nth column (numbered from 0) of the result set to the
         2804  +**           [prepared statement] S.
         2805  +**
         2806  +** {F13763}  If N is less than 0 or N is greater than or equal to
         2807  +**           the number of columns in [prepared statement] S
         2808  +**           or if the Nth column of S is an expression or subquery rather
         2809  +**           than a table column or if a memory allocation failure
         2810  +**           occurs during encoding conversions, then
         2811  +**           calls to [sqlite3_column_decltype(S,N)] or
         2812  +**           [sqlite3_column_decltype16(S,N)] return NULL.
  2032   2813   */
  2033         -const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
         2814  +const char *sqlite3_column_decltype(sqlite3_stmt*,int);
  2034   2815   const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
  2035   2816   
  2036   2817   /* 
  2037   2818   ** CAPI3REF:  Evaluate An SQL Statement {F13200}
  2038   2819   **
  2039         -** After an [sqlite3_stmt | SQL statement] has been prepared with a call
         2820  +** After an [prepared statement] has been prepared with a call
  2040   2821   ** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of
  2041   2822   ** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()],
  2042   2823   ** then this function must be called one or more times to evaluate the 
  2043   2824   ** statement.
  2044   2825   **
  2045   2826   ** The details of the behavior of this sqlite3_step() interface depend
  2046   2827   ** on whether the statement was prepared using the newer "v2" interface
................................................................................
  2075   2856   ** 
  2076   2857   ** [SQLITE_ERROR] means that a run-time error (such as a constraint
  2077   2858   ** violation) has occurred.  sqlite3_step() should not be called again on
  2078   2859   ** the VM. More information may be found by calling [sqlite3_errmsg()].
  2079   2860   ** With the legacy interface, a more specific error code (example:
  2080   2861   ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
  2081   2862   ** can be obtained by calling [sqlite3_reset()] on the
  2082         -** [sqlite3_stmt | prepared statement].  In the "v2" interface,
         2863  +** [prepared statement].  In the "v2" interface,
  2083   2864   ** the more specific error code is returned directly by sqlite3_step().
  2084   2865   **
  2085   2866   ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
  2086         -** Perhaps it was called on a [sqlite3_stmt | prepared statement] that has
         2867  +** Perhaps it was called on a [prepared statement] that has
  2087   2868   ** already been [sqlite3_finalize | finalized] or on one that had 
  2088   2869   ** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
  2089   2870   ** be the case that the same database connection is being used by two or
  2090   2871   ** more threads at the same moment in time.
  2091   2872   **
  2092   2873   ** <b>Goofy Interface Alert:</b>
  2093   2874   ** In the legacy interface, 
  2094   2875   ** the sqlite3_step() API always returns a generic error code,
  2095   2876   ** [SQLITE_ERROR], following any error other than [SQLITE_BUSY]
  2096   2877   ** and [SQLITE_MISUSE].  You must call [sqlite3_reset()] or
  2097   2878   ** [sqlite3_finalize()] in order to find one of the specific
  2098         -** [SQLITE_ERROR | result codes] that better describes the error.
         2879  +** [error codes] that better describes the error.
  2099   2880   ** We admit that this is a goofy design.  The problem has been fixed
  2100   2881   ** with the "v2" interface.  If you prepare all of your SQL statements
  2101   2882   ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
  2102   2883   ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the 
  2103         -** more specific [SQLITE_ERROR | result codes] are returned directly
         2884  +** more specific [error codes] are returned directly
  2104   2885   ** by sqlite3_step().  The use of the "v2" interface is recommended.
         2886  +**
         2887  +** INVARIANTS:
         2888  +**
         2889  +** {F13202}  If [prepared statement] S is ready to be
         2890  +**           run, then [sqlite3_step(S)] advances that prepared statement
         2891  +**           until to completion or until it is ready to return another
         2892  +**           row of the result set or an interrupt or run-time error occurs.
         2893  +**
         2894  +** {F15304}  When a call to [sqlite3_step(S)] causes the 
         2895  +**           [prepared statement] S to run to completion,
         2896  +**           the function returns [SQLITE_DONE].
         2897  +**
         2898  +** {F15306}  When a call to [sqlite3_step(S)] stops because it is ready
         2899  +**           to return another row of the result set, it returns
         2900  +**           [SQLITE_ROW].
         2901  +**
         2902  +** {F15308}  If a call to [sqlite3_step(S)] encounters an
         2903  +**           [sqlite3_interrupt|interrupt] or a run-time error,
         2904  +**           it returns an appropraite error code that is not one of
         2905  +**           [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE].
         2906  +**
         2907  +** {F15310}  If an [sqlite3_interrupt|interrupt] or run-time error
         2908  +**           occurs during a call to [sqlite3_step(S)]
         2909  +**           for a [prepared statement] S created using
         2910  +**           legacy interfaces [sqlite3_prepare()] or
         2911  +**           [sqlite3_prepare16()] then the function returns either
         2912  +**           [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE].
  2105   2913   */
  2106   2914   int sqlite3_step(sqlite3_stmt*);
  2107   2915   
  2108   2916   /*
  2109   2917   ** CAPI3REF: Number of columns in a result set {F13770}
  2110   2918   **
  2111   2919   ** Return the number of values in the current row of the result set.
  2112   2920   **
  2113         -** {F13771} After a call to [sqlite3_step()] that returns [SQLITE_ROW],
  2114         -** this routine
  2115         -** will return the same value as the [sqlite3_column_count()] function.
  2116         -** {F13772}
  2117         -** After [sqlite3_step()] has returned an [SQLITE_DONE], [SQLITE_BUSY], or
  2118         -** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been 
  2119         -** called on the [sqlite3_stmt | prepared statement] for the first time,
  2120         -** this routine returns zero.
         2921  +** INVARIANTS:
         2922  +**
         2923  +** {F13771}  After a call to [sqlite3_step(S)] that returns
         2924  +**           [SQLITE_ROW], the [sqlite3_data_count(S)] routine
         2925  +**           will return the same value as the
         2926  +**           [sqlite3_column_count(S)] function.
         2927  +**
         2928  +** {F13772}  After [sqlite3_step(S)] has returned any value other than
         2929  +**           [SQLITE_ROW] or before [sqlite3_step(S)] has been 
         2930  +**           called on the [prepared statement] for
         2931  +**           the first time since it was [sqlite3_prepare|prepared]
         2932  +**           or [sqlite3_reset|reset], the [sqlite3_data_count(S)]
         2933  +**           routine returns zero.
  2121   2934   */
  2122   2935   int sqlite3_data_count(sqlite3_stmt *pStmt);
  2123   2936   
  2124   2937   /*
  2125   2938   ** CAPI3REF: Fundamental Datatypes {F10265}
         2939  +** KEYWORDS: SQLITE_TEXT
  2126   2940   **
  2127   2941   ** {F10266}Every value in SQLite has one of five fundamental datatypes:
  2128   2942   **
  2129   2943   ** <ul>
  2130   2944   ** <li> 64-bit signed integer
  2131   2945   ** <li> 64-bit IEEE floating point number
  2132   2946   ** <li> string
................................................................................
  2151   2965   # define SQLITE_TEXT     3
  2152   2966   #endif
  2153   2967   #define SQLITE3_TEXT     3
  2154   2968   
  2155   2969   /*
  2156   2970   ** CAPI3REF: Results Values From A Query {F13800}
  2157   2971   **
         2972  +** These routines form the "result set query" interface.
         2973  +**
  2158   2974   ** These routines return information about
  2159   2975   ** a single column of the current result row of a query.  In every
  2160   2976   ** case the first argument is a pointer to the 
  2161         -** [sqlite3_stmt | SQL statement] that is being
         2977  +** [prepared statement] that is being
  2162   2978   ** evaluated (the [sqlite3_stmt*] that was returned from 
  2163   2979   ** [sqlite3_prepare_v2()] or one of its variants) and
  2164   2980   ** the second argument is the index of the column for which information 
  2165   2981   ** should be returned.  The left-most column of the result set
  2166   2982   ** has an index of 0.
  2167   2983   **
  2168   2984   ** If the SQL statement is not currently point to a valid row, or if the
................................................................................
  2195   3011   ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
  2196   3012   ** the number of bytes in that string.
  2197   3013   ** The value returned does not include the zero terminator at the end
  2198   3014   ** of the string.  For clarity: the value returned is the number of
  2199   3015   ** bytes in the string, not the number of characters.
  2200   3016   **
  2201   3017   ** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
  2202         -** even zero-length strings, are always zero terminated.  The return
         3018  +** even empty strings, are always zero terminated.  The return
  2203   3019   ** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
  2204   3020   ** pointer, possibly even a NULL pointer.
  2205   3021   **
  2206   3022   ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
  2207         -** but leaves the result in UTF-16 instead of UTF-8.  
         3023  +** but leaves the result in UTF-16 in native byte order instead of UTF-8.  
  2208   3024   ** The zero terminator is not included in this count.
  2209   3025   **
  2210   3026   ** These routines attempt to convert the value where appropriate.  For
  2211   3027   ** example, if the internal representation is FLOAT and a text result
  2212   3028   ** is requested, [sqlite3_snprintf()] is used internally to do the conversion
  2213   3029   ** automatically.  The following table details the conversions that
  2214   3030   ** are applied:
................................................................................
  2308   3124   int sqlite3_column_type(sqlite3_stmt*, int iCol);
  2309   3125   sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
  2310   3126   
  2311   3127   /*
  2312   3128   ** CAPI3REF: Destroy A Prepared Statement Object {F13300}
  2313   3129   **
  2314   3130   ** The sqlite3_finalize() function is called to delete a 
  2315         -** [sqlite3_stmt | compiled SQL statement]. If the statement was
         3131  +** [prepared statement]. If the statement was
  2316   3132   ** executed successfully, or not executed at all, then SQLITE_OK is returned.
  2317   3133   ** If execution of the statement failed then an 
  2318         -** [SQLITE_ERROR | error code] or [SQLITE_IOERR_READ | extended error code]
         3134  +** [error code] or [extended error code]
  2319   3135   ** is returned. 
  2320   3136   **
  2321   3137   ** This routine can be called at any point during the execution of the
  2322         -** [sqlite3_stmt | virtual machine].  If the virtual machine has not 
         3138  +** [prepared statement].  If the virtual machine has not 
  2323   3139   ** completed execution when this routine is called, that is like
  2324   3140   ** encountering an error or an interrupt.  (See [sqlite3_interrupt()].) 
  2325   3141   ** Incomplete updates may be rolled back and transactions cancelled,  
  2326   3142   ** depending on the circumstances, and the 
  2327         -** [SQLITE_ERROR | result code] returned will be [SQLITE_ABORT].
         3143  +** [error code] returned will be [SQLITE_ABORT].
         3144  +**
         3145  +** INVARIANTS:
         3146  +**
         3147  +** {F11302} The [sqlite3_finalize(S)] interface destroys the
         3148  +**          [prepared statement] S and releases all
         3149  +**          memory and file resources held by that object.
         3150  +**
         3151  +** {F11304} If the most recent call to [sqlite3_step(S)] for the
         3152  +**          [prepared statement] S returned an error,
         3153  +**          then [sqlite3_finalize(S)] returns that same error.
  2328   3154   */
  2329   3155   int sqlite3_finalize(sqlite3_stmt *pStmt);
  2330   3156   
  2331   3157   /*
  2332   3158   ** CAPI3REF: Reset A Prepared Statement Object {F13330}
  2333   3159   **
  2334   3160   ** The sqlite3_reset() function is called to reset a 
  2335         -** [sqlite3_stmt | compiled SQL statement] object.
         3161  +** [prepared statement] object.
  2336   3162   ** back to its initial state, ready to be re-executed.
  2337   3163   ** Any SQL statement variables that had values bound to them using
  2338   3164   ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
  2339   3165   ** Use [sqlite3_clear_bindings()] to reset the bindings.
         3166  +**
         3167  +** {F11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S
         3168  +**          back to the beginning of its program.
         3169  +**
         3170  +** {F11334} If the most recent call to [sqlite3_step(S)] for 
         3171  +**          [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
         3172  +**          or if [sqlite3_step(S)] has never before been called on S,
         3173  +**          then [sqlite3_reset(S)] returns [SQLITE_OK].
         3174  +**
         3175  +** {F11336} If the most recent call to [sqlite3_step(S)] for
         3176  +**          [prepared statement] S indicated an error, then
         3177  +**          [sqlite3_reset(S)] returns an appropriate [error code].
         3178  +**
         3179  +** {F11338} The [sqlite3_reset(S)] interface does not change the values
         3180  +**          of any [sqlite3_bind_blob|bindings] on [prepared statement] S.
  2340   3181   */
  2341   3182   int sqlite3_reset(sqlite3_stmt *pStmt);
  2342   3183   
  2343   3184   /*
  2344   3185   ** CAPI3REF: Create Or Redefine SQL Functions {F16100}
  2345   3186   **
  2346   3187   ** The following two functions are used to add SQL functions or aggregates
  2347   3188   ** or to redefine the behavior of existing SQL functions or aggregates.  The
  2348   3189   ** difference only between the two is that the second parameter, the
  2349   3190   ** name of the (scalar) function or aggregate, is encoded in UTF-8 for
  2350   3191   ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
  2351   3192   **
  2352         -** The first argument is the [sqlite3 | database handle] that holds the
         3193  +** The first argument is the [database connection] that holds the
  2353   3194   ** SQL function or aggregate is to be added or redefined. If a single
  2354   3195   ** program uses more than one database handle internally, then SQL
  2355   3196   ** functions or aggregates must be added individually to each database
  2356   3197   ** handle with which they will be used.
  2357   3198   **
  2358   3199   ** The second parameter is the name of the SQL function to be created
  2359   3200   ** or redefined.
................................................................................
  2395   3236   ** It is permitted to register multiple implementations of the same
  2396   3237   ** functions with the same name but with either differing numbers of
  2397   3238   ** arguments or differing perferred text encodings.  SQLite will use
  2398   3239   ** the implementation most closely matches the way in which the
  2399   3240   ** SQL function is used.
  2400   3241   */
  2401   3242   int sqlite3_create_function(
  2402         -  sqlite3 *,
         3243  +  sqlite3 *db,
  2403   3244     const char *zFunctionName,
  2404   3245     int nArg,
  2405   3246     int eTextRep,
  2406         -  void*,
         3247  +  void *pApp,
  2407   3248     void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  2408   3249     void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  2409   3250     void (*xFinal)(sqlite3_context*)
  2410   3251   );
  2411   3252   int sqlite3_create_function16(
  2412         -  sqlite3*,
         3253  +  sqlite3 *db,
  2413   3254     const void *zFunctionName,
  2414   3255     int nArg,
  2415   3256     int eTextRep,
  2416         -  void*,
         3257  +  void *pApp,
  2417   3258     void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  2418   3259     void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  2419   3260     void (*xFinal)(sqlite3_context*)
  2420   3261   );
  2421   3262   
  2422   3263   /*
  2423   3264   ** CAPI3REF: Text Encodings {F10267}
................................................................................
  2754   3595   ** {F16611} Each time the application
  2755   3596   ** supplied function is invoked, it is passed a copy of the void* passed as
  2756   3597   ** the fourth argument to sqlite3_create_collation() or
  2757   3598   ** sqlite3_create_collation16() as its first parameter.
  2758   3599   **
  2759   3600   ** {F16612}
  2760   3601   ** The remaining arguments to the application-supplied routine are two strings,
  2761         -** each represented by a [length, data] pair and encoded in the encoding
         3602  +** each represented by a (length, data) pair and encoded in the encoding
  2762   3603   ** that was passed as the third argument when the collation sequence was
  2763   3604   ** registered. {END} The application defined collation routine should
  2764   3605   ** return negative, zero or positive if
  2765   3606   ** the first string is less than, equal to, or greater than the second
  2766   3607   ** string. i.e. (STRING1 - STRING2).
  2767   3608   **
  2768   3609   ** {F16615}
................................................................................
  2895   3736   ** routines have been call and remain unchanged thereafter.
  2896   3737   */
  2897   3738   SQLITE_EXTERN char *sqlite3_temp_directory;
  2898   3739   
  2899   3740   /*
  2900   3741   ** CAPI3REF:  Test To See If The Database Is In Auto-Commit Mode {F12930}
  2901   3742   **
  2902         -** {F12931} The sqlite3_get_autocommit() interfaces returns non-zero or
         3743  +** The sqlite3_get_autocommit() interfaces returns non-zero or
  2903   3744   ** zero if the given database connection is or is not in autocommit mode,
  2904         -** respectively. {F12932}  Autocommit mode is on
  2905         -** by default.  {F12933} Autocommit mode is disabled by a BEGIN statement.
  2906         -** {F12934} Autocommit mode is reenabled by a COMMIT or ROLLBACK. {END}
         3745  +** respectively.   Autocommit mode is on
         3746  +** by default.  Autocommit mode is disabled by a [BEGIN] statement.
         3747  +** Autocommit mode is reenabled by a [COMMIT] or [ROLLBACK].
  2907   3748   **
  2908   3749   ** If certain kinds of errors occur on a statement within a multi-statement
  2909   3750   ** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR], 
  2910   3751   ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
  2911         -** transaction might be rolled back automatically.  {F12935} The only way to
         3752  +** transaction might be rolled back automatically.  The only way to
  2912   3753   ** find out if SQLite automatically rolled back the transaction after
  2913         -** an error is to use this function. {END}
         3754  +** an error is to use this function.
  2914   3755   **
         3756  +** INVARIANTS:
         3757  +**
         3758  +** {F12931} The [sqlite3_get_autocommit()] interface returns non-zero or
         3759  +**          zero if the given database connection is or is not in autocommit
         3760  +**          mode, respectively.
         3761  +**
         3762  +** {F12932} Autocommit mode is on by default.
         3763  +**
         3764  +** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement.
         3765  +**
         3766  +** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK]
         3767  +**          statement.
         3768  +** 
         3769  +**
         3770  +** LIMITATIONS:
         3771  +***
  2915   3772   ** {U12936} If another thread changes the autocommit status of the database
  2916         -** connection while this routine is running, then the return value
  2917         -** is undefined. {END}
         3773  +**          connection while this routine is running, then the return value
         3774  +**          is undefined.
  2918   3775   */
  2919   3776   int sqlite3_get_autocommit(sqlite3*);
  2920   3777   
  2921   3778   /*
  2922   3779   ** CAPI3REF:  Find The Database Handle Of A Prepared Statement {F13120}
  2923   3780   **
  2924   3781   ** {F13121} The sqlite3_db_handle interface
  2925   3782   ** returns the [sqlite3*] database handle to which a
  2926         -** [sqlite3_stmt | prepared statement] belongs.
         3783  +** [prepared statement] belongs.
  2927   3784   ** {F13122} the database handle returned by sqlite3_db_handle
  2928   3785   ** is the same database handle that was
  2929   3786   ** the first argument to the [sqlite3_prepare_v2()] or its variants
  2930   3787   ** that was used to create the statement in the first place.
  2931   3788   */
  2932   3789   sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
  2933   3790   
................................................................................
  3024   3881   ** that was in effect at the time they were opened. {END}
  3025   3882   **
  3026   3883   ** Virtual tables cannot be used with a shared cache.  {F10336} When shared
  3027   3884   ** cache is enabled, the [sqlite3_create_module()] API used to register
  3028   3885   ** virtual tables will always return an error. {END}
  3029   3886   **
  3030   3887   ** {F10337} This routine returns [SQLITE_OK] if shared cache was
  3031         -** enabled or disabled successfully.  {F10338} An [SQLITE_ERROR | error code]
         3888  +** enabled or disabled successfully.  {F10338} An [error code]
  3032   3889   ** is returned otherwise. {END}
  3033   3890   **
  3034   3891   ** {F10339} Shared cache is disabled by default. {END} But this might change in
  3035   3892   ** future releases of SQLite.  Applications that care about shared
  3036   3893   ** cache setting should set it explicitly.
  3037   3894   */
  3038   3895   int sqlite3_enable_shared_cache(int);
................................................................................
  3571   4428   ** z from the open blob, starting at offset iOffset.
  3572   4429   **
  3573   4430   ** {F17852} If offset iOffset is less than n bytes from the end of the blob, 
  3574   4431   ** [SQLITE_ERROR] is returned and no data is read.  {F17853} If n is
  3575   4432   ** less than zero [SQLITE_ERROR] is returned and no data is read.
  3576   4433   **
  3577   4434   ** {F17854} On success, SQLITE_OK is returned. Otherwise, an 
  3578         -** [SQLITE_ERROR | SQLite error code] or an
  3579         -** [SQLITE_IOERR_READ | extended error code] is returned.
         4435  +** [error code] or an [extended error code] is returned.
  3580   4436   */
  3581   4437   int sqlite3_blob_read(sqlite3_blob *, void *z, int n, int iOffset);
  3582   4438   
  3583   4439   /*
  3584   4440   ** CAPI3REF:  Write Data Into A BLOB Incrementally {F17870}
  3585   4441   **
  3586   4442   ** This function is used to write data into an open 
................................................................................
  3595   4451   ** {F17873} This function may only modify the contents of the blob; it is
  3596   4452   ** not possible to increase the size of a blob using this API.
  3597   4453   ** {F17874} If offset iOffset is less than n bytes from the end of the blob, 
  3598   4454   ** [SQLITE_ERROR] is returned and no data is written.  {F17875} If n is
  3599   4455   ** less than zero [SQLITE_ERROR] is returned and no data is written.
  3600   4456   **
  3601   4457   ** {F17876} On success, SQLITE_OK is returned. Otherwise, an 
  3602         -** [SQLITE_ERROR | SQLite error code] or an
  3603         -** [SQLITE_IOERR_READ | extended error code] is returned.
         4458  +** [error code] or an [extended error code] is returned.
  3604   4459   */
  3605   4460   int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
  3606   4461   
  3607   4462   /*
  3608   4463   ** CAPI3REF:  Virtual File System Objects {F11200}
  3609   4464   **
  3610   4465   ** A virtual filesystem (VFS) is an [sqlite3_vfs] object