sqllogictest
Check-in [b23e3b6dbe]
Not logged in

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

Overview
Comment:Update the SQLite amalgamation to version 3.6.22 RC2.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:b23e3b6dbeebc1a1a3f7b762dea09e7a979e33d6
User & Date: drh 2010-01-05 15:58:41
Context
2010-03-09
16:52
Update SQLite to pre-3.6.23. check-in: 10318b880c user: drh tags: trunk
2010-01-05
15:58
Update the SQLite amalgamation to version 3.6.22 RC2. check-in: b23e3b6dbe user: drh tags: trunk
2009-11-02
17:53
Update the SQLite implementation to the 3.6.20 release candidate. check-in: 2c7d3524b6 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite3.c.

more than 10,000 changes

Changes to src/sqlite3.h.

    77     77   # undef SQLITE_VERSION
    78     78   #endif
    79     79   #ifdef SQLITE_VERSION_NUMBER
    80     80   # undef SQLITE_VERSION_NUMBER
    81     81   #endif
    82     82   
    83     83   /*
    84         -** CAPI3REF: Compile-Time Library Version Numbers {H10010} <S60100>
           84  +** CAPI3REF: Compile-Time Library Version Numbers
    85     85   **
    86         -** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in
    87         -** the sqlite3.h file specify the version of SQLite with which
    88         -** that header file is associated.
    89         -**
    90         -** The "version" of SQLite is a string of the form "W.X.Y" or "W.X.Y.Z".
    91         -** The W value is major version number and is always 3 in SQLite3.
    92         -** The W value only changes when backwards compatibility is
    93         -** broken and we intend to never break backwards compatibility.
    94         -** The X value is the minor version number and only changes when
    95         -** there are major feature enhancements that are forwards compatible
    96         -** but not backwards compatible.
    97         -** The Y value is the release number and is incremented with
    98         -** each release but resets back to 0 whenever X is incremented.
    99         -** The Z value only appears on branch releases.
   100         -**
   101         -** The SQLITE_VERSION_NUMBER is an integer that is computed as
   102         -** follows:
   103         -**
   104         -** <blockquote><pre>
   105         -** SQLITE_VERSION_NUMBER = W*1000000 + X*1000 + Y
   106         -** </pre></blockquote>
           86  +** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
           87  +** evaluates to a string literal that is the SQLite version in the
           88  +** format "X.Y.Z" where X is the major version number (always 3 for
           89  +** SQLite3) and Y is the minor version number and Z is the release number.)^
           90  +** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
           91  +** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
           92  +** numbers used in [SQLITE_VERSION].)^
           93  +** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
           94  +** be larger than the release from which it is derived.  Either Y will
           95  +** be held constant and Z will be incremented or else Y will be incremented
           96  +** and Z will be reset to zero.
   107     97   **
   108     98   ** Since version 3.6.18, SQLite source code has been stored in the
   109         -** <a href="http://www.fossil-scm.org/">fossil configuration management
   110         -** system</a>.  The SQLITE_SOURCE_ID
   111         -** macro is a string which identifies a particular check-in of SQLite
   112         -** within its configuration management system.  The string contains the
   113         -** date and time of the check-in (UTC) and an SHA1 hash of the entire
   114         -** source tree.
           99  +** <a href="http://www.fossil-scm.org/">Fossil configuration management
          100  +** system</a>.  ^The SQLITE_SOURCE_ID macro evalutes to
          101  +** a string which identifies a particular check-in of SQLite
          102  +** within its configuration management system.  ^The SQLITE_SOURCE_ID
          103  +** string contains the date and time of the check-in (UTC) and an SHA1
          104  +** hash of the entire source tree.
   115    105   **
   116    106   ** See also: [sqlite3_libversion()],
   117    107   ** [sqlite3_libversion_number()], [sqlite3_sourceid()],
   118    108   ** [sqlite_version()] and [sqlite_source_id()].
   119         -**
   120         -** Requirements: [H10011] [H10014]
   121    109   */
   122         -#define SQLITE_VERSION        "3.6.20"
   123         -#define SQLITE_VERSION_NUMBER 3006020
   124         -#define SQLITE_SOURCE_ID      "2009-11-02 17:40:08 f19cb105d929f0a56f9597b6eb33ad96d0f7eddc"
          110  +#define SQLITE_VERSION        "3.6.22"
          111  +#define SQLITE_VERSION_NUMBER 3006022
          112  +#define SQLITE_SOURCE_ID      "2010-01-05 15:30:36 28d0d7710761114a44a1a3a425a6883c661f06e7"
   125    113   
   126    114   /*
   127         -** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100>
          115  +** CAPI3REF: Run-Time Library Version Numbers
   128    116   ** KEYWORDS: sqlite3_version
   129    117   **
   130    118   ** These interfaces provide the same information as the [SQLITE_VERSION],
   131         -** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] #defines in the header,
   132         -** but are associated with the library instead of the header file.  Cautious
          119  +** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
          120  +** but are associated with the library instead of the header file.  ^(Cautious
   133    121   ** programmers might include assert() statements in their application to
   134    122   ** verify that values returned by these interfaces match the macros in
   135    123   ** the header, and thus insure that the application is
   136    124   ** compiled with matching library and header files.
   137    125   **
   138    126   ** <blockquote><pre>
   139    127   ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
   140    128   ** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
   141         -** assert( strcmp(sqlite3_libversion,SQLITE_VERSION)==0 );
   142         -** </pre></blockquote>
          129  +** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
          130  +** </pre></blockquote>)^
   143    131   **
   144         -** The sqlite3_libversion() function returns the same information as is
   145         -** in the sqlite3_version[] string constant.  The function is provided
   146         -** for use in DLLs since DLL users usually do not have direct access to string
   147         -** constants within the DLL.  Similarly, the sqlite3_sourceid() function
   148         -** returns the same information as is in the [SQLITE_SOURCE_ID] #define of
   149         -** the header file.
          132  +** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
          133  +** macro.  ^The sqlite3_libversion() function returns a pointer to the
          134  +** to the sqlite3_version[] string constant.  The sqlite3_libversion()
          135  +** function is provided for use in DLLs since DLL users usually do not have
          136  +** direct access to string constants within the DLL.  ^The
          137  +** sqlite3_libversion_number() function returns an integer equal to
          138  +** [SQLITE_VERSION_NUMBER].  ^The sqlite3_sourceid() function a pointer
          139  +** to a string constant whose value is the same as the [SQLITE_SOURCE_ID]
          140  +** C preprocessor macro.
   150    141   **
   151    142   ** See also: [sqlite_version()] and [sqlite_source_id()].
   152         -**
   153         -** Requirements: [H10021] [H10022] [H10023]
   154    143   */
   155    144   SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
   156    145   SQLITE_API const char *sqlite3_libversion(void);
   157    146   SQLITE_API const char *sqlite3_sourceid(void);
   158    147   SQLITE_API int sqlite3_libversion_number(void);
   159    148   
   160    149   /*
   161         -** CAPI3REF: Test To See If The Library Is Threadsafe {H10100} <S60100>
          150  +** CAPI3REF: Test To See If The Library Is Threadsafe
          151  +**
          152  +** ^The sqlite3_threadsafe() function returns zero if and only if
          153  +** SQLite was compiled mutexing code omitted due to the
          154  +** [SQLITE_THREADSAFE] compile-time option being set to 0.
   162    155   **
   163    156   ** SQLite can be compiled with or without mutexes.  When
   164    157   ** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
   165    158   ** are enabled and SQLite is threadsafe.  When the
   166    159   ** [SQLITE_THREADSAFE] macro is 0, 
   167    160   ** the mutexes are omitted.  Without the mutexes, it is not safe
   168    161   ** to use SQLite concurrently from more than one thread.
   169    162   **
   170    163   ** Enabling mutexes incurs a measurable performance penalty.
   171    164   ** So if speed is of utmost importance, it makes sense to disable
   172    165   ** the mutexes.  But for maximum safety, mutexes should be enabled.
   173         -** The default behavior is for mutexes to be enabled.
          166  +** ^The default behavior is for mutexes to be enabled.
   174    167   **
   175    168   ** This interface can be used by an application to make sure that the
   176    169   ** version of SQLite that it is linking against was compiled with
   177    170   ** the desired setting of the [SQLITE_THREADSAFE] macro.
   178    171   **
   179    172   ** This interface only reports on the compile-time mutex setting
   180    173   ** of the [SQLITE_THREADSAFE] flag.  If SQLite is compiled with
   181         -** SQLITE_THREADSAFE=1 then mutexes are enabled by default but
          174  +** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
   182    175   ** can be fully or partially disabled using a call to [sqlite3_config()]
   183    176   ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
   184         -** or [SQLITE_CONFIG_MUTEX].  The return value of this function shows
   185         -** only the default compile-time setting, not any run-time changes
   186         -** to that setting.
          177  +** or [SQLITE_CONFIG_MUTEX].  ^(The return value of the
          178  +** sqlite3_threadsafe() function shows only the compile-time setting of
          179  +** thread safety, not any run-time changes to that setting made by
          180  +** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
          181  +** is unchanged by calls to sqlite3_config().)^
   187    182   **
   188    183   ** See the [threading mode] documentation for additional information.
   189         -**
   190         -** Requirements: [H10101] [H10102]
   191    184   */
   192    185   SQLITE_API int sqlite3_threadsafe(void);
   193    186   
   194    187   /*
   195         -** CAPI3REF: Database Connection Handle {H12000} <S40200>
          188  +** CAPI3REF: Database Connection Handle
   196    189   ** KEYWORDS: {database connection} {database connections}
   197    190   **
   198    191   ** Each open SQLite database is represented by a pointer to an instance of
   199    192   ** the opaque structure named "sqlite3".  It is useful to think of an sqlite3
   200    193   ** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and
   201    194   ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
   202    195   ** is its destructor.  There are many other interfaces (such as
................................................................................
   203    196   ** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
   204    197   ** [sqlite3_busy_timeout()] to name but three) that are methods on an
   205    198   ** sqlite3 object.
   206    199   */
   207    200   typedef struct sqlite3 sqlite3;
   208    201   
   209    202   /*
   210         -** CAPI3REF: 64-Bit Integer Types {H10200} <S10110>
          203  +** CAPI3REF: 64-Bit Integer Types
   211    204   ** KEYWORDS: sqlite_int64 sqlite_uint64
   212    205   **
   213    206   ** Because there is no cross-platform way to specify 64-bit integer types
   214    207   ** SQLite includes typedefs for 64-bit signed and unsigned integers.
   215    208   **
   216    209   ** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
   217    210   ** The sqlite_int64 and sqlite_uint64 types are supported for backwards
   218    211   ** compatibility only.
   219    212   **
   220         -** Requirements: [H10201] [H10202]
          213  +** ^The sqlite3_int64 and sqlite_int64 types can store integer values
          214  +** between -9223372036854775808 and +9223372036854775807 inclusive.  ^The
          215  +** sqlite3_uint64 and sqlite_uint64 types can store integer values 
          216  +** between 0 and +18446744073709551615 inclusive.
   221    217   */
   222    218   #ifdef SQLITE_INT64_TYPE
   223    219     typedef SQLITE_INT64_TYPE sqlite_int64;
   224    220     typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
   225    221   #elif defined(_MSC_VER) || defined(__BORLANDC__)
   226    222     typedef __int64 sqlite_int64;
   227    223     typedef unsigned __int64 sqlite_uint64;
................................................................................
   237    233   ** substitute integer for floating-point.
   238    234   */
   239    235   #ifdef SQLITE_OMIT_FLOATING_POINT
   240    236   # define double sqlite3_int64
   241    237   #endif
   242    238   
   243    239   /*
   244         -** CAPI3REF: Closing A Database Connection {H12010} <S30100><S40200>
          240  +** CAPI3REF: Closing A Database Connection
   245    241   **
   246         -** This routine is the destructor for the [sqlite3] object.
          242  +** ^The sqlite3_close() routine is the destructor for the [sqlite3] object.
          243  +** ^Calls to sqlite3_close() return SQLITE_OK if the [sqlite3] object is
          244  +** successfullly destroyed and all associated resources are deallocated.
   247    245   **
   248    246   ** Applications must [sqlite3_finalize | finalize] all [prepared statements]
   249    247   ** and [sqlite3_blob_close | close] all [BLOB handles] associated with
   250         -** the [sqlite3] object prior to attempting to close the object.
          248  +** the [sqlite3] object prior to attempting to close the object.  ^If
          249  +** sqlite3_close() is called on a [database connection] that still has
          250  +** outstanding [prepared statements] or [BLOB handles], then it returns
          251  +** SQLITE_BUSY.
   251    252   **
   252         -** If [sqlite3_close()] is invoked while a transaction is open,
          253  +** ^If [sqlite3_close()] is invoked while a transaction is open,
   253    254   ** the transaction is automatically rolled back.
   254    255   **
   255    256   ** The C parameter to [sqlite3_close(C)] must be either a NULL
   256    257   ** pointer or an [sqlite3] object pointer obtained
   257    258   ** from [sqlite3_open()], [sqlite3_open16()], or
   258    259   ** [sqlite3_open_v2()], and not previously closed.
   259         -**
   260         -** Requirements:
   261         -** [H12011] [H12012] [H12013] [H12014] [H12015] [H12019]
          260  +** ^Calling sqlite3_close() with a NULL pointer argument is a 
          261  +** harmless no-op.
   262    262   */
   263    263   SQLITE_API int sqlite3_close(sqlite3 *);
   264    264   
   265    265   /*
   266    266   ** The type for a callback function.
   267    267   ** This is legacy and deprecated.  It is included for historical
   268    268   ** compatibility and is not documented.
   269    269   */
   270    270   typedef int (*sqlite3_callback)(void*,int,char**, char**);
   271    271   
   272    272   /*
   273         -** CAPI3REF: One-Step Query Execution Interface {H12100} <S10000>
   274         -**
   275         -** The sqlite3_exec() interface is a convenient way of running one or more
   276         -** SQL statements without having to write a lot of C code.  The UTF-8 encoded
   277         -** SQL statements are passed in as the second parameter to sqlite3_exec().
   278         -** The statements are evaluated one by one until either an error or
   279         -** an interrupt is encountered, or until they are all done.  The 3rd parameter
   280         -** is an optional callback that is invoked once for each row of any query
   281         -** results produced by the SQL statements.  The 5th parameter tells where
   282         -** to write any error messages.
   283         -**
   284         -** The error message passed back through the 5th parameter is held
   285         -** in memory obtained from [sqlite3_malloc()].  To avoid a memory leak,
   286         -** the calling application should call [sqlite3_free()] on any error
   287         -** message returned through the 5th parameter when it has finished using
   288         -** the error message.
   289         -**
   290         -** If the SQL statement in the 2nd parameter is NULL or an empty string
   291         -** or a string containing only whitespace and comments, then no SQL
   292         -** statements are evaluated and the database is not changed.
   293         -**
   294         -** The sqlite3_exec() interface is implemented in terms of
   295         -** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
   296         -** The sqlite3_exec() routine does nothing to the database that cannot be done
   297         -** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
   298         -**
   299         -** The first parameter to [sqlite3_exec()] must be an valid and open
   300         -** [database connection].
   301         -**
   302         -** The database connection must not be closed while
   303         -** [sqlite3_exec()] is running.
   304         -**
   305         -** The calling function should use [sqlite3_free()] to free
   306         -** the memory that *errmsg is left pointing at once the error
   307         -** message is no longer needed.
   308         -**
   309         -** The SQL statement text in the 2nd parameter to [sqlite3_exec()]
   310         -** must remain unchanged while [sqlite3_exec()] is running.
   311         -**
   312         -** Requirements:
   313         -** [H12101] [H12102] [H12104] [H12105] [H12107] [H12110] [H12113] [H12116]
   314         -** [H12119] [H12122] [H12125] [H12131] [H12134] [H12137] [H12138]
          273  +** CAPI3REF: One-Step Query Execution Interface
          274  +**
          275  +** The sqlite3_exec() interface is a convenience wrapper around
          276  +** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
          277  +** that allows an application to run multiple statements of SQL
          278  +** without having to use a lot of C code. 
          279  +**
          280  +** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
          281  +** semicolon-separate SQL statements passed into its 2nd argument,
          282  +** in the context of the [database connection] passed in as its 1st
          283  +** argument.  ^If the callback function of the 3rd argument to
          284  +** sqlite3_exec() is not NULL, then it is invoked for each result row
          285  +** coming out of the evaluated SQL statements.  ^The 4th argument to
          286  +** to sqlite3_exec() is relayed through to the 1st argument of each
          287  +** callback invocation.  ^If the callback pointer to sqlite3_exec()
          288  +** is NULL, then no callback is ever invoked and result rows are
          289  +** ignored.
          290  +**
          291  +** ^If an error occurs while evaluating the SQL statements passed into
          292  +** sqlite3_exec(), then execution of the current statement stops and
          293  +** subsequent statements are skipped.  ^If the 5th parameter to sqlite3_exec()
          294  +** is not NULL then any error message is written into memory obtained
          295  +** from [sqlite3_malloc()] and passed back through the 5th parameter.
          296  +** To avoid memory leaks, the application should invoke [sqlite3_free()]
          297  +** on error message strings returned through the 5th parameter of
          298  +** of sqlite3_exec() after the error message string is no longer needed.
          299  +** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
          300  +** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
          301  +** NULL before returning.
          302  +**
          303  +** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
          304  +** routine returns SQLITE_ABORT without invoking the callback again and
          305  +** without running any subsequent SQL statements.
          306  +**
          307  +** ^The 2nd argument to the sqlite3_exec() callback function is the
          308  +** number of columns in the result.  ^The 3rd argument to the sqlite3_exec()
          309  +** callback is an array of pointers to strings obtained as if from
          310  +** [sqlite3_column_text()], one for each column.  ^If an element of a
          311  +** result row is NULL then the corresponding string pointer for the
          312  +** sqlite3_exec() callback is a NULL pointer.  ^The 4th argument to the
          313  +** sqlite3_exec() callback is an array of pointers to strings where each
          314  +** entry represents the name of corresponding result column as obtained
          315  +** from [sqlite3_column_name()].
          316  +**
          317  +** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
          318  +** to an empty string, or a pointer that contains only whitespace and/or 
          319  +** SQL comments, then no SQL statements are evaluated and the database
          320  +** is not changed.
          321  +**
          322  +** Restrictions:
          323  +**
          324  +** <ul>
          325  +** <li> The application must insure that the 1st parameter to sqlite3_exec()
          326  +**      is a valid and open [database connection].
          327  +** <li> The application must not close [database connection] specified by
          328  +**      the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
          329  +** <li> The application must not modify the SQL statement text passed into
          330  +**      the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
          331  +** </ul>
   315    332   */
   316    333   SQLITE_API int sqlite3_exec(
   317    334     sqlite3*,                                  /* An open database */
   318    335     const char *sql,                           /* SQL to be evaluated */
   319    336     int (*callback)(void*,int,char**,char**),  /* Callback function */
   320    337     void *,                                    /* 1st argument to callback */
   321    338     char **errmsg                              /* Error msg written here */
   322    339   );
   323    340   
   324    341   /*
   325         -** CAPI3REF: Result Codes {H10210} <S10700>
          342  +** CAPI3REF: Result Codes
   326    343   ** KEYWORDS: SQLITE_OK {error code} {error codes}
   327    344   ** KEYWORDS: {result code} {result codes}
   328    345   **
   329    346   ** Many SQLite functions return an integer result code from the set shown
   330    347   ** here in order to indicates success or failure.
   331    348   **
   332    349   ** New error codes may be added in future versions of SQLite.
................................................................................
   362    379   #define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
   363    380   #define SQLITE_NOTADB      26   /* File opened that is not a database file */
   364    381   #define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
   365    382   #define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
   366    383   /* end-of-error-codes */
   367    384   
   368    385   /*
   369         -** CAPI3REF: Extended Result Codes {H10220} <S10700>
          386  +** CAPI3REF: Extended Result Codes
   370    387   ** KEYWORDS: {extended error code} {extended error codes}
   371    388   ** KEYWORDS: {extended result code} {extended result codes}
   372    389   **
   373    390   ** In its default configuration, SQLite API routines return one of 26 integer
   374    391   ** [SQLITE_OK | result codes].  However, experience has shown that many of
   375    392   ** these result codes are too coarse-grained.  They do not provide as
   376    393   ** much information about problems as programmers might like.  In an effort to
................................................................................
   404    421   #define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
   405    422   #define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
   406    423   #define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
   407    424   #define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
   408    425   #define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED | (1<<8) )
   409    426   
   410    427   /*
   411         -** CAPI3REF: Flags For File Open Operations {H10230} <H11120> <H12700>
          428  +** CAPI3REF: Flags For File Open Operations
   412    429   **
   413    430   ** These bit values are intended for use in the
   414    431   ** 3rd parameter to the [sqlite3_open_v2()] interface and
   415    432   ** in the 4th parameter to the xOpen method of the
   416    433   ** [sqlite3_vfs] object.
   417    434   */
   418    435   #define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */
................................................................................
   429    446   #define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */
   430    447   #define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
   431    448   #define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
   432    449   #define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */
   433    450   #define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */
   434    451   
   435    452   /*
   436         -** CAPI3REF: Device Characteristics {H10240} <H11120>
          453  +** CAPI3REF: Device Characteristics
   437    454   **
   438    455   ** The xDeviceCapabilities method of the [sqlite3_io_methods]
   439    456   ** object returns an integer which is a vector of the these
   440    457   ** bit values expressing I/O characteristics of the mass storage
   441    458   ** device that holds the file that the [sqlite3_io_methods]
   442    459   ** refers to.
   443    460   **
................................................................................
   461    478   #define SQLITE_IOCAP_ATOMIC16K       0x00000040
   462    479   #define SQLITE_IOCAP_ATOMIC32K       0x00000080
   463    480   #define SQLITE_IOCAP_ATOMIC64K       0x00000100
   464    481   #define SQLITE_IOCAP_SAFE_APPEND     0x00000200
   465    482   #define SQLITE_IOCAP_SEQUENTIAL      0x00000400
   466    483   
   467    484   /*
   468         -** CAPI3REF: File Locking Levels {H10250} <H11120> <H11310>
          485  +** CAPI3REF: File Locking Levels
   469    486   **
   470    487   ** SQLite uses one of these integer values as the second
   471    488   ** argument to calls it makes to the xLock() and xUnlock() methods
   472    489   ** of an [sqlite3_io_methods] object.
   473    490   */
   474    491   #define SQLITE_LOCK_NONE          0
   475    492   #define SQLITE_LOCK_SHARED        1
   476    493   #define SQLITE_LOCK_RESERVED      2
   477    494   #define SQLITE_LOCK_PENDING       3
   478    495   #define SQLITE_LOCK_EXCLUSIVE     4
   479    496   
   480    497   /*
   481         -** CAPI3REF: Synchronization Type Flags {H10260} <H11120>
          498  +** CAPI3REF: Synchronization Type Flags
   482    499   **
   483    500   ** When SQLite invokes the xSync() method of an
   484    501   ** [sqlite3_io_methods] object it uses a combination of
   485    502   ** these integer values as the second argument.
   486    503   **
   487    504   ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
   488    505   ** sync operation only needs to flush data to mass storage.  Inode
................................................................................
   492    509   ** to use Mac OS X style fullsync instead of fsync().
   493    510   */
   494    511   #define SQLITE_SYNC_NORMAL        0x00002
   495    512   #define SQLITE_SYNC_FULL          0x00003
   496    513   #define SQLITE_SYNC_DATAONLY      0x00010
   497    514   
   498    515   /*
   499         -** CAPI3REF: OS Interface Open File Handle {H11110} <S20110>
          516  +** CAPI3REF: OS Interface Open File Handle
   500    517   **
   501    518   ** An [sqlite3_file] object represents an open file in the 
   502    519   ** [sqlite3_vfs | OS interface layer].  Individual OS interface
   503    520   ** implementations will
   504    521   ** want to subclass this object by appending additional fields
   505    522   ** for their own use.  The pMethods entry is a pointer to an
   506    523   ** [sqlite3_io_methods] object that defines methods for performing
................................................................................
   508    525   */
   509    526   typedef struct sqlite3_file sqlite3_file;
   510    527   struct sqlite3_file {
   511    528     const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
   512    529   };
   513    530   
   514    531   /*
   515         -** CAPI3REF: OS Interface File Virtual Methods Object {H11120} <S20110>
          532  +** CAPI3REF: OS Interface File Virtual Methods Object
   516    533   **
   517    534   ** Every file opened by the [sqlite3_vfs] xOpen method populates an
   518    535   ** [sqlite3_file] object (or, more commonly, a subclass of the
   519    536   ** [sqlite3_file] object) with a pointer to an instance of this object.
   520    537   ** This object defines the methods used to perform various operations
   521    538   ** against the open file represented by the [sqlite3_file] object.
   522    539   **
................................................................................
   613    630     int (*xFileControl)(sqlite3_file*, int op, void *pArg);
   614    631     int (*xSectorSize)(sqlite3_file*);
   615    632     int (*xDeviceCharacteristics)(sqlite3_file*);
   616    633     /* Additional methods may be added in future releases */
   617    634   };
   618    635   
   619    636   /*
   620         -** CAPI3REF: Standard File Control Opcodes {H11310} <S30800>
          637  +** CAPI3REF: Standard File Control Opcodes
   621    638   **
   622    639   ** These integer constants are opcodes for the xFileControl method
   623    640   ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
   624    641   ** interface.
   625    642   **
   626    643   ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
   627    644   ** opcode causes the xFileControl method to write the current state of
................................................................................
   633    650   */
   634    651   #define SQLITE_FCNTL_LOCKSTATE        1
   635    652   #define SQLITE_GET_LOCKPROXYFILE      2
   636    653   #define SQLITE_SET_LOCKPROXYFILE      3
   637    654   #define SQLITE_LAST_ERRNO             4
   638    655   
   639    656   /*
   640         -** CAPI3REF: Mutex Handle {H17110} <S20130>
          657  +** CAPI3REF: Mutex Handle
   641    658   **
   642    659   ** The mutex module within SQLite defines [sqlite3_mutex] to be an
   643    660   ** abstract type for a mutex object.  The SQLite core never looks
   644    661   ** at the internal representation of an [sqlite3_mutex].  It only
   645    662   ** deals with pointers to the [sqlite3_mutex] object.
   646    663   **
   647    664   ** Mutexes are created using [sqlite3_mutex_alloc()].
   648    665   */
   649    666   typedef struct sqlite3_mutex sqlite3_mutex;
   650    667   
   651    668   /*
   652         -** CAPI3REF: OS Interface Object {H11140} <S20100>
          669  +** CAPI3REF: OS Interface Object
   653    670   **
   654    671   ** An instance of the sqlite3_vfs object defines the interface between
   655    672   ** the SQLite core and the underlying operating system.  The "vfs"
   656    673   ** in the name of the object stands for "virtual file system".
   657    674   **
   658    675   ** The value of the iVersion field is initially 1 but may be larger in
   659    676   ** future versions of SQLite.  Additional fields may be appended to this
................................................................................
   799    816     int (*xCurrentTime)(sqlite3_vfs*, double*);
   800    817     int (*xGetLastError)(sqlite3_vfs*, int, char *);
   801    818     /* New fields may be appended in figure versions.  The iVersion
   802    819     ** value will increment whenever this happens. */
   803    820   };
   804    821   
   805    822   /*
   806         -** CAPI3REF: Flags for the xAccess VFS method {H11190} <H11140>
          823  +** CAPI3REF: Flags for the xAccess VFS method
   807    824   **
   808    825   ** These integer constants can be used as the third parameter to
   809         -** the xAccess method of an [sqlite3_vfs] object. {END}  They determine
          826  +** the xAccess method of an [sqlite3_vfs] object.  They determine
   810    827   ** what kind of permissions the xAccess method is looking for.
   811    828   ** With SQLITE_ACCESS_EXISTS, the xAccess method
   812    829   ** simply checks whether the file exists.
   813    830   ** With SQLITE_ACCESS_READWRITE, the xAccess method
   814    831   ** checks whether the file is both readable and writable.
   815    832   ** With SQLITE_ACCESS_READ, the xAccess method
   816    833   ** checks whether the file is readable.
   817    834   */
   818    835   #define SQLITE_ACCESS_EXISTS    0
   819    836   #define SQLITE_ACCESS_READWRITE 1
   820    837   #define SQLITE_ACCESS_READ      2
   821    838   
   822    839   /*
   823         -** CAPI3REF: Initialize The SQLite Library {H10130} <S20000><S30100>
          840  +** CAPI3REF: Initialize The SQLite Library
   824    841   **
   825         -** The sqlite3_initialize() routine initializes the
   826         -** SQLite library.  The sqlite3_shutdown() routine
          842  +** ^The sqlite3_initialize() routine initializes the
          843  +** SQLite library.  ^The sqlite3_shutdown() routine
   827    844   ** deallocates any resources that were allocated by sqlite3_initialize().
   828         -** This routines are designed to aid in process initialization and
          845  +** These routines are designed to aid in process initialization and
   829    846   ** shutdown on embedded systems.  Workstation applications using
   830    847   ** SQLite normally do not need to invoke either of these routines.
   831    848   **
   832    849   ** A call to sqlite3_initialize() is an "effective" call if it is
   833    850   ** the first time sqlite3_initialize() is invoked during the lifetime of
   834    851   ** the process, or if it is the first time sqlite3_initialize() is invoked
   835         -** following a call to sqlite3_shutdown().  Only an effective call
          852  +** following a call to sqlite3_shutdown().  ^(Only an effective call
   836    853   ** of sqlite3_initialize() does any initialization.  All other calls
   837         -** are harmless no-ops.
          854  +** are harmless no-ops.)^
   838    855   **
   839    856   ** A call to sqlite3_shutdown() is an "effective" call if it is the first
   840         -** call to sqlite3_shutdown() since the last sqlite3_initialize().  Only
          857  +** call to sqlite3_shutdown() since the last sqlite3_initialize().  ^(Only
   841    858   ** an effective call to sqlite3_shutdown() does any deinitialization.
   842         -** All other valid calls to sqlite3_shutdown() are harmless no-ops.
          859  +** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
   843    860   **
   844    861   ** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
   845    862   ** is not.  The sqlite3_shutdown() interface must only be called from a
   846    863   ** single thread.  All open [database connections] must be closed and all
   847    864   ** other SQLite resources must be deallocated prior to invoking
   848    865   ** sqlite3_shutdown().
   849    866   **
   850         -** Among other things, sqlite3_initialize() will invoke
   851         -** sqlite3_os_init().  Similarly, sqlite3_shutdown()
          867  +** Among other things, ^sqlite3_initialize() will invoke
          868  +** sqlite3_os_init().  Similarly, ^sqlite3_shutdown()
   852    869   ** will invoke sqlite3_os_end().
   853    870   **
   854         -** The sqlite3_initialize() routine returns [SQLITE_OK] on success.
   855         -** If for some reason, sqlite3_initialize() is unable to initialize
          871  +** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
          872  +** ^If for some reason, sqlite3_initialize() is unable to initialize
   856    873   ** the library (perhaps it is unable to allocate a needed resource such
   857    874   ** as a mutex) it returns an [error code] other than [SQLITE_OK].
   858    875   **
   859         -** The sqlite3_initialize() routine is called internally by many other
          876  +** ^The sqlite3_initialize() routine is called internally by many other
   860    877   ** SQLite interfaces so that an application usually does not need to
   861    878   ** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]
   862    879   ** calls sqlite3_initialize() so the SQLite library will be automatically
   863    880   ** initialized when [sqlite3_open()] is called if it has not be initialized
   864         -** already.  However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
          881  +** already.  ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
   865    882   ** compile-time option, then the automatic calls to sqlite3_initialize()
   866    883   ** are omitted and the application must call sqlite3_initialize() directly
   867    884   ** prior to using any other SQLite interface.  For maximum portability,
   868    885   ** it is recommended that applications always invoke sqlite3_initialize()
   869    886   ** directly prior to using any other SQLite interface.  Future releases
   870    887   ** of SQLite may require this.  In other words, the behavior exhibited
   871    888   ** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
................................................................................
   896    913   */
   897    914   SQLITE_API int sqlite3_initialize(void);
   898    915   SQLITE_API int sqlite3_shutdown(void);
   899    916   SQLITE_API int sqlite3_os_init(void);
   900    917   SQLITE_API int sqlite3_os_end(void);
   901    918   
   902    919   /*
   903         -** CAPI3REF: Configuring The SQLite Library {H14100} <S20000><S30200>
          920  +** CAPI3REF: Configuring The SQLite Library
   904    921   ** EXPERIMENTAL
   905    922   **
   906    923   ** The sqlite3_config() interface is used to make global configuration
   907    924   ** changes to SQLite in order to tune SQLite to the specific needs of
   908    925   ** the application.  The default configuration is recommended for most
   909    926   ** applications and so this routine is usually not necessary.  It is
   910    927   ** provided to support rare applications with unusual needs.
   911    928   **
   912    929   ** The sqlite3_config() interface is not threadsafe.  The application
   913    930   ** must insure that no other SQLite interfaces are invoked by other
   914    931   ** threads while sqlite3_config() is running.  Furthermore, sqlite3_config()
   915    932   ** may only be invoked prior to library initialization using
   916    933   ** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
   917         -** Note, however, that sqlite3_config() can be called as part of the
          934  +** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
          935  +** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
          936  +** Note, however, that ^sqlite3_config() can be called as part of the
   918    937   ** implementation of an application-defined [sqlite3_os_init()].
   919    938   **
   920    939   ** The first argument to sqlite3_config() is an integer
   921    940   ** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines
   922    941   ** what property of SQLite is to be configured.  Subsequent arguments
   923    942   ** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option]
   924    943   ** in the first argument.
   925    944   **
   926         -** When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
   927         -** If the option is unknown or SQLite is unable to set the option
          945  +** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
          946  +** ^If the option is unknown or SQLite is unable to set the option
   928    947   ** then this routine returns a non-zero [error code].
   929         -**
   930         -** Requirements:
   931         -** [H14103] [H14106] [H14120] [H14123] [H14126] [H14129] [H14132] [H14135]
   932         -** [H14138] [H14141] [H14144] [H14147] [H14150] [H14153] [H14156] [H14159]
   933         -** [H14162] [H14165] [H14168]
   934    948   */
   935    949   SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_config(int, ...);
   936    950   
   937    951   /*
   938         -** CAPI3REF: Configure database connections  {H14200} <S20000>
          952  +** CAPI3REF: Configure database connections
   939    953   ** EXPERIMENTAL
   940    954   **
   941    955   ** The sqlite3_db_config() interface is used to make configuration
   942    956   ** changes to a [database connection].  The interface is similar to
   943    957   ** [sqlite3_config()] except that the changes apply to a single
   944    958   ** [database connection] (specified in the first argument).  The
   945         -** sqlite3_db_config() interface can only be used immediately after
          959  +** sqlite3_db_config() interface should only be used immediately after
   946    960   ** the database connection is created using [sqlite3_open()],
   947    961   ** [sqlite3_open16()], or [sqlite3_open_v2()].  
   948    962   **
   949    963   ** The second argument to sqlite3_db_config(D,V,...)  is the
   950    964   ** configuration verb - an integer code that indicates what
   951    965   ** aspect of the [database connection] is being configured.
   952    966   ** The only choice for this value is [SQLITE_DBCONFIG_LOOKASIDE].
   953    967   ** New verbs are likely to be added in future releases of SQLite.
   954    968   ** Additional arguments depend on the verb.
   955    969   **
   956         -** Requirements:
   957         -** [H14203] [H14206] [H14209] [H14212] [H14215]
          970  +** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
          971  +** the call is considered successful.
   958    972   */
   959    973   SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
   960    974   
   961    975   /*
   962         -** CAPI3REF: Memory Allocation Routines {H10155} <S20120>
          976  +** CAPI3REF: Memory Allocation Routines
   963    977   ** EXPERIMENTAL
   964    978   **
   965    979   ** An instance of this object defines the interface between SQLite
   966    980   ** and low-level memory allocation routines.
   967    981   **
   968    982   ** This object is used in only one place in the SQLite interface.
   969    983   ** A pointer to an instance of this object is the argument to
................................................................................
   985    999   ** conditions.
   986   1000   **
   987   1001   ** The xMalloc and xFree methods must work like the
   988   1002   ** malloc() and free() functions from the standard C library.
   989   1003   ** The xRealloc method must work like realloc() from the standard C library
   990   1004   ** with the exception that if the second argument to xRealloc is zero,
   991   1005   ** xRealloc must be a no-op - it must not perform any allocation or
   992         -** deallocation.  SQLite guaranteeds that the second argument to
         1006  +** deallocation.  ^SQLite guarantees that the second argument to
   993   1007   ** xRealloc is always a value returned by a prior call to xRoundup.
   994   1008   ** And so in cases where xRoundup always returns a positive number,
   995   1009   ** xRealloc can perform exactly as the standard library realloc() and
   996   1010   ** still be in compliance with this specification.
   997   1011   **
   998   1012   ** xSize should return the allocated size of a memory allocation
   999   1013   ** previously obtained from xMalloc or xRealloc.  The allocated size
................................................................................
  1037   1051     int (*xRoundup)(int);          /* Round up request size to allocation size */
  1038   1052     int (*xInit)(void*);           /* Initialize the memory allocator */
  1039   1053     void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
  1040   1054     void *pAppData;                /* Argument to xInit() and xShutdown() */
  1041   1055   };
  1042   1056   
  1043   1057   /*
  1044         -** CAPI3REF: Configuration Options {H10160} <S20000>
         1058  +** CAPI3REF: Configuration Options
  1045   1059   ** EXPERIMENTAL
  1046   1060   **
  1047   1061   ** These constants are the available integer configuration options that
  1048   1062   ** can be passed as the first argument to the [sqlite3_config()] interface.
  1049   1063   **
  1050   1064   ** New configuration options may be added in future releases of SQLite.
  1051   1065   ** Existing configuration options might be discontinued.  Applications
................................................................................
  1052   1066   ** should check the return code from [sqlite3_config()] to make sure that
  1053   1067   ** the call worked.  The [sqlite3_config()] interface will return a
  1054   1068   ** non-zero [error code] if a discontinued or unsupported configuration option
  1055   1069   ** is invoked.
  1056   1070   **
  1057   1071   ** <dl>
  1058   1072   ** <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
  1059         -** <dd>There are no arguments to this option.  This option disables
         1073  +** <dd>There are no arguments to this option.  ^This option sets the
         1074  +** [threading mode] to Single-thread.  In other words, it disables
  1060   1075   ** all mutexing and puts SQLite into a mode where it can only be used
  1061         -** by a single thread.</dd>
         1076  +** by a single thread.   ^If SQLite is compiled with
         1077  +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
         1078  +** it is not possible to change the [threading mode] from its default
         1079  +** value of Single-thread and so [sqlite3_config()] will return 
         1080  +** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
         1081  +** configuration option.</dd>
  1062   1082   **
  1063   1083   ** <dt>SQLITE_CONFIG_MULTITHREAD</dt>
  1064         -** <dd>There are no arguments to this option.  This option disables
         1084  +** <dd>There are no arguments to this option.  ^This option sets the
         1085  +** [threading mode] to Multi-thread.  In other words, it disables
  1065   1086   ** mutexing on [database connection] and [prepared statement] objects.
  1066   1087   ** The application is responsible for serializing access to
  1067   1088   ** [database connections] and [prepared statements].  But other mutexes
  1068   1089   ** are enabled so that SQLite will be safe to use in a multi-threaded
  1069   1090   ** environment as long as no two threads attempt to use the same
  1070         -** [database connection] at the same time.  See the [threading mode]
  1071         -** documentation for additional information.</dd>
         1091  +** [database connection] at the same time.  ^If SQLite is compiled with
         1092  +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
         1093  +** it is not possible to set the Multi-thread [threading mode] and
         1094  +** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
         1095  +** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
  1072   1096   **
  1073   1097   ** <dt>SQLITE_CONFIG_SERIALIZED</dt>
  1074         -** <dd>There are no arguments to this option.  This option enables
         1098  +** <dd>There are no arguments to this option.  ^This option sets the
         1099  +** [threading mode] to Serialized. In other words, this option enables
  1075   1100   ** all mutexes including the recursive
  1076   1101   ** mutexes on [database connection] and [prepared statement] objects.
  1077   1102   ** In this mode (which is the default when SQLite is compiled with
  1078   1103   ** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
  1079   1104   ** to [database connections] and [prepared statements] so that the
  1080   1105   ** application is free to use the same [database connection] or the
  1081   1106   ** same [prepared statement] in different threads at the same time.
  1082         -** See the [threading mode] documentation for additional information.</dd>
         1107  +** ^If SQLite is compiled with
         1108  +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
         1109  +** it is not possible to set the Serialized [threading mode] and
         1110  +** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
         1111  +** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
  1083   1112   **
  1084   1113   ** <dt>SQLITE_CONFIG_MALLOC</dt>
  1085         -** <dd>This option takes a single argument which is a pointer to an
         1114  +** <dd> ^(This option takes a single argument which is a pointer to an
  1086   1115   ** instance of the [sqlite3_mem_methods] structure.  The argument specifies
  1087   1116   ** alternative low-level memory allocation routines to be used in place of
  1088         -** the memory allocation routines built into SQLite.</dd>
         1117  +** the memory allocation routines built into SQLite.)^ ^SQLite makes
         1118  +** its own private copy of the content of the [sqlite3_mem_methods] structure
         1119  +** before the [sqlite3_config()] call returns.</dd>
  1089   1120   **
  1090   1121   ** <dt>SQLITE_CONFIG_GETMALLOC</dt>
  1091         -** <dd>This option takes a single argument which is a pointer to an
         1122  +** <dd> ^(This option takes a single argument which is a pointer to an
  1092   1123   ** instance of the [sqlite3_mem_methods] structure.  The [sqlite3_mem_methods]
  1093         -** structure is filled with the currently defined memory allocation routines.
         1124  +** structure is filled with the currently defined memory allocation routines.)^
  1094   1125   ** This option can be used to overload the default memory allocation
  1095   1126   ** routines with a wrapper that simulations memory allocation failure or
  1096         -** tracks memory usage, for example.</dd>
         1127  +** tracks memory usage, for example. </dd>
  1097   1128   **
  1098   1129   ** <dt>SQLITE_CONFIG_MEMSTATUS</dt>
  1099         -** <dd>This option takes single argument of type int, interpreted as a 
         1130  +** <dd> ^This option takes single argument of type int, interpreted as a 
  1100   1131   ** boolean, which enables or disables the collection of memory allocation 
  1101         -** statistics. When disabled, the following SQLite interfaces become 
  1102         -** non-operational:
         1132  +** statistics. ^(When memory allocation statistics are disabled, the 
         1133  +** following SQLite interfaces become non-operational:
  1103   1134   **   <ul>
  1104   1135   **   <li> [sqlite3_memory_used()]
  1105   1136   **   <li> [sqlite3_memory_highwater()]
  1106   1137   **   <li> [sqlite3_soft_heap_limit()]
  1107   1138   **   <li> [sqlite3_status()]
  1108         -**   </ul>
         1139  +**   </ul>)^
         1140  +** ^Memory allocation statistics are enabled by default unless SQLite is
         1141  +** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
         1142  +** allocation statistics are disabled by default.
  1109   1143   ** </dd>
  1110   1144   **
  1111   1145   ** <dt>SQLITE_CONFIG_SCRATCH</dt>
  1112         -** <dd>This option specifies a static memory buffer that SQLite can use for
         1146  +** <dd> ^This option specifies a static memory buffer that SQLite can use for
  1113   1147   ** scratch memory.  There are three arguments:  A pointer an 8-byte
  1114   1148   ** aligned memory buffer from which the scrach allocations will be
  1115   1149   ** drawn, the size of each scratch allocation (sz),
  1116   1150   ** and the maximum number of scratch allocations (N).  The sz
  1117   1151   ** argument must be a multiple of 16. The sz parameter should be a few bytes
  1118   1152   ** larger than the actual scratch space required due to internal overhead.
  1119         -** The first argument should pointer to an 8-byte aligned buffer
         1153  +** The first argument must be a pointer to an 8-byte aligned buffer
  1120   1154   ** of at least sz*N bytes of memory.
  1121         -** SQLite will use no more than one scratch buffer at once per thread, so
  1122         -** N should be set to the expected maximum number of threads.  The sz
  1123         -** parameter should be 6 times the size of the largest database page size.
  1124         -** Scratch buffers are used as part of the btree balance operation.  If
  1125         -** The btree balancer needs additional memory beyond what is provided by
  1126         -** scratch buffers or if no scratch buffer space is specified, then SQLite
  1127         -** goes to [sqlite3_malloc()] to obtain the memory it needs.</dd>
         1155  +** ^SQLite will use no more than one scratch buffer per thread.  So
         1156  +** N should be set to the expected maximum number of threads.  ^SQLite will
         1157  +** never require a scratch buffer that is more than 6 times the database
         1158  +** page size. ^If SQLite needs needs additional scratch memory beyond 
         1159  +** what is provided by this configuration option, then 
         1160  +** [sqlite3_malloc()] will be used to obtain the memory needed.</dd>
  1128   1161   **
  1129   1162   ** <dt>SQLITE_CONFIG_PAGECACHE</dt>
  1130         -** <dd>This option specifies a static memory buffer that SQLite can use for
         1163  +** <dd> ^This option specifies a static memory buffer that SQLite can use for
  1131   1164   ** the database page cache with the default page cache implemenation.  
  1132   1165   ** This configuration should not be used if an application-define page
  1133   1166   ** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option.
  1134   1167   ** There are three arguments to this option: A pointer to 8-byte aligned
  1135   1168   ** memory, the size of each page buffer (sz), and the number of pages (N).
  1136   1169   ** The sz argument should be the size of the largest database page
  1137   1170   ** (a power of two between 512 and 32768) plus a little extra for each
  1138         -** page header.  The page header size is 20 to 40 bytes depending on
  1139         -** the host architecture.  It is harmless, apart from the wasted memory,
         1171  +** page header.  ^The page header size is 20 to 40 bytes depending on
         1172  +** the host architecture.  ^It is harmless, apart from the wasted memory,
  1140   1173   ** to make sz a little too large.  The first
  1141   1174   ** argument should point to an allocation of at least sz*N bytes of memory.
  1142         -** SQLite will use the memory provided by the first argument to satisfy its
  1143         -** memory needs for the first N pages that it adds to cache.  If additional
         1175  +** ^SQLite will use the memory provided by the first argument to satisfy its
         1176  +** memory needs for the first N pages that it adds to cache.  ^If additional
  1144   1177   ** page cache memory is needed beyond what is provided by this option, then
  1145   1178   ** SQLite goes to [sqlite3_malloc()] for the additional storage space.
  1146         -** The implementation might use one or more of the N buffers to hold 
         1179  +** ^The implementation might use one or more of the N buffers to hold 
  1147   1180   ** memory accounting information. The pointer in the first argument must
  1148   1181   ** be aligned to an 8-byte boundary or subsequent behavior of SQLite
  1149   1182   ** will be undefined.</dd>
  1150   1183   **
  1151   1184   ** <dt>SQLITE_CONFIG_HEAP</dt>
  1152         -** <dd>This option specifies a static memory buffer that SQLite will use
         1185  +** <dd> ^This option specifies a static memory buffer that SQLite will use
  1153   1186   ** for all of its dynamic memory allocation needs beyond those provided
  1154   1187   ** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
  1155   1188   ** There are three arguments: An 8-byte aligned pointer to the memory,
  1156   1189   ** the number of bytes in the memory buffer, and the minimum allocation size.
  1157         -** If the first pointer (the memory pointer) is NULL, then SQLite reverts
         1190  +** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
  1158   1191   ** to using its default memory allocator (the system malloc() implementation),
  1159         -** undoing any prior invocation of [SQLITE_CONFIG_MALLOC].  If the
         1192  +** undoing any prior invocation of [SQLITE_CONFIG_MALLOC].  ^If the
  1160   1193   ** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
  1161   1194   ** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory
  1162   1195   ** allocator is engaged to handle all of SQLites memory allocation needs.
  1163   1196   ** The first pointer (the memory pointer) must be aligned to an 8-byte
  1164   1197   ** boundary or subsequent behavior of SQLite will be undefined.</dd>
  1165   1198   **
  1166   1199   ** <dt>SQLITE_CONFIG_MUTEX</dt>
  1167         -** <dd>This option takes a single argument which is a pointer to an
         1200  +** <dd> ^(This option takes a single argument which is a pointer to an
  1168   1201   ** instance of the [sqlite3_mutex_methods] structure.  The argument specifies
  1169   1202   ** alternative low-level mutex routines to be used in place
  1170         -** the mutex routines built into SQLite.</dd>
         1203  +** the mutex routines built into SQLite.)^  ^SQLite makes a copy of the
         1204  +** content of the [sqlite3_mutex_methods] structure before the call to
         1205  +** [sqlite3_config()] returns. ^If SQLite is compiled with
         1206  +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
         1207  +** the entire mutexing subsystem is omitted from the build and hence calls to
         1208  +** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
         1209  +** return [SQLITE_ERROR].</dd>
  1171   1210   **
  1172   1211   ** <dt>SQLITE_CONFIG_GETMUTEX</dt>
  1173         -** <dd>This option takes a single argument which is a pointer to an
         1212  +** <dd> ^(This option takes a single argument which is a pointer to an
  1174   1213   ** instance of the [sqlite3_mutex_methods] structure.  The
  1175   1214   ** [sqlite3_mutex_methods]
  1176         -** structure is filled with the currently defined mutex routines.
         1215  +** structure is filled with the currently defined mutex routines.)^
  1177   1216   ** This option can be used to overload the default mutex allocation
  1178   1217   ** routines with a wrapper used to track mutex usage for performance
  1179         -** profiling or testing, for example.</dd>
         1218  +** profiling or testing, for example.   ^If SQLite is compiled with
         1219  +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
         1220  +** the entire mutexing subsystem is omitted from the build and hence calls to
         1221  +** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
         1222  +** return [SQLITE_ERROR].</dd>
  1180   1223   **
  1181   1224   ** <dt>SQLITE_CONFIG_LOOKASIDE</dt>
  1182         -** <dd>This option takes two arguments that determine the default
  1183         -** memory allocation lookaside optimization.  The first argument is the
         1225  +** <dd> ^(This option takes two arguments that determine the default
         1226  +** memory allocation for the lookaside memory allocator on each
         1227  +** [database connection].  The first argument is the
  1184   1228   ** size of each lookaside buffer slot and the second is the number of
  1185         -** slots allocated to each database connection.  This option sets the
  1186         -** <i>default</i> lookaside size.  The [SQLITE_DBCONFIG_LOOKASIDE]
         1229  +** slots allocated to each database connection.)^  ^(This option sets the
         1230  +** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
  1187   1231   ** verb to [sqlite3_db_config()] can be used to change the lookaside
  1188         -** configuration on individual connections.</dd>
         1232  +** configuration on individual connections.)^ </dd>
  1189   1233   **
  1190   1234   ** <dt>SQLITE_CONFIG_PCACHE</dt>
  1191         -** <dd>This option takes a single argument which is a pointer to
         1235  +** <dd> ^(This option takes a single argument which is a pointer to
  1192   1236   ** an [sqlite3_pcache_methods] object.  This object specifies the interface
  1193         -** to a custom page cache implementation.  SQLite makes a copy of the
         1237  +** to a custom page cache implementation.)^  ^SQLite makes a copy of the
  1194   1238   ** object and uses it for page cache memory allocations.</dd>
  1195   1239   **
  1196   1240   ** <dt>SQLITE_CONFIG_GETPCACHE</dt>
  1197         -** <dd>This option takes a single argument which is a pointer to an
         1241  +** <dd> ^(This option takes a single argument which is a pointer to an
  1198   1242   ** [sqlite3_pcache_methods] object.  SQLite copies of the current
  1199         -** page cache implementation into that object.</dd>
         1243  +** page cache implementation into that object.)^ </dd>
  1200   1244   **
  1201   1245   ** </dl>
  1202   1246   */
  1203   1247   #define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
  1204   1248   #define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
  1205   1249   #define SQLITE_CONFIG_SERIALIZED    3  /* nil */
  1206   1250   #define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
................................................................................
  1213   1257   #define SQLITE_CONFIG_GETMUTEX     11  /* sqlite3_mutex_methods* */
  1214   1258   /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ 
  1215   1259   #define SQLITE_CONFIG_LOOKASIDE    13  /* int int */
  1216   1260   #define SQLITE_CONFIG_PCACHE       14  /* sqlite3_pcache_methods* */
  1217   1261   #define SQLITE_CONFIG_GETPCACHE    15  /* sqlite3_pcache_methods* */
  1218   1262   
  1219   1263   /*
  1220         -** CAPI3REF: Configuration Options {H10170} <S20000>
         1264  +** CAPI3REF: Configuration Options
  1221   1265   ** EXPERIMENTAL
  1222   1266   **
  1223   1267   ** These constants are the available integer configuration options that
  1224   1268   ** can be passed as the second argument to the [sqlite3_db_config()] interface.
  1225   1269   **
  1226   1270   ** New configuration options may be added in future releases of SQLite.
  1227   1271   ** Existing configuration options might be discontinued.  Applications
  1228   1272   ** should check the return code from [sqlite3_db_config()] to make sure that
  1229         -** the call worked.  The [sqlite3_db_config()] interface will return a
         1273  +** the call worked.  ^The [sqlite3_db_config()] interface will return a
  1230   1274   ** non-zero [error code] if a discontinued or unsupported configuration option
  1231   1275   ** is invoked.
  1232   1276   **
  1233   1277   ** <dl>
  1234   1278   ** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
  1235         -** <dd>This option takes three additional arguments that determine the 
         1279  +** <dd> ^This option takes three additional arguments that determine the 
  1236   1280   ** [lookaside memory allocator] configuration for the [database connection].
  1237         -** The first argument (the third parameter to [sqlite3_db_config()] is a
         1281  +** ^The first argument (the third parameter to [sqlite3_db_config()] is a
  1238   1282   ** pointer to an memory buffer to use for lookaside memory.
  1239         -** The first argument may be NULL in which case SQLite will allocate the
  1240         -** lookaside buffer itself using [sqlite3_malloc()].  The second argument is the
  1241         -** size of each lookaside buffer slot and the third argument is the number of
         1283  +** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
         1284  +** may be NULL in which case SQLite will allocate the
         1285  +** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
         1286  +** size of each lookaside buffer slot.  ^The third argument is the number of
  1242   1287   ** slots.  The size of the buffer in the first argument must be greater than
  1243   1288   ** or equal to the product of the second and third arguments.  The buffer
  1244         -** must be aligned to an 8-byte boundary.  If the second argument is not
  1245         -** a multiple of 8, it is internally rounded down to the next smaller
         1289  +** must be aligned to an 8-byte boundary.  ^If the second argument to
         1290  +** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
         1291  +** rounded down to the next smaller
  1246   1292   ** multiple of 8.  See also: [SQLITE_CONFIG_LOOKASIDE]</dd>
  1247   1293   **
  1248   1294   ** </dl>
  1249   1295   */
  1250   1296   #define SQLITE_DBCONFIG_LOOKASIDE    1001  /* void* int int */
  1251   1297   
  1252   1298   
  1253   1299   /*
  1254         -** CAPI3REF: Enable Or Disable Extended Result Codes {H12200} <S10700>
         1300  +** CAPI3REF: Enable Or Disable Extended Result Codes
  1255   1301   **
  1256         -** The sqlite3_extended_result_codes() routine enables or disables the
  1257         -** [extended result codes] feature of SQLite. The extended result
  1258         -** codes are disabled by default for historical compatibility considerations.
  1259         -**
  1260         -** Requirements:
  1261         -** [H12201] [H12202]
         1302  +** ^The sqlite3_extended_result_codes() routine enables or disables the
         1303  +** [extended result codes] feature of SQLite. ^The extended result
         1304  +** codes are disabled by default for historical compatibility.
  1262   1305   */
  1263   1306   SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
  1264   1307   
  1265   1308   /*
  1266         -** CAPI3REF: Last Insert Rowid {H12220} <S10700>
         1309  +** CAPI3REF: Last Insert Rowid
  1267   1310   **
  1268         -** Each entry in an SQLite table has a unique 64-bit signed
  1269         -** integer key called the [ROWID | "rowid"]. The rowid is always available
         1311  +** ^Each entry in an SQLite table has a unique 64-bit signed
         1312  +** integer key called the [ROWID | "rowid"]. ^The rowid is always available
  1270   1313   ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
  1271         -** names are not also used by explicitly declared columns. If
         1314  +** names are not also used by explicitly declared columns. ^If
  1272   1315   ** the table has a column of type [INTEGER PRIMARY KEY] then that column
  1273   1316   ** is another alias for the rowid.
  1274   1317   **
  1275         -** This routine returns the [rowid] of the most recent
         1318  +** ^This routine returns the [rowid] of the most recent
  1276   1319   ** successful [INSERT] into the database from the [database connection]
  1277         -** in the first argument.  If no successful [INSERT]s
         1320  +** in the first argument.  ^If no successful [INSERT]s
  1278   1321   ** have ever occurred on that database connection, zero is returned.
  1279   1322   **
  1280         -** If an [INSERT] occurs within a trigger, then the [rowid] of the inserted
         1323  +** ^(If an [INSERT] occurs within a trigger, then the [rowid] of the inserted
  1281   1324   ** row is returned by this routine as long as the trigger is running.
  1282   1325   ** But once the trigger terminates, the value returned by this routine
  1283         -** reverts to the last value inserted before the trigger fired.
         1326  +** reverts to the last value inserted before the trigger fired.)^
  1284   1327   **
  1285         -** An [INSERT] that fails due to a constraint violation is not a
         1328  +** ^An [INSERT] that fails due to a constraint violation is not a
  1286   1329   ** successful [INSERT] and does not change the value returned by this
  1287         -** routine.  Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
         1330  +** routine.  ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
  1288   1331   ** and INSERT OR ABORT make no changes to the return value of this
  1289         -** routine when their insertion fails.  When INSERT OR REPLACE
         1332  +** routine when their insertion fails.  ^(When INSERT OR REPLACE
  1290   1333   ** encounters a constraint violation, it does not fail.  The
  1291   1334   ** INSERT continues to completion after deleting rows that caused
  1292   1335   ** the constraint problem so INSERT OR REPLACE will always change
  1293         -** the return value of this interface.
         1336  +** the return value of this interface.)^
  1294   1337   **
  1295         -** For the purposes of this routine, an [INSERT] is considered to
         1338  +** ^For the purposes of this routine, an [INSERT] is considered to
  1296   1339   ** be successful even if it is subsequently rolled back.
  1297   1340   **
  1298         -** Requirements:
  1299         -** [H12221] [H12223]
         1341  +** This function is accessible to SQL statements via the
         1342  +** [last_insert_rowid() SQL function].
  1300   1343   **
  1301   1344   ** If a separate thread performs a new [INSERT] on the same
  1302   1345   ** database connection while the [sqlite3_last_insert_rowid()]
  1303   1346   ** function is running and thus changes the last insert [rowid],
  1304   1347   ** then the value returned by [sqlite3_last_insert_rowid()] is
  1305   1348   ** unpredictable and might not equal either the old or the new
  1306   1349   ** last insert [rowid].
  1307   1350   */
  1308   1351   SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
  1309   1352   
  1310   1353   /*
  1311         -** CAPI3REF: Count The Number Of Rows Modified {H12240} <S10600>
         1354  +** CAPI3REF: Count The Number Of Rows Modified
  1312   1355   **
  1313         -** This function returns the number of database rows that were changed
         1356  +** ^This function returns the number of database rows that were changed
  1314   1357   ** or inserted or deleted by the most recently completed SQL statement
  1315   1358   ** on the [database connection] specified by the first parameter.
  1316         -** Only changes that are directly specified by the [INSERT], [UPDATE],
         1359  +** ^(Only changes that are directly specified by the [INSERT], [UPDATE],
  1317   1360   ** or [DELETE] statement are counted.  Auxiliary changes caused by
  1318         -** triggers or [foreign key actions] are not counted. Use the
         1361  +** triggers or [foreign key actions] are not counted.)^ Use the
  1319   1362   ** [sqlite3_total_changes()] function to find the total number of changes
  1320   1363   ** including changes caused by triggers and foreign key actions.
  1321   1364   **
  1322         -** Changes to a view that are simulated by an [INSTEAD OF trigger]
         1365  +** ^Changes to a view that are simulated by an [INSTEAD OF trigger]
  1323   1366   ** are not counted.  Only real table changes are counted.
  1324   1367   **
  1325         -** A "row change" is a change to a single row of a single table
         1368  +** ^(A "row change" is a change to a single row of a single table
  1326   1369   ** caused by an INSERT, DELETE, or UPDATE statement.  Rows that
  1327   1370   ** are changed as side effects of [REPLACE] constraint resolution,
  1328   1371   ** rollback, ABORT processing, [DROP TABLE], or by any other
  1329         -** mechanisms do not count as direct row changes.
         1372  +** mechanisms do not count as direct row changes.)^
  1330   1373   **
  1331   1374   ** A "trigger context" is a scope of execution that begins and
  1332   1375   ** ends with the script of a [CREATE TRIGGER | trigger]. 
  1333   1376   ** Most SQL statements are
  1334   1377   ** evaluated outside of any trigger.  This is the "top level"
  1335   1378   ** trigger context.  If a trigger fires from the top level, a
  1336   1379   ** new trigger context is entered for the duration of that one
  1337   1380   ** trigger.  Subtriggers create subcontexts for their duration.
  1338   1381   **
  1339         -** Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
         1382  +** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
  1340   1383   ** not create a new trigger context.
  1341   1384   **
  1342         -** This function returns the number of direct row changes in the
         1385  +** ^This function returns the number of direct row changes in the
  1343   1386   ** most recent INSERT, UPDATE, or DELETE statement within the same
  1344   1387   ** trigger context.
  1345   1388   **
  1346         -** Thus, when called from the top level, this function returns the
         1389  +** ^Thus, when called from the top level, this function returns the
  1347   1390   ** number of changes in the most recent INSERT, UPDATE, or DELETE
  1348         -** that also occurred at the top level.  Within the body of a trigger,
         1391  +** that also occurred at the top level.  ^(Within the body of a trigger,
  1349   1392   ** the sqlite3_changes() interface can be called to find the number of
  1350   1393   ** changes in the most recently completed INSERT, UPDATE, or DELETE
  1351   1394   ** statement within the body of the same trigger.
  1352   1395   ** However, the number returned does not include changes
  1353         -** caused by subtriggers since those have their own context.
         1396  +** caused by subtriggers since those have their own context.)^
  1354   1397   **
  1355         -** See also the [sqlite3_total_changes()] interface and the
  1356         -** [count_changes pragma].
  1357         -**
  1358         -** Requirements:
  1359         -** [H12241] [H12243]
         1398  +** See also the [sqlite3_total_changes()] interface, the
         1399  +** [count_changes pragma], and the [changes() SQL function].
  1360   1400   **
  1361   1401   ** If a separate thread makes changes on the same database connection
  1362   1402   ** while [sqlite3_changes()] is running then the value returned
  1363   1403   ** is unpredictable and not meaningful.
  1364   1404   */
  1365   1405   SQLITE_API int sqlite3_changes(sqlite3*);
  1366   1406   
  1367   1407   /*
  1368         -** CAPI3REF: Total Number Of Rows Modified {H12260} <S10600>
         1408  +** CAPI3REF: Total Number Of Rows Modified
  1369   1409   **
  1370         -** This function returns the number of row changes caused by [INSERT],
         1410  +** ^This function returns the number of row changes caused by [INSERT],
  1371   1411   ** [UPDATE] or [DELETE] statements since the [database connection] was opened.
  1372         -** The count includes all changes from all [CREATE TRIGGER | trigger] 
  1373         -** contexts and changes made by [foreign key actions]. However,
         1412  +** ^(The count returned by sqlite3_total_changes() includes all changes
         1413  +** from all [CREATE TRIGGER | trigger] contexts and changes made by
         1414  +** [foreign key actions]. However,
  1374   1415   ** the count does not include changes used to implement [REPLACE] constraints,
  1375   1416   ** do rollbacks or ABORT processing, or [DROP TABLE] processing.  The
  1376   1417   ** count does not include rows of views that fire an [INSTEAD OF trigger],
  1377   1418   ** though if the INSTEAD OF trigger makes changes of its own, those changes 
  1378         -** are counted.
  1379         -** The changes are counted as soon as the statement that makes them is
  1380         -** completed (when the statement handle is passed to [sqlite3_reset()] or
  1381         -** [sqlite3_finalize()]).
         1419  +** are counted.)^
         1420  +** ^The sqlite3_total_changes() function counts the changes as soon as
         1421  +** the statement that makes them is completed (when the statement handle
         1422  +** is passed to [sqlite3_reset()] or [sqlite3_finalize()]).
  1382   1423   **
  1383         -** See also the [sqlite3_changes()] interface and the
  1384         -** [count_changes pragma].
  1385         -**
  1386         -** Requirements:
  1387         -** [H12261] [H12263]
         1424  +** See also the [sqlite3_changes()] interface, the
         1425  +** [count_changes pragma], and the [total_changes() SQL function].
  1388   1426   **
  1389   1427   ** If a separate thread makes changes on the same database connection
  1390   1428   ** while [sqlite3_total_changes()] is running then the value
  1391   1429   ** returned is unpredictable and not meaningful.
  1392   1430   */
  1393   1431   SQLITE_API int sqlite3_total_changes(sqlite3*);
  1394   1432   
  1395   1433   /*
  1396         -** CAPI3REF: Interrupt A Long-Running Query {H12270} <S30500>
         1434  +** CAPI3REF: Interrupt A Long-Running Query
  1397   1435   **
  1398         -** This function causes any pending database operation to abort and
         1436  +** ^This function causes any pending database operation to abort and
  1399   1437   ** return at its earliest opportunity. This routine is typically
  1400   1438   ** called in response to a user action such as pressing "Cancel"
  1401   1439   ** or Ctrl-C where the user wants a long query operation to halt
  1402   1440   ** immediately.
  1403   1441   **
  1404         -** It is safe to call this routine from a thread different from the
         1442  +** ^It is safe to call this routine from a thread different from the
  1405   1443   ** thread that is currently running the database operation.  But it
  1406   1444   ** is not safe to call this routine with a [database connection] that
  1407   1445   ** is closed or might close before sqlite3_interrupt() returns.
  1408   1446   **
  1409         -** If an SQL operation is very nearly finished at the time when
         1447  +** ^If an SQL operation is very nearly finished at the time when
  1410   1448   ** sqlite3_interrupt() is called, then it might not have an opportunity
  1411   1449   ** to be interrupted and might continue to completion.
  1412   1450   **
  1413         -** An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
  1414         -** If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
         1451  +** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
         1452  +** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
  1415   1453   ** that is inside an explicit transaction, then the entire transaction
  1416   1454   ** will be rolled back automatically.
  1417   1455   **
  1418         -** The sqlite3_interrupt(D) call is in effect until all currently running
  1419         -** SQL statements on [database connection] D complete.  Any new SQL statements
         1456  +** ^The sqlite3_interrupt(D) call is in effect until all currently running
         1457  +** SQL statements on [database connection] D complete.  ^Any new SQL statements
  1420   1458   ** that are started after the sqlite3_interrupt() call and before the 
  1421   1459   ** running statements reaches zero are interrupted as if they had been
  1422         -** running prior to the sqlite3_interrupt() call.  New SQL statements
         1460  +** running prior to the sqlite3_interrupt() call.  ^New SQL statements
  1423   1461   ** that are started after the running statement count reaches zero are
  1424   1462   ** not effected by the sqlite3_interrupt().
  1425         -** A call to sqlite3_interrupt(D) that occurs when there are no running
         1463  +** ^A call to sqlite3_interrupt(D) that occurs when there are no running
  1426   1464   ** SQL statements is a no-op and has no effect on SQL statements
  1427   1465   ** that are started after the sqlite3_interrupt() call returns.
  1428   1466   **
  1429         -** Requirements:
  1430         -** [H12271] [H12272]
  1431         -**
  1432   1467   ** If the database connection closes while [sqlite3_interrupt()]
  1433   1468   ** is running then bad things will likely happen.
  1434   1469   */
  1435   1470   SQLITE_API void sqlite3_interrupt(sqlite3*);
  1436   1471   
  1437   1472   /*
  1438         -** CAPI3REF: Determine If An SQL Statement Is Complete {H10510} <S70200>
         1473  +** CAPI3REF: Determine If An SQL Statement Is Complete
  1439   1474   **
  1440   1475   ** These routines are useful during command-line input to determine if the
  1441   1476   ** currently entered text seems to form a complete SQL statement or
  1442   1477   ** if additional input is needed before sending the text into
  1443         -** SQLite for parsing.  These routines return 1 if the input string
  1444         -** appears to be a complete SQL statement.  A statement is judged to be
         1478  +** SQLite for parsing.  ^These routines return 1 if the input string
         1479  +** appears to be a complete SQL statement.  ^A statement is judged to be
  1445   1480   ** complete if it ends with a semicolon token and is not a prefix of a
  1446         -** well-formed CREATE TRIGGER statement.  Semicolons that are embedded within
         1481  +** well-formed CREATE TRIGGER statement.  ^Semicolons that are embedded within
  1447   1482   ** string literals or quoted identifier names or comments are not
  1448   1483   ** independent tokens (they are part of the token in which they are
  1449         -** embedded) and thus do not count as a statement terminator.  Whitespace
         1484  +** embedded) and thus do not count as a statement terminator.  ^Whitespace
  1450   1485   ** and comments that follow the final semicolon are ignored.
  1451   1486   **
  1452         -** These routines return 0 if the statement is incomplete.  If a
         1487  +** ^These routines return 0 if the statement is incomplete.  ^If a
  1453   1488   ** memory allocation fails, then SQLITE_NOMEM is returned.
  1454   1489   **
  1455         -** These routines do not parse the SQL statements thus
         1490  +** ^These routines do not parse the SQL statements thus
  1456   1491   ** will not detect syntactically incorrect SQL.
  1457   1492   **
  1458         -** If SQLite has not been initialized using [sqlite3_initialize()] prior 
         1493  +** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior 
  1459   1494   ** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
  1460   1495   ** automatically by sqlite3_complete16().  If that initialization fails,
  1461   1496   ** then the return value from sqlite3_complete16() will be non-zero
  1462         -** regardless of whether or not the input SQL is complete.
  1463         -**
  1464         -** Requirements: [H10511] [H10512]
         1497  +** regardless of whether or not the input SQL is complete.)^
  1465   1498   **
  1466   1499   ** The input to [sqlite3_complete()] must be a zero-terminated
  1467   1500   ** UTF-8 string.
  1468   1501   **
  1469   1502   ** The input to [sqlite3_complete16()] must be a zero-terminated
  1470   1503   ** UTF-16 string in native byte order.
  1471   1504   */
  1472   1505   SQLITE_API int sqlite3_complete(const char *sql);
  1473   1506   SQLITE_API int sqlite3_complete16(const void *sql);
  1474   1507   
  1475   1508   /*
  1476         -** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {H12310} <S40400>
         1509  +** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
  1477   1510   **
  1478         -** This routine sets a callback function that might be invoked whenever
         1511  +** ^This routine sets a callback function that might be invoked whenever
  1479   1512   ** an attempt is made to open a database table that another thread
  1480   1513   ** or process has locked.
  1481   1514   **
  1482         -** If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]
  1483         -** is returned immediately upon encountering the lock. If the busy callback
  1484         -** is not NULL, then the callback will be invoked with two arguments.
         1515  +** ^If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]
         1516  +** is returned immediately upon encountering the lock.  ^If the busy callback
         1517  +** is not NULL, then the callback might be invoked with two arguments.
  1485   1518   **
  1486         -** The first argument to the handler is a copy of the void* pointer which
  1487         -** is the third argument to sqlite3_busy_handler().  The second argument to
  1488         -** the handler callback is the number of times that the busy handler has
  1489         -** been invoked for this locking event.  If the
         1519  +** ^The first argument to the busy handler is a copy of the void* pointer which
         1520  +** is the third argument to sqlite3_busy_handler().  ^The second argument to
         1521  +** the busy handler callback is the number of times that the busy handler has
         1522  +** been invoked for this locking event.  ^If the
  1490   1523   ** busy callback returns 0, then no additional attempts are made to
  1491   1524   ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
  1492         -** If the callback returns non-zero, then another attempt
         1525  +** ^If the callback returns non-zero, then another attempt
  1493   1526   ** is made to open the database for reading and the cycle repeats.
  1494   1527   **
  1495   1528   ** The presence of a busy handler does not guarantee that it will be invoked
  1496         -** when there is lock contention. If SQLite determines that invoking the busy
         1529  +** when there is lock contention. ^If SQLite determines that invoking the busy
  1497   1530   ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
  1498   1531   ** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler.
  1499   1532   ** Consider a scenario where one process is holding a read lock that
  1500   1533   ** it is trying to promote to a reserved lock and
  1501   1534   ** a second process is holding a reserved lock that it is trying
  1502   1535   ** to promote to an exclusive lock.  The first process cannot proceed
  1503   1536   ** because it is blocked by the second and the second process cannot
  1504   1537   ** proceed because it is blocked by the first.  If both processes
  1505   1538   ** invoke the busy handlers, neither will make any progress.  Therefore,
  1506   1539   ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
  1507   1540   ** will induce the first process to release its read lock and allow
  1508   1541   ** the second process to proceed.
  1509   1542   **
  1510         -** The default busy callback is NULL.
         1543  +** ^The default busy callback is NULL.
  1511   1544   **
  1512         -** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
         1545  +** ^The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
  1513   1546   ** when SQLite is in the middle of a large transaction where all the
  1514   1547   ** changes will not fit into the in-memory cache.  SQLite will
  1515   1548   ** already hold a RESERVED lock on the database file, but it needs
  1516   1549   ** to promote this lock to EXCLUSIVE so that it can spill cache
  1517   1550   ** pages into the database file without harm to concurrent
  1518         -** readers.  If it is unable to promote the lock, then the in-memory
         1551  +** readers.  ^If it is unable to promote the lock, then the in-memory
  1519   1552   ** cache will be left in an inconsistent state and so the error
  1520   1553   ** code is promoted from the relatively benign [SQLITE_BUSY] to
  1521         -** the more severe [SQLITE_IOERR_BLOCKED].  This error code promotion
         1554  +** the more severe [SQLITE_IOERR_BLOCKED].  ^This error code promotion
  1522   1555   ** forces an automatic rollback of the changes.  See the
  1523   1556   ** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">
  1524   1557   ** CorruptionFollowingBusyError</a> wiki page for a discussion of why
  1525   1558   ** this is important.
  1526   1559   **
  1527         -** There can only be a single busy handler defined for each
         1560  +** ^(There can only be a single busy handler defined for each
  1528   1561   ** [database connection].  Setting a new busy handler clears any
  1529         -** previously set handler.  Note that calling [sqlite3_busy_timeout()]
         1562  +** previously set handler.)^  ^Note that calling [sqlite3_busy_timeout()]
  1530   1563   ** will also set or clear the busy handler.
  1531   1564   **
  1532   1565   ** The busy callback should not take any actions which modify the
  1533   1566   ** database connection that invoked the busy handler.  Any such actions
  1534   1567   ** result in undefined behavior.
  1535   1568   ** 
  1536         -** Requirements:
  1537         -** [H12311] [H12312] [H12314] [H12316] [H12318]
  1538         -**
  1539   1569   ** A busy handler must not close the database connection
  1540   1570   ** or [prepared statement] that invoked the busy handler.
  1541   1571   */
  1542   1572   SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
  1543   1573   
  1544   1574   /*
  1545         -** CAPI3REF: Set A Busy Timeout {H12340} <S40410>
         1575  +** CAPI3REF: Set A Busy Timeout
  1546   1576   **
  1547         -** This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
  1548         -** for a specified amount of time when a table is locked.  The handler
         1577  +** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
         1578  +** for a specified amount of time when a table is locked.  ^The handler
  1549   1579   ** will sleep multiple times until at least "ms" milliseconds of sleeping
  1550         -** have accumulated. {H12343} After "ms" milliseconds of sleeping,
         1580  +** have accumulated.  ^After at least "ms" milliseconds of sleeping,
  1551   1581   ** the handler returns 0 which causes [sqlite3_step()] to return
  1552   1582   ** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
  1553   1583   **
  1554         -** Calling this routine with an argument less than or equal to zero
         1584  +** ^Calling this routine with an argument less than or equal to zero
  1555   1585   ** turns off all busy handlers.
  1556   1586   **
  1557         -** There can only be a single busy handler for a particular
         1587  +** ^(There can only be a single busy handler for a particular
  1558   1588   ** [database connection] any any given moment.  If another busy handler
  1559   1589   ** was defined  (using [sqlite3_busy_handler()]) prior to calling
  1560         -** this routine, that other busy handler is cleared.
  1561         -**
  1562         -** Requirements:
  1563         -** [H12341] [H12343] [H12344]
         1590  +** this routine, that other busy handler is cleared.)^
  1564   1591   */
  1565   1592   SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
  1566   1593   
  1567   1594   /*
  1568         -** CAPI3REF: Convenience Routines For Running Queries {H12370} <S10000>
         1595  +** CAPI3REF: Convenience Routines For Running Queries
  1569   1596   **
  1570   1597   ** Definition: A <b>result table</b> is memory data structure created by the
  1571   1598   ** [sqlite3_get_table()] interface.  A result table records the
  1572   1599   ** complete query results from one or more queries.
  1573   1600   **
  1574   1601   ** The table conceptually has a number of rows and columns.  But
  1575   1602   ** these numbers are not part of the result table itself.  These
................................................................................
  1609   1636   **        azResult&#91;3] = "43";
  1610   1637   **        azResult&#91;4] = "Bob";
  1611   1638   **        azResult&#91;5] = "28";
  1612   1639   **        azResult&#91;6] = "Cindy";
  1613   1640   **        azResult&#91;7] = "21";
  1614   1641   ** </pre></blockquote>
  1615   1642   **
  1616         -** The sqlite3_get_table() function evaluates one or more
         1643  +** ^The sqlite3_get_table() function evaluates one or more
  1617   1644   ** semicolon-separated SQL statements in the zero-terminated UTF-8
  1618         -** string of its 2nd parameter.  It returns a result table to the
         1645  +** string of its 2nd parameter and returns a result table to the
  1619   1646   ** pointer given in its 3rd parameter.
  1620   1647   **
  1621         -** After the calling function has finished using the result, it should
  1622         -** pass the pointer to the result table to sqlite3_free_table() in order to
         1648  +** After the application has finished with the result from sqlite3_get_table(),
         1649  +** it should pass the result table pointer to sqlite3_free_table() in order to
  1623   1650   ** release the memory that was malloced.  Because of the way the
  1624   1651   ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
  1625   1652   ** function must not try to call [sqlite3_free()] directly.  Only
  1626   1653   ** [sqlite3_free_table()] is able to release the memory properly and safely.
  1627   1654   **
  1628         -** The sqlite3_get_table() interface is implemented as a wrapper around
         1655  +** ^(The sqlite3_get_table() interface is implemented as a wrapper around
  1629   1656   ** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access
  1630   1657   ** to any internal data structures of SQLite.  It uses only the public
  1631   1658   ** interface defined here.  As a consequence, errors that occur in the
  1632   1659   ** wrapper layer outside of the internal [sqlite3_exec()] call are not
  1633         -** reflected in subsequent calls to [sqlite3_errcode()] or [sqlite3_errmsg()].
  1634         -**
  1635         -** Requirements:
  1636         -** [H12371] [H12373] [H12374] [H12376] [H12379] [H12382]
         1660  +** reflected in subsequent calls to [sqlite3_errcode()] or
         1661  +** [sqlite3_errmsg()].)^
  1637   1662   */
  1638   1663   SQLITE_API int sqlite3_get_table(
  1639   1664     sqlite3 *db,          /* An open database */
  1640   1665     const char *zSql,     /* SQL to be evaluated */
  1641   1666     char ***pazResult,    /* Results of the query */
  1642   1667     int *pnRow,           /* Number of result rows written here */
  1643   1668     int *pnColumn,        /* Number of result columns written here */
  1644   1669     char **pzErrmsg       /* Error msg written here */
  1645   1670   );
  1646   1671   SQLITE_API void sqlite3_free_table(char **result);
  1647   1672   
  1648   1673   /*
  1649         -** CAPI3REF: Formatted String Printing Functions {H17400} <S70000><S20000>
         1674  +** CAPI3REF: Formatted String Printing Functions
  1650   1675   **
  1651   1676   ** These routines are work-alikes of the "printf()" family of functions
  1652   1677   ** from the standard C library.
  1653   1678   **
  1654         -** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
         1679  +** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
  1655   1680   ** results into memory obtained from [sqlite3_malloc()].
  1656   1681   ** The strings returned by these two routines should be
  1657         -** released by [sqlite3_free()].  Both routines return a
         1682  +** released by [sqlite3_free()].  ^Both routines return a
  1658   1683   ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
  1659   1684   ** memory to hold the resulting string.
  1660   1685   **
  1661         -** In sqlite3_snprintf() routine is similar to "snprintf()" from
         1686  +** ^(In sqlite3_snprintf() routine is similar to "snprintf()" from
  1662   1687   ** the standard C library.  The result is written into the
  1663   1688   ** buffer supplied as the second parameter whose size is given by
  1664   1689   ** the first parameter. Note that the order of the
  1665         -** first two parameters is reversed from snprintf().  This is an
         1690  +** first two parameters is reversed from snprintf().)^  This is an
  1666   1691   ** historical accident that cannot be fixed without breaking
  1667         -** backwards compatibility.  Note also that sqlite3_snprintf()
         1692  +** backwards compatibility.  ^(Note also that sqlite3_snprintf()
  1668   1693   ** returns a pointer to its buffer instead of the number of
  1669         -** characters actually written into the buffer.  We admit that
         1694  +** characters actually written into the buffer.)^  We admit that
  1670   1695   ** the number of characters written would be a more useful return
  1671   1696   ** value but we cannot change the implementation of sqlite3_snprintf()
  1672   1697   ** now without breaking compatibility.
  1673   1698   **
  1674         -** As long as the buffer size is greater than zero, sqlite3_snprintf()
  1675         -** guarantees that the buffer is always zero-terminated.  The first
         1699  +** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
         1700  +** guarantees that the buffer is always zero-terminated.  ^The first
  1676   1701   ** parameter "n" is the total size of the buffer, including space for
  1677   1702   ** the zero terminator.  So the longest string that can be completely
  1678   1703   ** written will be n-1 characters.
  1679   1704   **
  1680   1705   ** These routines all implement some additional formatting
  1681   1706   ** options that are useful for constructing SQL statements.
  1682   1707   ** All of the usual printf() formatting options apply.  In addition, there
  1683   1708   ** is are "%q", "%Q", and "%z" options.
  1684   1709   **
  1685         -** The %q option works like %s in that it substitutes a null-terminated
         1710  +** ^(The %q option works like %s in that it substitutes a null-terminated
  1686   1711   ** string from the argument list.  But %q also doubles every '\'' character.
  1687         -** %q is designed for use inside a string literal.  By doubling each '\''
         1712  +** %q is designed for use inside a string literal.)^  By doubling each '\''
  1688   1713   ** character it escapes that character and allows it to be inserted into
  1689   1714   ** the string.
  1690   1715   **
  1691   1716   ** For example, assume the string variable zText contains text as follows:
  1692   1717   **
  1693   1718   ** <blockquote><pre>
  1694   1719   **  char *zText = "It's a happy day!";
................................................................................
  1715   1740   ** <blockquote><pre>
  1716   1741   **  INSERT INTO table1 VALUES('It's a happy day!');
  1717   1742   ** </pre></blockquote>
  1718   1743   **
  1719   1744   ** This second example is an SQL syntax error.  As a general rule you should
  1720   1745   ** always use %q instead of %s when inserting text into a string literal.
  1721   1746   **
  1722         -** The %Q option works like %q except it also adds single quotes around
         1747  +** ^(The %Q option works like %q except it also adds single quotes around
  1723   1748   ** the outside of the total string.  Additionally, if the parameter in the
  1724   1749   ** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
  1725         -** single quotes) in place of the %Q option.  So, for example, one could say:
         1750  +** single quotes).)^  So, for example, one could say:
  1726   1751   **
  1727   1752   ** <blockquote><pre>
  1728   1753   **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
  1729   1754   **  sqlite3_exec(db, zSQL, 0, 0, 0);
  1730   1755   **  sqlite3_free(zSQL);
  1731   1756   ** </pre></blockquote>
  1732   1757   **
  1733   1758   ** The code above will render a correct SQL statement in the zSQL
  1734   1759   ** variable even if the zText variable is a NULL pointer.
  1735   1760   **
  1736         -** The "%z" formatting option works exactly like "%s" with the
         1761  +** ^(The "%z" formatting option works like "%s" but with the
  1737   1762   ** addition that after the string has been read and copied into
  1738         -** the result, [sqlite3_free()] is called on the input string. {END}
  1739         -**
  1740         -** Requirements:
  1741         -** [H17403] [H17406] [H17407]
         1763  +** the result, [sqlite3_free()] is called on the input string.)^
  1742   1764   */
  1743   1765   SQLITE_API char *sqlite3_mprintf(const char*,...);
  1744   1766   SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
  1745   1767   SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
  1746   1768   
  1747   1769   /*
  1748         -** CAPI3REF: Memory Allocation Subsystem {H17300} <S20000>
         1770  +** CAPI3REF: Memory Allocation Subsystem
  1749   1771   **
  1750         -** The SQLite core  uses these three routines for all of its own
         1772  +** The SQLite core uses these three routines for all of its own
  1751   1773   ** internal memory allocation needs. "Core" in the previous sentence
  1752   1774   ** does not include operating-system specific VFS implementation.  The
  1753   1775   ** Windows VFS uses native malloc() and free() for some operations.
  1754   1776   **
  1755         -** The sqlite3_malloc() routine returns a pointer to a block
         1777  +** ^The sqlite3_malloc() routine returns a pointer to a block
  1756   1778   ** of memory at least N bytes in length, where N is the parameter.
  1757         -** If sqlite3_malloc() is unable to obtain sufficient free
  1758         -** memory, it returns a NULL pointer.  If the parameter N to
         1779  +** ^If sqlite3_malloc() is unable to obtain sufficient free
         1780  +** memory, it returns a NULL pointer.  ^If the parameter N to
  1759   1781   ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
  1760   1782   ** a NULL pointer.
  1761   1783   **
  1762         -** Calling sqlite3_free() with a pointer previously returned
         1784  +** ^Calling sqlite3_free() with a pointer previously returned
  1763   1785   ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
  1764         -** that it might be reused.  The sqlite3_free() routine is
         1786  +** that it might be reused.  ^The sqlite3_free() routine is
  1765   1787   ** a no-op if is called with a NULL pointer.  Passing a NULL pointer
  1766   1788   ** to sqlite3_free() is harmless.  After being freed, memory
  1767   1789   ** should neither be read nor written.  Even reading previously freed
  1768   1790   ** memory might result in a segmentation fault or other severe error.
  1769   1791   ** Memory corruption, a segmentation fault, or other severe error
  1770   1792   ** might result if sqlite3_free() is called with a non-NULL pointer that
  1771   1793   ** was not obtained from sqlite3_malloc() or sqlite3_realloc().
  1772   1794   **
  1773         -** The sqlite3_realloc() interface attempts to resize a
         1795  +** ^(The sqlite3_realloc() interface attempts to resize a
  1774   1796   ** prior memory allocation to be at least N bytes, where N is the
  1775   1797   ** second parameter.  The memory allocation to be resized is the first
  1776         -** parameter.  If the first parameter to sqlite3_realloc()
         1798  +** parameter.)^ ^ If the first parameter to sqlite3_realloc()
  1777   1799   ** is a NULL pointer then its behavior is identical to calling
  1778   1800   ** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
  1779         -** If the second parameter to sqlite3_realloc() is zero or
         1801  +** ^If the second parameter to sqlite3_realloc() is zero or
  1780   1802   ** negative then the behavior is exactly the same as calling
  1781   1803   ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
  1782         -** sqlite3_realloc() returns a pointer to a memory allocation
         1804  +** ^sqlite3_realloc() returns a pointer to a memory allocation
  1783   1805   ** of at least N bytes in size or NULL if sufficient memory is unavailable.
  1784         -** If M is the size of the prior allocation, then min(N,M) bytes
         1806  +** ^If M is the size of the prior allocation, then min(N,M) bytes
  1785   1807   ** of the prior allocation are copied into the beginning of buffer returned
  1786   1808   ** by sqlite3_realloc() and the prior allocation is freed.
  1787         -** If sqlite3_realloc() returns NULL, then the prior allocation
         1809  +** ^If sqlite3_realloc() returns NULL, then the prior allocation
  1788   1810   ** is not freed.
  1789   1811   **
  1790         -** The memory returned by sqlite3_malloc() and sqlite3_realloc()
  1791         -** is always aligned to at least an 8 byte boundary. {END}
  1792         -**
  1793         -** The default implementation of the memory allocation subsystem uses
  1794         -** the malloc(), realloc() and free() provided by the standard C library.
  1795         -** {H17382} However, if SQLite is compiled with the
  1796         -** SQLITE_MEMORY_SIZE=<i>NNN</i> C preprocessor macro (where <i>NNN</i>
  1797         -** is an integer), then SQLite create a static array of at least
  1798         -** <i>NNN</i> bytes in size and uses that array for all of its dynamic
  1799         -** memory allocation needs. {END}  Additional memory allocator options
  1800         -** may be added in future releases.
         1812  +** ^The memory returned by sqlite3_malloc() and sqlite3_realloc()
         1813  +** is always aligned to at least an 8 byte boundary.
  1801   1814   **
  1802   1815   ** In SQLite version 3.5.0 and 3.5.1, it was possible to define
  1803   1816   ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
  1804   1817   ** implementation of these routines to be omitted.  That capability
  1805   1818   ** is no longer provided.  Only built-in memory allocators can be used.
  1806   1819   **
  1807   1820   ** The Windows OS interface layer calls
................................................................................
  1808   1821   ** the system malloc() and free() directly when converting
  1809   1822   ** filenames between the UTF-8 encoding used by SQLite
  1810   1823   ** and whatever filename encoding is used by the particular Windows
  1811   1824   ** installation.  Memory allocation errors are detected, but
  1812   1825   ** they are reported back as [SQLITE_CANTOPEN] or
  1813   1826   ** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
  1814   1827   **
  1815         -** Requirements:
  1816         -** [H17303] [H17304] [H17305] [H17306] [H17310] [H17312] [H17315] [H17318]
  1817         -** [H17321] [H17322] [H17323]
  1818         -**
  1819   1828   ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
  1820   1829   ** must be either NULL or else pointers obtained from a prior
  1821   1830   ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
  1822   1831   ** not yet been released.
  1823   1832   **
  1824   1833   ** The application must not read or write any part of
  1825   1834   ** a block of memory after it has been released using
................................................................................
  1826   1835   ** [sqlite3_free()] or [sqlite3_realloc()].
  1827   1836   */
  1828   1837   SQLITE_API void *sqlite3_malloc(int);
  1829   1838   SQLITE_API void *sqlite3_realloc(void*, int);
  1830   1839   SQLITE_API void sqlite3_free(void*);
  1831   1840   
  1832   1841   /*
  1833         -** CAPI3REF: Memory Allocator Statistics {H17370} <S30210>
         1842  +** CAPI3REF: Memory Allocator Statistics
  1834   1843   **
  1835   1844   ** SQLite provides these two interfaces for reporting on the status
  1836   1845   ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
  1837   1846   ** routines, which form the built-in memory allocation subsystem.
  1838   1847   **
  1839         -** Requirements:
  1840         -** [H17371] [H17373] [H17374] [H17375]
         1848  +** ^The [sqlite3_memory_used()] routine returns the number of bytes
         1849  +** of memory currently outstanding (malloced but not freed).
         1850  +** ^The [sqlite3_memory_highwater()] routine returns the maximum
         1851  +** value of [sqlite3_memory_used()] since the high-water mark
         1852  +** was last reset.  ^The values returned by [sqlite3_memory_used()] and
         1853  +** [sqlite3_memory_highwater()] include any overhead
         1854  +** added by SQLite in its implementation of [sqlite3_malloc()],
         1855  +** but not overhead added by the any underlying system library
         1856  +** routines that [sqlite3_malloc()] may call.
         1857  +**
         1858  +** ^The memory high-water mark is reset to the current value of
         1859  +** [sqlite3_memory_used()] if and only if the parameter to
         1860  +** [sqlite3_memory_highwater()] is true.  ^The value returned
         1861  +** by [sqlite3_memory_highwater(1)] is the high-water mark
         1862  +** prior to the reset.
  1841   1863   */
  1842   1864   SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
  1843   1865   SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
  1844   1866   
  1845   1867   /*
  1846         -** CAPI3REF: Pseudo-Random Number Generator {H17390} <S20000>
         1868  +** CAPI3REF: Pseudo-Random Number Generator
  1847   1869   **
  1848   1870   ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
  1849   1871   ** select random [ROWID | ROWIDs] when inserting new records into a table that
  1850   1872   ** already uses the largest possible [ROWID].  The PRNG is also used for
  1851   1873   ** the build-in random() and randomblob() SQL functions.  This interface allows
  1852   1874   ** applications to access the same PRNG for other purposes.
  1853   1875   **
  1854         -** A call to this routine stores N bytes of randomness into buffer P.
         1876  +** ^A call to this routine stores N bytes of randomness into buffer P.
  1855   1877   **
  1856         -** The first time this routine is invoked (either internally or by
         1878  +** ^The first time this routine is invoked (either internally or by
  1857   1879   ** the application) the PRNG is seeded using randomness obtained
  1858   1880   ** from the xRandomness method of the default [sqlite3_vfs] object.
  1859         -** On all subsequent invocations, the pseudo-randomness is generated
         1881  +** ^On all subsequent invocations, the pseudo-randomness is generated
  1860   1882   ** internally and without recourse to the [sqlite3_vfs] xRandomness
  1861   1883   ** method.
  1862         -**
  1863         -** Requirements:
  1864         -** [H17392]
  1865   1884   */
  1866   1885   SQLITE_API void sqlite3_randomness(int N, void *P);
  1867   1886   
  1868   1887   /*
  1869         -** CAPI3REF: Compile-Time Authorization Callbacks {H12500} <S70100>
         1888  +** CAPI3REF: Compile-Time Authorization Callbacks
  1870   1889   **
  1871         -** This routine registers a authorizer callback with a particular
         1890  +** ^This routine registers a authorizer callback with a particular
  1872   1891   ** [database connection], supplied in the first argument.
  1873         -** The authorizer callback is invoked as SQL statements are being compiled
         1892  +** ^The authorizer callback is invoked as SQL statements are being compiled
  1874   1893   ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
  1875         -** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  At various
         1894  +** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  ^At various
  1876   1895   ** points during the compilation process, as logic is being created
  1877   1896   ** to perform various actions, the authorizer callback is invoked to
  1878         -** see if those actions are allowed.  The authorizer callback should
         1897  +** see if those actions are allowed.  ^The authorizer callback should
  1879   1898   ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
  1880   1899   ** specific action but allow the SQL statement to continue to be
  1881   1900   ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
  1882         -** rejected with an error.  If the authorizer callback returns
         1901  +** rejected with an error.  ^If the authorizer callback returns
  1883   1902   ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
  1884   1903   ** then the [sqlite3_prepare_v2()] or equivalent call that triggered
  1885   1904   ** the authorizer will fail with an error message.
  1886   1905   **
  1887   1906   ** When the callback returns [SQLITE_OK], that means the operation
  1888         -** requested is ok.  When the callback returns [SQLITE_DENY], the
         1907  +** requested is ok.  ^When the callback returns [SQLITE_DENY], the
  1889   1908   ** [sqlite3_prepare_v2()] or equivalent call that triggered the
  1890   1909   ** authorizer will fail with an error message explaining that
  1891   1910   ** access is denied. 
  1892   1911   **
  1893         -** The first parameter to the authorizer callback is a copy of the third
  1894         -** parameter to the sqlite3_set_authorizer() interface. The second parameter
         1912  +** ^The first parameter to the authorizer callback is a copy of the third
         1913  +** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
  1895   1914   ** to the callback is an integer [SQLITE_COPY | action code] that specifies
  1896         -** the particular action to be authorized. The third through sixth parameters
         1915  +** the particular action to be authorized. ^The third through sixth parameters
  1897   1916   ** to the callback are zero-terminated strings that contain additional
  1898   1917   ** details about the action to be authorized.
  1899   1918   **
  1900         -** If the action code is [SQLITE_READ]
         1919  +** ^If the action code is [SQLITE_READ]
  1901   1920   ** and the callback returns [SQLITE_IGNORE] then the
  1902   1921   ** [prepared statement] statement is constructed to substitute
  1903   1922   ** a NULL value in place of the table column that would have
  1904   1923   ** been read if [SQLITE_OK] had been returned.  The [SQLITE_IGNORE]
  1905   1924   ** return can be used to deny an untrusted user access to individual
  1906   1925   ** columns of a table.
  1907         -** If the action code is [SQLITE_DELETE] and the callback returns
         1926  +** ^If the action code is [SQLITE_DELETE] and the callback returns
  1908   1927   ** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
  1909   1928   ** [truncate optimization] is disabled and all rows are deleted individually.
  1910   1929   **
  1911   1930   ** An authorizer is used when [sqlite3_prepare | preparing]
  1912   1931   ** SQL statements from an untrusted source, to ensure that the SQL statements
  1913   1932   ** do not try to access data they are not allowed to see, or that they do not
  1914   1933   ** try to execute malicious statements that damage the database.  For
................................................................................
  1920   1939   ** disallows everything except [SELECT] statements.
  1921   1940   **
  1922   1941   ** Applications that need to process SQL from untrusted sources
  1923   1942   ** might also consider lowering resource limits using [sqlite3_limit()]
  1924   1943   ** and limiting database size using the [max_page_count] [PRAGMA]
  1925   1944   ** in addition to using an authorizer.
  1926   1945   **
  1927         -** Only a single authorizer can be in place on a database connection
         1946  +** ^(Only a single authorizer can be in place on a database connection
  1928   1947   ** at a time.  Each call to sqlite3_set_authorizer overrides the
  1929         -** previous call.  Disable the authorizer by installing a NULL callback.
         1948  +** previous call.)^  ^Disable the authorizer by installing a NULL callback.
  1930   1949   ** The authorizer is disabled by default.
  1931   1950   **
  1932   1951   ** The authorizer callback must not do anything that will modify
  1933   1952   ** the database connection that invoked the authorizer callback.
  1934   1953   ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  1935   1954   ** database connections for the meaning of "modify" in this paragraph.
  1936   1955   **
  1937         -** When [sqlite3_prepare_v2()] is used to prepare a statement, the
         1956  +** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
  1938   1957   ** statement might be re-prepared during [sqlite3_step()] due to a 
  1939   1958   ** schema change.  Hence, the application should ensure that the
  1940   1959   ** correct authorizer callback remains in place during the [sqlite3_step()].
  1941   1960   **
  1942         -** Note that the authorizer callback is invoked only during
         1961  +** ^Note that the authorizer callback is invoked only during
  1943   1962   ** [sqlite3_prepare()] or its variants.  Authorization is not
  1944   1963   ** performed during statement evaluation in [sqlite3_step()], unless
  1945   1964   ** as stated in the previous paragraph, sqlite3_step() invokes
  1946   1965   ** sqlite3_prepare_v2() to reprepare a statement after a schema change.
  1947         -**
  1948         -** Requirements:
  1949         -** [H12501] [H12502] [H12503] [H12504] [H12505] [H12506] [H12507] [H12510]
  1950         -** [H12511] [H12512] [H12520] [H12521] [H12522]
  1951   1966   */
  1952   1967   SQLITE_API int sqlite3_set_authorizer(
  1953   1968     sqlite3*,
  1954   1969     int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
  1955   1970     void *pUserData
  1956   1971   );
  1957   1972   
  1958   1973   /*
  1959         -** CAPI3REF: Authorizer Return Codes {H12590} <H12500>
         1974  +** CAPI3REF: Authorizer Return Codes
  1960   1975   **
  1961   1976   ** The [sqlite3_set_authorizer | authorizer callback function] must
  1962   1977   ** return either [SQLITE_OK] or one of these two constants in order
  1963   1978   ** to signal SQLite whether or not the action is permitted.  See the
  1964   1979   ** [sqlite3_set_authorizer | authorizer documentation] for additional
  1965   1980   ** information.
  1966   1981   */
  1967   1982   #define SQLITE_DENY   1   /* Abort the SQL statement with an error */
  1968   1983   #define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
  1969   1984   
  1970   1985   /*
  1971         -** CAPI3REF: Authorizer Action Codes {H12550} <H12500>
         1986  +** CAPI3REF: Authorizer Action Codes
  1972   1987   **
  1973   1988   ** The [sqlite3_set_authorizer()] interface registers a callback function
  1974   1989   ** that is invoked to authorize certain SQL statement actions.  The
  1975   1990   ** second parameter to the callback is an integer code that specifies
  1976   1991   ** what action is being authorized.  These are the integer action codes that
  1977   1992   ** the authorizer callback may be passed.
  1978   1993   **
  1979   1994   ** These action code values signify what kind of operation is to be
  1980   1995   ** authorized.  The 3rd and 4th parameters to the authorization
  1981   1996   ** callback function will be parameters or NULL depending on which of these
  1982         -** codes is used as the second parameter.  The 5th parameter to the
         1997  +** codes is used as the second parameter.  ^(The 5th parameter to the
  1983   1998   ** authorizer callback is the name of the database ("main", "temp",
  1984         -** etc.) if applicable.  The 6th parameter to the authorizer callback
         1999  +** etc.) if applicable.)^  ^The 6th parameter to the authorizer callback
  1985   2000   ** is the name of the inner-most trigger or view that is responsible for
  1986   2001   ** the access attempt or NULL if this access attempt is directly from
  1987   2002   ** top-level SQL code.
  1988         -**
  1989         -** Requirements:
  1990         -** [H12551] [H12552] [H12553] [H12554]
  1991   2003   */
  1992   2004   /******************************************* 3rd ************ 4th ***********/
  1993   2005   #define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
  1994   2006   #define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
  1995   2007   #define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
  1996   2008   #define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
  1997   2009   #define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
................................................................................
  2021   2033   #define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
  2022   2034   #define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
  2023   2035   #define SQLITE_FUNCTION             31   /* NULL            Function Name   */
  2024   2036   #define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
  2025   2037   #define SQLITE_COPY                  0   /* No longer used */
  2026   2038   
  2027   2039   /*
  2028         -** CAPI3REF: Tracing And Profiling Functions {H12280} <S60400>
         2040  +** CAPI3REF: Tracing And Profiling Functions
  2029   2041   ** EXPERIMENTAL
  2030   2042   **
  2031   2043   ** These routines register callback functions that can be used for
  2032   2044   ** tracing and profiling the execution of SQL statements.
  2033   2045   **
  2034         -** The callback function registered by sqlite3_trace() is invoked at
         2046  +** ^The callback function registered by sqlite3_trace() is invoked at
  2035   2047   ** various times when an SQL statement is being run by [sqlite3_step()].
  2036         -** The callback returns a UTF-8 rendering of the SQL statement text
  2037         -** as the statement first begins executing.  Additional callbacks occur
         2048  +** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
         2049  +** SQL statement text as the statement first begins executing.
         2050  +** ^(Additional sqlite3_trace() callbacks might occur
  2038   2051   ** as each triggered subprogram is entered.  The callbacks for triggers
  2039         -** contain a UTF-8 SQL comment that identifies the trigger.
         2052  +** contain a UTF-8 SQL comment that identifies the trigger.)^
  2040   2053   **
  2041         -** The callback function registered by sqlite3_profile() is invoked
  2042         -** as each SQL statement finishes.  The profile callback contains
         2054  +** ^The callback function registered by sqlite3_profile() is invoked
         2055  +** as each SQL statement finishes.  ^The profile callback contains
  2043   2056   ** the original statement text and an estimate of wall-clock time
  2044   2057   ** of how long that statement took to run.
  2045         -**
  2046         -** Requirements:
  2047         -** [H12281] [H12282] [H12283] [H12284] [H12285] [H12287] [H12288] [H12289]
  2048         -** [H12290]
  2049   2058   */
  2050   2059   SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
  2051   2060   SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
  2052   2061      void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
  2053   2062   
  2054   2063   /*
  2055         -** CAPI3REF: Query Progress Callbacks {H12910} <S60400>
         2064  +** CAPI3REF: Query Progress Callbacks
  2056   2065   **
  2057         -** This routine configures a callback function - the
         2066  +** ^This routine configures a callback function - the
  2058   2067   ** progress callback - that is invoked periodically during long
  2059   2068   ** running calls to [sqlite3_exec()], [sqlite3_step()] and
  2060   2069   ** [sqlite3_get_table()].  An example use for this
  2061   2070   ** interface is to keep a GUI updated during a large query.
  2062   2071   **
  2063         -** If the progress callback returns non-zero, the operation is
         2072  +** ^If the progress callback returns non-zero, the operation is
  2064   2073   ** interrupted.  This feature can be used to implement a
  2065   2074   ** "Cancel" button on a GUI progress dialog box.
  2066   2075   **
  2067   2076   ** The progress handler must not do anything that will modify
  2068   2077   ** the database connection that invoked the progress handler.
  2069   2078   ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  2070   2079   ** database connections for the meaning of "modify" in this paragraph.
  2071   2080   **
  2072         -** Requirements:
  2073         -** [H12911] [H12912] [H12913] [H12914] [H12915] [H12916] [H12917] [H12918]
  2074         -**
  2075   2081   */
  2076   2082   SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
  2077   2083   
  2078   2084   /*
  2079         -** CAPI3REF: Opening A New Database Connection {H12700} <S40200>
         2085  +** CAPI3REF: Opening A New Database Connection
  2080   2086   **
  2081         -** These routines open an SQLite database file whose name is given by the
  2082         -** filename argument. The filename argument is interpreted as UTF-8 for
         2087  +** ^These routines open an SQLite database file whose name is given by the
         2088  +** filename argument. ^The filename argument is interpreted as UTF-8 for
  2083   2089   ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
  2084         -** order for sqlite3_open16(). A [database connection] handle is usually
         2090  +** order for sqlite3_open16(). ^(A [database connection] handle is usually
  2085   2091   ** returned in *ppDb, even if an error occurs.  The only exception is that
  2086   2092   ** if SQLite is unable to allocate memory to hold the [sqlite3] object,
  2087   2093   ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
  2088         -** object. If the database is opened (and/or created) successfully, then
  2089         -** [SQLITE_OK] is returned.  Otherwise an [error code] is returned.  The
         2094  +** object.)^ ^(If the database is opened (and/or created) successfully, then
         2095  +** [SQLITE_OK] is returned.  Otherwise an [error code] is returned.)^ ^The
  2090   2096   ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
  2091         -** an English language description of the error.
         2097  +** an English language description of the error following a failure of any
         2098  +** of the sqlite3_open() routines.
  2092   2099   **
  2093         -** The default encoding for the database will be UTF-8 if
         2100  +** ^The default encoding for the database will be UTF-8 if
  2094   2101   ** sqlite3_open() or sqlite3_open_v2() is called and
  2095   2102   ** UTF-16 in the native byte order if sqlite3_open16() is used.
  2096   2103   **
  2097   2104   ** Whether or not an error occurs when it is opened, resources
  2098   2105   ** associated with the [database connection] handle should be released by
  2099   2106   ** passing it to [sqlite3_close()] when it is no longer required.
  2100   2107   **
  2101   2108   ** The sqlite3_open_v2() interface works like sqlite3_open()
  2102   2109   ** except that it accepts two additional parameters for additional control
  2103         -** over the new database connection.  The flags parameter can take one of
         2110  +** over the new database connection.  ^(The flags parameter to
         2111  +** sqlite3_open_v2() can take one of
  2104   2112   ** the following three values, optionally combined with the 
  2105   2113   ** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
  2106         -** and/or [SQLITE_OPEN_PRIVATECACHE] flags:
         2114  +** and/or [SQLITE_OPEN_PRIVATECACHE] flags:)^
  2107   2115   **
  2108   2116   ** <dl>
  2109         -** <dt>[SQLITE_OPEN_READONLY]</dt>
         2117  +** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
  2110   2118   ** <dd>The database is opened in read-only mode.  If the database does not
  2111         -** already exist, an error is returned.</dd>
         2119  +** already exist, an error is returned.</dd>)^
  2112   2120   **
  2113         -** <dt>[SQLITE_OPEN_READWRITE]</dt>
         2121  +** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
  2114   2122   ** <dd>The database is opened for reading and writing if possible, or reading
  2115   2123   ** only if the file is write protected by the operating system.  In either
  2116         -** case the database must already exist, otherwise an error is returned.</dd>
         2124  +** case the database must already exist, otherwise an error is returned.</dd>)^
  2117   2125   **
  2118         -** <dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
         2126  +** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
  2119   2127   ** <dd>The database is opened for reading and writing, and is creates it if
  2120   2128   ** it does not already exist. This is the behavior that is always used for
  2121         -** sqlite3_open() and sqlite3_open16().</dd>
         2129  +** sqlite3_open() and sqlite3_open16().</dd>)^
  2122   2130   ** </dl>
  2123   2131   **
  2124   2132   ** If the 3rd parameter to sqlite3_open_v2() is not one of the
  2125   2133   ** combinations shown above or one of the combinations shown above combined
  2126   2134   ** with the [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX],
  2127   2135   ** [SQLITE_OPEN_SHAREDCACHE] and/or [SQLITE_OPEN_SHAREDCACHE] flags,
  2128   2136   ** then the behavior is undefined.
  2129   2137   **
  2130         -** If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
         2138  +** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
  2131   2139   ** opens in the multi-thread [threading mode] as long as the single-thread
  2132         -** mode has not been set at compile-time or start-time.  If the
         2140  +** mode has not been set at compile-time or start-time.  ^If the
  2133   2141   ** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
  2134   2142   ** in the serialized [threading mode] unless single-thread was
  2135   2143   ** previously selected at compile-time or start-time.
  2136         -** The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
         2144  +** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
  2137   2145   ** eligible to use [shared cache mode], regardless of whether or not shared
  2138         -** cache is enabled using [sqlite3_enable_shared_cache()].  The
         2146  +** cache is enabled using [sqlite3_enable_shared_cache()].  ^The
  2139   2147   ** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
  2140   2148   ** participate in [shared cache mode] even if it is enabled.
  2141   2149   **
  2142         -** If the filename is ":memory:", then a private, temporary in-memory database
  2143         -** is created for the connection.  This in-memory database will vanish when
         2150  +** ^If the filename is ":memory:", then a private, temporary in-memory database
         2151  +** is created for the connection.  ^This in-memory database will vanish when
  2144   2152   ** the database connection is closed.  Future versions of SQLite might
  2145   2153   ** make use of additional special filenames that begin with the ":" character.
  2146   2154   ** It is recommended that when a database filename actually does begin with
  2147   2155   ** a ":" character you should prefix the filename with a pathname such as
  2148   2156   ** "./" to avoid ambiguity.
  2149   2157   **
  2150         -** If the filename is an empty string, then a private, temporary
  2151         -** on-disk database will be created.  This private database will be
         2158  +** ^If the filename is an empty string, then a private, temporary
         2159  +** on-disk database will be created.  ^This private database will be
  2152   2160   ** automatically deleted as soon as the database connection is closed.
  2153   2161   **
  2154         -** The fourth parameter to sqlite3_open_v2() is the name of the
         2162  +** ^The fourth parameter to sqlite3_open_v2() is the name of the
  2155   2163   ** [sqlite3_vfs] object that defines the operating system interface that
  2156         -** the new database connection should use.  If the fourth parameter is
         2164  +** the new database connection should use.  ^If the fourth parameter is
  2157   2165   ** a NULL pointer then the default [sqlite3_vfs] object is used.
  2158   2166   **
  2159   2167   ** <b>Note to Windows users:</b>  The encoding used for the filename argument
  2160   2168   ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
  2161   2169   ** codepage is currently defined.  Filenames containing international
  2162   2170   ** characters must be converted to UTF-8 prior to passing them into
  2163   2171   ** sqlite3_open() or sqlite3_open_v2().
  2164         -**
  2165         -** Requirements:
  2166         -** [H12701] [H12702] [H12703] [H12704] [H12706] [H12707] [H12709] [H12711]
  2167         -** [H12712] [H12713] [H12714] [H12717] [H12719] [H12721] [H12723]
  2168   2172   */
  2169   2173   SQLITE_API int sqlite3_open(
  2170   2174     const char *filename,   /* Database filename (UTF-8) */
  2171   2175     sqlite3 **ppDb          /* OUT: SQLite db handle */
  2172   2176   );
  2173   2177   SQLITE_API int sqlite3_open16(
  2174   2178     const void *filename,   /* Database filename (UTF-16) */
................................................................................
  2178   2182     const char *filename,   /* Database filename (UTF-8) */
  2179   2183     sqlite3 **ppDb,         /* OUT: SQLite db handle */
  2180   2184     int flags,              /* Flags */
  2181   2185     const char *zVfs        /* Name of VFS module to use */
  2182   2186   );
  2183   2187   
  2184   2188   /*
  2185         -** CAPI3REF: Error Codes And Messages {H12800} <S60200>
         2189  +** CAPI3REF: Error Codes And Messages
  2186   2190   **
  2187         -** The sqlite3_errcode() interface returns the numeric [result code] or
         2191  +** ^The sqlite3_errcode() interface returns the numeric [result code] or
  2188   2192   ** [extended result code] for the most recent failed sqlite3_* API call
  2189   2193   ** associated with a [database connection]. If a prior API call failed
  2190   2194   ** but the most recent API call succeeded, the return value from
  2191         -** sqlite3_errcode() is undefined.  The sqlite3_extended_errcode()
         2195  +** sqlite3_errcode() is undefined.  ^The sqlite3_extended_errcode()
  2192   2196   ** interface is the same except that it always returns the 
  2193   2197   ** [extended result code] even when extended result codes are
  2194   2198   ** disabled.
  2195   2199   **
  2196         -** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
         2200  +** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
  2197   2201   ** text that describes the error, as either UTF-8 or UTF-16 respectively.
  2198         -** Memory to hold the error message string is managed internally.
         2202  +** ^(Memory to hold the error message string is managed internally.
  2199   2203   ** The application does not need to worry about freeing the result.
  2200   2204   ** However, the error string might be overwritten or deallocated by
  2201         -** subsequent calls to other SQLite interface functions.
         2205  +** subsequent calls to other SQLite interface functions.)^
  2202   2206   **
  2203   2207   ** When the serialized [threading mode] is in use, it might be the
  2204   2208   ** case that a second error occurs on a separate thread in between
  2205   2209   ** the time of the first error and the call to these interfaces.
  2206   2210   ** When that happens, the second error will be reported since these
  2207   2211   ** interfaces always report the most recent result.  To avoid
  2208   2212   ** this, each thread can obtain exclusive use of the [database connection] D
................................................................................
  2209   2213   ** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
  2210   2214   ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
  2211   2215   ** all calls to the interfaces listed here are completed.
  2212   2216   **
  2213   2217   ** If an interface fails with SQLITE_MISUSE, that means the interface
  2214   2218   ** was invoked incorrectly by the application.  In that case, the
  2215   2219   ** error code and message may or may not be set.
  2216         -**
  2217         -** Requirements:
  2218         -** [H12801] [H12802] [H12803] [H12807] [H12808] [H12809]
  2219   2220   */
  2220   2221   SQLITE_API int sqlite3_errcode(sqlite3 *db);
  2221   2222   SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
  2222   2223   SQLITE_API const char *sqlite3_errmsg(sqlite3*);
  2223   2224   SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
  2224   2225   
  2225   2226   /*
  2226         -** CAPI3REF: SQL Statement Object {H13000} <H13010>
         2227  +** CAPI3REF: SQL Statement Object
  2227   2228   ** KEYWORDS: {prepared statement} {prepared statements}
  2228   2229   **
  2229   2230   ** An instance of this object represents a single SQL statement.
  2230   2231   ** This object is variously known as a "prepared statement" or a
  2231   2232   ** "compiled SQL statement" or simply as a "statement".
  2232   2233   **
  2233   2234   ** The life of a statement object goes something like this:
................................................................................
  2245   2246   **
  2246   2247   ** Refer to documentation on individual methods above for additional
  2247   2248   ** information.
  2248   2249   */
  2249   2250   typedef struct sqlite3_stmt sqlite3_stmt;
  2250   2251   
  2251   2252   /*
  2252         -** CAPI3REF: Run-time Limits {H12760} <S20600>
         2253  +** CAPI3REF: Run-time Limits
  2253   2254   **
  2254         -** This interface allows the size of various constructs to be limited
         2255  +** ^(This interface allows the size of various constructs to be limited
  2255   2256   ** on a connection by connection basis.  The first parameter is the
  2256   2257   ** [database connection] whose limit is to be set or queried.  The
  2257   2258   ** second parameter is one of the [limit categories] that define a
  2258   2259   ** class of constructs to be size limited.  The third parameter is the
  2259         -** new limit for that construct.  The function returns the old limit.
         2260  +** new limit for that construct.  The function returns the old limit.)^
  2260   2261   **
  2261         -** If the new limit is a negative number, the limit is unchanged.
  2262         -** For the limit category of SQLITE_LIMIT_XYZ there is a 
         2262  +** ^If the new limit is a negative number, the limit is unchanged.
         2263  +** ^(For the limit category of SQLITE_LIMIT_XYZ there is a 
  2263   2264   ** [limits | hard upper bound]
  2264   2265   ** set by a compile-time C preprocessor macro named 
  2265   2266   ** [limits | SQLITE_MAX_XYZ].
  2266         -** (The "_LIMIT_" in the name is changed to "_MAX_".)
  2267         -** Attempts to increase a limit above its hard upper bound are
  2268         -** silently truncated to the hard upper limit.
         2267  +** (The "_LIMIT_" in the name is changed to "_MAX_".))^
         2268  +** ^Attempts to increase a limit above its hard upper bound are
         2269  +** silently truncated to the hard upper bound.
  2269   2270   **
  2270         -** Run time limits are intended for use in applications that manage
         2271  +** Run-time limits are intended for use in applications that manage
  2271   2272   ** both their own internal database and also databases that are controlled
  2272   2273   ** by untrusted external sources.  An example application might be a
  2273   2274   ** web browser that has its own databases for storing history and
  2274   2275   ** separate databases controlled by JavaScript applications downloaded
  2275   2276   ** off the Internet.  The internal databases can be given the
  2276   2277   ** large, default limits.  Databases managed by external sources can
  2277   2278   ** be given much smaller limits designed to prevent a denial of service
  2278   2279   ** attack.  Developers might also want to use the [sqlite3_set_authorizer()]
  2279   2280   ** interface to further control untrusted SQL.  The size of the database
  2280   2281   ** created by an untrusted script can be contained using the
  2281   2282   ** [max_page_count] [PRAGMA].
  2282   2283   **
  2283   2284   ** New run-time limit categories may be added in future releases.
  2284         -**
  2285         -** Requirements:
  2286         -** [H12762] [H12766] [H12769]
  2287   2285   */
  2288   2286   SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
  2289   2287   
  2290   2288   /*
  2291         -** CAPI3REF: Run-Time Limit Categories {H12790} <H12760>
         2289  +** CAPI3REF: Run-Time Limit Categories
  2292   2290   ** KEYWORDS: {limit category} {*limit categories}
  2293   2291   **
  2294   2292   ** These constants define various performance limits
  2295   2293   ** that can be lowered at run-time using [sqlite3_limit()].
  2296   2294   ** The synopsis of the meanings of the various limits is shown below.
  2297   2295   ** Additional information is available at [limits | Limits in SQLite].
  2298   2296   **
  2299   2297   ** <dl>
  2300         -** <dt>SQLITE_LIMIT_LENGTH</dt>
  2301         -** <dd>The maximum size of any string or BLOB or table row.<dd>
         2298  +** ^(<dt>SQLITE_LIMIT_LENGTH</dt>
         2299  +** <dd>The maximum size of any string or BLOB or table row.<dd>)^
  2302   2300   **
  2303         -** <dt>SQLITE_LIMIT_SQL_LENGTH</dt>
  2304         -** <dd>The maximum length of an SQL statement.</dd>
         2301  +** ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
         2302  +** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
  2305   2303   **
  2306         -** <dt>SQLITE_LIMIT_COLUMN</dt>
         2304  +** ^(<dt>SQLITE_LIMIT_COLUMN</dt>
  2307   2305   ** <dd>The maximum number of columns in a table definition or in the
  2308   2306   ** result set of a [SELECT] or the maximum number of columns in an index
  2309         -** or in an ORDER BY or GROUP BY clause.</dd>
         2307  +** or in an ORDER BY or GROUP BY clause.</dd>)^
  2310   2308   **
  2311         -** <dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
  2312         -** <dd>The maximum depth of the parse tree on any expression.</dd>
         2309  +** ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
         2310  +** <dd>The maximum depth of the parse tree on any expression.</dd>)^
  2313   2311   **
  2314         -** <dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
  2315         -** <dd>The maximum number of terms in a compound SELECT statement.</dd>
         2312  +** ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
         2313  +** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
  2316   2314   **
  2317         -** <dt>SQLITE_LIMIT_VDBE_OP</dt>
         2315  +** ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
  2318   2316   ** <dd>The maximum number of instructions in a virtual machine program
  2319         -** used to implement an SQL statement.</dd>
         2317  +** used to implement an SQL statement.</dd>)^
  2320   2318   **
  2321         -** <dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
  2322         -** <dd>The maximum number of arguments on a function.</dd>
         2319  +** ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
         2320  +** <dd>The maximum number of arguments on a function.</dd>)^
  2323   2321   **
  2324         -** <dt>SQLITE_LIMIT_ATTACHED</dt>
  2325         -** <dd>The maximum number of [ATTACH | attached databases].</dd>
         2322  +** ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
         2323  +** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
  2326   2324   **
  2327         -** <dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
         2325  +** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
  2328   2326   ** <dd>The maximum length of the pattern argument to the [LIKE] or
  2329         -** [GLOB] operators.</dd>
         2327  +** [GLOB] operators.</dd>)^
  2330   2328   **
  2331         -** <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
         2329  +** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
  2332   2330   ** <dd>The maximum number of variables in an SQL statement that can
  2333         -** be bound.</dd>
         2331  +** be bound.</dd>)^
  2334   2332   **
  2335         -** <dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
  2336         -** <dd>The maximum depth of recursion for triggers.</dd>
         2333  +** ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
         2334  +** <dd>The maximum depth of recursion for triggers.</dd>)^
  2337   2335   ** </dl>
  2338   2336   */
  2339   2337   #define SQLITE_LIMIT_LENGTH                    0
  2340   2338   #define SQLITE_LIMIT_SQL_LENGTH                1
  2341   2339   #define SQLITE_LIMIT_COLUMN                    2
  2342   2340   #define SQLITE_LIMIT_EXPR_DEPTH                3
  2343   2341   #define SQLITE_LIMIT_COMPOUND_SELECT           4
................................................................................
  2345   2343   #define SQLITE_LIMIT_FUNCTION_ARG              6
  2346   2344   #define SQLITE_LIMIT_ATTACHED                  7
  2347   2345   #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
  2348   2346   #define SQLITE_LIMIT_VARIABLE_NUMBER           9
  2349   2347   #define SQLITE_LIMIT_TRIGGER_DEPTH            10
  2350   2348   
  2351   2349   /*
  2352         -** CAPI3REF: Compiling An SQL Statement {H13010} <S10000>
         2350  +** CAPI3REF: Compiling An SQL Statement
  2353   2351   ** KEYWORDS: {SQL statement compiler}
  2354   2352   **
  2355   2353   ** To execute an SQL query, it must first be compiled into a byte-code
  2356   2354   ** program using one of these routines.
  2357   2355   **
  2358   2356   ** The first argument, "db", is a [database connection] obtained from a
  2359   2357   ** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
................................................................................
  2360   2358   ** [sqlite3_open16()].  The database connection must not have been closed.
  2361   2359   **
  2362   2360   ** The second argument, "zSql", is the statement to be compiled, encoded
  2363   2361   ** as either UTF-8 or UTF-16.  The sqlite3_prepare() and sqlite3_prepare_v2()
  2364   2362   ** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
  2365   2363   ** use UTF-16.
  2366   2364   **
  2367         -** If the nByte argument is less than zero, then zSql is read up to the
  2368         -** first zero terminator. If nByte is non-negative, then it is the maximum
  2369         -** number of  bytes read from zSql.  When nByte is non-negative, the
         2365  +** ^If the nByte argument is less than zero, then zSql is read up to the
         2366  +** first zero terminator. ^If nByte is non-negative, then it is the maximum
         2367  +** number of  bytes read from zSql.  ^When nByte is non-negative, the
  2370   2368   ** zSql string ends at either the first '\000' or '\u0000' character or
  2371   2369   ** the nByte-th byte, whichever comes first. If the caller knows
  2372   2370   ** that the supplied string is nul-terminated, then there is a small
  2373   2371   ** performance advantage to be gained by passing an nByte parameter that
  2374   2372   ** is equal to the number of bytes in the input string <i>including</i>
  2375   2373   ** the nul-terminator bytes.
  2376   2374   **
  2377         -** If pzTail is not NULL then *pzTail is made to point to the first byte
         2375  +** ^If pzTail is not NULL then *pzTail is made to point to the first byte
  2378   2376   ** past the end of the first SQL statement in zSql.  These routines only
  2379   2377   ** compile the first statement in zSql, so *pzTail is left pointing to
  2380   2378   ** what remains uncompiled.
  2381   2379   **
  2382         -** *ppStmt is left pointing to a compiled [prepared statement] that can be
  2383         -** executed using [sqlite3_step()].  If there is an error, *ppStmt is set
  2384         -** to NULL.  If the input text contains no SQL (if the input is an empty
         2380  +** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
         2381  +** executed using [sqlite3_step()].  ^If there is an error, *ppStmt is set
         2382  +** to NULL.  ^If the input text contains no SQL (if the input is an empty
  2385   2383   ** string or a comment) then *ppStmt is set to NULL.
  2386   2384   ** The calling procedure is responsible for deleting the compiled
  2387   2385   ** SQL statement using [sqlite3_finalize()] after it has finished with it.
  2388   2386   ** ppStmt may not be NULL.
  2389   2387   **
  2390         -** On success, [SQLITE_OK] is returned, otherwise an [error code] is returned.
         2388  +** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
         2389  +** otherwise an [error code] is returned.
  2391   2390   **
  2392   2391   ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
  2393   2392   ** recommended for all new programs. The two older interfaces are retained
  2394   2393   ** for backwards compatibility, but their use is discouraged.
  2395         -** In the "v2" interfaces, the prepared statement
         2394  +** ^In the "v2" interfaces, the prepared statement
  2396   2395   ** that is returned (the [sqlite3_stmt] object) contains a copy of the
  2397   2396   ** original SQL text. This causes the [sqlite3_step()] interface to
  2398         -** behave a differently in three ways:
         2397  +** behave differently in three ways:
  2399   2398   **
  2400   2399   ** <ol>
  2401   2400   ** <li>
  2402         -** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
         2401  +** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
  2403   2402   ** always used to do, [sqlite3_step()] will automatically recompile the SQL
  2404         -** statement and try to run it again.  If the schema has changed in
         2403  +** statement and try to run it again.  ^If the schema has changed in
  2405   2404   ** a way that makes the statement no longer valid, [sqlite3_step()] will still
  2406   2405   ** return [SQLITE_SCHEMA].  But unlike the legacy behavior, [SQLITE_SCHEMA] is
  2407   2406   ** now a fatal error.  Calling [sqlite3_prepare_v2()] again will not make the
  2408   2407   ** error go away.  Note: use [sqlite3_errmsg()] to find the text
  2409   2408   ** of the parsing error that results in an [SQLITE_SCHEMA] return.
  2410   2409   ** </li>
  2411   2410   **
  2412   2411   ** <li>
  2413         -** When an error occurs, [sqlite3_step()] will return one of the detailed
  2414         -** [error codes] or [extended error codes].  The legacy behavior was that
         2412  +** ^When an error occurs, [sqlite3_step()] will return one of the detailed
         2413  +** [error codes] or [extended error codes].  ^The legacy behavior was that
  2415   2414   ** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
  2416         -** and you would have to make a second call to [sqlite3_reset()] in order
  2417         -** to find the underlying cause of the problem. With the "v2" prepare
         2415  +** and the application would have to make a second call to [sqlite3_reset()]
         2416  +** in order to find the underlying cause of the problem. With the "v2" prepare
  2418   2417   ** interfaces, the underlying reason for the error is returned immediately.
  2419   2418   ** </li>
  2420   2419   **
  2421   2420   ** <li>
  2422   2421   ** ^If the value of a [parameter | host parameter] in the WHERE clause might
  2423   2422   ** change the query plan for a statement, then the statement may be
  2424   2423   ** automatically recompiled (as if there had been a schema change) on the first 
  2425   2424   ** [sqlite3_step()] call following any change to the 
  2426   2425   ** [sqlite3_bind_text | bindings] of the [parameter]. 
  2427   2426   ** </li>
  2428   2427   ** </ol>
  2429         -**
  2430         -** Requirements:
  2431         -** [H13011] [H13012] [H13013] [H13014] [H13015] [H13016] [H13019] [H13021]
  2432         -**
  2433   2428   */
  2434   2429   SQLITE_API int sqlite3_prepare(
  2435   2430     sqlite3 *db,            /* Database handle */
  2436   2431     const char *zSql,       /* SQL statement, UTF-8 encoded */
  2437   2432     int nByte,              /* Maximum length of zSql in bytes. */
  2438   2433     sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  2439   2434     const char **pzTail     /* OUT: Pointer to unused portion of zSql */
................................................................................
  2457   2452     const void *zSql,       /* SQL statement, UTF-16 encoded */
  2458   2453     int nByte,              /* Maximum length of zSql in bytes. */
  2459   2454     sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  2460   2455     const void **pzTail     /* OUT: Pointer to unused portion of zSql */
  2461   2456   );
  2462   2457   
  2463   2458   /*
  2464         -** CAPI3REF: Retrieving Statement SQL {H13100} <H13000>
         2459  +** CAPI3REF: Retrieving Statement SQL
  2465   2460   **
  2466         -** This interface can be used to retrieve a saved copy of the original
         2461  +** ^This interface can be used to retrieve a saved copy of the original
  2467   2462   ** SQL text used to create a [prepared statement] if that statement was
  2468   2463   ** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
  2469         -**
  2470         -** Requirements:
  2471         -** [H13101] [H13102] [H13103]
  2472   2464   */
  2473   2465   SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
  2474   2466   
  2475   2467   /*
  2476         -** CAPI3REF: Dynamically Typed Value Object {H15000} <S20200>
         2468  +** CAPI3REF: Dynamically Typed Value Object
  2477   2469   ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
  2478   2470   **
  2479   2471   ** SQLite uses the sqlite3_value object to represent all values
  2480   2472   ** that can be stored in a database table. SQLite uses dynamic typing
  2481         -** for the values it stores. Values stored in sqlite3_value objects
         2473  +** for the values it stores.  ^Values stored in sqlite3_value objects
  2482   2474   ** can be integers, floating point values, strings, BLOBs, or NULL.
  2483   2475   **
  2484   2476   ** An sqlite3_value object may be either "protected" or "unprotected".
  2485   2477   ** Some interfaces require a protected sqlite3_value.  Other interfaces
  2486   2478   ** will accept either a protected or an unprotected sqlite3_value.
  2487   2479   ** Every interface that accepts sqlite3_value arguments specifies
  2488   2480   ** whether or not it requires a protected sqlite3_value.
................................................................................
  2496   2488   ** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
  2497   2489   ** then there is no distinction between protected and unprotected
  2498   2490   ** sqlite3_value objects and they can be used interchangeably.  However,
  2499   2491   ** for maximum code portability it is recommended that applications
  2500   2492   ** still make the distinction between between protected and unprotected
  2501   2493   ** sqlite3_value objects even when not strictly required.
  2502   2494   **
  2503         -** The sqlite3_value objects that are passed as parameters into the
         2495  +** ^The sqlite3_value objects that are passed as parameters into the
  2504   2496   ** implementation of [application-defined SQL functions] are protected.
  2505         -** The sqlite3_value object returned by
         2497  +** ^The sqlite3_value object returned by
  2506   2498   ** [sqlite3_column_value()] is unprotected.
  2507   2499   ** Unprotected sqlite3_value objects may only be used with
  2508   2500   ** [sqlite3_result_value()] and [sqlite3_bind_value()].
  2509   2501   ** The [sqlite3_value_blob | sqlite3_value_type()] family of
  2510   2502   ** interfaces require protected sqlite3_value objects.
  2511   2503   */
  2512   2504   typedef struct Mem sqlite3_value;
  2513   2505   
  2514   2506   /*
  2515         -** CAPI3REF: SQL Function Context Object {H16001} <S20200>
         2507  +** CAPI3REF: SQL Function Context Object
  2516   2508   **
  2517   2509   ** The context in which an SQL function executes is stored in an
  2518         -** sqlite3_context object.  A pointer to an sqlite3_context object
         2510  +** sqlite3_context object.  ^A pointer to an sqlite3_context object
  2519   2511   ** is always first parameter to [application-defined SQL functions].
  2520   2512   ** The application-defined SQL function implementation will pass this
  2521   2513   ** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
  2522   2514   ** [sqlite3_aggregate_context()], [sqlite3_user_data()],
  2523   2515   ** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
  2524   2516   ** and/or [sqlite3_set_auxdata()].
  2525   2517   */
  2526   2518   typedef struct sqlite3_context sqlite3_context;
  2527   2519   
  2528   2520   /*
  2529         -** CAPI3REF: Binding Values To Prepared Statements {H13500} <S70300>
         2521  +** CAPI3REF: Binding Values To Prepared Statements
  2530   2522   ** KEYWORDS: {host parameter} {host parameters} {host parameter name}
  2531   2523   ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
  2532   2524   **
  2533         -** In the SQL strings input to [sqlite3_prepare_v2()] and its variants,
         2525  +** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
  2534   2526   ** literals may be replaced by a [parameter] that matches one of following
  2535   2527   ** templates:
  2536   2528   **
  2537   2529   ** <ul>
  2538   2530   ** <li>  ?
  2539   2531   ** <li>  ?NNN
  2540   2532   ** <li>  :VVV
  2541   2533   ** <li>  @VVV
  2542   2534   ** <li>  $VVV
  2543   2535   ** </ul>
  2544   2536   **
  2545   2537   ** In the templates above, NNN represents an integer literal,
  2546         -** and VVV represents an alphanumeric identifer.  The values of these
         2538  +** and VVV represents an alphanumeric identifer.)^  ^The values of these
  2547   2539   ** parameters (also called "host parameter names" or "SQL parameters")
  2548   2540   ** can be set using the sqlite3_bind_*() routines defined here.
  2549   2541   **
  2550         -** The first argument to the sqlite3_bind_*() routines is always
         2542  +** ^The first argument to the sqlite3_bind_*() routines is always
  2551   2543   ** a pointer to the [sqlite3_stmt] object returned from
  2552   2544   ** [sqlite3_prepare_v2()] or its variants.
  2553   2545   **
  2554         -** The second argument is the index of the SQL parameter to be set.
  2555         -** The leftmost SQL parameter has an index of 1.  When the same named
         2546  +** ^The second argument is the index of the SQL parameter to be set.
         2547  +** ^The leftmost SQL parameter has an index of 1.  ^When the same named
  2556   2548   ** SQL parameter is used more than once, second and subsequent
  2557   2549   ** occurrences have the same index as the first occurrence.
  2558         -** The index for named parameters can be looked up using the
  2559         -** [sqlite3_bind_parameter_index()] API if desired.  The index
         2550  +** ^The index for named parameters can be looked up using the
         2551  +** [sqlite3_bind_parameter_index()] API if desired.  ^The index
  2560   2552   ** for "?NNN" parameters is the value of NNN.
  2561         -** The NNN value must be between 1 and the [sqlite3_limit()]
         2553  +** ^The NNN value must be between 1 and the [sqlite3_limit()]
  2562   2554   ** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
  2563   2555   **
  2564         -** The third argument is the value to bind to the parameter.
         2556  +** ^The third argument is the value to bind to the parameter.
  2565   2557   **
  2566         -** In those routines that have a fourth argument, its value is the
         2558  +** ^(In those routines that have a fourth argument, its value is the
  2567   2559   ** number of bytes in the parameter.  To be clear: the value is the
  2568         -** number of <u>bytes</u> in the value, not the number of characters.
  2569         -** If the fourth parameter is negative, the length of the string is
         2560  +** number of <u>bytes</u> in the value, not the number of characters.)^
         2561  +** ^If the fourth parameter is negative, the length of the string is
  2570   2562   ** the number of bytes up to the first zero terminator.
  2571   2563   **
  2572         -** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
         2564  +** ^The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
  2573   2565   ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
  2574         -** string after SQLite has finished with it. If the fifth argument is
         2566  +** string after SQLite has finished with it. ^If the fifth argument is
  2575   2567   ** the special value [SQLITE_STATIC], then SQLite assumes that the
  2576   2568   ** information is in static, unmanaged space and does not need to be freed.
  2577         -** If the fifth argument has the value [SQLITE_TRANSIENT], then
         2569  +** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
  2578   2570   ** SQLite makes its own private copy of the data immediately, before
  2579   2571   ** the sqlite3_bind_*() routine returns.
  2580   2572   **
  2581         -** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
  2582         -** is filled with zeroes.  A zeroblob uses a fixed amount of memory
         2573  +** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
         2574  +** is filled with zeroes.  ^A zeroblob uses a fixed amount of memory
  2583   2575   ** (just an integer to hold its size) while it is being processed.
  2584   2576   ** Zeroblobs are intended to serve as placeholders for BLOBs whose
  2585   2577   ** content is later written using
  2586   2578   ** [sqlite3_blob_open | incremental BLOB I/O] routines.
  2587         -** A negative value for the zeroblob results in a zero-length BLOB.
         2579  +** ^A negative value for the zeroblob results in a zero-length BLOB.
  2588   2580   **
  2589         -** The sqlite3_bind_*() routines must be called after
  2590         -** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
  2591         -** before [sqlite3_step()].
  2592         -** Bindings are not cleared by the [sqlite3_reset()] routine.
  2593         -** Unbound parameters are interpreted as NULL.
         2581  +** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
         2582  +** for the [prepared statement] or with a prepared statement for which
         2583  +** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
         2584  +** then the call will return [SQLITE_MISUSE].  If any sqlite3_bind_()
         2585  +** routine is passed a [prepared statement] that has been finalized, the
         2586  +** result is undefined and probably harmful.
  2594   2587   **
  2595         -** These routines return [SQLITE_OK] on success or an error code if
  2596         -** anything goes wrong.  [SQLITE_RANGE] is returned if the parameter
  2597         -** index is out of range.  [SQLITE_NOMEM] is returned if malloc() fails.
  2598         -** [SQLITE_MISUSE] might be returned if these routines are called on a
  2599         -** virtual machine that is the wrong state or which has already been finalized.
  2600         -** Detection of misuse is unreliable.  Applications should not depend
  2601         -** on SQLITE_MISUSE returns.  SQLITE_MISUSE is intended to indicate a
  2602         -** a logic error in the application.  Future versions of SQLite might
  2603         -** panic rather than return SQLITE_MISUSE.
         2588  +** ^Bindings are not cleared by the [sqlite3_reset()] routine.
         2589  +** ^Unbound parameters are interpreted as NULL.
         2590  +**
         2591  +** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
         2592  +** [error code] if anything goes wrong.
         2593  +** ^[SQLITE_RANGE] is returned if the parameter
         2594  +** index is out of range.  ^[SQLITE_NOMEM] is returned if malloc() fails.
  2604   2595   **
  2605   2596   ** See also: [sqlite3_bind_parameter_count()],
  2606   2597   ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
  2607         -**
  2608         -** Requirements:
  2609         -** [H13506] [H13509] [H13512] [H13515] [H13518] [H13521] [H13524] [H13527]
  2610         -** [H13530] [H13533] [H13536] [H13539] [H13542] [H13545] [H13548] [H13551]
  2611         -**
  2612   2598   */
  2613   2599   SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
  2614   2600   SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
  2615   2601   SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
  2616   2602   SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
  2617   2603   SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
  2618   2604   SQLITE_API int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
  2619   2605   SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
  2620   2606   SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
  2621   2607   SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
  2622   2608   
  2623   2609   /*
  2624         -** CAPI3REF: Number Of SQL Parameters {H13600} <S70300>
         2610  +** CAPI3REF: Number Of SQL Parameters
  2625   2611   **
  2626         -** This routine can be used to find the number of [SQL parameters]
         2612  +** ^This routine can be used to find the number of [SQL parameters]
  2627   2613   ** in a [prepared statement].  SQL parameters are tokens of the
  2628   2614   ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
  2629   2615   ** placeholders for values that are [sqlite3_bind_blob | bound]
  2630   2616   ** to the parameters at a later time.
  2631   2617   **
  2632         -** This routine actually returns the index of the largest (rightmost)
         2618  +** ^(This routine actually returns the index of the largest (rightmost)
  2633   2619   ** parameter. For all forms except ?NNN, this will correspond to the
  2634         -** number of unique parameters.  If parameters of the ?NNN are used,
  2635         -** there may be gaps in the list.
         2620  +** number of unique parameters.  If parameters of the ?NNN form are used,
         2621  +** there may be gaps in the list.)^
  2636   2622   **
  2637   2623   ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  2638   2624   ** [sqlite3_bind_parameter_name()], and
  2639   2625   ** [sqlite3_bind_parameter_index()].
  2640         -**
  2641         -** Requirements:
  2642         -** [H13601]
  2643   2626   */
  2644   2627   SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
  2645   2628   
  2646   2629   /*
  2647         -** CAPI3REF: Name Of A Host Parameter {H13620} <S70300>
         2630  +** CAPI3REF: Name Of A Host Parameter
  2648   2631   **
  2649         -** This routine returns a pointer to the name of the n-th
  2650         -** [SQL parameter] in a [prepared statement].
  2651         -** SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
         2632  +** ^The sqlite3_bind_parameter_name(P,N) interface returns
         2633  +** the name of the N-th [SQL parameter] in the [prepared statement] P.
         2634  +** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
  2652   2635   ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
  2653   2636   ** respectively.
  2654   2637   ** In other words, the initial ":" or "$" or "@" or "?"
  2655         -** is included as part of the name.
  2656         -** Parameters of the form "?" without a following integer have no name
  2657         -** and are also referred to as "anonymous parameters".
         2638  +** is included as part of the name.)^
         2639  +** ^Parameters of the form "?" without a following integer have no name
         2640  +** and are referred to as "nameless" or "anonymous parameters".
  2658   2641   **
  2659         -** The first host parameter has an index of 1, not 0.
         2642  +** ^The first host parameter has an index of 1, not 0.
  2660   2643   **
  2661         -** If the value n is out of range or if the n-th parameter is
  2662         -** nameless, then NULL is returned.  The returned string is
         2644  +** ^If the value N is out of range or if the N-th parameter is
         2645  +** nameless, then NULL is returned.  ^The returned string is
  2663   2646   ** always in UTF-8 encoding even if the named parameter was
  2664   2647   ** originally specified as UTF-16 in [sqlite3_prepare16()] or
  2665   2648   ** [sqlite3_prepare16_v2()].
  2666   2649   **
  2667   2650   ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  2668   2651   ** [sqlite3_bind_parameter_count()], and
  2669   2652   ** [sqlite3_bind_parameter_index()].
  2670         -**
  2671         -** Requirements:
  2672         -** [H13621]
  2673   2653   */
  2674   2654   SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
  2675   2655   
  2676   2656   /*
  2677         -** CAPI3REF: Index Of A Parameter With A Given Name {H13640} <S70300>
         2657  +** CAPI3REF: Index Of A Parameter With A Given Name
  2678   2658   **
  2679         -** Return the index of an SQL parameter given its name.  The
         2659  +** ^Return the index of an SQL parameter given its name.  ^The
  2680   2660   ** index value returned is suitable for use as the second
  2681         -** parameter to [sqlite3_bind_blob|sqlite3_bind()].  A zero
  2682         -** is returned if no matching parameter is found.  The parameter
         2661  +** parameter to [sqlite3_bind_blob|sqlite3_bind()].  ^A zero
         2662  +** is returned if no matching parameter is found.  ^The parameter
  2683   2663   ** name must be given in UTF-8 even if the original statement
  2684   2664   ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
  2685   2665   **
  2686   2666   ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  2687   2667   ** [sqlite3_bind_parameter_count()], and
  2688   2668   ** [sqlite3_bind_parameter_index()].
  2689         -**
  2690         -** Requirements:
  2691         -** [H13641]
  2692   2669   */
  2693   2670   SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
  2694   2671   
  2695   2672   /*
  2696         -** CAPI3REF: Reset All Bindings On A Prepared Statement {H13660} <S70300>
         2673  +** CAPI3REF: Reset All Bindings On A Prepared Statement
  2697   2674   **
  2698         -** Contrary to the intuition of many, [sqlite3_reset()] does not reset
         2675  +** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
  2699   2676   ** the [sqlite3_bind_blob | bindings] on a [prepared statement].
  2700         -** Use this routine to reset all host parameters to NULL.
  2701         -**
  2702         -** Requirements:
  2703         -** [H13661]
         2677  +** ^Use this routine to reset all host parameters to NULL.
  2704   2678   */
  2705   2679   SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
  2706   2680   
  2707   2681   /*
  2708         -** CAPI3REF: Number Of Columns In A Result Set {H13710} <S10700>
         2682  +** CAPI3REF: Number Of Columns In A Result Set
  2709   2683   **
  2710         -** Return the number of columns in the result set returned by the
  2711         -** [prepared statement]. This routine returns 0 if pStmt is an SQL
         2684  +** ^Return the number of columns in the result set returned by the
         2685  +** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
  2712   2686   ** statement that does not return data (for example an [UPDATE]).
  2713         -**
  2714         -** Requirements:
  2715         -** [H13711]
  2716   2687   */
  2717   2688   SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
  2718   2689   
  2719   2690   /*
  2720         -** CAPI3REF: Column Names In A Result Set {H13720} <S10700>
         2691  +** CAPI3REF: Column Names In A Result Set
  2721   2692   **
  2722         -** These routines return the name assigned to a particular column
  2723         -** in the result set of a [SELECT] statement.  The sqlite3_column_name()
         2693  +** ^These routines return the name assigned to a particular column
         2694  +** in the result set of a [SELECT] statement.  ^The sqlite3_column_name()
  2724   2695   ** interface returns a pointer to a zero-terminated UTF-8 string
  2725   2696   ** and sqlite3_column_name16() returns a pointer to a zero-terminated
  2726         -** UTF-16 string.  The first parameter is the [prepared statement]
  2727         -** that implements the [SELECT] statement. The second parameter is the
  2728         -** column number.  The leftmost column is number 0.
         2697  +** UTF-16 string.  ^The first parameter is the [prepared statement]
         2698  +** that implements the [SELECT] statement. ^The second parameter is the
         2699  +** column number.  ^The leftmost column is number 0.
  2729   2700   **
  2730         -** The returned string pointer is valid until either the [prepared statement]
         2701  +** ^The returned string pointer is valid until either the [prepared statement]
  2731   2702   ** is destroyed by [sqlite3_finalize()] or until the next call to
  2732   2703   ** sqlite3_column_name() or sqlite3_column_name16() on the same column.
  2733   2704   **
  2734         -** If sqlite3_malloc() fails during the processing of either routine
         2705  +** ^If sqlite3_malloc() fails during the processing of either routine
  2735   2706   ** (for example during a conversion from UTF-8 to UTF-16) then a
  2736   2707   ** NULL pointer is returned.
  2737   2708   **
  2738         -** The name of a result column is the value of the "AS" clause for
         2709  +** ^The name of a result column is the value of the "AS" clause for
  2739   2710   ** that column, if there is an AS clause.  If there is no AS clause
  2740   2711   ** then the name of the column is unspecified and may change from
  2741   2712   ** one release of SQLite to the next.
  2742         -**
  2743         -** Requirements:
  2744         -** [H13721] [H13723] [H13724] [H13725] [H13726] [H13727]
  2745   2713   */
  2746   2714   SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
  2747   2715   SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
  2748   2716   
  2749   2717   /*
  2750         -** CAPI3REF: Source Of Data In A Query Result {H13740} <S10700>
         2718  +** CAPI3REF: Source Of Data In A Query Result
  2751   2719   **
  2752         -** These routines provide a means to determine what column of what
  2753         -** table in which database a result of a [SELECT] statement comes from.
  2754         -** The name of the database or table or column can be returned as
  2755         -** either a UTF-8 or UTF-16 string.  The _database_ routines return
         2720  +** ^These routines provide a means to determine the database, table, and
         2721  +** table column that is the origin of a particular result column in
         2722  +** [SELECT] statement.
         2723  +** ^The name of the database or table or column can be returned as
         2724  +** either a UTF-8 or UTF-16 string.  ^The _database_ routines return
  2756   2725   ** the database name, the _table_ routines return the table name, and
  2757   2726   ** the origin_ routines return the column name.
  2758         -** The returned string is valid until the [prepared statement] is destroyed
         2727  +** ^The returned string is valid until the [prepared statement] is destroyed
  2759   2728   ** using [sqlite3_finalize()] or until the same information is requested
  2760   2729   ** again in a different encoding.
  2761   2730   **
  2762         -** The names returned are the original un-aliased names of the
         2731  +** ^The names returned are the original un-aliased names of the
  2763   2732   ** database, table, and column.
  2764   2733   **
  2765         -** The first argument to the following calls is a [prepared statement].
  2766         -** These functions return information about the Nth column returned by
         2734  +** ^The first argument to these interfaces is a [prepared statement].
         2735  +** ^These functions return information about the Nth result column returned by
  2767   2736   ** the statement, where N is the second function argument.
         2737  +** ^The left-most column is column 0 for these routines.
  2768   2738   **
  2769         -** If the Nth column returned by the statement is an expression or
         2739  +** ^If the Nth column returned by the statement is an expression or
  2770   2740   ** subquery and is not a column value, then all of these functions return
  2771         -** NULL.  These routine might also return NULL if a memory allocation error
  2772         -** occurs.  Otherwise, they return the name of the attached database, table
  2773         -** and column that query result column was extracted from.
         2741  +** NULL.  ^These routine might also return NULL if a memory allocation error
         2742  +** occurs.  ^Otherwise, they return the name of the attached database, table,
         2743  +** or column that query result column was extracted from.
  2774   2744   **
  2775         -** As with all other SQLite APIs, those postfixed with "16" return
  2776         -** UTF-16 encoded strings, the other functions return UTF-8. {END}
         2745  +** ^As with all other SQLite APIs, those whose names end with "16" return
         2746  +** UTF-16 encoded strings and the other functions return UTF-8.
  2777   2747   **
  2778         -** These APIs are only available if the library was compiled with the
  2779         -** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined.
         2748  +** ^These APIs are only available if the library was compiled with the
         2749  +** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
  2780   2750   **
  2781         -** {A13751}
  2782   2751   ** If two or more threads call one or more of these routines against the same
  2783   2752   ** prepared statement and column at the same time then the results are
  2784   2753   ** undefined.
  2785   2754   **
  2786         -** Requirements:
  2787         -** [H13741] [H13742] [H13743] [H13744] [H13745] [H13746] [H13748]
  2788         -**
  2789   2755   ** If two or more threads call one or more
  2790   2756   ** [sqlite3_column_database_name | column metadata interfaces]
  2791   2757   ** for the same [prepared statement] and result column
  2792   2758   ** at the same time then the results are undefined.
  2793   2759   */
  2794   2760   SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
  2795   2761   SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
  2796   2762   SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
  2797   2763   SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
  2798   2764   SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
  2799   2765   SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
  2800   2766   
  2801   2767   /*
  2802         -** CAPI3REF: Declared Datatype Of A Query Result {H13760} <S10700>
         2768  +** CAPI3REF: Declared Datatype Of A Query Result
  2803   2769   **
  2804         -** The first parameter is a [prepared statement].
         2770  +** ^(The first parameter is a [prepared statement].
  2805   2771   ** If this statement is a [SELECT] statement and the Nth column of the
  2806   2772   ** returned result set of that [SELECT] is a table column (not an
  2807   2773   ** expression or subquery) then the declared type of the table
  2808         -** column is returned.  If the Nth column of the result set is an
         2774  +** column is returned.)^  ^If the Nth column of the result set is an
  2809   2775   ** expression or subquery, then a NULL pointer is returned.
  2810         -** The returned string is always UTF-8 encoded. {END}
         2776  +** ^The returned string is always UTF-8 encoded.
  2811   2777   **
  2812         -** For example, given the database schema:
         2778  +** ^(For example, given the database schema:
  2813   2779   **
  2814   2780   ** CREATE TABLE t1(c1 VARIANT);
  2815   2781   **
  2816   2782   ** and the following statement to be compiled:
  2817   2783   **
  2818   2784   ** SELECT c1 + 1, c1 FROM t1;
  2819   2785   **
  2820   2786   ** this routine would return the string "VARIANT" for the second result
  2821         -** column (i==1), and a NULL pointer for the first result column (i==0).
         2787  +** column (i==1), and a NULL pointer for the first result column (i==0).)^
  2822   2788   **
  2823         -** SQLite uses dynamic run-time typing.  So just because a column
         2789  +** ^SQLite uses dynamic run-time typing.  ^So just because a column
  2824   2790   ** is declared to contain a particular type does not mean that the
  2825   2791   ** data stored in that column is of the declared type.  SQLite is
  2826         -** strongly typed, but the typing is dynamic not static.  Type
         2792  +** strongly typed, but the typing is dynamic not static.  ^Type
  2827   2793   ** is associated with individual values, not with the containers
  2828   2794   ** used to hold those values.
  2829         -**
  2830         -** Requirements:
  2831         -** [H13761] [H13762] [H13763]
  2832   2795   */
  2833   2796   SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
  2834   2797   SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
  2835   2798   
  2836   2799   /*
  2837         -** CAPI3REF: Evaluate An SQL Statement {H13200} <S10000>
         2800  +** CAPI3REF: Evaluate An SQL Statement
  2838   2801   **
  2839   2802   ** After a [prepared statement] has been prepared using either
  2840   2803   ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
  2841   2804   ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
  2842   2805   ** must be called one or more times to evaluate the statement.
  2843   2806   **
  2844   2807   ** The details of the behavior of the sqlite3_step() interface depend
  2845   2808   ** on whether the statement was prepared using the newer "v2" interface
  2846   2809   ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
  2847   2810   ** interface [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the
  2848   2811   ** new "v2" interface is recommended for new applications but the legacy
  2849   2812   ** interface will continue to be supported.
  2850   2813   **
  2851         -** In the legacy interface, the return value will be either [SQLITE_BUSY],
         2814  +** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
  2852   2815   ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
  2853         -** With the "v2" interface, any of the other [result codes] or
         2816  +** ^With the "v2" interface, any of the other [result codes] or
  2854   2817   ** [extended result codes] might be returned as well.
  2855   2818   **
  2856         -** [SQLITE_BUSY] means that the database engine was unable to acquire the
  2857         -** database locks it needs to do its job.  If the statement is a [COMMIT]
         2819  +** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
         2820  +** database locks it needs to do its job.  ^If the statement is a [COMMIT]
  2858   2821   ** or occurs outside of an explicit transaction, then you can retry the
  2859   2822   ** statement.  If the statement is not a [COMMIT] and occurs within a
  2860   2823   ** explicit transaction then you should rollback the transaction before
  2861   2824   ** continuing.
  2862   2825   **
  2863         -** [SQLITE_DONE] means that the statement has finished executing
         2826  +** ^[SQLITE_DONE] means that the statement has finished executing
  2864   2827   ** successfully.  sqlite3_step() should not be called again on this virtual
  2865   2828   ** machine without first calling [sqlite3_reset()] to reset the virtual
  2866   2829   ** machine back to its initial state.
  2867   2830   **
  2868         -** If the SQL statement being executed returns any data, then [SQLITE_ROW]
         2831  +** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
  2869   2832   ** is returned each time a new row of data is ready for processing by the
  2870   2833   ** caller. The values may be accessed using the [column access functions].
  2871   2834   ** sqlite3_step() is called again to retrieve the next row of data.
  2872   2835   **
  2873         -** [SQLITE_ERROR] means that a run-time error (such as a constraint
         2836  +** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
  2874   2837   ** violation) has occurred.  sqlite3_step() should not be called again on
  2875   2838   ** the VM. More information may be found by calling [sqlite3_errmsg()].
  2876         -** With the legacy interface, a more specific error code (for example,
         2839  +** ^With the legacy interface, a more specific error code (for example,
  2877   2840   ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
  2878   2841   ** can be obtained by calling [sqlite3_reset()] on the
  2879         -** [prepared statement].  In the "v2" interface,
         2842  +** [prepared statement].  ^In the "v2" interface,
  2880   2843   ** the more specific error code is returned directly by sqlite3_step().
  2881   2844   **
  2882   2845   ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
  2883   2846   ** Perhaps it was called on a [prepared statement] that has
  2884   2847   ** already been [sqlite3_finalize | finalized] or on one that had
  2885   2848   ** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
  2886   2849   ** be the case that the same database connection is being used by two or
................................................................................
  2893   2856   ** specific [error codes] that better describes the error.
  2894   2857   ** We admit that this is a goofy design.  The problem has been fixed
  2895   2858   ** with the "v2" interface.  If you prepare all of your SQL statements
  2896   2859   ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
  2897   2860   ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
  2898   2861   ** then the more specific [error codes] are returned directly
  2899   2862   ** by sqlite3_step().  The use of the "v2" interface is recommended.
  2900         -**
  2901         -** Requirements:
  2902         -** [H13202] [H15304] [H15306] [H15308] [H15310]
  2903   2863   */
  2904   2864   SQLITE_API int sqlite3_step(sqlite3_stmt*);
  2905   2865   
  2906   2866   /*
  2907         -** CAPI3REF: Number of columns in a result set {H13770} <S10700>
         2867  +** CAPI3REF: Number of columns in a result set
  2908   2868   **
  2909         -** Returns the number of values in the current row of the result set.
  2910         -**
  2911         -** Requirements:
  2912         -** [H13771] [H13772]
         2869  +** ^The sqlite3_data_count(P) the number of columns in the
         2870  +** of the result set of [prepared statement] P.
  2913   2871   */
  2914   2872   SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
  2915   2873   
  2916   2874   /*
  2917         -** CAPI3REF: Fundamental Datatypes {H10265} <S10110><S10120>
         2875  +** CAPI3REF: Fundamental Datatypes
  2918   2876   ** KEYWORDS: SQLITE_TEXT
  2919   2877   **
  2920         -** {H10266} Every value in SQLite has one of five fundamental datatypes:
         2878  +** ^(Every value in SQLite has one of five fundamental datatypes:
  2921   2879   **
  2922   2880   ** <ul>
  2923   2881   ** <li> 64-bit signed integer
  2924   2882   ** <li> 64-bit IEEE floating point number
  2925   2883   ** <li> string
  2926   2884   ** <li> BLOB
  2927   2885   ** <li> NULL
  2928         -** </ul> {END}
         2886  +** </ul>)^
  2929   2887   **
  2930   2888   ** These constants are codes for each of those types.
  2931   2889   **
  2932   2890   ** Note that the SQLITE_TEXT constant was also used in SQLite version 2
  2933   2891   ** for a completely different meaning.  Software that links against both
  2934   2892   ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
  2935   2893   ** SQLITE_TEXT.
................................................................................
  2942   2900   # undef SQLITE_TEXT
  2943   2901   #else
  2944   2902   # define SQLITE_TEXT     3
  2945   2903   #endif
  2946   2904   #define SQLITE3_TEXT     3
  2947   2905   
  2948   2906   /*
  2949         -** CAPI3REF: Result Values From A Query {H13800} <S10700>
         2907  +** CAPI3REF: Result Values From A Query
  2950   2908   ** KEYWORDS: {column access functions}
  2951   2909   **
  2952         -** These routines form the "result set query" interface.
         2910  +** These routines form the "result set" interface.
  2953   2911   **
  2954         -** These routines return information about a single column of the current
  2955         -** result row of a query.  In every case the first argument is a pointer
         2912  +** ^These routines return information about a single column of the current
         2913  +** result row of a query.  ^In every case the first argument is a pointer
  2956   2914   ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
  2957   2915   ** that was returned from [sqlite3_prepare_v2()] or one of its variants)
  2958   2916   ** and the second argument is the index of the column for which information
  2959         -** should be returned.  The leftmost column of the result set has the index 0.
  2960         -** The number of columns in the result can be determined using
         2917  +** should be returned. ^The leftmost column of the result set has the index 0.
         2918  +** ^The number of columns in the result can be determined using
  2961   2919   ** [sqlite3_column_count()].
  2962   2920   **
  2963   2921   ** If the SQL statement does not currently point to a valid row, or if the
  2964   2922   ** column index is out of range, the result is undefined.
  2965   2923   ** These routines may only be called when the most recent call to
  2966   2924   ** [sqlite3_step()] has returned [SQLITE_ROW] and neither
  2967   2925   ** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
................................................................................
  2968   2926   ** If any of these routines are called after [sqlite3_reset()] or
  2969   2927   ** [sqlite3_finalize()] or after [sqlite3_step()] has returned
  2970   2928   ** something other than [SQLITE_ROW], the results are undefined.
  2971   2929   ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
  2972   2930   ** are called from a different thread while any of these routines
  2973   2931   ** are pending, then the results are undefined.
  2974   2932   **
  2975         -** The sqlite3_column_type() routine returns the
         2933  +** ^The sqlite3_column_type() routine returns the
  2976   2934   ** [SQLITE_INTEGER | datatype code] for the initial data type
  2977         -** of the result column.  The returned value is one of [SQLITE_INTEGER],
         2935  +** of the result column.  ^The returned value is one of [SQLITE_INTEGER],
  2978   2936   ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].  The value
  2979   2937   ** returned by sqlite3_column_type() is only meaningful if no type
  2980   2938   ** conversions have occurred as described below.  After a type conversion,
  2981   2939   ** the value returned by sqlite3_column_type() is undefined.  Future
  2982   2940   ** versions of SQLite may change the behavior of sqlite3_column_type()
  2983   2941   ** following a type conversion.
  2984   2942   **
  2985         -** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
         2943  +** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
  2986   2944   ** routine returns the number of bytes in that BLOB or string.
  2987         -** If the result is a UTF-16 string, then sqlite3_column_bytes() converts
         2945  +** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
  2988   2946   ** the string to UTF-8 and then returns the number of bytes.
  2989         -** If the result is a numeric value then sqlite3_column_bytes() uses
         2947  +** ^If the result is a numeric value then sqlite3_column_bytes() uses
  2990   2948   ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
  2991   2949   ** the number of bytes in that string.
  2992         -** The value returned does not include the zero terminator at the end
  2993         -** of the string.  For clarity: the value returned is the number of
         2950  +** ^The value returned does not include the zero terminator at the end
         2951  +** of the string.  ^For clarity: the value returned is the number of
  2994   2952   ** bytes in the string, not the number of characters.
  2995   2953   **
  2996         -** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
  2997         -** even empty strings, are always zero terminated.  The return
         2954  +** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
         2955  +** even empty strings, are always zero terminated.  ^The return
  2998   2956   ** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary
  2999   2957   ** pointer, possibly even a NULL pointer.
  3000   2958   **
  3001         -** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
         2959  +** ^The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
  3002   2960   ** but leaves the result in UTF-16 in native byte order instead of UTF-8.
  3003         -** The zero terminator is not included in this count.
         2961  +** ^The zero terminator is not included in this count.
  3004   2962   **
  3005         -** The object returned by [sqlite3_column_value()] is an
         2963  +** ^The object returned by [sqlite3_column_value()] is an
  3006   2964   ** [unprotected sqlite3_value] object.  An unprotected sqlite3_value object
  3007   2965   ** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
  3008   2966   ** If the [unprotected sqlite3_value] object returned by
  3009   2967   ** [sqlite3_column_value()] is used in any other way, including calls
  3010   2968   ** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
  3011   2969   ** or [sqlite3_value_bytes()], then the behavior is undefined.
  3012   2970   **
  3013         -** These routines attempt to convert the value where appropriate.  For
         2971  +** These routines attempt to convert the value where appropriate.  ^For
  3014   2972   ** example, if the internal representation is FLOAT and a text result
  3015   2973   ** is requested, [sqlite3_snprintf()] is used internally to perform the
  3016         -** conversion automatically.  The following table details the conversions
         2974  +** conversion automatically.  ^(The following table details the conversions
  3017   2975   ** that are applied:
  3018   2976   **
  3019   2977   ** <blockquote>
  3020   2978   ** <table border="1">
  3021   2979   ** <tr><th> Internal<br>Type <th> Requested<br>Type <th>  Conversion
  3022   2980   **
  3023   2981   ** <tr><td>  NULL    <td> INTEGER   <td> Result is 0
................................................................................
  3033   2991   ** <tr><td>  TEXT    <td> INTEGER   <td> Use atoi()
  3034   2992   ** <tr><td>  TEXT    <td>  FLOAT    <td> Use atof()
  3035   2993   ** <tr><td>  TEXT    <td>   BLOB    <td> No change
  3036   2994   ** <tr><td>  BLOB    <td> INTEGER   <td> Convert to TEXT then use atoi()
  3037   2995   ** <tr><td>  BLOB    <td>  FLOAT    <td> Convert to TEXT then use atof()
  3038   2996   ** <tr><td>  BLOB    <td>   TEXT    <td> Add a zero terminator if needed
  3039   2997   ** </table>
  3040         -** </blockquote>
         2998  +** </blockquote>)^
  3041   2999   **
  3042   3000   ** The table above makes reference to standard C library functions atoi()
  3043   3001   ** and atof().  SQLite does not really use these functions.  It has its
  3044   3002   ** own equivalent internal routines.  The atoi() and atof() names are
  3045   3003   ** used in the table for brevity and because they are familiar to most
  3046   3004   ** C programmers.
  3047   3005   **
  3048         -** Note that when type conversions occur, pointers returned by prior
         3006  +** ^Note that when type conversions occur, pointers returned by prior
  3049   3007   ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
  3050   3008   ** sqlite3_column_text16() may be invalidated.
  3051         -** Type conversions and pointer invalidations might occur
         3009  +** ^(Type conversions and pointer invalidations might occur
  3052   3010   ** in the following cases:
  3053   3011   **
  3054   3012   ** <ul>
  3055   3013   ** <li> The initial content is a BLOB and sqlite3_column_text() or
  3056   3014   **      sqlite3_column_text16() is called.  A zero-terminator might
  3057   3015   **      need to be added to the string.</li>
  3058   3016   ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
  3059   3017   **      sqlite3_column_text16() is called.  The content must be converted
  3060   3018   **      to UTF-16.</li>
  3061   3019   ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
  3062   3020   **      sqlite3_column_text() is called.  The content must be converted
  3063   3021   **      to UTF-8.</li>
  3064         -** </ul>
         3022  +** </ul>)^
  3065   3023   **
  3066         -** Conversions between UTF-16be and UTF-16le are always done in place and do
         3024  +** ^Conversions between UTF-16be and UTF-16le are always done in place and do
  3067   3025   ** not invalidate a prior pointer, though of course the content of the buffer
  3068   3026   ** that the prior pointer points to will have been modified.  Other kinds
  3069   3027   ** of conversion are done in place when it is possible, but sometimes they
  3070   3028   ** are not possible and in those cases prior pointers are invalidated.
  3071   3029   **
  3072         -** The safest and easiest to remember policy is to invoke these routines
         3030  +** ^(The safest and easiest to remember policy is to invoke these routines
  3073   3031   ** in one of the following ways:
  3074   3032   **
  3075   3033   ** <ul>
  3076   3034   **  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
  3077   3035   **  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
  3078   3036   **  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
  3079         -** </ul>
         3037  +** </ul>)^
  3080   3038   **
  3081   3039   ** In other words, you should call sqlite3_column_text(),
  3082   3040   ** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
  3083   3041   ** into the desired format, then invoke sqlite3_column_bytes() or
  3084   3042   ** sqlite3_column_bytes16() to find the size of the result.  Do not mix calls
  3085   3043   ** to sqlite3_column_text() or sqlite3_column_blob() with calls to
  3086   3044   ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
  3087   3045   ** with calls to sqlite3_column_bytes().
  3088   3046   **
  3089         -** The pointers returned are valid until a type conversion occurs as
         3047  +** ^The pointers returned are valid until a type conversion occurs as
  3090   3048   ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
  3091         -** [sqlite3_finalize()] is called.  The memory space used to hold strings
         3049  +** [sqlite3_finalize()] is called.  ^The memory space used to hold strings
  3092   3050   ** and BLOBs is freed automatically.  Do <b>not</b> pass the pointers returned
  3093   3051   ** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
  3094   3052   ** [sqlite3_free()].
  3095   3053   **
  3096         -** If a memory allocation error occurs during the evaluation of any
         3054  +** ^(If a memory allocation error occurs during the evaluation of any
  3097   3055   ** of these routines, a default value is returned.  The default value
  3098   3056   ** is either the integer 0, the floating point number 0.0, or a NULL
  3099   3057   ** pointer.  Subsequent calls to [sqlite3_errcode()] will return
  3100         -** [SQLITE_NOMEM].
  3101         -**
  3102         -** Requirements:
  3103         -** [H13803] [H13806] [H13809] [H13812] [H13815] [H13818] [H13821] [H13824]
  3104         -** [H13827] [H13830]
         3058  +** [SQLITE_NOMEM].)^
  3105   3059   */
  3106   3060   SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
  3107   3061   SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
  3108   3062   SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
  3109   3063   SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
  3110   3064   SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
  3111   3065   SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
  3112   3066   SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
  3113   3067   SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
  3114   3068   SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
  3115   3069   SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
  3116   3070   
  3117   3071   /*
  3118         -** CAPI3REF: Destroy A Prepared Statement Object {H13300} <S70300><S30100>
         3072  +** CAPI3REF: Destroy A Prepared Statement Object
  3119   3073   **
  3120         -** The sqlite3_finalize() function is called to delete a [prepared statement].
  3121         -** If the statement was executed successfully or not executed at all, then
  3122         -** SQLITE_OK is returned. If execution of the statement failed then an
         3074  +** ^The sqlite3_finalize() function is called to delete a [prepared statement].
         3075  +** ^If the statement was executed successfully or not executed at all, then
         3076  +** SQLITE_OK is returned. ^If execution of the statement failed then an
  3123   3077   ** [error code] or [extended error code] is returned.
  3124   3078   **
  3125         -** This routine can be called at any point during the execution of the
  3126         -** [prepared statement].  If the virtual machine has not
         3079  +** ^This routine can be called at any point during the execution of the
         3080  +** [prepared statement].  ^If the virtual machine has not
  3127   3081   ** completed execution when this routine is called, that is like
  3128   3082   ** encountering an error or an [sqlite3_interrupt | interrupt].
  3129         -** Incomplete updates may be rolled back and transactions canceled,
         3083  +** ^Incomplete updates may be rolled back and transactions canceled,
  3130   3084   ** depending on the circumstances, and the
  3131   3085   ** [error code] returned will be [SQLITE_ABORT].
  3132         -**
  3133         -** Requirements:
  3134         -** [H11302] [H11304]
  3135   3086   */
  3136   3087   SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
  3137   3088   
  3138   3089   /*
  3139         -** CAPI3REF: Reset A Prepared Statement Object {H13330} <S70300>
         3090  +** CAPI3REF: Reset A Prepared Statement Object
  3140   3091   **
  3141   3092   ** The sqlite3_reset() function is called to reset a [prepared statement]
  3142   3093   ** object back to its initial state, ready to be re-executed.
  3143         -** Any SQL statement variables that had values bound to them using
         3094  +** ^Any SQL statement variables that had values bound to them using
  3144   3095   ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
  3145   3096   ** Use [sqlite3_clear_bindings()] to reset the bindings.
  3146   3097   **
  3147         -** {H11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S
  3148         -**          back to the beginning of its program.
         3098  +** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
         3099  +** back to the beginning of its program.
  3149   3100   **
  3150         -** {H11334} If the most recent call to [sqlite3_step(S)] for the
  3151         -**          [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
  3152         -**          or if [sqlite3_step(S)] has never before been called on S,
  3153         -**          then [sqlite3_reset(S)] returns [SQLITE_OK].
         3101  +** ^If the most recent call to [sqlite3_step(S)] for the
         3102  +** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
         3103  +** or if [sqlite3_step(S)] has never before been called on S,
         3104  +** then [sqlite3_reset(S)] returns [SQLITE_OK].
  3154   3105   **
  3155         -** {H11336} If the most recent call to [sqlite3_step(S)] for the
  3156         -**          [prepared statement] S indicated an error, then
  3157         -**          [sqlite3_reset(S)] returns an appropriate [error code].
         3106  +** ^If the most recent call to [sqlite3_step(S)] for the
         3107  +** [prepared statement] S indicated an error, then
         3108  +** [sqlite3_reset(S)] returns an appropriate [error code].
  3158   3109   **
  3159         -** {H11338} The [sqlite3_reset(S)] interface does not change the values
  3160         -**          of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
         3110  +** ^The [sqlite3_reset(S)] interface does not change the values
         3111  +** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
  3161   3112   */
  3162   3113   SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
  3163   3114   
  3164   3115   /*
  3165         -** CAPI3REF: Create Or Redefine SQL Functions {H16100} <S20200>
         3116  +** CAPI3REF: Create Or Redefine SQL Functions
  3166   3117   ** KEYWORDS: {function creation routines}
  3167   3118   ** KEYWORDS: {application-defined SQL function}
  3168   3119   ** KEYWORDS: {application-defined SQL functions}
  3169   3120   **
  3170         -** These two functions (collectively known as "function creation routines")
         3121  +** ^These two functions (collectively known as "function creation routines")
  3171   3122   ** are used to add SQL functions or aggregates or to redefine the behavior
  3172   3123   ** of existing SQL functions or aggregates.  The only difference between the
  3173   3124   ** two is that the second parameter, the name of the (scalar) function or
  3174   3125   ** aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16
  3175   3126   ** for sqlite3_create_function16().
  3176   3127   **
  3177         -** The first parameter is the [database connection] to which the SQL
  3178         -** function is to be added.  If a single program uses more than one database
  3179         -** connection internally, then SQL functions must be added individually to
  3180         -** each database connection.
         3128  +** ^The first parameter is the [database connection] to which the SQL
         3129  +** function is to be added.  ^If an application uses more than one database
         3130  +** connection then application-defined SQL functions must be added
         3131  +** to each database connection separately.
  3181   3132   **
  3182   3133   ** The second parameter is the name of the SQL function to be created or
  3183         -** redefined.  The length of the name is limited to 255 bytes, exclusive of
         3134  +** redefined.  ^The length of the name is limited to 255 bytes, exclusive of
  3184   3135   ** the zero-terminator.  Note that the name length limit is in bytes, not
  3185         -** characters.  Any attempt to create a function with a longer name
         3136  +** characters.  ^Any attempt to create a function with a longer name
  3186   3137   ** will result in [SQLITE_ERROR] being returned.
  3187   3138   **
  3188         -** The third parameter (nArg)
         3139  +** ^The third parameter (nArg)
  3189   3140   ** is the number of arguments that the SQL function or
  3190         -** aggregate takes. If this parameter is -1, then the SQL function or
         3141  +** aggregate takes. ^If this parameter is -1, then the SQL function or
  3191   3142   ** aggregate may take any number of arguments between 0 and the limit
  3192   3143   ** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]).  If the third
  3193   3144   ** parameter is less than -1 or greater than 127 then the behavior is
  3194   3145   ** undefined.
  3195   3146   **
  3196   3147   ** The fourth parameter, eTextRep, specifies what
  3197   3148   ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
  3198   3149   ** its parameters.  Any SQL function implementation should be able to work
  3199   3150   ** work with UTF-8, UTF-16le, or UTF-16be.  But some implementations may be
  3200         -** more efficient with one encoding than another.  An application may
         3151  +** more efficient with one encoding than another.  ^An application may
  3201   3152   ** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
  3202   3153   ** times with the same function but with different values of eTextRep.
  3203         -** When multiple implementations of the same function are available, SQLite
         3154  +** ^When multiple implementations of the same function are available, SQLite
  3204   3155   ** will pick the one that involves the least amount of data conversion.
  3205   3156   ** If there is only a single implementation which does not care what text
  3206   3157   ** encoding is used, then the fourth argument should be [SQLITE_ANY].
  3207   3158   **
  3208         -** The fifth parameter is an arbitrary pointer.  The implementation of the
  3209         -** function can gain access to this pointer using [sqlite3_user_data()].
         3159  +** ^(The fifth parameter is an arbitrary pointer.  The implementation of the
         3160  +** function can gain access to this pointer using [sqlite3_user_data()].)^
  3210   3161   **
  3211   3162   ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
  3212   3163   ** pointers to C-language functions that implement the SQL function or
  3213         -** aggregate. A scalar SQL function requires an implementation of the xFunc
  3214         -** callback only, NULL pointers should be passed as the xStep and xFinal
  3215         -** parameters. An aggregate SQL function requires an implementation of xStep
  3216         -** and xFinal and NULL should be passed for xFunc. To delete an existing
         3164  +** aggregate. ^A scalar SQL function requires an implementation of the xFunc
         3165  +** callback only; NULL pointers should be passed as the xStep and xFinal
         3166  +** parameters. ^An aggregate SQL function requires an implementation of xStep
         3167  +** and xFinal and NULL should be passed for xFunc. ^To delete an existing
  3217   3168   ** SQL function or aggregate, pass NULL for all three function callbacks.
  3218   3169   **
  3219         -** It is permitted to register multiple implementations of the same
         3170  +** ^It is permitted to register multiple implementations of the same
  3220   3171   ** functions with the same name but with either differing numbers of
  3221         -** arguments or differing preferred text encodings.  SQLite will use
         3172  +** arguments or differing preferred text encodings.  ^SQLite will use
  3222   3173   ** the implementation that most closely matches the way in which the
  3223         -** SQL function is used.  A function implementation with a non-negative
         3174  +** SQL function is used.  ^A function implementation with a non-negative
  3224   3175   ** nArg parameter is a better match than a function implementation with
  3225         -** a negative nArg.  A function where the preferred text encoding
         3176  +** a negative nArg.  ^A function where the preferred text encoding
  3226   3177   ** matches the database encoding is a better
  3227   3178   ** match than a function where the encoding is different.  
  3228         -** A function where the encoding difference is between UTF16le and UTF16be
         3179  +** ^A function where the encoding difference is between UTF16le and UTF16be
  3229   3180   ** is a closer match than a function where the encoding difference is
  3230   3181   ** between UTF8 and UTF16.
  3231   3182   **
  3232         -** Built-in functions may be overloaded by new application-defined functions.
  3233         -** The first application-defined function with a given name overrides all
         3183  +** ^Built-in functions may be overloaded by new application-defined functions.
         3184  +** ^The first application-defined function with a given name overrides all
  3234   3185   ** built-in functions in the same [database connection] with the same name.
  3235         -** Subsequent application-defined functions of the same name only override 
         3186  +** ^Subsequent application-defined functions of the same name only override 
  3236   3187   ** prior application-defined functions that are an exact match for the
  3237   3188   ** number of parameters and preferred encoding.
  3238   3189   **
  3239         -** An application-defined function is permitted to call other
         3190  +** ^An application-defined function is permitted to call other
  3240   3191   ** SQLite interfaces.  However, such calls must not
  3241   3192   ** close the database connection nor finalize or reset the prepared
  3242   3193   ** statement in which the function is running.
  3243         -**
  3244         -** Requirements:
  3245         -** [H16103] [H16106] [H16109] [H16112] [H16118] [H16121] [H16127]
  3246         -** [H16130] [H16133] [H16136] [H16139] [H16142]
  3247   3194   */
  3248   3195   SQLITE_API int sqlite3_create_function(
  3249   3196     sqlite3 *db,
  3250   3197     const char *zFunctionName,
  3251   3198     int nArg,
  3252   3199     int eTextRep,
  3253   3200     void *pApp,
................................................................................
  3263   3210     void *pApp,
  3264   3211     void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  3265   3212     void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  3266   3213     void (*xFinal)(sqlite3_context*)
  3267   3214   );
  3268   3215   
  3269   3216   /*
  3270         -** CAPI3REF: Text Encodings {H10267} <S50200> <H16100>
         3217  +** CAPI3REF: Text Encodings
  3271   3218   **
  3272   3219   ** These constant define integer codes that represent the various
  3273   3220   ** text encodings supported by SQLite.
  3274   3221   */
  3275   3222   #define SQLITE_UTF8           1
  3276   3223   #define SQLITE_UTF16LE        2
  3277   3224   #define SQLITE_UTF16BE        3
................................................................................
  3295   3242   SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
  3296   3243   SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
  3297   3244   SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
  3298   3245   SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
  3299   3246   #endif
  3300   3247   
  3301   3248   /*
  3302         -** CAPI3REF: Obtaining SQL Function Parameter Values {H15100} <S20200>
         3249  +** CAPI3REF: Obtaining SQL Function Parameter Values
  3303   3250   **
  3304   3251   ** The C-language implementation of SQL functions and aggregates uses
  3305   3252   ** this set of interface routines to access the parameter values on
  3306   3253   ** the function or aggregate.
  3307   3254   **
  3308   3255   ** The xFunc (for scalar functions) or xStep (for aggregates) parameters
  3309   3256   ** to [sqlite3_create_function()] and [sqlite3_create_function16()]
................................................................................
  3313   3260   ** each parameter to the SQL function.  These routines are used to
  3314   3261   ** extract values from the [sqlite3_value] objects.
  3315   3262   **
  3316   3263   ** These routines work only with [protected sqlite3_value] objects.
  3317   3264   ** Any attempt to use these routines on an [unprotected sqlite3_value]
  3318   3265   ** object results in undefined behavior.
  3319   3266   **
  3320         -** These routines work just like the corresponding [column access functions]
         3267  +** ^These routines work just like the corresponding [column access functions]
  3321   3268   ** except that  these routines take a single [protected sqlite3_value] object
  3322   3269   ** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
  3323   3270   **
  3324         -** The sqlite3_value_text16() interface extracts a UTF-16 string
  3325         -** in the native byte-order of the host machine.  The
         3271  +** ^The sqlite3_value_text16() interface extracts a UTF-16 string
         3272  +** in the native byte-order of the host machine.  ^The
  3326   3273   ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
  3327   3274   ** extract UTF-16 strings as big-endian and little-endian respectively.
  3328   3275   **
  3329         -** The sqlite3_value_numeric_type() interface attempts to apply
         3276  +** ^(The sqlite3_value_numeric_type() interface attempts to apply
  3330   3277   ** numeric affinity to the value.  This means that an attempt is
  3331   3278   ** made to convert the value to an integer or floating point.  If
  3332   3279   ** such a conversion is possible without loss of information (in other
  3333   3280   ** words, if the value is a string that looks like a number)
  3334   3281   ** then the conversion is performed.  Otherwise no conversion occurs.
  3335         -** The [SQLITE_INTEGER | datatype] after conversion is returned.
         3282  +** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
  3336   3283   **
  3337   3284   ** Please pay particular attention to the fact that the pointer returned
  3338   3285   ** from [sqlite3_value_blob()], [sqlite3_value_text()], or
  3339   3286   ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
  3340   3287   ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
  3341   3288   ** or [sqlite3_value_text16()].
  3342   3289   **
  3343   3290   ** These routines must be called from the same thread as
  3344   3291   ** the SQL function that supplied the [sqlite3_value*] parameters.
  3345         -**
  3346         -** Requirements:
  3347         -** [H15103] [H15106] [H15109] [H15112] [H15115] [H15118] [H15121] [H15124]
  3348         -** [H15127] [H15130] [H15133] [H15136]
  3349   3292   */
  3350   3293   SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
  3351   3294   SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
  3352   3295   SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
  3353   3296   SQLITE_API double sqlite3_value_double(sqlite3_value*);
  3354   3297   SQLITE_API int sqlite3_value_int(sqlite3_value*);
  3355   3298   SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
................................................................................
  3357   3300   SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
  3358   3301   SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
  3359   3302   SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
  3360   3303   SQLITE_API int sqlite3_value_type(sqlite3_value*);
  3361   3304   SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
  3362   3305   
  3363   3306   /*
  3364         -** CAPI3REF: Obtain Aggregate Function Context {H16210} <S20200>
  3365         -**
  3366         -** The implementation of aggregate SQL functions use this routine to allocate
  3367         -** a structure for storing their state.
  3368         -**
  3369         -** The first time the sqlite3_aggregate_context() routine is called for a
  3370         -** particular aggregate, SQLite allocates nBytes of memory, zeroes out that
  3371         -** memory, and returns a pointer to it. On second and subsequent calls to
  3372         -** sqlite3_aggregate_context() for the same aggregate function index,
  3373         -** the same buffer is returned. The implementation of the aggregate can use
  3374         -** the returned buffer to accumulate data.
  3375         -**
  3376         -** SQLite automatically frees the allocated buffer when the aggregate
  3377         -** query concludes.
  3378         -**
  3379         -** The first parameter should be a copy of the
         3307  +** CAPI3REF: Obtain Aggregate Function Context
         3308  +**
         3309  +** Implementions of aggregate SQL functions use this
         3310  +** routine to allocate memory for storing their state.
         3311  +**
         3312  +** ^The first time the sqlite3_aggregate_context(C,N) routine is called 
         3313  +** for a particular aggregate function, SQLite
         3314  +** allocates N of memory, zeroes out that memory, and returns a pointer
         3315  +** to the new memory. ^On second and subsequent calls to
         3316  +** sqlite3_aggregate_context() for the same aggregate function instance,
         3317  +** the same buffer is returned.  Sqlite3_aggregate_context() is normally
         3318  +** called once for each invocation of the xStep callback and then one
         3319  +** last time when the xFinal callback is invoked.  ^(When no rows match
         3320  +** an aggregate query, the xStep() callback of the aggregate function
         3321  +** implementation is never called and xFinal() is called exactly once.
         3322  +** In those cases, sqlite3_aggregate_context() might be called for the
         3323  +** first time from within xFinal().)^
         3324  +**
         3325  +** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer if N is
         3326  +** less than or equal to zero or if a memory allocate error occurs.
         3327  +**
         3328  +** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
         3329  +** determined by the N parameter on first successful call.  Changing the
         3330  +** value of N in subsequent call to sqlite3_aggregate_context() within
         3331  +** the same aggregate function instance will not resize the memory
         3332  +** allocation.)^
         3333  +**
         3334  +** ^SQLite automatically frees the memory allocated by 
         3335  +** sqlite3_aggregate_context() when the aggregate query concludes.
         3336  +**
         3337  +** The first parameter must be a copy of the
  3380   3338   ** [sqlite3_context | SQL function context] that is the first parameter
  3381         -** to the callback routine that implements the aggregate function.
         3339  +** to the xStep or xFinal callback routine that implements the aggregate
         3340  +** function.
  3382   3341   **
  3383   3342   ** This routine must be called from the same thread in which
  3384   3343   ** the aggregate SQL function is running.
  3385         -**
  3386         -** Requirements:
  3387         -** [H16211] [H16213] [H16215] [H16217]
  3388   3344   */
  3389   3345   SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
  3390   3346   
  3391   3347   /*
  3392         -** CAPI3REF: User Data For Functions {H16240} <S20200>
         3348  +** CAPI3REF: User Data For Functions
  3393   3349   **
  3394         -** The sqlite3_user_data() interface returns a copy of
         3350  +** ^The sqlite3_user_data() interface returns a copy of
  3395   3351   ** the pointer that was the pUserData parameter (the 5th parameter)
  3396   3352   ** of the [sqlite3_create_function()]
  3397   3353   ** and [sqlite3_create_function16()] routines that originally
  3398         -** registered the application defined function. {END}
         3354  +** registered the application defined function.
  3399   3355   **
  3400   3356   ** This routine must be called from the same thread in which
  3401   3357   ** the application-defined function is running.
  3402         -**
  3403         -** Requirements:
  3404         -** [H16243]
  3405   3358   */
  3406   3359   SQLITE_API void *sqlite3_user_data(sqlite3_context*);
  3407   3360   
  3408   3361   /*
  3409         -** CAPI3REF: Database Connection For Functions {H16250} <S60600><S20200>
         3362  +** CAPI3REF: Database Connection For Functions
  3410   3363   **
  3411         -** The sqlite3_context_db_handle() interface returns a copy of
         3364  +** ^The sqlite3_context_db_handle() interface returns a copy of
  3412   3365   ** the pointer to the [database connection] (the 1st parameter)
  3413   3366   ** of the [sqlite3_create_function()]
  3414   3367   ** and [sqlite3_create_function16()] routines that originally
  3415   3368   ** registered the application defined function.
  3416         -**
  3417         -** Requirements:
  3418         -** [H16253]
  3419   3369   */
  3420   3370   SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
  3421   3371   
  3422   3372   /*
  3423         -** CAPI3REF: Function Auxiliary Data {H16270} <S20200>
         3373  +** CAPI3REF: Function Auxiliary Data
  3424   3374   **
  3425   3375   ** The following two functions may be used by scalar SQL functions to
  3426   3376   ** associate metadata with argument values. If the same value is passed to
  3427   3377   ** multiple invocations of the same SQL function during query execution, under
  3428   3378   ** some circumstances the associated metadata may be preserved. This may
  3429   3379   ** be used, for example, to add a regular-expression matching scalar
  3430   3380   ** function. The compiled version of the regular expression is stored as
  3431   3381   ** metadata associated with the SQL value passed as the regular expression
  3432   3382   ** pattern.  The compiled regular expression can be reused on multiple
  3433   3383   ** invocations of the same function so that the original pattern string
  3434   3384   ** does not need to be recompiled on each invocation.
  3435   3385   **
  3436         -** The sqlite3_get_auxdata() interface returns a pointer to the metadata
         3386  +** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata
  3437   3387   ** associated by the sqlite3_set_auxdata() function with the Nth argument
  3438         -** value to the application-defined function. If no metadata has been ever
         3388  +** value to the application-defined function. ^If no metadata has been ever
  3439   3389   ** been set for the Nth argument of the function, or if the corresponding
  3440   3390   ** function parameter has changed since the meta-data was set,
  3441   3391   ** then sqlite3_get_auxdata() returns a NULL pointer.
  3442   3392   **
  3443         -** The sqlite3_set_auxdata() interface saves the metadata
         3393  +** ^The sqlite3_set_auxdata() interface saves the metadata
  3444   3394   ** pointed to by its 3rd parameter as the metadata for the N-th
  3445   3395   ** argument of the application-defined function.  Subsequent
  3446   3396   ** calls to sqlite3_get_auxdata() might return this data, if it has
  3447   3397   ** not been destroyed.
  3448         -** If it is not NULL, SQLite will invoke the destructor
         3398  +** ^If it is not NULL, SQLite will invoke the destructor
  3449   3399   ** function given by the 4th parameter to sqlite3_set_auxdata() on
  3450   3400   ** the metadata when the corresponding function parameter changes
  3451   3401   ** or when the SQL statement completes, whichever comes first.
  3452   3402   **
  3453   3403   ** SQLite is free to call the destructor and drop metadata on any
  3454         -** parameter of any function at any time.  The only guarantee is that
         3404  +** parameter of any function at any time.  ^The only guarantee is that
  3455   3405   ** the destructor will be called before the metadata is dropped.
  3456   3406   **
  3457         -** In practice, metadata is preserved between function calls for
         3407  +** ^(In practice, metadata is preserved between function calls for
  3458   3408   ** expressions that are constant at compile time. This includes literal
  3459         -** values and SQL variables.
         3409  +** values and [parameters].)^
  3460   3410   **
  3461   3411   ** These routines must be called from the same thread in which
  3462   3412   ** the SQL function is running.
  3463         -**
  3464         -** Requirements:
  3465         -** [H16272] [H16274] [H16276] [H16277] [H16278] [H16279]
  3466   3413   */
  3467   3414   SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
  3468   3415   SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
  3469   3416   
  3470   3417   
  3471   3418   /*
  3472         -** CAPI3REF: Constants Defining Special Destructor Behavior {H10280} <S30100>
         3419  +** CAPI3REF: Constants Defining Special Destructor Behavior
  3473   3420   **
  3474   3421   ** These are special values for the destructor that is passed in as the
  3475         -** final argument to routines like [sqlite3_result_blob()].  If the destructor
         3422  +** final argument to routines like [sqlite3_result_blob()].  ^If the destructor
  3476   3423   ** argument is SQLITE_STATIC, it means that the content pointer is constant
  3477         -** and will never change.  It does not need to be destroyed.  The
         3424  +** and will never change.  It does not need to be destroyed.  ^The
  3478   3425   ** SQLITE_TRANSIENT value means that the content will likely change in
  3479   3426   ** the near future and that SQLite should make its own private copy of
  3480   3427   ** the content before returning.
  3481   3428   **
  3482   3429   ** The typedef is necessary to work around problems in certain
  3483   3430   ** C++ compilers.  See ticket #2191.
  3484   3431   */
  3485   3432   typedef void (*sqlite3_destructor_type)(void*);
  3486   3433   #define SQLITE_STATIC      ((sqlite3_destructor_type)0)
  3487   3434   #define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)
  3488   3435   
  3489   3436   /*
  3490         -** CAPI3REF: Setting The Result Of An SQL Function {H16400} <S20200>
         3437  +** CAPI3REF: Setting The Result Of An SQL Function
  3491   3438   **
  3492   3439   ** These routines are used by the xFunc or xFinal callbacks that
  3493   3440   ** implement SQL functions and aggregates.  See
  3494   3441   ** [sqlite3_create_function()] and [sqlite3_create_function16()]
  3495   3442   ** for additional information.
  3496   3443   **
  3497   3444   ** These functions work very much like the [parameter binding] family of
  3498   3445   ** functions used to bind values to host parameters in prepared statements.
  3499   3446   ** Refer to the [SQL parameter] documentation for additional information.
  3500   3447   **
  3501         -** The sqlite3_result_blob() interface sets the result from
         3448  +** ^The sqlite3_result_blob() interface sets the result from
  3502   3449   ** an application-defined function to be the BLOB whose content is pointed
  3503   3450   ** to by the second parameter and which is N bytes long where N is the
  3504   3451   ** third parameter.
  3505   3452   **
  3506         -** The sqlite3_result_zeroblob() interfaces set the result of
         3453  +** ^The sqlite3_result_zeroblob() interfaces set the result of
  3507   3454   ** the application-defined function to be a BLOB containing all zero
  3508   3455   ** bytes and N bytes in size, where N is the value of the 2nd parameter.
  3509   3456   **
  3510         -** The sqlite3_result_double() interface sets the result from
         3457  +** ^The sqlite3_result_double() interface sets the result from
  3511   3458   ** an application-defined function to be a floating point value specified
  3512   3459   ** by its 2nd argument.
  3513   3460   **
  3514         -** The sqlite3_result_error() and sqlite3_result_error16() functions
         3461  +** ^The sqlite3_result_error() and sqlite3_result_error16() functions
  3515   3462   ** cause the implemented SQL function to throw an exception.
  3516         -** SQLite uses the string pointed to by the
         3463  +** ^SQLite uses the string pointed to by the
  3517   3464   ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
  3518         -** as the text of an error message.  SQLite interprets the error
  3519         -** message string from sqlite3_result_error() as UTF-8. SQLite
         3465  +** as the text of an error message.  ^SQLite interprets the error
         3466  +** message string from sqlite3_result_error() as UTF-8. ^SQLite
  3520   3467   ** interprets the string from sqlite3_result_error16() as UTF-16 in native
  3521         -** byte order.  If the third parameter to sqlite3_result_error()
         3468  +** byte order.  ^If the third parameter to sqlite3_result_error()
  3522   3469   ** or sqlite3_result_error16() is negative then SQLite takes as the error
  3523   3470   ** message all text up through the first zero character.
  3524         -** If the third parameter to sqlite3_result_error() or
         3471  +** ^If the third parameter to sqlite3_result_error() or
  3525   3472   ** sqlite3_result_error16() is non-negative then SQLite takes that many
  3526   3473   ** bytes (not characters) from the 2nd parameter as the error message.
  3527         -** The sqlite3_result_error() and sqlite3_result_error16()
         3474  +** ^The sqlite3_result_error() and sqlite3_result_error16()
  3528   3475   ** routines make a private copy of the error message text before
  3529   3476   ** they return.  Hence, the calling function can deallocate or
  3530   3477   ** modify the text after they return without harm.
  3531         -** The sqlite3_result_error_code() function changes the error code
  3532         -** returned by SQLite as a result of an error in a function.  By default,
  3533         -** the error code is SQLITE_ERROR.  A subsequent call to sqlite3_result_error()
         3478  +** ^The sqlite3_result_error_code() function changes the error code
         3479  +** returned by SQLite as a result of an error in a function.  ^By default,
         3480  +** the error code is SQLITE_ERROR.  ^A subsequent call to sqlite3_result_error()
  3534   3481   ** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
  3535   3482   **
  3536         -** The sqlite3_result_toobig() interface causes SQLite to throw an error
  3537         -** indicating that a string or BLOB is to long to represent.
         3483  +** ^The sqlite3_result_toobig() interface causes SQLite to throw an error
         3484  +** indicating that a string or BLOB is too long to represent.
  3538   3485   **
  3539         -** The sqlite3_result_nomem() interface causes SQLite to throw an error
         3486  +** ^The sqlite3_result_nomem() interface causes SQLite to throw an error
  3540   3487   ** indicating that a memory allocation failed.
  3541   3488   **
  3542         -** The sqlite3_result_int() interface sets the return value
         3489  +** ^The sqlite3_result_int() interface sets the return value
  3543   3490   ** of the application-defined function to be the 32-bit signed integer
  3544   3491   ** value given in the 2nd argument.
  3545         -** The sqlite3_result_int64() interface sets the return value
         3492  +** ^The sqlite3_result_int64() interface sets the return value
  3546   3493   ** of the application-defined function to be the 64-bit signed integer
  3547   3494   ** value given in the 2nd argument.
  3548   3495   **
  3549         -** The sqlite3_result_null() interface sets the return value
         3496  +** ^The sqlite3_result_null() interface sets the return value
  3550   3497   ** of the application-defined function to be NULL.
  3551   3498   **
  3552         -** The sqlite3_result_text(), sqlite3_result_text16(),
         3499  +** ^The sqlite3_result_text(), sqlite3_result_text16(),
  3553   3500   ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
  3554   3501   ** set the return value of the application-defined function to be
  3555   3502   ** a text string which is represented as UTF-8, UTF-16 native byte order,
  3556   3503   ** UTF-16 little endian, or UTF-16 big endian, respectively.
  3557         -** SQLite takes the text result from the application from
         3504  +** ^SQLite takes the text result from the application from
  3558   3505   ** the 2nd parameter of the sqlite3_result_text* interfaces.
  3559         -** If the 3rd parameter to the sqlite3_result_text* interfaces
         3506  +** ^If the 3rd parameter to the sqlite3_result_text* interfaces
  3560   3507   ** is negative, then SQLite takes result text from the 2nd parameter
  3561   3508   ** through the first zero character.
  3562         -** If the 3rd parameter to the sqlite3_result_text* interfaces
         3509  +** ^If the 3rd parameter to the sqlite3_result_text* interfaces
  3563   3510   ** is non-negative, then as many bytes (not characters) of the text
  3564   3511   ** pointed to by the 2nd parameter are taken as the application-defined
  3565   3512   ** function result.
  3566         -** If the 4th parameter to the sqlite3_result_text* interfaces
         3513  +** ^If the 4th parameter to the sqlite3_result_text* interfaces
  3567   3514   ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
  3568   3515   ** function as the destructor on the text or BLOB result when it has
  3569   3516   ** finished using that result.
  3570         -** If the 4th parameter to the sqlite3_result_text* interfaces or to
         3517  +** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
  3571   3518   ** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
  3572   3519   ** assumes that the text or BLOB result is in constant space and does not
  3573   3520   ** copy the content of the parameter nor call a destructor on the content
  3574   3521   ** when it has finished using that result.
  3575         -** If the 4th parameter to the sqlite3_result_text* interfaces
         3522  +** ^If the 4th parameter to the sqlite3_result_text* interfaces
  3576   3523   ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
  3577   3524   ** then SQLite makes a copy of the result into space obtained from
  3578   3525   ** from [sqlite3_malloc()] before it returns.
  3579   3526   **
  3580         -** The sqlite3_result_value() interface sets the result of
         3527  +** ^The sqlite3_result_value() interface sets the result of
  3581   3528   ** the application-defined function to be a copy the
  3582         -** [unprotected sqlite3_value] object specified by the 2nd parameter.  The
         3529  +** [unprotected sqlite3_value] object specified by the 2nd parameter.  ^The
  3583   3530   ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
  3584   3531   ** so that the [sqlite3_value] specified in the parameter may change or
  3585   3532   ** be deallocated after sqlite3_result_value() returns without harm.
  3586         -** A [protected sqlite3_value] object may always be used where an
         3533  +** ^A [protected sqlite3_value] object may always be used where an
  3587   3534   ** [unprotected sqlite3_value] object is required, so either
  3588   3535   ** kind of [sqlite3_value] object can be used with this interface.
  3589   3536   **
  3590   3537   ** If these routines are called from within the different thread
  3591   3538   ** than the one containing the application-defined function that received
  3592   3539   ** the [sqlite3_context] pointer, the results are undefined.
  3593         -**
  3594         -** Requirements:
  3595         -** [H16403] [H16406] [H16409] [H16412] [H16415] [H16418] [H16421] [H16424]
  3596         -** [H16427] [H16430] [H16433] [H16436] [H16439] [H16442] [H16445] [H16448]
  3597         -** [H16451] [H16454] [H16457] [H16460] [H16463]
  3598   3540   */
  3599   3541   SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
  3600   3542   SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
  3601   3543   SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
  3602   3544   SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
  3603   3545   SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
  3604   3546   SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
................................................................................
  3610   3552   SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
  3611   3553   SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
  3612   3554   SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
  3613   3555   SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
  3614   3556   SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
  3615   3557   
  3616   3558   /*
  3617         -** CAPI3REF: Define New Collating Sequences {H16600} <S20300>
         3559  +** CAPI3REF: Define New Collating Sequences
  3618   3560   **
  3619   3561   ** These functions are used to add new collation sequences to the
  3620   3562   ** [database connection] specified as the first argument.
  3621   3563   **
  3622         -** The name of the new collation sequence is specified as a UTF-8 string
         3564  +** ^The name of the new collation sequence is specified as a UTF-8 string
  3623   3565   ** for sqlite3_create_collation() and sqlite3_create_collation_v2()
  3624         -** and a UTF-16 string for sqlite3_create_collation16(). In all cases
         3566  +** and a UTF-16 string for sqlite3_create_collation16(). ^In all cases
  3625   3567   ** the name is passed as the second function argument.
  3626   3568   **
  3627         -** The third argument may be one of the constants [SQLITE_UTF8],
         3569  +** ^The third argument may be one of the constants [SQLITE_UTF8],
  3628   3570   ** [SQLITE_UTF16LE], or [SQLITE_UTF16BE], indicating that the user-supplied
  3629   3571   ** routine expects to be passed pointers to strings encoded using UTF-8,
  3630         -** UTF-16 little-endian, or UTF-16 big-endian, respectively. The
         3572  +** UTF-16 little-endian, or UTF-16 big-endian, respectively. ^The
  3631   3573   ** third argument might also be [SQLITE_UTF16] to indicate that the routine
  3632   3574   ** expects pointers to be UTF-16 strings in the native byte order, or the
  3633   3575   ** argument can be [SQLITE_UTF16_ALIGNED] if the
  3634   3576   ** the routine expects pointers to 16-bit word aligned strings
  3635   3577   ** of UTF-16 in the native byte order.
  3636   3578   **
  3637   3579   ** A pointer to the user supplied routine must be passed as the fifth
  3638         -** argument.  If it is NULL, this is the same as deleting the collation
         3580  +** argument.  ^If it is NULL, this is the same as deleting the collation
  3639   3581   ** sequence (so that SQLite cannot call it anymore).
  3640         -** Each time the application supplied function is invoked, it is passed
         3582  +** ^Each time the application supplied function is invoked, it is passed
  3641   3583   ** as its first parameter a copy of the void* passed as the fourth argument
  3642   3584   ** to sqlite3_create_collation() or sqlite3_create_collation16().
  3643   3585   **
  3644         -** The remaining arguments to the application-supplied routine are two strings,
         3586  +** ^The remaining arguments to the application-supplied routine are two strings,
  3645   3587   ** each represented by a (length, data) pair and encoded in the encoding
  3646   3588   ** that was passed as the third argument when the collation sequence was
  3647         -** registered. {END}  The application defined collation routine should
         3589  +** registered.  The application defined collation routine should
  3648   3590   ** return negative, zero or positive if the first string is less than,
  3649   3591   ** equal to, or greater than the second string. i.e. (STRING1 - STRING2).
  3650   3592   **
  3651         -** The sqlite3_create_collation_v2() works like sqlite3_create_collation()
         3593  +** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
  3652   3594   ** except that it takes an extra argument which is a destructor for
  3653         -** the collation.  The destructor is called when the collation is
         3595  +** the collation.  ^The destructor is called when the collation is
  3654   3596   ** destroyed and is passed a copy of the fourth parameter void* pointer
  3655   3597   ** of the sqlite3_create_collation_v2().
  3656         -** Collations are destroyed when they are overridden by later calls to the
         3598  +** ^Collations are destroyed when they are overridden by later calls to the
  3657   3599   ** collation creation functions or when the [database connection] is closed
  3658   3600   ** using [sqlite3_close()].
  3659   3601   **
  3660   3602   ** See also:  [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
  3661         -**
  3662         -** Requirements:
  3663         -** [H16603] [H16604] [H16606] [H16609] [H16612] [H16615] [H16618] [H16621]
  3664         -** [H16624] [H16627] [H16630]
  3665   3603   */
  3666   3604   SQLITE_API int sqlite3_create_collation(
  3667   3605     sqlite3*, 
  3668   3606     const char *zName, 
  3669   3607     int eTextRep, 
  3670   3608     void*,
  3671   3609     int(*xCompare)(void*,int,const void*,int,const void*)
................................................................................
  3683   3621     const void *zName,
  3684   3622     int eTextRep, 
  3685   3623     void*,
  3686   3624     int(*xCompare)(void*,int,const void*,int,const void*)
  3687   3625   );
  3688   3626   
  3689   3627   /*
  3690         -** CAPI3REF: Collation Needed Callbacks {H16700} <S20300>
         3628  +** CAPI3REF: Collation Needed Callbacks
  3691   3629   **
  3692         -** To avoid having to register all collation sequences before a database
         3630  +** ^To avoid having to register all collation sequences before a database
  3693   3631   ** can be used, a single callback function may be registered with the
  3694         -** [database connection] to be called whenever an undefined collation
         3632  +** [database connection] to be invoked whenever an undefined collation
  3695   3633   ** sequence is required.
  3696   3634   **
  3697         -** If the function is registered using the sqlite3_collation_needed() API,
         3635  +** ^If the function is registered using the sqlite3_collation_needed() API,
  3698   3636   ** then it is passed the names of undefined collation sequences as strings
  3699         -** encoded in UTF-8. {H16703} If sqlite3_collation_needed16() is used,
         3637  +** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
  3700   3638   ** the names are passed as UTF-16 in machine native byte order.
  3701         -** A call to either function replaces any existing callback.
         3639  +** ^A call to either function replaces the existing collation-needed callback.
  3702   3640   **
  3703         -** When the callback is invoked, the first argument passed is a copy
         3641  +** ^(When the callback is invoked, the first argument passed is a copy
  3704   3642   ** of the second argument to sqlite3_collation_needed() or
  3705   3643   ** sqlite3_collation_needed16().  The second argument is the database
  3706   3644   ** connection.  The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
  3707   3645   ** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
  3708   3646   ** sequence function required.  The fourth parameter is the name of the
  3709         -** required collation sequence.
         3647  +** required collation sequence.)^
  3710   3648   **
  3711   3649   ** The callback function should register the desired collation using
  3712   3650   ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
  3713   3651   ** [sqlite3_create_collation_v2()].
  3714         -**
  3715         -** Requirements:
  3716         -** [H16702] [H16704] [H16706]
  3717   3652   */
  3718   3653   SQLITE_API int sqlite3_collation_needed(
  3719   3654     sqlite3*, 
  3720   3655     void*, 
  3721   3656     void(*)(void*,sqlite3*,int eTextRep,const char*)
  3722   3657   );
  3723   3658   SQLITE_API int sqlite3_collation_needed16(
................................................................................
  3748   3683   */
  3749   3684   SQLITE_API int sqlite3_rekey(
  3750   3685     sqlite3 *db,                   /* Database to be rekeyed */
  3751   3686     const void *pKey, int nKey     /* The new key */
  3752   3687   );
  3753   3688   
  3754   3689   /*
  3755         -** CAPI3REF: Suspend Execution For A Short Time {H10530} <S40410>
         3690  +** CAPI3REF: Suspend Execution For A Short Time
  3756   3691   **
  3757         -** The sqlite3_sleep() function causes the current thread to suspend execution
         3692  +** ^The sqlite3_sleep() function causes the current thread to suspend execution
  3758   3693   ** for at least a number of milliseconds specified in its parameter.
  3759   3694   **
  3760         -** If the operating system does not support sleep requests with
         3695  +** ^If the operating system does not support sleep requests with
  3761   3696   ** millisecond time resolution, then the time will be rounded up to
  3762         -** the nearest second. The number of milliseconds of sleep actually
         3697  +** the nearest second. ^The number of milliseconds of sleep actually
  3763   3698   ** requested from the operating system is returned.
  3764   3699   **
  3765         -** SQLite implements this interface by calling the xSleep()
         3700  +** ^SQLite implements this interface by calling the xSleep()
  3766   3701   ** method of the default [sqlite3_vfs] object.
  3767         -**
  3768         -** Requirements: [H10533] [H10536]
  3769   3702   */
  3770   3703   SQLITE_API int sqlite3_sleep(int);
  3771   3704   
  3772   3705   /*
  3773         -** CAPI3REF: Name Of The Folder Holding Temporary Files {H10310} <S20000>
         3706  +** CAPI3REF: Name Of The Folder Holding Temporary Files
  3774   3707   **
  3775         -** If this global variable is made to point to a string which is
         3708  +** ^(If this global variable is made to point to a string which is
  3776   3709   ** the name of a folder (a.k.a. directory), then all temporary files
  3777         -** created by SQLite will be placed in that directory.  If this variable
         3710  +** created by SQLite when using a built-in [sqlite3_vfs | VFS]
         3711  +** will be placed in that directory.)^  ^If this variable
  3778   3712   ** is a NULL pointer, then SQLite performs a search for an appropriate
  3779   3713   ** temporary file directory.
  3780   3714   **
  3781   3715   ** It is not safe to read or modify this variable in more than one
  3782   3716   ** thread at a time.  It is not safe to read or modify this variable
  3783   3717   ** if a [database connection] is being used at the same time in a separate
  3784   3718   ** thread.
  3785   3719   ** It is intended that this variable be set once
  3786   3720   ** as part of process initialization and before any SQLite interface
  3787   3721   ** routines have been called and that this variable remain unchanged
  3788   3722   ** thereafter.
  3789   3723   **
  3790         -** The [temp_store_directory pragma] may modify this variable and cause
  3791         -** it to point to memory obtained from [sqlite3_malloc].  Furthermore,
         3724  +** ^The [temp_store_directory pragma] may modify this variable and cause
         3725  +** it to point to memory obtained from [sqlite3_malloc].  ^Furthermore,
  3792   3726   ** the [temp_store_directory pragma] always assumes that any string
  3793   3727   ** that this variable points to is held in memory obtained from 
  3794   3728   ** [sqlite3_malloc] and the pragma may attempt to free that memory
  3795   3729   ** using [sqlite3_free].
  3796   3730   ** Hence, if this variable is modified directly, either it should be
  3797   3731   ** made NULL or made to point to memory obtained from [sqlite3_malloc]
  3798   3732   ** or else the use of the [temp_store_directory pragma] should be avoided.
  3799   3733   */
  3800   3734   SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;
  3801   3735   
  3802   3736   /*
  3803         -** CAPI3REF: Test For Auto-Commit Mode {H12930} <S60200>
         3737  +** CAPI3REF: Test For Auto-Commit Mode
  3804   3738   ** KEYWORDS: {autocommit mode}
  3805   3739   **
  3806         -** The sqlite3_get_autocommit() interface returns non-zero or
         3740  +** ^The sqlite3_get_autocommit() interface returns non-zero or
  3807   3741   ** zero if the given database connection is or is not in autocommit mode,
  3808         -** respectively.  Autocommit mode is on by default.
  3809         -** Autocommit mode is disabled by a [BEGIN] statement.
  3810         -** Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
         3742  +** respectively.  ^Autocommit mode is on by default.
         3743  +** ^Autocommit mode is disabled by a [BEGIN] statement.
         3744  +** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
  3811   3745   **
  3812   3746   ** If certain kinds of errors occur on a statement within a multi-statement
  3813   3747   ** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],
  3814   3748   ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
  3815   3749   ** transaction might be rolled back automatically.  The only way to
  3816   3750   ** find out whether SQLite automatically rolled back the transaction after
  3817   3751   ** an error is to use this function.
  3818   3752   **
  3819   3753   ** If another thread changes the autocommit status of the database
  3820   3754   ** connection while this routine is running, then the return value
  3821   3755   ** is undefined.
  3822         -**
  3823         -** Requirements: [H12931] [H12932] [H12933] [H12934]
  3824   3756   */
  3825   3757   SQLITE_API int sqlite3_get_autocommit(sqlite3*);
  3826   3758   
  3827   3759   /*
  3828         -** CAPI3REF: Find The Database Handle Of A Prepared Statement {H13120} <S60600>
         3760  +** CAPI3REF: Find The Database Handle Of A Prepared Statement
  3829   3761   **
  3830         -** The sqlite3_db_handle interface returns the [database connection] handle
  3831         -** to which a [prepared statement] belongs.  The [database connection]
  3832         -** returned by sqlite3_db_handle is the same [database connection] that was the first argument
         3762  +** ^The sqlite3_db_handle interface returns the [database connection] handle
         3763  +** to which a [prepared statement] belongs.  ^The [database connection]
         3764  +** returned by sqlite3_db_handle is the same [database connection]
         3765  +** that was the first argument
  3833   3766   ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
  3834   3767   ** create the statement in the first place.
  3835         -**
  3836         -** Requirements: [H13123]
  3837   3768   */
  3838   3769   SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
  3839   3770   
  3840   3771   /*
  3841         -** CAPI3REF: Find the next prepared statement {H13140} <S60600>
         3772  +** CAPI3REF: Find the next prepared statement
  3842   3773   **
  3843         -** This interface returns a pointer to the next [prepared statement] after
  3844         -** pStmt associated with the [database connection] pDb.  If pStmt is NULL
         3774  +** ^This interface returns a pointer to the next [prepared statement] after
         3775  +** pStmt associated with the [database connection] pDb.  ^If pStmt is NULL
  3845   3776   ** then this interface returns a pointer to the first prepared statement
  3846         -** associated with the database connection pDb.  If no prepared statement
         3777  +** associated with the database connection pDb.  ^If no prepared statement
  3847   3778   ** satisfies the conditions of this routine, it returns NULL.
  3848   3779   **
  3849   3780   ** The [database connection] pointer D in a call to
  3850   3781   ** [sqlite3_next_stmt(D,S)] must refer to an open database
  3851   3782   ** connection and in particular must not be a NULL pointer.
  3852         -**
  3853         -** Requirements: [H13143] [H13146] [H13149] [H13152]
  3854   3783   */
  3855   3784   SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
  3856   3785   
  3857   3786   /*
  3858         -** CAPI3REF: Commit And Rollback Notification Callbacks {H12950} <S60400>
         3787  +** CAPI3REF: Commit And Rollback Notification Callbacks
  3859   3788   **
  3860         -** The sqlite3_commit_hook() interface registers a callback
         3789  +** ^The sqlite3_commit_hook() interface registers a callback
  3861   3790   ** function to be invoked whenever a transaction is [COMMIT | committed].
  3862         -** Any callback set by a previous call to sqlite3_commit_hook()
         3791  +** ^Any callback set by a previous call to sqlite3_commit_hook()
  3863   3792   ** for the same database connection is overridden.
  3864         -** The sqlite3_rollback_hook() interface registers a callback
         3793  +** ^The sqlite3_rollback_hook() interface registers a callback
  3865   3794   ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
  3866         -** Any callback set by a previous call to sqlite3_commit_hook()
         3795  +** ^Any callback set by a previous call to sqlite3_rollback_hook()
  3867   3796   ** for the same database connection is overridden.
  3868         -** The pArg argument is passed through to the callback.
  3869         -** If the callback on a commit hook function returns non-zero,
         3797  +** ^The pArg argument is passed through to the callback.
         3798  +** ^If the callback on a commit hook function returns non-zero,
  3870   3799   ** then the commit is converted into a rollback.
  3871   3800   **
  3872         -** If another function was previously registered, its
  3873         -** pArg value is returned.  Otherwise NULL is returned.
         3801  +** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
         3802  +** return the P argument from the previous call of the same function
         3803  +** on the same [database connection] D, or NULL for
         3804  +** the first call for each function on D.
  3874   3805   **
  3875   3806   ** The callback implementation must not do anything that will modify
  3876   3807   ** the database connection that invoked the callback.  Any actions
  3877   3808   ** to modify the database connection must be deferred until after the
  3878   3809   ** completion of the [sqlite3_step()] call that triggered the commit
  3879   3810   ** or rollback hook in the first place.
  3880   3811   ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  3881   3812   ** database connections for the meaning of "modify" in this paragraph.
  3882   3813   **
  3883         -** Registering a NULL function disables the callback.
         3814  +** ^Registering a NULL function disables the callback.
  3884   3815   **
  3885         -** When the commit hook callback routine returns zero, the [COMMIT]
  3886         -** operation is allowed to continue normally.  If the commit hook
         3816  +** ^When the commit hook callback routine returns zero, the [COMMIT]
         3817  +** operation is allowed to continue normally.  ^If the commit hook
  3887   3818   ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
  3888         -** The rollback hook is invoked on a rollback that results from a commit
         3819  +** ^The rollback hook is invoked on a rollback that results from a commit
  3889   3820   ** hook returning non-zero, just as it would be with any other rollback.
  3890   3821   **
  3891         -** For the purposes of this API, a transaction is said to have been
         3822  +** ^For the purposes of this API, a transaction is said to have been
  3892   3823   ** rolled back if an explicit "ROLLBACK" statement is executed, or
  3893   3824   ** an error or constraint causes an implicit rollback to occur.
  3894         -** The rollback callback is not invoked if a transaction is
         3825  +** ^The rollback callback is not invoked if a transaction is
  3895   3826   ** automatically rolled back because the database connection is closed.
  3896         -** The rollback callback is not invoked if a transaction is
         3827  +** ^The rollback callback is not invoked if a transaction is
  3897   3828   ** rolled back because a commit callback returned non-zero.
  3898         -** <todo> Check on this </todo>
  3899   3829   **
  3900   3830   ** See also the [sqlite3_update_hook()] interface.
  3901         -**
  3902         -** Requirements:
  3903         -** [H12951] [H12952] [H12953] [H12954] [H12955]
  3904         -** [H12961] [H12962] [H12963] [H12964]
  3905   3831   */
  3906   3832   SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
  3907   3833   SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
  3908   3834   
  3909   3835   /*
  3910         -** CAPI3REF: Data Change Notification Callbacks {H12970} <S60400>
         3836  +** CAPI3REF: Data Change Notification Callbacks
  3911   3837   **
  3912         -** The sqlite3_update_hook() interface registers a callback function
         3838  +** ^The sqlite3_update_hook() interface registers a callback function
  3913   3839   ** with the [database connection] identified by the first argument
  3914   3840   ** to be invoked whenever a row is updated, inserted or deleted.
  3915         -** Any callback set by a previous call to this function
         3841  +** ^Any callback set by a previous call to this function
  3916   3842   ** for the same database connection is overridden.
  3917   3843   **
  3918         -** The second argument is a pointer to the function to invoke when a
         3844  +** ^The second argument is a pointer to the function to invoke when a
  3919   3845   ** row is updated, inserted or deleted.
  3920         -** The first argument to the callback is a copy of the third argument
         3846  +** ^The first argument to the callback is a copy of the third argument
  3921   3847   ** to sqlite3_update_hook().
  3922         -** The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
         3848  +** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
  3923   3849   ** or [SQLITE_UPDATE], depending on the operation that caused the callback
  3924   3850   ** to be invoked.
  3925         -** The third and fourth arguments to the callback contain pointers to the
         3851  +** ^The third and fourth arguments to the callback contain pointers to the
  3926   3852   ** database and table name containing the affected row.
  3927         -** The final callback parameter is the [rowid] of the row.
  3928         -** In the case of an update, this is the [rowid] after the update takes place.
         3853  +** ^The final callback parameter is the [rowid] of the row.
         3854  +** ^In the case of an update, this is the [rowid] after the update takes place.
  3929   3855   **
  3930         -** The update hook is not invoked when internal system tables are
  3931         -** modified (i.e. sqlite_master and sqlite_sequence).
         3856  +** ^(The update hook is not invoked when internal system tables are
         3857  +** modified (i.e. sqlite_master and sqlite_sequence).)^
  3932   3858   **
  3933         -** In the current implementation, the update hook
         3859  +** ^In the current implementation, the update hook
  3934   3860   ** is not invoked when duplication rows are deleted because of an
  3935         -** [ON CONFLICT | ON CONFLICT REPLACE] clause.  Nor is the update hook
         3861  +** [ON CONFLICT | ON CONFLICT REPLACE] clause.  ^Nor is the update hook
  3936   3862   ** invoked when rows are deleted using the [truncate optimization].
  3937   3863   ** The exceptions defined in this paragraph might change in a future
  3938   3864   ** release of SQLite.
  3939   3865   **
  3940   3866   ** The update hook implementation must not do anything that will modify
  3941   3867   ** the database connection that invoked the update hook.  Any actions
  3942   3868   ** to modify the database connection must be deferred until after the
  3943   3869   ** completion of the [sqlite3_step()] call that triggered the update hook.
  3944   3870   ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  3945   3871   ** database connections for the meaning of "modify" in this paragraph.
  3946   3872   **
  3947         -** If another function was previously registered, its pArg value
  3948         -** is returned.  Otherwise NULL is returned.
         3873  +** ^The sqlite3_update_hook(D,C,P) function
         3874  +** returns the P argument from the previous call
         3875  +** on the same [database connection] D, or NULL for
         3876  +** the first call on D.
  3949   3877   **
  3950   3878   ** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()]
  3951   3879   ** interfaces.
  3952         -**
  3953         -** Requirements:
  3954         -** [H12971] [H12973] [H12975] [H12977] [H12979] [H12981] [H12983] [H12986]
  3955   3880   */
  3956   3881   SQLITE_API void *sqlite3_update_hook(
  3957   3882     sqlite3*, 
  3958   3883     void(*)(void *,int ,char const *,char const *,sqlite3_int64),
  3959   3884     void*
  3960   3885   );
  3961   3886   
  3962   3887   /*
  3963         -** CAPI3REF: Enable Or Disable Shared Pager Cache {H10330} <S30900>
         3888  +** CAPI3REF: Enable Or Disable Shared Pager Cache
  3964   3889   ** KEYWORDS: {shared cache}
  3965   3890   **
  3966         -** This routine enables or disables the sharing of the database cache
         3891  +** ^(This routine enables or disables the sharing of the database cache
  3967   3892   ** and schema data structures between [database connection | connections]
  3968   3893   ** to the same database. Sharing is enabled if the argument is true
  3969         -** and disabled if the argument is false.
         3894  +** and disabled if the argument is false.)^
  3970   3895   **
  3971         -** Cache sharing is enabled and disabled for an entire process.
         3896  +** ^Cache sharing is enabled and disabled for an entire process.
  3972   3897   ** This is a change as of SQLite version 3.5.0. In prior versions of SQLite,
  3973   3898   ** sharing was enabled or disabled for each thread separately.
  3974   3899   **
  3975         -** The cache sharing mode set by this interface effects all subsequent
         3900  +** ^(The cache sharing mode set by this interface effects all subsequent
  3976   3901   ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
  3977   3902   ** Existing database connections continue use the sharing mode
  3978         -** that was in effect at the time they were opened.
         3903  +** that was in effect at the time they were opened.)^
  3979   3904   **
  3980         -** Virtual tables cannot be used with a shared cache.  When shared
  3981         -** cache is enabled, the [sqlite3_create_module()] API used to register
  3982         -** virtual tables will always return an error.
         3905  +** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled
         3906  +** successfully.  An [error code] is returned otherwise.)^
  3983   3907   **
  3984         -** This routine returns [SQLITE_OK] if shared cache was enabled or disabled
  3985         -** successfully.  An [error code] is returned otherwise.
  3986         -**
  3987         -** Shared cache is disabled by default. But this might change in
         3908  +** ^Shared cache is disabled by default. But this might change in
  3988   3909   ** future releases of SQLite.  Applications that care about shared
  3989   3910   ** cache setting should set it explicitly.
  3990   3911   **
  3991   3912   ** See Also:  [SQLite Shared-Cache Mode]
  3992         -**
  3993         -** Requirements: [H10331] [H10336] [H10337] [H10339]
  3994   3913   */
  3995   3914   SQLITE_API int sqlite3_enable_shared_cache(int);
  3996   3915   
  3997   3916   /*
  3998         -** CAPI3REF: Attempt To Free Heap Memory {H17340} <S30220>
         3917  +** CAPI3REF: Attempt To Free Heap Memory
  3999   3918   **
  4000         -** The sqlite3_release_memory() interface attempts to free N bytes
         3919  +** ^The sqlite3_release_memory() interface attempts to free N bytes
  4001   3920   ** of heap memory by deallocating non-essential memory allocations
  4002         -** held by the database library. {END}  Memory used to cache database
         3921  +** held by the database library.   Memory used to cache database
  4003   3922   ** pages to improve performance is an example of non-essential memory.
  4004         -** sqlite3_release_memory() returns the number of bytes actually freed,
         3923  +** ^sqlite3_release_memory() returns the number of bytes actually freed,
  4005   3924   ** which might be more or less than the amount requested.
  4006         -**
  4007         -** Requirements: [H17341] [H17342]
  4008   3925   */
  4009   3926   SQLITE_API int sqlite3_release_memory(int);
  4010   3927   
  4011   3928   /*
  4012         -** CAPI3REF: Impose A Limit On Heap Size {H17350} <S30220>
         3929  +** CAPI3REF: Impose A Limit On Heap Size
  4013   3930   **
  4014         -** The sqlite3_soft_heap_limit() interface places a "soft" limit
         3931  +** ^The sqlite3_soft_heap_limit() interface places a "soft" limit
  4015   3932   ** on the amount of heap memory that may be allocated by SQLite.
  4016         -** If an internal allocation is requested that would exceed the
         3933  +** ^If an internal allocation is requested that would exceed the
  4017   3934   ** soft heap limit, [sqlite3_release_memory()] is invoked one or
  4018   3935   ** more times to free up some space before the allocation is performed.
  4019   3936   **
  4020         -** The limit is called "soft", because if [sqlite3_release_memory()]
         3937  +** ^The limit is called "soft" because if [sqlite3_release_memory()]
  4021   3938   ** cannot free sufficient memory to prevent the limit from being exceeded,
  4022   3939   ** the memory is allocated anyway and the current operation proceeds.
  4023   3940   **
  4024         -** A negative or zero value for N means that there is no soft heap limit and
         3941  +** ^A negative or zero value for N means that there is no soft heap limit and
  4025   3942   ** [sqlite3_release_memory()] will only be called when memory is exhausted.
  4026         -** The default value for the soft heap limit is zero.
         3943  +** ^The default value for the soft heap limit is zero.
  4027   3944   **
  4028         -** SQLite makes a best effort to honor the soft heap limit.
         3945  +** ^(SQLite makes a best effort to honor the soft heap limit.
  4029   3946   ** But if the soft heap limit cannot be honored, execution will
  4030         -** continue without error or notification.  This is why the limit is
         3947  +** continue without error or notification.)^  This is why the limit is
  4031   3948   ** called a "soft" limit.  It is advisory only.
  4032   3949   **
  4033   3950   ** Prior to SQLite version 3.5.0, this routine only constrained the memory
  4034   3951   ** allocated by a single thread - the same thread in which this routine
  4035   3952   ** runs.  Beginning with SQLite version 3.5.0, the soft heap limit is
  4036   3953   ** applied to all threads. The value specified for the soft heap limit
  4037   3954   ** is an upper bound on the total memory allocation for all threads. In
  4038   3955   ** version 3.5.0 there is no mechanism for limiting the heap usage for
  4039   3956   ** individual threads.
  4040         -**
  4041         -** Requirements:
  4042         -** [H16351] [H16352] [H16353] [H16354] [H16355] [H16358]
  4043   3957   */
  4044   3958   SQLITE_API void sqlite3_soft_heap_limit(int);
  4045   3959   
  4046   3960   /*
  4047         -** CAPI3REF: Extract Metadata About A Column Of A Table {H12850} <S60300>
         3961  +** CAPI3REF: Extract Metadata About A Column Of A Table
  4048   3962   **
  4049         -** This routine returns metadata about a specific column of a specific
         3963  +** ^This routine returns metadata about a specific column of a specific
  4050   3964   ** database table accessible using the [database connection] handle
  4051   3965   ** passed as the first function argument.
  4052   3966   **
  4053         -** The column is identified by the second, third and fourth parameters to
  4054         -** this function. The second parameter is either the name of the database
  4055         -** (i.e. "main", "temp" or an attached database) containing the specified
  4056         -** table or NULL. If it is NULL, then all attached databases are searched
         3967  +** ^The column is identified by the second, third and fourth parameters to
         3968  +** this function. ^The second parameter is either the name of the database
         3969  +** (i.e. "main", "temp", or an attached database) containing the specified
         3970  +** table or NULL. ^If it is NULL, then all attached databases are searched
  4057   3971   ** for the table using the same algorithm used by the database engine to
  4058   3972   ** resolve unqualified table references.
  4059   3973   **
  4060         -** The third and fourth parameters to this function are the table and column
         3974  +** ^The third and fourth parameters to this function are the table and column
  4061   3975   ** name of the desired column, respectively. Neither of these parameters
  4062   3976   ** may be NULL.
  4063   3977   **
  4064         -** Metadata is returned by writing to the memory locations passed as the 5th
  4065         -** and subsequent parameters to this function. Any of these arguments may be
         3978  +** ^Metadata is returned by writing to the memory locations passed as the 5th
         3979  +** and subsequent parameters to this function. ^Any of these arguments may be
  4066   3980   ** NULL, in which case the corresponding element of metadata is omitted.
  4067   3981   **
  4068         -** <blockquote>
         3982  +** ^(<blockquote>
  4069   3983   ** <table border="1">
  4070   3984   ** <tr><th> Parameter <th> Output<br>Type <th>  Description
  4071   3985   **
  4072   3986   ** <tr><td> 5th <td> const char* <td> Data type
  4073   3987   ** <tr><td> 6th <td> const char* <td> Name of default collation sequence
  4074   3988   ** <tr><td> 7th <td> int         <td> True if column has a NOT NULL constraint
  4075   3989   ** <tr><td> 8th <td> int         <td> True if column is part of the PRIMARY KEY
  4076   3990   ** <tr><td> 9th <td> int         <td> True if column is [AUTOINCREMENT]
  4077   3991   ** </table>
  4078         -** </blockquote>
         3992  +** </blockquote>)^
  4079   3993   **
  4080         -** The memory pointed to by the character pointers returned for the
         3994  +** ^The memory pointed to by the character pointers returned for the
  4081   3995   ** declaration type and collation sequence is valid only until the next
  4082   3996   ** call to any SQLite API function.
  4083   3997   **
  4084         -** If the specified table is actually a view, an [error code] is returned.
         3998  +** ^If the specified table is actually a view, an [error code] is returned.
  4085   3999   **
  4086         -** If the specified column is "rowid", "oid" or "_rowid_" and an
         4000  +** ^If the specified column is "rowid", "oid" or "_rowid_" and an
  4087   4001   ** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output
  4088         -** parameters are set for the explicitly declared column. If there is no
         4002  +** parameters are set for the explicitly declared column. ^(If there is no
  4089   4003   ** explicitly declared [INTEGER PRIMARY KEY] column, then the output
  4090   4004   ** parameters are set as follows:
  4091   4005   **
  4092   4006   ** <pre>
  4093   4007   **     data type: "INTEGER"
  4094   4008   **     collation sequence: "BINARY"
  4095   4009   **     not null: 0
  4096   4010   **     primary key: 1
  4097   4011   **     auto increment: 0
  4098         -** </pre>
         4012  +** </pre>)^
  4099   4013   **
  4100         -** This function may load one or more schemas from database files. If an
         4014  +** ^(This function may load one or more schemas from database files. If an
  4101   4015   ** error occurs during this process, or if the requested table or column
  4102   4016   ** cannot be found, an [error code] is returned and an error message left
  4103         -** in the [database connection] (to be retrieved using sqlite3_errmsg()).
         4017  +** in the [database connection] (to be retrieved using sqlite3_errmsg()).)^
  4104   4018   **
  4105         -** This API is only available if the library was compiled with the
         4019  +** ^This API is only available if the library was compiled with the
  4106   4020   ** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined.
  4107   4021   */
  4108   4022   SQLITE_API int sqlite3_table_column_metadata(
  4109   4023     sqlite3 *db,                /* Connection handle */
  4110   4024     const char *zDbName,        /* Database name or NULL */
  4111   4025     const char *zTableName,     /* Table name */
  4112   4026     const char *zColumnName,    /* Column name */
................................................................................
  4114   4028     char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
  4115   4029     int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
  4116   4030     int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
  4117   4031     int *pAutoinc               /* OUTPUT: True if column is auto-increment */
  4118   4032   );
  4119   4033   
  4120   4034   /*
  4121         -** CAPI3REF: Load An Extension {H12600} <S20500>
  4122         -**
  4123         -** This interface loads an SQLite extension library from the named file.
  4124         -**
  4125         -** {H12601} The sqlite3_load_extension() interface attempts to load an
  4126         -**          SQLite extension library contained in the file zFile.
  4127         -**
  4128         -** {H12602} The entry point is zProc.
  4129         -**
  4130         -** {H12603} zProc may be 0, in which case the name of the entry point
  4131         -**          defaults to "sqlite3_extension_init".
  4132         -**
  4133         -** {H12604} The sqlite3_load_extension() interface shall return
  4134         -**          [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
  4135         -**
  4136         -** {H12605} If an error occurs and pzErrMsg is not 0, then the
  4137         -**          [sqlite3_load_extension()] interface shall attempt to
  4138         -**          fill *pzErrMsg with error message text stored in memory
  4139         -**          obtained from [sqlite3_malloc()]. {END}  The calling function
  4140         -**          should free this memory by calling [sqlite3_free()].
  4141         -**
  4142         -** {H12606} Extension loading must be enabled using
  4143         -**          [sqlite3_enable_load_extension()] prior to calling this API,
  4144         -**          otherwise an error will be returned.
         4035  +** CAPI3REF: Load An Extension
         4036  +**
         4037  +** ^This interface loads an SQLite extension library from the named file.
         4038  +**
         4039  +** ^The sqlite3_load_extension() interface attempts to load an
         4040  +** SQLite extension library contained in the file zFile.
         4041  +**
         4042  +** ^The entry point is zProc.
         4043  +** ^zProc may be 0, in which case the name of the entry point
         4044  +** defaults to "sqlite3_extension_init".
         4045  +** ^The sqlite3_load_extension() interface returns
         4046  +** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
         4047  +** ^If an error occurs and pzErrMsg is not 0, then the
         4048  +** [sqlite3_load_extension()] interface shall attempt to
         4049  +** fill *pzErrMsg with error message text stored in memory
         4050  +** obtained from [sqlite3_malloc()]. The calling function
         4051  +** should free this memory by calling [sqlite3_free()].
         4052  +**
         4053  +** ^Extension loading must be enabled using
         4054  +** [sqlite3_enable_load_extension()] prior to calling this API,
         4055  +** otherwise an error will be returned.
         4056  +**
         4057  +** See also the [load_extension() SQL function].
  4145   4058   */
  4146   4059   SQLITE_API int sqlite3_load_extension(
  4147   4060     sqlite3 *db,          /* Load the extension into this database connection */
  4148   4061     const char *zFile,    /* Name of the shared library containing extension */
  4149   4062     const char *zProc,    /* Entry point.  Derived from zFile if 0 */
  4150   4063     char **pzErrMsg       /* Put error message here if not 0 */
  4151   4064   );
  4152   4065   
  4153   4066   /*
  4154         -** CAPI3REF: Enable Or Disable Extension Loading {H12620} <S20500>
         4067  +** CAPI3REF: Enable Or Disable Extension Loading
  4155   4068   **
  4156         -** So as not to open security holes in older applications that are
         4069  +** ^So as not to open security holes in older applications that are
  4157   4070   ** unprepared to deal with extension loading, and as a means of disabling
  4158   4071   ** extension loading while evaluating user-entered SQL, the following API
  4159   4072   ** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
  4160   4073   **
  4161         -** Extension loading is off by default. See ticket #1863.
  4162         -**
  4163         -** {H12621} Call the sqlite3_enable_load_extension() routine with onoff==1
  4164         -**          to turn extension loading on and call it with onoff==0 to turn
  4165         -**          it back off again.
  4166         -**
  4167         -** {H12622} Extension loading is off by default.
         4074  +** ^Extension loading is off by default. See ticket #1863.
         4075  +** ^Call the sqlite3_enable_load_extension() routine with onoff==1
         4076  +** to turn extension loading on and call it with onoff==0 to turn
         4077  +** it back off again.
  4168   4078   */
  4169   4079   SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
  4170   4080   
  4171   4081   /*
  4172         -** CAPI3REF: Automatically Load An Extensions {H12640} <S20500>
         4082  +** CAPI3REF: Automatically Load An Extensions
  4173   4083   **
  4174         -** This API can be invoked at program startup in order to register
         4084  +** ^This API can be invoked at program startup in order to register
  4175   4085   ** one or more statically linked extensions that will be available
  4176         -** to all new [database connections]. {END}
         4086  +** to all new [database connections].
  4177   4087   **
  4178         -** This routine stores a pointer to the extension in an array that is
  4179         -** obtained from [sqlite3_malloc()].  If you run a memory leak checker
  4180         -** on your program and it reports a leak because of this array, invoke
  4181         -** [sqlite3_reset_auto_extension()] prior to shutdown to free the memory.
         4088  +** ^(This routine stores a pointer to the extension entry point
         4089  +** in an array that is obtained from [sqlite3_malloc()].  That memory
         4090  +** is deallocated by [sqlite3_reset_auto_extension()].)^
  4182   4091   **
  4183         -** {H12641} This function registers an extension entry point that is
  4184         -**          automatically invoked whenever a new [database connection]
  4185         -**          is opened using [sqlite3_open()], [sqlite3_open16()],
  4186         -**          or [sqlite3_open_v2()].
  4187         -**
  4188         -** {H12642} Duplicate extensions are detected so calling this routine
  4189         -**          multiple times with the same extension is harmless.
  4190         -**
  4191         -** {H12643} This routine stores a pointer to the extension in an array
  4192         -**          that is obtained from [sqlite3_malloc()].
  4193         -**
  4194         -** {H12644} Automatic extensions apply across all threads.
         4092  +** ^This function registers an extension entry point that is
         4093  +** automatically invoked whenever a new [database connection]
         4094  +** is opened using [sqlite3_open()], [sqlite3_open16()],
         4095  +** or [sqlite3_open_v2()].
         4096  +** ^Duplicate extensions are detected so calling this routine
         4097  +** multiple times with the same extension is harmless.
         4098  +** ^Automatic extensions apply across all threads.
  4195   4099   */
  4196   4100   SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void));
  4197   4101   
  4198   4102   /*
  4199         -** CAPI3REF: Reset Automatic Extension Loading {H12660} <S20500>
         4103  +** CAPI3REF: Reset Automatic Extension Loading
  4200   4104   **
  4201         -** This function disables all previously registered automatic
  4202         -** extensions. {END}  It undoes the effect of all prior
  4203         -** [sqlite3_auto_extension()] calls.
         4105  +** ^(This function disables all previously registered automatic
         4106  +** extensions. It undoes the effect of all prior
         4107  +** [sqlite3_auto_extension()] calls.)^
  4204   4108   **
  4205         -** {H12661} This function disables all previously registered
  4206         -**          automatic extensions.
  4207         -**
  4208         -** {H12662} This function disables automatic extensions in all threads.
         4109  +** ^This function disables automatic extensions in all threads.
  4209   4110   */
  4210   4111   SQLITE_API void sqlite3_reset_auto_extension(void);
  4211   4112   
  4212   4113   /*
  4213   4114   ****** EXPERIMENTAL - subject to change without notice **************
  4214   4115   **
  4215   4116   ** The interface to the virtual-table mechanism is currently considered
................................................................................
  4225   4126   */
  4226   4127   typedef struct sqlite3_vtab sqlite3_vtab;
  4227   4128   typedef struct sqlite3_index_info sqlite3_index_info;
  4228   4129   typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
  4229   4130   typedef struct sqlite3_module sqlite3_module;
  4230   4131   
  4231   4132   /*
  4232         -** CAPI3REF: Virtual Table Object {H18000} <S20400>
         4133  +** CAPI3REF: Virtual Table Object
  4233   4134   ** KEYWORDS: sqlite3_module {virtual table module}
  4234   4135   ** EXPERIMENTAL
  4235   4136   **
  4236   4137   ** This structure, sometimes called a a "virtual table module", 
  4237   4138   ** defines the implementation of a [virtual tables].  
  4238   4139   ** This structure consists mostly of methods for the module.
  4239   4140   **
  4240         -** A virtual table module is created by filling in a persistent
         4141  +** ^A virtual table module is created by filling in a persistent
  4241   4142   ** instance of this structure and passing a pointer to that instance
  4242   4143   ** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].
  4243         -** The registration remains valid until it is replaced by a different
         4144  +** ^The registration remains valid until it is replaced by a different
  4244   4145   ** module or until the [database connection] closes.  The content
  4245   4146   ** of this structure must not change while it is registered with
  4246   4147   ** any database connection.
  4247   4148   */
  4248   4149   struct sqlite3_module {
  4249   4150     int iVersion;
  4250   4151     int (*xCreate)(sqlite3*, void *pAux,
................................................................................
  4272   4173     int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
  4273   4174                          void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
  4274   4175                          void **ppArg);
  4275   4176     int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
  4276   4177   };
  4277   4178   
  4278   4179   /*
  4279         -** CAPI3REF: Virtual Table Indexing Information {H18100} <S20400>
         4180  +** CAPI3REF: Virtual Table Indexing Information
  4280   4181   ** KEYWORDS: sqlite3_index_info
  4281   4182   ** EXPERIMENTAL
  4282   4183   **
  4283   4184   ** The sqlite3_index_info structure and its substructures is used to
  4284   4185   ** pass information into and receive the reply from the [xBestIndex]
  4285   4186   ** method of a [virtual table module].  The fields under **Inputs** are the
  4286   4187   ** inputs to xBestIndex and are read-only.  xBestIndex inserts its
  4287   4188   ** results into the **Outputs** fields.
  4288   4189   **
  4289         -** The aConstraint[] array records WHERE clause constraints of the form:
         4190  +** ^(The aConstraint[] array records WHERE clause constraints of the form:
  4290   4191   **
  4291   4192   ** <pre>column OP expr</pre>
  4292   4193   **
  4293         -** where OP is =, &lt;, &lt;=, &gt;, or &gt;=.  The particular operator is
  4294         -** stored in aConstraint[].op.  The index of the column is stored in
  4295         -** aConstraint[].iColumn.  aConstraint[].usable is TRUE if the
         4194  +** where OP is =, &lt;, &lt;=, &gt;, or &gt;=.)^  ^(The particular operator is
         4195  +** stored in aConstraint[].op.)^  ^(The index of the column is stored in
         4196  +** aConstraint[].iColumn.)^  ^(aConstraint[].usable is TRUE if the
  4296   4197   ** expr on the right-hand side can be evaluated (and thus the constraint
  4297         -** is usable) and false if it cannot.
         4198  +** is usable) and false if it cannot.)^
  4298   4199   **
  4299         -** The optimizer automatically inverts terms of the form "expr OP column"
         4200  +** ^The optimizer automatically inverts terms of the form "expr OP column"
  4300   4201   ** and makes other simplifications to the WHERE clause in an attempt to
  4301   4202   ** get as many WHERE clause terms into the form shown above as possible.
  4302         -** The aConstraint[] array only reports WHERE clause terms in the correct
  4303         -** form that refer to the particular virtual table being queried.
         4203  +** ^The aConstraint[] array only reports WHERE clause terms that are
         4204  +** relevant to the particular virtual table being queried.
  4304   4205   **
  4305         -** Information about the ORDER BY clause is stored in aOrderBy[].
  4306         -** Each term of aOrderBy records a column of the ORDER BY clause.
         4206  +** ^Information about the ORDER BY clause is stored in aOrderBy[].
         4207  +** ^Each term of aOrderBy records a column of the ORDER BY clause.
  4307   4208   **
  4308   4209   ** The [xBestIndex] method must fill aConstraintUsage[] with information
  4309         -** about what parameters to pass to xFilter.  If argvIndex>0 then
         4210  +** about what parameters to pass to xFilter.  ^If argvIndex>0 then
  4310   4211   ** the right-hand side of the corresponding aConstraint[] is evaluated
  4311         -** and becomes the argvIndex-th entry in argv.  If aConstraintUsage[].omit
         4212  +** and becomes the argvIndex-th entry in argv.  ^(If aConstraintUsage[].omit
  4312   4213   ** is true, then the constraint is assumed to be fully handled by the
  4313         -** virtual table and is not checked again by SQLite.
         4214  +** virtual table and is not checked again by SQLite.)^
  4314   4215   **
  4315         -** The idxNum and idxPtr values are recorded and passed into the
         4216  +** ^The idxNum and idxPtr values are recorded and passed into the
  4316   4217   ** [xFilter] method.
  4317         -** [sqlite3_free()] is used to free idxPtr if and only iff
         4218  +** ^[sqlite3_free()] is used to free idxPtr if and only if
  4318   4219   ** needToFreeIdxPtr is true.
  4319   4220   **
  4320         -** The orderByConsumed means that output from [xFilter]/[xNext] will occur in
         4221  +** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in
  4321   4222   ** the correct order to satisfy the ORDER BY clause so that no separate
  4322   4223   ** sorting step is required.
  4323   4224   **
  4324         -** The estimatedCost value is an estimate of the cost of doing the
         4225  +** ^The estimatedCost value is an estimate of the cost of doing the
  4325   4226   ** particular lookup.  A full scan of a table with N entries should have
  4326   4227   ** a cost of N.  A binary search of a table of N entries should have a
  4327   4228   ** cost of approximately log(N).
  4328   4229   */
  4329   4230   struct sqlite3_index_info {
  4330   4231     /* Inputs */
  4331   4232     int nConstraint;           /* Number of entries in aConstraint */
................................................................................
  4355   4256   #define SQLITE_INDEX_CONSTRAINT_GT    4
  4356   4257   #define SQLITE_INDEX_CONSTRAINT_LE    8
  4357   4258   #define SQLITE_INDEX_CONSTRAINT_LT    16
  4358   4259   #define SQLITE_INDEX_CONSTRAINT_GE    32
  4359   4260   #define SQLITE_INDEX_CONSTRAINT_MATCH 64
  4360   4261   
  4361   4262   /*
  4362         -** CAPI3REF: Register A Virtual Table Implementation {H18200} <S20400>
         4263  +** CAPI3REF: Register A Virtual Table Implementation
  4363   4264   ** EXPERIMENTAL
  4364   4265   **
  4365         -** This routine is used to register a new [virtual table module] name.
  4366         -** Module names must be registered before
  4367         -** creating a new [virtual table] using the module, or before using a
         4266  +** ^These routines are used to register a new [virtual table module] name.
         4267  +** ^Module names must be registered before
         4268  +** creating a new [virtual table] using the module and before using a
  4368   4269   ** preexisting [virtual table] for the module.
  4369   4270   **
  4370         -** The module name is registered on the [database connection] specified
  4371         -** by the first parameter.  The name of the module is given by the 
  4372         -** second parameter.  The third parameter is a pointer to
  4373         -** the implementation of the [virtual table module].   The fourth
         4271  +** ^The module name is registered on the [database connection] specified
         4272  +** by the first parameter.  ^The name of the module is given by the 
         4273  +** second parameter.  ^The third parameter is a pointer to
         4274  +** the implementation of the [virtual table module].   ^The fourth
  4374   4275   ** parameter is an arbitrary client data pointer that is passed through
  4375   4276   ** into the [xCreate] and [xConnect] methods of the virtual table module
  4376   4277   ** when a new virtual table is be being created or reinitialized.
  4377   4278   **
  4378         -** This interface has exactly the same effect as calling
  4379         -** [sqlite3_create_module_v2()] with a NULL client data destructor.
         4279  +** ^The sqlite3_create_module_v2() interface has a fifth parameter which
         4280  +** is a pointer to a destructor for the pClientData.  ^SQLite will
         4281  +** invoke the destructor function (if it is not NULL) when SQLite
         4282  +** no longer needs the pClientData pointer.  ^The sqlite3_create_module()
         4283  +** interface is equivalent to sqlite3_create_module_v2() with a NULL
         4284  +** destructor.
  4380   4285   */
  4381   4286   SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_create_module(
  4382   4287     sqlite3 *db,               /* SQLite connection to register module with */
  4383   4288     const char *zName,         /* Name of the module */
  4384   4289     const sqlite3_module *p,   /* Methods for the module */
  4385   4290     void *pClientData          /* Client data for xCreate/xConnect */
  4386   4291   );
  4387         -
  4388         -/*
  4389         -** CAPI3REF: Register A Virtual Table Implementation {H18210} <S20400>
  4390         -** EXPERIMENTAL
  4391         -**
  4392         -** This routine is identical to the [sqlite3_create_module()] method,
  4393         -** except that it has an extra parameter to specify 
  4394         -** a destructor function for the client data pointer.  SQLite will
  4395         -** invoke the destructor function (if it is not NULL) when SQLite
  4396         -** no longer needs the pClientData pointer.  
  4397         -*/
  4398   4292   SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_create_module_v2(
  4399   4293     sqlite3 *db,               /* SQLite connection to register module with */
  4400   4294     const char *zName,         /* Name of the module */
  4401   4295     const sqlite3_module *p,   /* Methods for the module */
  4402   4296     void *pClientData,         /* Client data for xCreate/xConnect */
  4403   4297     void(*xDestroy)(void*)     /* Module destructor function */
  4404   4298   );
  4405   4299   
  4406   4300   /*
  4407         -** CAPI3REF: Virtual Table Instance Object {H18010} <S20400>
         4301  +** CAPI3REF: Virtual Table Instance Object
  4408   4302   ** KEYWORDS: sqlite3_vtab
  4409   4303   ** EXPERIMENTAL
  4410   4304   **
  4411   4305   ** Every [virtual table module] implementation uses a subclass
  4412         -** of the following structure to describe a particular instance
         4306  +** of this object to describe a particular instance
  4413   4307   ** of the [virtual table].  Each subclass will
  4414   4308   ** be tailored to the specific needs of the module implementation.
  4415   4309   ** The purpose of this superclass is to define certain fields that are
  4416   4310   ** common to all module implementations.
  4417   4311   **
  4418         -** Virtual tables methods can set an error message by assigning a
         4312  +** ^Virtual tables methods can set an error message by assigning a
  4419   4313   ** string obtained from [sqlite3_mprintf()] to zErrMsg.  The method should
  4420   4314   ** take care that any prior string is freed by a call to [sqlite3_free()]
  4421         -** prior to assigning a new string to zErrMsg.  After the error message
         4315  +** prior to assigning a new string to zErrMsg.  ^After the error message
  4422   4316   ** is delivered up to the client application, the string will be automatically
  4423   4317   ** freed by sqlite3_free() and the zErrMsg field will be zeroed.
  4424   4318   */
  4425   4319   struct sqlite3_vtab {
  4426   4320     const sqlite3_module *pModule;  /* The module for this virtual table */
  4427   4321     int nRef;                       /* NO LONGER USED */
  4428   4322     char *zErrMsg;                  /* Error message from sqlite3_mprintf() */
  4429   4323     /* Virtual table implementations will typically add additional fields */
  4430   4324   };
  4431   4325   
  4432   4326   /*
  4433         -** CAPI3REF: Virtual Table Cursor Object  {H18020} <S20400>
         4327  +** CAPI3REF: Virtual Table Cursor Object
  4434   4328   ** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
  4435   4329   ** EXPERIMENTAL
  4436   4330   **
  4437   4331   ** Every [virtual table module] implementation uses a subclass of the
  4438   4332   ** following structure to describe cursors that point into the
  4439   4333   ** [virtual table] and are used
  4440   4334   ** to loop through the virtual table.  Cursors are created using the
  4441   4335   ** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed
  4442         -** by the [sqlite3_module.xClose | xClose] method.  Cussors are used
         4336  +** by the [sqlite3_module.xClose | xClose] method.  Cursors are used
  4443   4337   ** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods
  4444   4338   ** of the module.  Each module implementation will define
  4445   4339   ** the content of a cursor structure to suit its own needs.
  4446   4340   **
  4447   4341   ** This superclass exists in order to define fields of the cursor that
  4448   4342   ** are common to all implementations.
  4449   4343   */
  4450   4344   struct sqlite3_vtab_cursor {
  4451   4345     sqlite3_vtab *pVtab;      /* Virtual table of this cursor */
  4452   4346     /* Virtual table implementations will typically add additional fields */
  4453   4347   };
  4454   4348   
  4455   4349   /*
  4456         -** CAPI3REF: Declare The Schema Of A Virtual Table {H18280} <S20400>
         4350  +** CAPI3REF: Declare The Schema Of A Virtual Table
  4457   4351   ** EXPERIMENTAL
  4458   4352   **
  4459         -** The [xCreate] and [xConnect] methods of a
         4353  +** ^The [xCreate] and [xConnect] methods of a
  4460   4354   ** [virtual table module] call this interface
  4461   4355   ** to declare the format (the names and datatypes of the columns) of
  4462   4356   ** the virtual tables they implement.
  4463   4357   */
  4464   4358   SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
  4465   4359   
  4466   4360   /*
  4467         -** CAPI3REF: Overload A Function For A Virtual Table {H18300} <S20400>
         4361  +** CAPI3REF: Overload A Function For A Virtual Table
  4468   4362   ** EXPERIMENTAL
  4469   4363   **
  4470         -** Virtual tables can provide alternative implementations of functions
         4364  +** ^(Virtual tables can provide alternative implementations of functions
  4471   4365   ** using the [xFindFunction] method of the [virtual table module].  
  4472   4366   ** But global versions of those functions
  4473         -** must exist in order to be overloaded.
         4367  +** must exist in order to be overloaded.)^
  4474   4368   **
  4475         -** This API makes sure a global version of a function with a particular
         4369  +** ^(This API makes sure a global version of a function with a particular
  4476   4370   ** name and number of parameters exists.  If no such function exists
  4477         -** before this API is called, a new function is created.  The implementation
         4371  +** before this API is called, a new function is created.)^  ^The implementation
  4478   4372   ** of the new function always causes an exception to be thrown.  So
  4479   4373   ** the new function is not good for anything by itself.  Its only
  4480   4374   ** purpose is to be a placeholder function that can be overloaded
  4481   4375   ** by a [virtual table].
  4482   4376   */
  4483   4377   SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
  4484   4378   
................................................................................
  4491   4385   ** When the virtual-table mechanism stabilizes, we will declare the
  4492   4386   ** interface fixed, support it indefinitely, and remove this comment.
  4493   4387   **
  4494   4388   ****** EXPERIMENTAL - subject to change without notice **************
  4495   4389   */
  4496   4390   
  4497   4391   /*
  4498         -** CAPI3REF: A Handle To An Open BLOB {H17800} <S30230>
         4392  +** CAPI3REF: A Handle To An Open BLOB
  4499   4393   ** KEYWORDS: {BLOB handle} {BLOB handles}
  4500   4394   **
  4501   4395   ** An instance of this object represents an open BLOB on which
  4502   4396   ** [sqlite3_blob_open | incremental BLOB I/O] can be performed.
  4503         -** Objects of this type are created by [sqlite3_blob_open()]
         4397  +** ^Objects of this type are created by [sqlite3_blob_open()]
  4504   4398   ** and destroyed by [sqlite3_blob_close()].
  4505         -** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
         4399  +** ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
  4506   4400   ** can be used to read or write small subsections of the BLOB.
  4507         -** The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.
         4401  +** ^The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.
  4508   4402   */
  4509   4403   typedef struct sqlite3_blob sqlite3_blob;
  4510   4404   
  4511   4405   /*
  4512         -** CAPI3REF: Open A BLOB For Incremental I/O {H17810} <S30230>
         4406  +** CAPI3REF: Open A BLOB For Incremental I/O
  4513   4407   **
  4514         -** This interfaces opens a [BLOB handle | handle] to the BLOB located
         4408  +** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located
  4515   4409   ** in row iRow, column zColumn, table zTable in database zDb;
  4516   4410   ** in other words, the same BLOB that would be selected by:
  4517   4411   **
  4518   4412   ** <pre>
  4519   4413   **     SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
  4520         -** </pre> {END}
         4414  +** </pre>)^
  4521   4415   **
  4522         -** If the flags parameter is non-zero, then the BLOB is opened for read
  4523         -** and write access. If it is zero, the BLOB is opened for read access.
  4524         -** It is not possible to open a column that is part of an index or primary 
         4416  +** ^If the flags parameter is non-zero, then the BLOB is opened for read
         4417  +** and write access. ^If it is zero, the BLOB is opened for read access.
         4418  +** ^It is not possible to open a column that is part of an index or primary 
  4525   4419   ** key for writing. ^If [foreign key constraints] are enabled, it is 
  4526   4420   ** not possible to open a column that is part of a [child key] for writing.
  4527   4421   **
  4528         -** Note that the database name is not the filename that contains
         4422  +** ^Note that the database name is not the filename that contains
  4529   4423   ** the database but rather the symbolic name of the database that
  4530         -** is assigned when the database is connected using [ATTACH].
  4531         -** For the main database file, the database name is "main".
  4532         -** For TEMP tables, the database name is "temp".
         4424  +** appears after the AS keyword when the database is connected using [ATTACH].
         4425  +** ^For the main database file, the database name is "main".
         4426  +** ^For TEMP tables, the database name is "temp".
  4533   4427   **
  4534         -** On success, [SQLITE_OK] is returned and the new [BLOB handle] is written
         4428  +** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is written
  4535   4429   ** to *ppBlob. Otherwise an [error code] is returned and *ppBlob is set
  4536         -** to be a null pointer.
  4537         -** This function sets the [database connection] error code and message
         4430  +** to be a null pointer.)^
         4431  +** ^This function sets the [database connection] error code and message
  4538   4432   ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()] and related
  4539         -** functions.  Note that the *ppBlob variable is always initialized in a
         4433  +** functions. ^Note that the *ppBlob variable is always initialized in a
  4540   4434   ** way that makes it safe to invoke [sqlite3_blob_close()] on *ppBlob
  4541   4435   ** regardless of the success or failure of this routine.
  4542   4436   **
  4543         -** If the row that a BLOB handle points to is modified by an
         4437  +** ^(If the row that a BLOB handle points to is modified by an
  4544   4438   ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
  4545   4439   ** then the BLOB handle is marked as "expired".
  4546   4440   ** This is true if any column of the row is changed, even a column
  4547         -** other than the one the BLOB handle is open on.
  4548         -** Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
         4441  +** other than the one the BLOB handle is open on.)^
         4442  +** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
  4549   4443   ** a expired BLOB handle fail with an return code of [SQLITE_ABORT].
  4550         -** Changes written into a BLOB prior to the BLOB expiring are not
  4551         -** rollback by the expiration of the BLOB.  Such changes will eventually
  4552         -** commit if the transaction continues to completion.
         4444  +** ^(Changes written into a BLOB prior to the BLOB expiring are not
         4445  +** rolled back by the expiration of the BLOB.  Such changes will eventually
         4446  +** commit if the transaction continues to completion.)^
  4553   4447   **
  4554         -** Use the [sqlite3_blob_bytes()] interface to determine the size of
  4555         -** the opened blob.  The size of a blob may not be changed by this
         4448  +** ^Use the [sqlite3_blob_bytes()] interface to determine the size of
         4449  +** the opened blob.  ^The size of a blob may not be changed by this
  4556   4450   ** interface.  Use the [UPDATE] SQL command to change the size of a
  4557   4451   ** blob.
  4558   4452   **
  4559         -** The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
         4453  +** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
  4560   4454   ** and the built-in [zeroblob] SQL function can be used, if desired,
  4561   4455   ** to create an empty, zero-filled blob in which to read or write using
  4562   4456   ** this interface.
  4563   4457   **
  4564   4458   ** To avoid a resource leak, every open [BLOB handle] should eventually
  4565   4459   ** be released by a call to [sqlite3_blob_close()].
  4566         -**
  4567         -** Requirements:
  4568         -** [H17813] [H17814] [H17816] [H17819] [H17821] [H17824]
  4569   4460   */
  4570   4461   SQLITE_API int sqlite3_blob_open(
  4571   4462     sqlite3*,
  4572   4463     const char *zDb,
  4573   4464     const char *zTable,
  4574   4465     const char *zColumn,
  4575   4466     sqlite3_int64 iRow,
  4576   4467     int flags,
  4577   4468     sqlite3_blob **ppBlob
  4578   4469   );
  4579   4470   
  4580   4471   /*
  4581         -** CAPI3REF: Close A BLOB Handle {H17830} <S30230>
         4472  +** CAPI3REF: Close A BLOB Handle
  4582   4473   **
  4583         -** Closes an open [BLOB handle].
         4474  +** ^Closes an open [BLOB handle].
  4584   4475   **
  4585         -** Closing a BLOB shall cause the current transaction to commit
         4476  +** ^Closing a BLOB shall cause the current transaction to commit
  4586   4477   ** if there are no other BLOBs, no pending prepared statements, and the
  4587   4478   ** database connection is in [autocommit mode].
  4588         -** If any writes were made to the BLOB, they might be held in cache
         4479  +** ^If any writes were made to the BLOB, they might be held in cache
  4589   4480   ** until the close operation if they will fit.
  4590   4481   **
  4591         -** Closing the BLOB often forces the changes
         4482  +** ^(Closing the BLOB often forces the changes
  4592   4483   ** out to disk and so if any I/O errors occur, they will likely occur
  4593   4484   ** at the time when the BLOB is closed.  Any errors that occur during
  4594         -** closing are reported as a non-zero return value.
         4485  +** closing are reported as a non-zero return value.)^
  4595   4486   **
  4596         -** The BLOB is closed unconditionally.  Even if this routine returns
  4597         -** an error code, the BLOB is still closed.
         4487  +** ^(The BLOB is closed unconditionally.  Even if this routine returns
         4488  +** an error code, the BLOB is still closed.)^
  4598   4489   **
  4599         -** Calling this routine with a null pointer (which as would be returned
  4600         -** by failed call to [sqlite3_blob_open()]) is a harmless no-op.
  4601         -**
  4602         -** Requirements:
  4603         -** [H17833] [H17836] [H17839]
         4490  +** ^Calling this routine with a null pointer (such as would be returned
         4491  +** by a failed call to [sqlite3_blob_open()]) is a harmless no-op.
  4604   4492   */
  4605   4493   SQLITE_API int sqlite3_blob_close(sqlite3_blob *);
  4606   4494   
  4607   4495   /*
  4608         -** CAPI3REF: Return The Size Of An Open BLOB {H17840} <S30230>
         4496  +** CAPI3REF: Return The Size Of An Open BLOB
  4609   4497   **
  4610         -** Returns the size in bytes of the BLOB accessible via the 
  4611         -** successfully opened [BLOB handle] in its only argument.  The
         4498  +** ^Returns the size in bytes of the BLOB accessible via the 
         4499  +** successfully opened [BLOB handle] in its only argument.  ^The
  4612   4500   ** incremental blob I/O routines can only read or overwriting existing
  4613   4501   ** blob content; they cannot change the size of a blob.
  4614   4502   **
  4615   4503   ** This routine only works on a [BLOB handle] which has been created
  4616   4504   ** by a prior successful call to [sqlite3_blob_open()] and which has not
  4617   4505   ** been closed by [sqlite3_blob_close()].  Passing any other pointer in
  4618   4506   ** to this routine results in undefined and probably undesirable behavior.
  4619         -**
  4620         -** Requirements:
  4621         -** [H17843]
  4622   4507   */
  4623   4508   SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *);
  4624   4509   
  4625   4510   /*
  4626         -** CAPI3REF: Read Data From A BLOB Incrementally {H17850} <S30230>
         4511  +** CAPI3REF: Read Data From A BLOB Incrementally
  4627   4512   **
  4628         -** This function is used to read data from an open [BLOB handle] into a
         4513  +** ^(This function is used to read data from an open [BLOB handle] into a
  4629   4514   ** caller-supplied buffer. N bytes of data are copied into buffer Z
  4630         -** from the open BLOB, starting at offset iOffset.
         4515  +** from the open BLOB, starting at offset iOffset.)^
  4631   4516   **
  4632         -** If offset iOffset is less than N bytes from the end of the BLOB,
  4633         -** [SQLITE_ERROR] is returned and no data is read.  If N or iOffset is
         4517  +** ^If offset iOffset is less than N bytes from the end of the BLOB,
         4518  +** [SQLITE_ERROR] is returned and no data is read.  ^If N or iOffset is
  4634   4519   ** less than zero, [SQLITE_ERROR] is returned and no data is read.
  4635         -** The size of the blob (and hence the maximum value of N+iOffset)
         4520  +** ^The size of the blob (and hence the maximum value of N+iOffset)
  4636   4521   ** can be determined using the [sqlite3_blob_bytes()] interface.
  4637   4522   **
  4638         -** An attempt to read from an expired [BLOB handle] fails with an
         4523  +** ^An attempt to read from an expired [BLOB handle] fails with an
  4639   4524   ** error code of [SQLITE_ABORT].
  4640   4525   **
  4641         -** On success, SQLITE_OK is returned.
  4642         -** Otherwise, an [error code] or an [extended error code] is returned.
         4526  +** ^(On success, sqlite3_blob_read() returns SQLITE_OK.
         4527  +** Otherwise, an [error code] or an [extended error code] is returned.)^
  4643   4528   **
  4644   4529   ** This routine only works on a [BLOB handle] which has been created
  4645   4530   ** by a prior successful call to [sqlite3_blob_open()] and which has not
  4646   4531   ** been closed by [sqlite3_blob_close()].  Passing any other pointer in
  4647   4532   ** to this routine results in undefined and probably undesirable behavior.
  4648   4533   **
  4649   4534   ** See also: [sqlite3_blob_write()].
  4650         -**
  4651         -** Requirements:
  4652         -** [H17853] [H17856] [H17859] [H17862] [H17863] [H17865] [H17868]
  4653   4535   */
  4654   4536   SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
  4655   4537   
  4656   4538   /*
  4657         -** CAPI3REF: Write Data Into A BLOB Incrementally {H17870} <S30230>
         4539  +** CAPI3REF: Write Data Into A BLOB Incrementally
  4658   4540   **
  4659         -** This function is used to write data into an open [BLOB handle] from a
  4660         -** caller-supplied buffer. N bytes of data are copied from the buffer Z
         4541  +** ^This function is used to write data into an open [BLOB handle] from a
         4542  +** caller-supplied buffer. ^N bytes of data are copied from the buffer Z
  4661   4543   ** into the open BLOB, starting at offset iOffset.
  4662   4544   **
  4663         -** If the [BLOB handle] passed as the first argument was not opened for
         4545  +** ^If the [BLOB handle] passed as the first argument was not opened for
  4664   4546   ** writing (the flags parameter to [sqlite3_blob_open()] was zero),
  4665   4547   ** this function returns [SQLITE_READONLY].
  4666   4548   **
  4667         -** This function may only modify the contents of the BLOB; it is
         4549  +** ^This function may only modify the contents of the BLOB; it is
  4668   4550   ** not possible to increase the size of a BLOB using this API.
  4669         -** If offset iOffset is less than N bytes from the end of the BLOB,
  4670         -** [SQLITE_ERROR] is returned and no data is written.  If N is
         4551  +** ^If offset iOffset is less than N bytes from the end of the BLOB,
         4552  +** [SQLITE_ERROR] is returned and no data is written.  ^If N is
  4671   4553   ** less than zero [SQLITE_ERROR] is returned and no data is written.
  4672   4554   ** The size of the BLOB (and hence the maximum value of N+iOffset)
  4673   4555   ** can be determined using the [sqlite3_blob_bytes()] interface.
  4674   4556   **
  4675         -** An attempt to write to an expired [BLOB handle] fails with an
  4676         -** error code of [SQLITE_ABORT].  Writes to the BLOB that occurred
         4557  +** ^An attempt to write to an expired [BLOB handle] fails with an
         4558  +** error code of [SQLITE_ABORT].  ^Writes to the BLOB that occurred
  4677   4559   ** before the [BLOB handle] expired are not rolled back by the
  4678   4560   ** expiration of the handle, though of course those changes might
  4679   4561   ** have been overwritten by the statement that expired the BLOB handle
  4680   4562   ** or by other independent statements.
  4681   4563   **
  4682         -** On success, SQLITE_OK is returned.
  4683         -** Otherwise, an  [error code] or an [extended error code] is returned.
         4564  +** ^(On success, sqlite3_blob_write() returns SQLITE_OK.
         4565  +** Otherwise, an  [error code] or an [extended error code] is returned.)^
  4684   4566   **
  4685   4567   ** This routine only works on a [BLOB handle] which has been created
  4686   4568   ** by a prior successful call to [sqlite3_blob_open()] and which has not
  4687   4569   ** been closed by [sqlite3_blob_close()].  Passing any other pointer in
  4688   4570   ** to this routine results in undefined and probably undesirable behavior.
  4689   4571   **
  4690   4572   ** See also: [sqlite3_blob_read()].
  4691         -**
  4692         -** Requirements:
  4693         -** [H17873] [H17874] [H17875] [H17876] [H17877] [H17879] [H17882] [H17885]
  4694         -** [H17888]
  4695   4573   */
  4696   4574   SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
  4697   4575   
  4698   4576   /*
  4699         -** CAPI3REF: Virtual File System Objects {H11200} <S20100>
         4577  +** CAPI3REF: Virtual File System Objects
  4700   4578   **
  4701   4579   ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
  4702   4580   ** that SQLite uses to interact
  4703   4581   ** with the underlying operating system.  Most SQLite builds come with a
  4704   4582   ** single default VFS that is appropriate for the host computer.
  4705   4583   ** New VFSes can be registered and existing VFSes can be unregistered.
  4706   4584   ** The following interfaces are provided.
  4707   4585   **
  4708         -** The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.
  4709         -** Names are case sensitive.
  4710         -** Names are zero-terminated UTF-8 strings.
  4711         -** If there is no match, a NULL pointer is returned.
  4712         -** If zVfsName is NULL then the default VFS is returned.
         4586  +** ^The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.
         4587  +** ^Names are case sensitive.
         4588  +** ^Names are zero-terminated UTF-8 strings.
         4589  +** ^If there is no match, a NULL pointer is returned.
         4590  +** ^If zVfsName is NULL then the default VFS is returned.
  4713   4591   **
  4714         -** New VFSes are registered with sqlite3_vfs_register().
  4715         -** Each new VFS becomes the default VFS if the makeDflt flag is set.
  4716         -** The same VFS can be registered multiple times without injury.
  4717         -** To make an existing VFS into the default VFS, register it again
         4592  +** ^New VFSes are registered with sqlite3_vfs_register().
         4593  +** ^Each new VFS becomes the default VFS if the makeDflt flag is set.
         4594  +** ^The same VFS can be registered multiple times without injury.
         4595  +** ^To make an existing VFS into the default VFS, register it again
  4718   4596   ** with the makeDflt flag set.  If two different VFSes with the
  4719   4597   ** same name are registered, the behavior is undefined.  If a
  4720   4598   ** VFS is registered with a name that is NULL or an empty string,
  4721   4599   ** then the behavior is undefined.
  4722   4600   **
  4723         -** Unregister a VFS with the sqlite3_vfs_unregister() interface.
  4724         -** If the default VFS is unregistered, another VFS is chosen as
  4725         -** the default.  The choice for the new VFS is arbitrary.
  4726         -**
  4727         -** Requirements:
  4728         -** [H11203] [H11206] [H11209] [H11212] [H11215] [H11218]
         4601  +** ^Unregister a VFS with the sqlite3_vfs_unregister() interface.
         4602  +** ^(If the default VFS is unregistered, another VFS is chosen as
         4603  +** the default.  The choice for the new VFS is arbitrary.)^
  4729   4604   */
  4730   4605   SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
  4731   4606   SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
  4732   4607   SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
  4733   4608   
  4734   4609   /*
  4735         -** CAPI3REF: Mutexes {H17000} <S20000>
         4610  +** CAPI3REF: Mutexes
  4736   4611   **
  4737   4612   ** The SQLite core uses these routines for thread
  4738   4613   ** synchronization. Though they are intended for internal
  4739   4614   ** use by SQLite, code that links against SQLite is
  4740   4615   ** permitted to use any of these routines.
  4741   4616   **
  4742   4617   ** The SQLite source code contains multiple implementations
  4743   4618   ** of these mutex routines.  An appropriate implementation
  4744         -** is selected automatically at compile-time.  The following
         4619  +** is selected automatically at compile-time.  ^(The following
  4745   4620   ** implementations are available in the SQLite core:
  4746   4621   **
  4747   4622   ** <ul>
  4748   4623   ** <li>   SQLITE_MUTEX_OS2
  4749   4624   ** <li>   SQLITE_MUTEX_PTHREAD
  4750   4625   ** <li>   SQLITE_MUTEX_W32
  4751   4626   ** <li>   SQLITE_MUTEX_NOOP
  4752         -** </ul>
         4627  +** </ul>)^
  4753   4628   **
  4754         -** The SQLITE_MUTEX_NOOP implementation is a set of routines
         4629  +** ^The SQLITE_MUTEX_NOOP implementation is a set of routines
  4755   4630   ** that does no real locking and is appropriate for use in
  4756         -** a single-threaded application.  The SQLITE_MUTEX_OS2,
         4631  +** a single-threaded application.  ^The SQLITE_MUTEX_OS2,
  4757   4632   ** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations
  4758   4633   ** are appropriate for use on OS/2, Unix, and Windows.
  4759   4634   **
  4760         -** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
         4635  +** ^(If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
  4761   4636   ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
  4762   4637   ** implementation is included with the library. In this case the
  4763   4638   ** application must supply a custom mutex implementation using the
  4764   4639   ** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function
  4765   4640   ** before calling sqlite3_initialize() or any other public sqlite3_
  4766         -** function that calls sqlite3_initialize().
         4641  +** function that calls sqlite3_initialize().)^
  4767   4642   **
  4768         -** {H17011} The sqlite3_mutex_alloc() routine allocates a new
  4769         -** mutex and returns a pointer to it. {H17012} If it returns NULL
  4770         -** that means that a mutex could not be allocated. {H17013} SQLite
  4771         -** will unwind its stack and return an error. {H17014} The argument
         4643  +** ^The sqlite3_mutex_alloc() routine allocates a new
         4644  +** mutex and returns a pointer to it. ^If it returns NULL
         4645  +** that means that a mutex could not be allocated.  ^SQLite
         4646  +** will unwind its stack and return an error.  ^(The argument
  4772   4647   ** to sqlite3_mutex_alloc() is one of these integer constants:
  4773   4648   **
  4774   4649   ** <ul>
  4775   4650   ** <li>  SQLITE_MUTEX_FAST
  4776   4651   ** <li>  SQLITE_MUTEX_RECURSIVE
  4777   4652   ** <li>  SQLITE_MUTEX_STATIC_MASTER
  4778   4653   ** <li>  SQLITE_MUTEX_STATIC_MEM
  4779   4654   ** <li>  SQLITE_MUTEX_STATIC_MEM2
  4780   4655   ** <li>  SQLITE_MUTEX_STATIC_PRNG
  4781   4656   ** <li>  SQLITE_MUTEX_STATIC_LRU
  4782   4657   ** <li>  SQLITE_MUTEX_STATIC_LRU2
  4783         -** </ul>
         4658  +** </ul>)^
  4784   4659   **
  4785         -** {H17015} The first two constants cause sqlite3_mutex_alloc() to create
  4786         -** a new mutex.  The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
  4787         -** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END}
         4660  +** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
         4661  +** cause sqlite3_mutex_alloc() to create
         4662  +** a new mutex.  ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
         4663  +** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
  4788   4664   ** The mutex implementation does not need to make a distinction
  4789   4665   ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
  4790         -** not want to.  {H17016} But SQLite will only request a recursive mutex in
  4791         -** cases where it really needs one.  {END} If a faster non-recursive mutex
         4666  +** not want to.  ^SQLite will only request a recursive mutex in
         4667  +** cases where it really needs one.  ^If a faster non-recursive mutex
  4792   4668   ** implementation is available on the host platform, the mutex subsystem
  4793   4669   ** might return such a mutex in response to SQLITE_MUTEX_FAST.
  4794   4670   **
  4795         -** {H17017} The other allowed parameters to sqlite3_mutex_alloc() each return
  4796         -** a pointer to a static preexisting mutex. {END}  Six static mutexes are
         4671  +** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other
         4672  +** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
         4673  +** a pointer to a static preexisting mutex.  ^Six static mutexes are
  4797   4674   ** used by the current version of SQLite.  Future versions of SQLite
  4798   4675   ** may add additional static mutexes.  Static mutexes are for internal
  4799   4676   ** use by SQLite only.  Applications that use SQLite mutexes should
  4800   4677   ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
  4801   4678   ** SQLITE_MUTEX_RECURSIVE.
  4802   4679   **
  4803         -** {H17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
         4680  +** ^Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
  4804   4681   ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
  4805         -** returns a different mutex on every call.  {H17034} But for the static
         4682  +** returns a different mutex on every call.  ^But for the static
  4806   4683   ** mutex types, the same mutex is returned on every call that has
  4807   4684   ** the same type number.
  4808   4685   **
  4809         -** {H17019} The sqlite3_mutex_free() routine deallocates a previously
  4810         -** allocated dynamic mutex. {H17020} SQLite is careful to deallocate every
  4811         -** dynamic mutex that it allocates. {A17021} The dynamic mutexes must not be in
  4812         -** use when they are deallocated. {A17022} Attempting to deallocate a static
  4813         -** mutex results in undefined behavior. {H17023} SQLite never deallocates
  4814         -** a static mutex. {END}
         4686  +** ^The sqlite3_mutex_free() routine deallocates a previously
         4687  +** allocated dynamic mutex.  ^SQLite is careful to deallocate every
         4688  +** dynamic mutex that it allocates.  The dynamic mutexes must not be in
         4689  +** use when they are deallocated.  Attempting to deallocate a static
         4690  +** mutex results in undefined behavior.  ^SQLite never deallocates
         4691  +** a static mutex.
  4815   4692   **
  4816         -** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
  4817         -** to enter a mutex. {H17024} If another thread is already within the mutex,
         4693  +** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
         4694  +** to enter a mutex.  ^If another thread is already within the mutex,
  4818   4695   ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
  4819         -** SQLITE_BUSY. {H17025}  The sqlite3_mutex_try() interface returns [SQLITE_OK]
  4820         -** upon successful entry.  {H17026} Mutexes created using
         4696  +** SQLITE_BUSY.  ^The sqlite3_mutex_try() interface returns [SQLITE_OK]
         4697  +** upon successful entry.  ^(Mutexes created using
  4821   4698   ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
  4822         -** {H17027} In such cases the,
         4699  +** In such cases the,
  4823   4700   ** mutex must be exited an equal number of times before another thread
  4824         -** can enter.  {A17028} If the same thread tries to enter any other
         4701  +** can enter.)^  ^(If the same thread tries to enter any other
  4825   4702   ** kind of mutex more than once, the behavior is undefined.
  4826         -** {H17029} SQLite will never exhibit
  4827         -** such behavior in its own use of mutexes.
         4703  +** SQLite will never exhibit
         4704  +** such behavior in its own use of mutexes.)^
  4828   4705   **
  4829         -** Some systems (for example, Windows 95) do not support the operation
         4706  +** ^(Some systems (for example, Windows 95) do not support the operation
  4830   4707   ** implemented by sqlite3_mutex_try().  On those systems, sqlite3_mutex_try()
  4831         -** will always return SQLITE_BUSY.  {H17030} The SQLite core only ever uses
  4832         -** sqlite3_mutex_try() as an optimization so this is acceptable behavior.
         4708  +** will always return SQLITE_BUSY.  The SQLite core only ever uses
         4709  +** sqlite3_mutex_try() as an optimization so this is acceptable behavior.)^
  4833   4710   **
  4834         -** {H17031} The sqlite3_mutex_leave() routine exits a mutex that was
  4835         -** previously entered by the same thread.  {A17032} The behavior
         4711  +** ^The sqlite3_mutex_leave() routine exits a mutex that was
         4712  +** previously entered by the same thread.   ^(The behavior
  4836   4713   ** is undefined if the mutex is not currently entered by the
  4837         -** calling thread or is not currently allocated.  {H17033} SQLite will
  4838         -** never do either. {END}
         4714  +** calling thread or is not currently allocated.  SQLite will
         4715  +** never do either.)^
  4839   4716   **
  4840         -** If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
         4717  +** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
  4841   4718   ** sqlite3_mutex_leave() is a NULL pointer, then all three routines
  4842   4719   ** behave as no-ops.
  4843   4720   **
  4844   4721   ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
  4845   4722   */
  4846   4723   SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);
  4847   4724   SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*);
  4848   4725   SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*);
  4849   4726   SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
  4850   4727   SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
  4851   4728   
  4852   4729   /*
  4853         -** CAPI3REF: Mutex Methods Object {H17120} <S20130>
         4730  +** CAPI3REF: Mutex Methods Object
  4854   4731   ** EXPERIMENTAL
  4855   4732   **
  4856   4733   ** An instance of this structure defines the low-level routines
  4857   4734   ** used to allocate and use mutexes.
  4858   4735   **
  4859   4736   ** Usually, the default mutex implementations provided by SQLite are
  4860   4737   ** sufficient, however the user has the option of substituting a custom
................................................................................
  4862   4739   ** does not provide a suitable implementation. In this case, the user
  4863   4740   ** creates and populates an instance of this structure to pass
  4864   4741   ** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
  4865   4742   ** Additionally, an instance of this structure can be used as an
  4866   4743   ** output variable when querying the system for the current mutex
  4867   4744   ** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.
  4868   4745   **
  4869         -** The xMutexInit method defined by this structure is invoked as
         4746  +** ^The xMutexInit method defined by this structure is invoked as
  4870   4747   ** part of system initialization by the sqlite3_initialize() function.
  4871         -** {H17001} The xMutexInit routine shall be called by SQLite once for each
         4748  +** ^The xMutexInit routine is calle by SQLite exactly once for each
  4872   4749   ** effective call to [sqlite3_initialize()].
  4873   4750   **
  4874         -** The xMutexEnd method defined by this structure is invoked as
         4751  +** ^The xMutexEnd method defined by this structure is invoked as
  4875   4752   ** part of system shutdown by the sqlite3_shutdown() function. The
  4876   4753   ** implementation of this method is expected to release all outstanding
  4877   4754   ** resources obtained by the mutex methods implementation, especially
  4878         -** those obtained by the xMutexInit method. {H17003} The xMutexEnd()
  4879         -** interface shall be invoked once for each call to [sqlite3_shutdown()].
         4755  +** those obtained by the xMutexInit method.  ^The xMutexEnd()
         4756  +** interface is invoked exactly once for each call to [sqlite3_shutdown()].
  4880   4757   **
  4881         -** The remaining seven methods defined by this structure (xMutexAlloc,
         4758  +** ^(The remaining seven methods defined by this structure (xMutexAlloc,
  4882   4759   ** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
  4883   4760   ** xMutexNotheld) implement the following interfaces (respectively):
  4884   4761   **
  4885   4762   ** <ul>
  4886   4763   **   <li>  [sqlite3_mutex_alloc()] </li>
  4887   4764   **   <li>  [sqlite3_mutex_free()] </li>
  4888   4765   **   <li>  [sqlite3_mutex_enter()] </li>
  4889   4766   **   <li>  [sqlite3_mutex_try()] </li>
  4890   4767   **   <li>  [sqlite3_mutex_leave()] </li>
  4891   4768   **   <li>  [sqlite3_mutex_held()] </li>
  4892   4769   **   <li>  [sqlite3_mutex_notheld()] </li>
  4893         -** </ul>
         4770  +** </ul>)^
  4894   4771   **
  4895   4772   ** The only difference is that the public sqlite3_XXX functions enumerated
  4896   4773   ** above silently ignore any invocations that pass a NULL pointer instead
  4897   4774   ** of a valid mutex handle. The implementations of the methods defined
  4898   4775   ** by this structure are not required to handle this case, the results
  4899   4776   ** of passing a NULL pointer instead of a valid mutex handle are undefined
  4900   4777   ** (i.e. it is acceptable to provide an implementation that segfaults if
  4901   4778   ** it is passed a NULL pointer).
  4902   4779   **
  4903         -** The xMutexInit() method must be threadsafe.  It must be harmless to
         4780  +** The xMutexInit() method must be threadsafe.  ^It must be harmless to
  4904   4781   ** invoke xMutexInit() mutiple times within the same process and without
  4905   4782   ** intervening calls to xMutexEnd().  Second and subsequent calls to
  4906   4783   ** xMutexInit() must be no-ops.
  4907   4784   **
  4908         -** xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
  4909         -** and its associates).  Similarly, xMutexAlloc() must not use SQLite memory
  4910         -** allocation for a static mutex.  However xMutexAlloc() may use SQLite
         4785  +** ^xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
         4786  +** and its associates).  ^Similarly, xMutexAlloc() must not use SQLite memory
         4787  +** allocation for a static mutex.  ^However xMutexAlloc() may use SQLite
  4911   4788   ** memory allocation for a fast or recursive mutex.
  4912   4789   **
  4913         -** SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
         4790  +** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
  4914   4791   ** called, but only if the prior call to xMutexInit returned SQLITE_OK.
  4915   4792   ** If xMutexInit fails in any way, it is expected to clean up after itself
  4916   4793   ** prior to returning.
  4917   4794   */
  4918   4795   typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
  4919   4796   struct sqlite3_mutex_methods {
  4920   4797     int (*xMutexInit)(void);
................................................................................
  4925   4802     int (*xMutexTry)(sqlite3_mutex *);
  4926   4803     void (*xMutexLeave)(sqlite3_mutex *);
  4927   4804     int (*xMutexHeld)(sqlite3_mutex *);
  4928   4805     int (*xMutexNotheld)(sqlite3_mutex *);
  4929   4806   };
  4930   4807   
  4931   4808   /*
  4932         -** CAPI3REF: Mutex Verification Routines {H17080} <S20130> <S30800>
         4809  +** CAPI3REF: Mutex Verification Routines
  4933   4810   **
  4934   4811   ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
  4935         -** are intended for use inside assert() statements. {H17081} The SQLite core
         4812  +** are intended for use inside assert() statements.  ^The SQLite core
  4936   4813   ** never uses these routines except inside an assert() and applications
  4937         -** are advised to follow the lead of the core.  {H17082} The core only
         4814  +** are advised to follow the lead of the core.  ^The SQLite core only
  4938   4815   ** provides implementations for these routines when it is compiled
  4939         -** with the SQLITE_DEBUG flag.  {A17087} External mutex implementations
         4816  +** with the SQLITE_DEBUG flag.  ^External mutex implementations
  4940   4817   ** are only required to provide these routines if SQLITE_DEBUG is
  4941   4818   ** defined and if NDEBUG is not defined.
  4942   4819   **
  4943         -** {H17083} These routines should return true if the mutex in their argument
         4820  +** ^These routines should return true if the mutex in their argument
  4944   4821   ** is held or not held, respectively, by the calling thread.
  4945   4822   **
  4946         -** {X17084} The implementation is not required to provided versions of these
         4823  +** ^The implementation is not required to provided versions of these
  4947   4824   ** routines that actually work. If the implementation does not provide working
  4948   4825   ** versions of these routines, it should at least provide stubs that always
  4949   4826   ** return true so that one does not get spurious assertion failures.
  4950   4827   **
  4951         -** {H17085} If the argument to sqlite3_mutex_held() is a NULL pointer then
  4952         -** the routine should return 1.  {END} This seems counter-intuitive since
         4828  +** ^If the argument to sqlite3_mutex_held() is a NULL pointer then
         4829  +** the routine should return 1.   This seems counter-intuitive since
  4953   4830   ** clearly the mutex cannot be held if it does not exist.  But the
  4954   4831   ** the reason the mutex does not exist is because the build is not
  4955   4832   ** using mutexes.  And we do not want the assert() containing the
  4956   4833   ** call to sqlite3_mutex_held() to fail, so a non-zero return is
  4957         -** the appropriate thing to do.  {H17086} The sqlite3_mutex_notheld()
         4834  +** the appropriate thing to do.  ^The sqlite3_mutex_notheld()
  4958   4835   ** interface should also return 1 when given a NULL pointer.
  4959   4836   */
         4837  +#ifndef NDEBUG
  4960   4838   SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);
  4961   4839   SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
         4840  +#endif
  4962   4841   
  4963   4842   /*
  4964         -** CAPI3REF: Mutex Types {H17001} <H17000>
         4843  +** CAPI3REF: Mutex Types
  4965   4844   **
  4966   4845   ** The [sqlite3_mutex_alloc()] interface takes a single argument
  4967   4846   ** which is one of these integer constants.
  4968   4847   **
  4969   4848   ** The set of static mutexes may change from one SQLite release to the
  4970   4849   ** next.  Applications that override the built-in mutex logic must be
  4971   4850   ** prepared to accommodate additional static mutexes.
................................................................................
  4977   4856   #define SQLITE_MUTEX_STATIC_MEM2      4  /* NOT USED */
  4978   4857   #define SQLITE_MUTEX_STATIC_OPEN      4  /* sqlite3BtreeOpen() */
  4979   4858   #define SQLITE_MUTEX_STATIC_PRNG      5  /* sqlite3_random() */
  4980   4859   #define SQLITE_MUTEX_STATIC_LRU       6  /* lru page list */
  4981   4860   #define SQLITE_MUTEX_STATIC_LRU2      7  /* lru page list */
  4982   4861   
  4983   4862   /*
  4984         -** CAPI3REF: Retrieve the mutex for a database connection {H17002} <H17000>
         4863  +** CAPI3REF: Retrieve the mutex for a database connection
  4985   4864   **
  4986         -** This interface returns a pointer the [sqlite3_mutex] object that 
         4865  +** ^This interface returns a pointer the [sqlite3_mutex] object that 
  4987   4866   ** serializes access to the [database connection] given in the argument
  4988   4867   ** when the [threading mode] is Serialized.
  4989         -** If the [threading mode] is Single-thread or Multi-thread then this
         4868  +** ^If the [threading mode] is Single-thread or Multi-thread then this
  4990   4869   ** routine returns a NULL pointer.
  4991   4870   */
  4992   4871   SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
  4993   4872   
  4994   4873   /*
  4995         -** CAPI3REF: Low-Level Control Of Database Files {H11300} <S30800>
         4874  +** CAPI3REF: Low-Level Control Of Database Files
  4996   4875   **
  4997         -** {H11301} The [sqlite3_file_control()] interface makes a direct call to the
         4876  +** ^The [sqlite3_file_control()] interface makes a direct call to the
  4998   4877   ** xFileControl method for the [sqlite3_io_methods] object associated
  4999         -** with a particular database identified by the second argument. {H11302} The
  5000         -** name of the database is the name assigned to the database by the
  5001         -** <a href="lang_attach.html">ATTACH</a> SQL command that opened the
  5002         -** database. {H11303} To control the main database file, use the name "main"
  5003         -** or a NULL pointer. {H11304} The third and fourth parameters to this routine
         4878  +** with a particular database identified by the second argument. ^The
         4879  +** name of the database "main" for the main database or "temp" for the
         4880  +** TEMP database, or the name that appears after the AS keyword for
         4881  +** databases that are added using the [ATTACH] SQL command.
         4882  +** ^A NULL pointer can be used in place of "main" to refer to the
         4883  +** main database file.
         4884  +** ^The third and fourth parameters to this routine
  5004   4885   ** are passed directly through to the second and third parameters of
  5005         -** the xFileControl method.  {H11305} The return value of the xFileControl
         4886  +** the xFileControl method.  ^The return value of the xFileControl
  5006   4887   ** method becomes the return value of this routine.
  5007   4888   **
  5008         -** {H11306} If the second parameter (zDbName) does not match the name of any
  5009         -** open database file, then SQLITE_ERROR is returned. {H11307} This error
         4889  +** ^If the second parameter (zDbName) does not match the name of any
         4890  +** open database file, then SQLITE_ERROR is returned.  ^This error
  5010   4891   ** code is not remembered and will not be recalled by [sqlite3_errcode()]
  5011         -** or [sqlite3_errmsg()]. {A11308} The underlying xFileControl method might
  5012         -** also return SQLITE_ERROR.  {A11309} There is no way to distinguish between
         4892  +** or [sqlite3_errmsg()].  The underlying xFileControl method might
         4893  +** also return SQLITE_ERROR.  There is no way to distinguish between
  5013   4894   ** an incorrect zDbName and an SQLITE_ERROR return from the underlying
  5014         -** xFileControl method. {END}
         4895  +** xFileControl method.
  5015   4896   **
  5016   4897   ** See also: [SQLITE_FCNTL_LOCKSTATE]
  5017   4898   */
  5018   4899   SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
  5019   4900   
  5020   4901   /*
  5021         -** CAPI3REF: Testing Interface {H11400} <S30800>
         4902  +** CAPI3REF: Testing Interface
  5022   4903   **
  5023         -** The sqlite3_test_control() interface is used to read out internal
         4904  +** ^The sqlite3_test_control() interface is used to read out internal
  5024   4905   ** state of SQLite and to inject faults into SQLite for testing
  5025         -** purposes.  The first parameter is an operation code that determines
         4906  +** purposes.  ^The first parameter is an operation code that determines
  5026   4907   ** the number, meaning, and operation of all subsequent parameters.
  5027   4908   **
  5028   4909   ** This interface is not for use by applications.  It exists solely
  5029   4910   ** for verifying the correct operation of the SQLite library.  Depending
  5030   4911   ** on how the SQLite library is compiled, this interface might not exist.
  5031   4912   **
  5032   4913   ** The details of the operation codes, their meanings, the parameters
................................................................................
  5033   4914   ** they take, and what they do are all subject to change without notice.
  5034   4915   ** Unlike most of the SQLite API, this function is not guaranteed to
  5035   4916   ** operate consistently from one release to the next.
  5036   4917   */
  5037   4918   SQLITE_API int sqlite3_test_control(int op, ...);
  5038   4919   
  5039   4920   /*
  5040         -** CAPI3REF: Testing Interface Operation Codes {H11410} <H11400>
         4921  +** CAPI3REF: Testing Interface Operation Codes
  5041   4922   **
  5042   4923   ** These constants are the valid operation code parameters used
  5043   4924   ** as the first argument to [sqlite3_test_control()].
  5044   4925   **
  5045   4926   ** These parameters and their meanings are subject to change
  5046   4927   ** without notice.  These values are for testing purposes only.
  5047   4928   ** Applications should not use any of these parameters or the
  5048   4929   ** [sqlite3_test_control()] interface.
  5049   4930   */
         4931  +#define SQLITE_TESTCTRL_FIRST                    5
  5050   4932   #define SQLITE_TESTCTRL_PRNG_SAVE                5
  5051   4933   #define SQLITE_TESTCTRL_PRNG_RESTORE             6
  5052   4934   #define SQLITE_TESTCTRL_PRNG_RESET               7
  5053   4935   #define SQLITE_TESTCTRL_BITVEC_TEST              8
  5054   4936   #define SQLITE_TESTCTRL_FAULT_INSTALL            9
  5055   4937   #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS     10
  5056   4938   #define SQLITE_TESTCTRL_PENDING_BYTE            11
  5057   4939   #define SQLITE_TESTCTRL_ASSERT                  12
  5058   4940   #define SQLITE_TESTCTRL_ALWAYS                  13
  5059   4941   #define SQLITE_TESTCTRL_RESERVE                 14
         4942  +#define SQLITE_TESTCTRL_OPTIMIZATIONS           15
         4943  +#define SQLITE_TESTCTRL_ISKEYWORD               16
         4944  +#define SQLITE_TESTCTRL_LAST                    16
  5060   4945   
  5061   4946   /*
  5062         -** CAPI3REF: SQLite Runtime Status {H17200} <S60200>
         4947  +** CAPI3REF: SQLite Runtime Status
  5063   4948   ** EXPERIMENTAL
  5064   4949   **
  5065         -** This interface is used to retrieve runtime status information
         4950  +** ^This interface is used to retrieve runtime status information
  5066   4951   ** about the preformance of SQLite, and optionally to reset various
  5067         -** highwater marks.  The first argument is an integer code for
  5068         -** the specific parameter to measure.  Recognized integer codes
  5069         -** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...].
  5070         -** The current value of the parameter is returned into *pCurrent.
  5071         -** The highest recorded value is returned in *pHighwater.  If the
         4952  +** highwater marks.  ^The first argument is an integer code for
         4953  +** the specific parameter to measure.  ^(Recognized integer codes
         4954  +** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...].)^
         4955  +** ^The current value of the parameter is returned into *pCurrent.
         4956  +** ^The highest recorded value is returned in *pHighwater.  ^If the
  5072   4957   ** resetFlag is true, then the highest record value is reset after
  5073         -** *pHighwater is written. Some parameters do not record the highest
         4958  +** *pHighwater is written.  ^(Some parameters do not record the highest
  5074   4959   ** value.  For those parameters
  5075         -** nothing is written into *pHighwater and the resetFlag is ignored.
  5076         -** Other parameters record only the highwater mark and not the current
  5077         -** value.  For these latter parameters nothing is written into *pCurrent.
         4960  +** nothing is written into *pHighwater and the resetFlag is ignored.)^
         4961  +** ^(Other parameters record only the highwater mark and not the current
         4962  +** value.  For these latter parameters nothing is written into *pCurrent.)^
  5078   4963   **
  5079         -** This routine returns SQLITE_OK on success and a non-zero
  5080         -** [error code] on failure.
         4964  +** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a
         4965  +** non-zero [error code] on failure.
  5081   4966   **
  5082   4967   ** This routine is threadsafe but is not atomic.  This routine can be
  5083   4968   ** called while other threads are running the same or different SQLite
  5084   4969   ** interfaces.  However the values returned in *pCurrent and
  5085   4970   ** *pHighwater reflect the status of SQLite at different points in time
  5086   4971   ** and it is possible that another thread might change the parameter
  5087   4972   ** in between the times when *pCurrent and *pHighwater are written.
................................................................................
  5088   4973   **
  5089   4974   ** See also: [sqlite3_db_status()]
  5090   4975   */
  5091   4976   SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
  5092   4977   
  5093   4978   
  5094   4979   /*
  5095         -** CAPI3REF: Status Parameters {H17250} <H17200>
         4980  +** CAPI3REF: Status Parameters
  5096   4981   ** EXPERIMENTAL
  5097   4982   **
  5098   4983   ** These integer constants designate various run-time status parameters
  5099   4984   ** that can be returned by [sqlite3_status()].
  5100   4985   **
  5101   4986   ** <dl>
  5102         -** <dt>SQLITE_STATUS_MEMORY_USED</dt>
         4987  +** ^(<dt>SQLITE_STATUS_MEMORY_USED</dt>
  5103   4988   ** <dd>This parameter is the current amount of memory checked out
  5104   4989   ** using [sqlite3_malloc()], either directly or indirectly.  The
  5105   4990   ** figure includes calls made to [sqlite3_malloc()] by the application
  5106   4991   ** and internal memory usage by the SQLite library.  Scratch memory
  5107   4992   ** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache
  5108   4993   ** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
  5109   4994   ** this parameter.  The amount returned is the sum of the allocation
  5110         -** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>
         4995  +** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^
  5111   4996   **
  5112         -** <dt>SQLITE_STATUS_MALLOC_SIZE</dt>
         4997  +** ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt>
  5113   4998   ** <dd>This parameter records the largest memory allocation request
  5114   4999   ** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
  5115   5000   ** internal equivalents).  Only the value returned in the
  5116   5001   ** *pHighwater parameter to [sqlite3_status()] is of interest.  
  5117         -** The value written into the *pCurrent parameter is undefined.</dd>
         5002  +** The value written into the *pCurrent parameter is undefined.</dd>)^
  5118   5003   **
  5119         -** <dt>SQLITE_STATUS_PAGECACHE_USED</dt>
         5004  +** ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt>
  5120   5005   ** <dd>This parameter returns the number of pages used out of the
  5121   5006   ** [pagecache memory allocator] that was configured using 
  5122   5007   ** [SQLITE_CONFIG_PAGECACHE].  The
  5123         -** value returned is in pages, not in bytes.</dd>
         5008  +** value returned is in pages, not in bytes.</dd>)^
  5124   5009   **
  5125         -** <dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
         5010  +** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
  5126   5011   ** <dd>This parameter returns the number of bytes of page cache
  5127   5012   ** allocation which could not be statisfied by the [SQLITE_CONFIG_PAGECACHE]
  5128   5013   ** buffer and where forced to overflow to [sqlite3_malloc()].  The
  5129   5014   ** returned value includes allocations that overflowed because they
  5130   5015   ** where too large (they were larger than the "sz" parameter to
  5131   5016   ** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
  5132         -** no space was left in the page cache.</dd>
         5017  +** no space was left in the page cache.</dd>)^
  5133   5018   **
  5134         -** <dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
         5019  +** ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
  5135   5020   ** <dd>This parameter records the largest memory allocation request
  5136   5021   ** handed to [pagecache memory allocator].  Only the value returned in the
  5137   5022   ** *pHighwater parameter to [sqlite3_status()] is of interest.  
  5138         -** The value written into the *pCurrent parameter is undefined.</dd>
         5023  +** The value written into the *pCurrent parameter is undefined.</dd>)^
  5139   5024   **
  5140         -** <dt>SQLITE_STATUS_SCRATCH_USED</dt>
         5025  +** ^(<dt>SQLITE_STATUS_SCRATCH_USED</dt>
  5141   5026   ** <dd>This parameter returns the number of allocations used out of the
  5142   5027   ** [scratch memory allocator] configured using
  5143   5028   ** [SQLITE_CONFIG_SCRATCH].  The value returned is in allocations, not
  5144   5029   ** in bytes.  Since a single thread may only have one scratch allocation
  5145   5030   ** outstanding at time, this parameter also reports the number of threads
  5146         -** using scratch memory at the same time.</dd>
         5031  +** using scratch memory at the same time.</dd>)^
  5147   5032   **
  5148         -** <dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
         5033  +** ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
  5149   5034   ** <dd>This parameter returns the number of bytes of scratch memory
  5150   5035   ** allocation which could not be statisfied by the [SQLITE_CONFIG_SCRATCH]
  5151   5036   ** buffer and where forced to overflow to [sqlite3_malloc()].  The values
  5152   5037   ** returned include overflows because the requested allocation was too
  5153   5038   ** larger (that is, because the requested allocation was larger than the
  5154   5039   ** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer
  5155   5040   ** slots were available.
  5156         -** </dd>
         5041  +** </dd>)^
  5157   5042   **
  5158         -** <dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
         5043  +** ^(<dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
  5159   5044   ** <dd>This parameter records the largest memory allocation request
  5160   5045   ** handed to [scratch memory allocator].  Only the value returned in the
  5161   5046   ** *pHighwater parameter to [sqlite3_status()] is of interest.  
  5162         -** The value written into the *pCurrent parameter is undefined.</dd>
         5047  +** The value written into the *pCurrent parameter is undefined.</dd>)^
  5163   5048   **
  5164         -** <dt>SQLITE_STATUS_PARSER_STACK</dt>
         5049  +** ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
  5165   5050   ** <dd>This parameter records the deepest parser stack.  It is only
  5166         -** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>
         5051  +** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
  5167   5052   ** </dl>
  5168   5053   **
  5169   5054   ** New status parameters may be added from time to time.
  5170   5055   */
  5171   5056   #define SQLITE_STATUS_MEMORY_USED          0
  5172   5057   #define SQLITE_STATUS_PAGECACHE_USED       1
  5173   5058   #define SQLITE_STATUS_PAGECACHE_OVERFLOW   2
................................................................................
  5175   5060   #define SQLITE_STATUS_SCRATCH_OVERFLOW     4
  5176   5061   #define SQLITE_STATUS_MALLOC_SIZE          5
  5177   5062   #define SQLITE_STATUS_PARSER_STACK         6
  5178   5063   #define SQLITE_STATUS_PAGECACHE_SIZE       7
  5179   5064   #define SQLITE_STATUS_SCRATCH_SIZE         8
  5180   5065   
  5181   5066   /*
  5182         -** CAPI3REF: Database Connection Status {H17500} <S60200>
         5067  +** CAPI3REF: Database Connection Status
  5183   5068   ** EXPERIMENTAL
  5184   5069   **
  5185         -** This interface is used to retrieve runtime status information 
  5186         -** about a single [database connection].  The first argument is the
  5187         -** database connection object to be interrogated.  The second argument
  5188         -** is the parameter to interrogate.  Currently, the only allowed value
         5070  +** ^This interface is used to retrieve runtime status information 
         5071  +** about a single [database connection].  ^The first argument is the
         5072  +** database connection object to be interrogated.  ^The second argument
         5073  +** is the parameter to interrogate.  ^Currently, the only allowed value
  5189   5074   ** for the second parameter is [SQLITE_DBSTATUS_LOOKASIDE_USED].
  5190   5075   ** Additional options will likely appear in future releases of SQLite.
  5191   5076   **
  5192         -** The current value of the requested parameter is written into *pCur
  5193         -** and the highest instantaneous value is written into *pHiwtr.  If
         5077  +** ^The current value of the requested parameter is written into *pCur
         5078  +** and the highest instantaneous value is written into *pHiwtr.  ^If
  5194   5079   ** the resetFlg is true, then the highest instantaneous value is
  5195   5080   ** reset back down to the current value.
  5196   5081   **
  5197   5082   ** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
  5198   5083   */
  5199   5084   SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
  5200   5085   
  5201   5086   /*
  5202         -** CAPI3REF: Status Parameters for database connections {H17520} <H17500>
         5087  +** CAPI3REF: Status Parameters for database connections
  5203   5088   ** EXPERIMENTAL
  5204   5089   **
  5205   5090   ** These constants are the available integer "verbs" that can be passed as
  5206   5091   ** the second argument to the [sqlite3_db_status()] interface.
  5207   5092   **
  5208   5093   ** New verbs may be added in future releases of SQLite. Existing verbs
  5209   5094   ** might be discontinued. Applications should check the return code from
  5210   5095   ** [sqlite3_db_status()] to make sure that the call worked.
  5211   5096   ** The [sqlite3_db_status()] interface will return a non-zero error code
  5212   5097   ** if a discontinued or unsupported verb is invoked.
  5213   5098   **
  5214   5099   ** <dl>
  5215         -** <dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
         5100  +** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
  5216   5101   ** <dd>This parameter returns the number of lookaside memory slots currently
  5217         -** checked out.</dd>
         5102  +** checked out.</dd>)^
  5218   5103   ** </dl>
  5219   5104   */
  5220   5105   #define SQLITE_DBSTATUS_LOOKASIDE_USED     0
  5221   5106   
  5222   5107   
  5223   5108   /*
  5224         -** CAPI3REF: Prepared Statement Status {H17550} <S60200>
         5109  +** CAPI3REF: Prepared Statement Status
  5225   5110   ** EXPERIMENTAL
  5226   5111   **
  5227         -** Each prepared statement maintains various
         5112  +** ^(Each prepared statement maintains various
  5228   5113   ** [SQLITE_STMTSTATUS_SORT | counters] that measure the number
  5229         -** of times it has performed specific operations.  These counters can
         5114  +** of times it has performed specific operations.)^  These counters can
  5230   5115   ** be used to monitor the performance characteristics of the prepared
  5231   5116   ** statements.  For example, if the number of table steps greatly exceeds
  5232   5117   ** the number of table searches or result rows, that would tend to indicate
  5233   5118   ** that the prepared statement is using a full table scan rather than
  5234   5119   ** an index.  
  5235   5120   **
  5236         -** This interface is used to retrieve and reset counter values from
         5121  +** ^(This interface is used to retrieve and reset counter values from
  5237   5122   ** a [prepared statement].  The first argument is the prepared statement
  5238   5123   ** object to be interrogated.  The second argument
  5239   5124   ** is an integer code for a specific [SQLITE_STMTSTATUS_SORT | counter]
  5240         -** to be interrogated. 
  5241         -** The current value of the requested counter is returned.
  5242         -** If the resetFlg is true, then the counter is reset to zero after this
         5125  +** to be interrogated.)^
         5126  +** ^The current value of the requested counter is returned.
         5127  +** ^If the resetFlg is true, then the counter is reset to zero after this
  5243   5128   ** interface call returns.
  5244   5129   **
  5245   5130   ** See also: [sqlite3_status()] and [sqlite3_db_status()].
  5246   5131   */
  5247   5132   SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
  5248   5133   
  5249   5134   /*
  5250         -** CAPI3REF: Status Parameters for prepared statements {H17570} <H17550>
         5135  +** CAPI3REF: Status Parameters for prepared statements
  5251   5136   ** EXPERIMENTAL
  5252   5137   **
  5253   5138   ** These preprocessor macros define integer codes that name counter
  5254   5139   ** values associated with the [sqlite3_stmt_status()] interface.
  5255   5140   ** The meanings of the various counters are as follows:
  5256   5141   **
  5257   5142   ** <dl>
  5258   5143   ** <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>
  5259         -** <dd>This is the number of times that SQLite has stepped forward in
         5144  +** <dd>^This is the number of times that SQLite has stepped forward in
  5260   5145   ** a table as part of a full table scan.  Large numbers for this counter
  5261   5146   ** may indicate opportunities for performance improvement through 
  5262   5147   ** careful use of indices.</dd>
  5263   5148   **
  5264   5149   ** <dt>SQLITE_STMTSTATUS_SORT</dt>
  5265         -** <dd>This is the number of sort operations that have occurred.
         5150  +** <dd>^This is the number of sort operations that have occurred.
  5266   5151   ** A non-zero value in this counter may indicate an opportunity to
  5267   5152   ** improvement performance through careful use of indices.</dd>
  5268   5153   **
  5269   5154   ** </dl>
  5270   5155   */
  5271   5156   #define SQLITE_STMTSTATUS_FULLSCAN_STEP     1
  5272   5157   #define SQLITE_STMTSTATUS_SORT              2
................................................................................
  5286   5171   typedef struct sqlite3_pcache sqlite3_pcache;
  5287   5172   
  5288   5173   /*
  5289   5174   ** CAPI3REF: Application Defined Page Cache.
  5290   5175   ** KEYWORDS: {page cache}
  5291   5176   ** EXPERIMENTAL
  5292   5177   **
  5293         -** The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
         5178  +** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
  5294   5179   ** register an alternative page cache implementation by passing in an 
  5295         -** instance of the sqlite3_pcache_methods structure. The majority of the 
         5180  +** instance of the sqlite3_pcache_methods structure.)^ The majority of the 
  5296   5181   ** heap memory used by SQLite is used by the page cache to cache data read 
  5297   5182   ** from, or ready to be written to, the database file. By implementing a 
  5298   5183   ** custom page cache using this API, an application can control more 
  5299   5184   ** precisely the amount of memory consumed by SQLite, the way in which 
  5300   5185   ** that memory is allocated and released, and the policies used to 
  5301   5186   ** determine exactly which parts of a database file are cached and for 
  5302   5187   ** how long.
  5303   5188   **
  5304         -** The contents of the sqlite3_pcache_methods structure are copied to an
         5189  +** ^(The contents of the sqlite3_pcache_methods structure are copied to an
  5305   5190   ** internal buffer by SQLite within the call to [sqlite3_config].  Hence
  5306   5191   ** the application may discard the parameter after the call to
  5307         -** [sqlite3_config()] returns.
         5192  +** [sqlite3_config()] returns.)^
  5308   5193   **
  5309         -** The xInit() method is called once for each call to [sqlite3_initialize()]
  5310         -** (usually only once during the lifetime of the process). It is passed
  5311         -** a copy of the sqlite3_pcache_methods.pArg value. It can be used to set
  5312         -** up global structures and mutexes required by the custom page cache 
  5313         -** implementation. 
         5194  +** ^The xInit() method is called once for each call to [sqlite3_initialize()]
         5195  +** (usually only once during the lifetime of the process). ^(The xInit()
         5196  +** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^
         5197  +** ^The xInit() method can set up up global structures and/or any mutexes
         5198  +** required by the custom page cache implementation. 
  5314   5199   **
  5315         -** The xShutdown() method is called from within [sqlite3_shutdown()], 
         5200  +** ^The xShutdown() method is called from within [sqlite3_shutdown()], 
  5316   5201   ** if the application invokes this API. It can be used to clean up 
  5317   5202   ** any outstanding resources before process shutdown, if required.
  5318   5203   **
  5319         -** SQLite holds a [SQLITE_MUTEX_RECURSIVE] mutex when it invokes
  5320         -** the xInit method, so the xInit method need not be threadsafe.  The
         5204  +** ^SQLite holds a [SQLITE_MUTEX_RECURSIVE] mutex when it invokes
         5205  +** the xInit method, so the xInit method need not be threadsafe.  ^The
  5321   5206   ** xShutdown method is only called from [sqlite3_shutdown()] so it does
  5322   5207   ** not need to be threadsafe either.  All other methods must be threadsafe
  5323   5208   ** in multithreaded applications.
  5324   5209   **
  5325         -** SQLite will never invoke xInit() more than once without an intervening
         5210  +** ^SQLite will never invoke xInit() more than once without an intervening
  5326   5211   ** call to xShutdown().
  5327   5212   **
  5328         -** The xCreate() method is used to construct a new cache instance.  SQLite
         5213  +** ^The xCreate() method is used to construct a new cache instance.  SQLite
  5329   5214   ** will typically create one cache instance for each open database file,
  5330         -** though this is not guaranteed. The
         5215  +** though this is not guaranteed. ^The
  5331   5216   ** first parameter, szPage, is the size in bytes of the pages that must
  5332         -** be allocated by the cache.  szPage will not be a power of two.  szPage
         5217  +** be allocated by the cache.  ^szPage will not be a power of two.  ^szPage
  5333   5218   ** will the page size of the database file that is to be cached plus an
  5334         -** increment (here called "R") of about 100 or 200.  SQLite will use the
         5219  +** increment (here called "R") of about 100 or 200.  ^SQLite will use the
  5335   5220   ** extra R bytes on each page to store metadata about the underlying
  5336   5221   ** database page on disk.  The value of R depends
  5337   5222   ** on the SQLite version, the target platform, and how SQLite was compiled.
  5338         -** R is constant for a particular build of SQLite.  The second argument to
         5223  +** ^R is constant for a particular build of SQLite.  ^The second argument to
  5339   5224   ** xCreate(), bPurgeable, is true if the cache being created will
  5340   5225   ** be used to cache database pages of a file stored on disk, or
  5341         -** false if it is used for an in-memory database. The cache implementation
         5226  +** false if it is used for an in-memory database. ^The cache implementation
  5342   5227   ** does not have to do anything special based with the value of bPurgeable;
  5343         -** it is purely advisory.  On a cache where bPurgeable is false, SQLite will
         5228  +** it is purely advisory.  ^On a cache where bPurgeable is false, SQLite will
  5344   5229   ** never invoke xUnpin() except to deliberately delete a page.
  5345         -** In other words, a cache created with bPurgeable set to false will
         5230  +** ^In other words, a cache created with bPurgeable set to false will
  5346   5231   ** never contain any unpinned pages.
  5347   5232   **
  5348         -** The xCachesize() method may be called at any time by SQLite to set the
         5233  +** ^(The xCachesize() method may be called at any time by SQLite to set the
  5349   5234   ** suggested maximum cache-size (number of pages stored by) the cache
  5350   5235   ** instance passed as the first argument. This is the value configured using
  5351         -** the SQLite "[PRAGMA cache_size]" command. As with the bPurgeable parameter,
  5352         -** the implementation is not required to do anything with this
         5236  +** the SQLite "[PRAGMA cache_size]" command.)^  ^As with the bPurgeable
         5237  +** parameter, the implementation is not required to do anything with this
  5353   5238   ** value; it is advisory only.
  5354   5239   **
  5355         -** The xPagecount() method should return the number of pages currently
         5240  +** ^The xPagecount() method should return the number of pages currently
  5356   5241   ** stored in the cache.
  5357   5242   ** 
  5358         -** The xFetch() method is used to fetch a page and return a pointer to it. 
  5359         -** A 'page', in this context, is a buffer of szPage bytes aligned at an
  5360         -** 8-byte boundary. The page to be fetched is determined by the key. The
         5243  +** ^The xFetch() method is used to fetch a page and return a pointer to it. 
         5244  +** ^A 'page', in this context, is a buffer of szPage bytes aligned at an
         5245  +** 8-byte boundary. ^The page to be fetched is determined by the key. ^The
  5361   5246   ** mimimum key value is 1. After it has been retrieved using xFetch, the page 
  5362   5247   ** is considered to be "pinned".
  5363   5248   **
  5364         -** If the requested page is already in the page cache, then the page cache
         5249  +** ^If the requested page is already in the page cache, then the page cache
  5365   5250   ** implementation must return a pointer to the page buffer with its content
  5366         -** intact.  If the requested page is not already in the cache, then the
         5251  +** intact.  ^(If the requested page is not already in the cache, then the
  5367   5252   ** behavior of the cache implementation is determined by the value of the
  5368   5253   ** createFlag parameter passed to xFetch, according to the following table:
  5369   5254   **
  5370   5255   ** <table border=1 width=85% align=center>
  5371   5256   ** <tr><th> createFlag <th> Behaviour when page is not already in cache
  5372   5257   ** <tr><td> 0 <td> Do not allocate a new page.  Return NULL.
  5373   5258   ** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
  5374   5259   **                 Otherwise return NULL.
  5375   5260   ** <tr><td> 2 <td> Make every effort to allocate a new page.  Only return
  5376   5261   **                 NULL if allocating a new page is effectively impossible.
  5377         -** </table>
         5262  +** </table>)^
  5378   5263   **
  5379   5264   ** SQLite will normally invoke xFetch() with a createFlag of 0 or 1.  If
  5380   5265   ** a call to xFetch() with createFlag==1 returns NULL, then SQLite will
  5381   5266   ** attempt to unpin one or more cache pages by spilling the content of
  5382   5267   ** pinned pages to disk and synching the operating system disk cache. After
  5383   5268   ** attempting to unpin pages, the xFetch() method will be invoked again with
  5384   5269   ** a createFlag of 2.
  5385   5270   **
  5386         -** xUnpin() is called by SQLite with a pointer to a currently pinned page
  5387         -** as its second argument. If the third parameter, discard, is non-zero,
         5271  +** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
         5272  +** as its second argument. ^(If the third parameter, discard, is non-zero,
  5388   5273   ** then the page should be evicted from the cache. In this case SQLite 
  5389   5274   ** assumes that the next time the page is retrieved from the cache using
  5390         -** the xFetch() method, it will be zeroed. If the discard parameter is
  5391         -** zero, then the page is considered to be unpinned. The cache implementation
         5275  +** the xFetch() method, it will be zeroed.)^ ^If the discard parameter is
         5276  +** zero, then the page is considered to be unpinned. ^The cache implementation
  5392   5277   ** may choose to evict unpinned pages at any time.
  5393   5278   **
  5394         -** The cache is not required to perform any reference counting. A single 
         5279  +** ^(The cache is not required to perform any reference counting. A single 
  5395   5280   ** call to xUnpin() unpins the page regardless of the number of prior calls 
  5396         -** to xFetch().
         5281  +** to xFetch().)^
  5397   5282   **
  5398         -** The xRekey() method is used to change the key value associated with the
  5399         -** page passed as the second argument from oldKey to newKey. If the cache
         5283  +** ^The xRekey() method is used to change the key value associated with the
         5284  +** page passed as the second argument from oldKey to newKey. ^If the cache
  5400   5285   ** previously contains an entry associated with newKey, it should be
  5401         -** discarded. Any prior cache entry associated with newKey is guaranteed not
         5286  +** discarded. ^Any prior cache entry associated with newKey is guaranteed not
  5402   5287   ** to be pinned.
  5403   5288   **
  5404         -** When SQLite calls the xTruncate() method, the cache must discard all
         5289  +** ^When SQLite calls the xTruncate() method, the cache must discard all
  5405   5290   ** existing cache entries with page numbers (keys) greater than or equal
  5406         -** to the value of the iLimit parameter passed to xTruncate(). If any
         5291  +** to the value of the iLimit parameter passed to xTruncate(). ^If any
  5407   5292   ** of these pages are pinned, they are implicitly unpinned, meaning that
  5408   5293   ** they can be safely discarded.
  5409   5294   **
  5410         -** The xDestroy() method is used to delete a cache allocated by xCreate().
  5411         -** All resources associated with the specified cache should be freed. After
         5295  +** ^The xDestroy() method is used to delete a cache allocated by xCreate().
         5296  +** All resources associated with the specified cache should be freed. ^After
  5412   5297   ** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
  5413   5298   ** handle invalid, and will not use it with any other sqlite3_pcache_methods
  5414   5299   ** functions.
  5415   5300   */
  5416   5301   typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
  5417   5302   struct sqlite3_pcache_methods {
  5418   5303     void *pArg;
................................................................................
  5429   5314   };
  5430   5315   
  5431   5316   /*
  5432   5317   ** CAPI3REF: Online Backup Object
  5433   5318   ** EXPERIMENTAL
  5434   5319   **
  5435   5320   ** The sqlite3_backup object records state information about an ongoing
  5436         -** online backup operation.  The sqlite3_backup object is created by
         5321  +** online backup operation.  ^The sqlite3_backup object is created by
  5437   5322   ** a call to [sqlite3_backup_init()] and is destroyed by a call to
  5438   5323   ** [sqlite3_backup_finish()].
  5439   5324   **
  5440   5325   ** See Also: [Using the SQLite Online Backup API]
  5441   5326   */
  5442   5327   typedef struct sqlite3_backup sqlite3_backup;
  5443   5328   
  5444   5329   /*
  5445   5330   ** CAPI3REF: Online Backup API.
  5446   5331   ** EXPERIMENTAL
  5447   5332   **
  5448         -** This API is used to overwrite the contents of one database with that
  5449         -** of another. It is useful either for creating backups of databases or
         5333  +** The backup API copies the content of one database into another.
         5334  +** It is useful either for creating backups of databases or
  5450   5335   ** for copying in-memory databases to or from persistent files. 
  5451   5336   **
  5452   5337   ** See Also: [Using the SQLite Online Backup API]
  5453   5338   **
  5454         -** Exclusive access is required to the destination database for the 
  5455         -** duration of the operation. However the source database is only
  5456         -** read-locked while it is actually being read, it is not locked
  5457         -** continuously for the entire operation. Thus, the backup may be
  5458         -** performed on a live database without preventing other users from
  5459         -** writing to the database for an extended period of time.
         5339  +** ^Exclusive access is required to the destination database for the 
         5340  +** duration of the operation. ^However the source database is only
         5341  +** read-locked while it is actually being read; it is not locked
         5342  +** continuously for the entire backup operation. ^Thus, the backup may be
         5343  +** performed on a live source database without preventing other users from
         5344  +** reading or writing to the source database while the backup is underway.
  5460   5345   ** 
  5461         -** To perform a backup operation: 
         5346  +** ^(To perform a backup operation: 
  5462   5347   **   <ol>
  5463   5348   **     <li><b>sqlite3_backup_init()</b> is called once to initialize the
  5464   5349   **         backup, 
  5465   5350   **     <li><b>sqlite3_backup_step()</b> is called one or more times to transfer 
  5466   5351   **         the data between the two databases, and finally
  5467   5352   **     <li><b>sqlite3_backup_finish()</b> is called to release all resources 
  5468   5353   **         associated with the backup operation. 
  5469         -**   </ol>
         5354  +**   </ol>)^
  5470   5355   ** There should be exactly one call to sqlite3_backup_finish() for each
  5471   5356   ** successful call to sqlite3_backup_init().
  5472   5357   **
  5473   5358   ** <b>sqlite3_backup_init()</b>
  5474   5359   **
  5475         -** The first two arguments passed to [sqlite3_backup_init()] are the database
  5476         -** handle associated with the destination database and the database name 
  5477         -** used to attach the destination database to the handle. The database name
  5478         -** is "main" for the main database, "temp" for the temporary database, or
  5479         -** the name specified as part of the [ATTACH] statement if the destination is
  5480         -** an attached database. The third and fourth arguments passed to 
  5481         -** sqlite3_backup_init() identify the [database connection]
  5482         -** and database name used
  5483         -** to access the source database. The values passed for the source and 
  5484         -** destination [database connection] parameters must not be the same.
         5360  +** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the 
         5361  +** [database connection] associated with the destination database 
         5362  +** and the database name, respectively.
         5363  +** ^The database name is "main" for the main database, "temp" for the
         5364  +** temporary database, or the name specified after the AS keyword in
         5365  +** an [ATTACH] statement for an attached database.
         5366  +** ^The S and M arguments passed to 
         5367  +** sqlite3_backup_init(D,N,S,M) identify the [database connection]
         5368  +** and database name of the source database, respectively.
         5369  +** ^The source and destination [database connections] (parameters S and D)
         5370  +** must be different or else sqlite3_backup_init(D,N,S,M) will file with
         5371  +** an error.
  5485   5372   **
  5486         -** If an error occurs within sqlite3_backup_init(), then NULL is returned
  5487         -** and an error code and error message written into the [database connection] 
  5488         -** passed as the first argument. They may be retrieved using the
  5489         -** [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()] functions.
  5490         -** Otherwise, if successful, a pointer to an [sqlite3_backup] object is
  5491         -** returned. This pointer may be used with the sqlite3_backup_step() and
         5373  +** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
         5374  +** returned and an error code and error message are store3d in the
         5375  +** destination [database connection] D.
         5376  +** ^The error code and message for the failed call to sqlite3_backup_init()
         5377  +** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
         5378  +** [sqlite3_errmsg16()] functions.
         5379  +** ^A successful call to sqlite3_backup_init() returns a pointer to an
         5380  +** [sqlite3_backup] object.
         5381  +** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
  5492   5382   ** sqlite3_backup_finish() functions to perform the specified backup 
  5493   5383   ** operation.
  5494   5384   **
  5495   5385   ** <b>sqlite3_backup_step()</b>
  5496   5386   **
  5497         -** Function [sqlite3_backup_step()] is used to copy up to nPage pages between 
  5498         -** the source and destination databases, where nPage is the value of the 
  5499         -** second parameter passed to sqlite3_backup_step(). If nPage is a negative
  5500         -** value, all remaining source pages are copied. If the required pages are 
  5501         -** succesfully copied, but there are still more pages to copy before the 
  5502         -** backup is complete, it returns [SQLITE_OK]. If no error occured and there 
  5503         -** are no more pages to copy, then [SQLITE_DONE] is returned. If an error 
  5504         -** occurs, then an SQLite error code is returned. As well as [SQLITE_OK] and
         5387  +** ^Function sqlite3_backup_step(B,N) will copy up to N pages between 
         5388  +** the source and destination databases specified by [sqlite3_backup] object B.
         5389  +** ^If N is negative, all remaining source pages are copied. 
         5390  +** ^If sqlite3_backup_step(B,N) successfully copies N pages and there
         5391  +** are still more pages to be copied, then the function resturns [SQLITE_OK].
         5392  +** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages
         5393  +** from source to destination, then it returns [SQLITE_DONE].
         5394  +** ^If an error occurs while running sqlite3_backup_step(B,N),
         5395  +** then an [error code] is returned. ^As well as [SQLITE_OK] and
  5505   5396   ** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
  5506   5397   ** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
  5507   5398   ** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
  5508   5399   **
  5509         -** As well as the case where the destination database file was opened for
  5510         -** read-only access, sqlite3_backup_step() may return [SQLITE_READONLY] if
         5400  +** ^The sqlite3_backup_step() might return [SQLITE_READONLY] if the destination
         5401  +** database was opened read-only or if
  5511   5402   ** the destination is an in-memory database with a different page size
  5512   5403   ** from the source database.
  5513   5404   **
  5514         -** If sqlite3_backup_step() cannot obtain a required file-system lock, then
         5405  +** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
  5515   5406   ** the [sqlite3_busy_handler | busy-handler function]
  5516         -** is invoked (if one is specified). If the 
         5407  +** is invoked (if one is specified). ^If the 
  5517   5408   ** busy-handler returns non-zero before the lock is available, then 
  5518         -** [SQLITE_BUSY] is returned to the caller. In this case the call to
  5519         -** sqlite3_backup_step() can be retried later. If the source
         5409  +** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
         5410  +** sqlite3_backup_step() can be retried later. ^If the source
  5520   5411   ** [database connection]
  5521   5412   ** is being used to write to the source database when sqlite3_backup_step()
  5522         -** is called, then [SQLITE_LOCKED] is returned immediately. Again, in this
  5523         -** case the call to sqlite3_backup_step() can be retried later on. If
         5413  +** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
         5414  +** case the call to sqlite3_backup_step() can be retried later on. ^(If
  5524   5415   ** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
  5525   5416   ** [SQLITE_READONLY] is returned, then 
  5526   5417   ** there is no point in retrying the call to sqlite3_backup_step(). These 
  5527         -** errors are considered fatal. At this point the application must accept 
         5418  +** errors are considered fatal.)^  The application must accept 
  5528   5419   ** that the backup operation has failed and pass the backup operation handle 
  5529   5420   ** to the sqlite3_backup_finish() to release associated resources.
  5530   5421   **
  5531         -** Following the first call to sqlite3_backup_step(), an exclusive lock is
  5532         -** obtained on the destination file. It is not released until either 
         5422  +** ^The first call to sqlite3_backup_step() obtains an exclusive lock
         5423  +** on the destination file. ^The exclusive lock is not released until either 
  5533   5424   ** sqlite3_backup_finish() is called or the backup operation is complete 
  5534         -** and sqlite3_backup_step() returns [SQLITE_DONE]. Additionally, each time 
  5535         -** a call to sqlite3_backup_step() is made a [shared lock] is obtained on
  5536         -** the source database file. This lock is released before the
  5537         -** sqlite3_backup_step() call returns. Because the source database is not
  5538         -** locked between calls to sqlite3_backup_step(), it may be modified mid-way
  5539         -** through the backup procedure. If the source database is modified by an
         5425  +** and sqlite3_backup_step() returns [SQLITE_DONE].  ^Every call to
         5426  +** sqlite3_backup_step() obtains a [shared lock] on the source database that
         5427  +** lasts for the duration of the sqlite3_backup_step() call.
         5428  +** ^Because the source database is not locked between calls to
         5429  +** sqlite3_backup_step(), the source database may be modified mid-way
         5430  +** through the backup process.  ^If the source database is modified by an
  5540   5431   ** external process or via a database connection other than the one being
  5541         -** used by the backup operation, then the backup will be transparently
  5542         -** restarted by the next call to sqlite3_backup_step(). If the source 
         5432  +** used by the backup operation, then the backup will be automatically
         5433  +** restarted by the next call to sqlite3_backup_step(). ^If the source 
  5543   5434   ** database is modified by the using the same database connection as is used
  5544         -** by the backup operation, then the backup database is transparently 
         5435  +** by the backup operation, then the backup database is automatically
  5545   5436   ** updated at the same time.
  5546   5437   **
  5547   5438   ** <b>sqlite3_backup_finish()</b>
  5548   5439   **
  5549         -** Once sqlite3_backup_step() has returned [SQLITE_DONE], or when the 
  5550         -** application wishes to abandon the backup operation, the [sqlite3_backup]
  5551         -** object should be passed to sqlite3_backup_finish(). This releases all
  5552         -** resources associated with the backup operation. If sqlite3_backup_step()
  5553         -** has not yet returned [SQLITE_DONE], then any active write-transaction on the
  5554         -** destination database is rolled back. The [sqlite3_backup] object is invalid
         5440  +** When sqlite3_backup_step() has returned [SQLITE_DONE], or when the 
         5441  +** application wishes to abandon the backup operation, the application
         5442  +** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
         5443  +** ^The sqlite3_backup_finish() interfaces releases all
         5444  +** resources associated with the [sqlite3_backup] object. 
         5445  +** ^If sqlite3_backup_step() has not yet returned [SQLITE_DONE], then any
         5446  +** active write-transaction on the destination database is rolled back.
         5447  +** The [sqlite3_backup] object is invalid
  5555   5448   ** and may not be used following a call to sqlite3_backup_finish().
  5556   5449   **
  5557         -** The value returned by sqlite3_backup_finish is [SQLITE_OK] if no error
  5558         -** occurred, regardless or whether or not sqlite3_backup_step() was called
  5559         -** a sufficient number of times to complete the backup operation. Or, if
  5560         -** an out-of-memory condition or IO error occured during a call to
  5561         -** sqlite3_backup_step() then [SQLITE_NOMEM] or an
  5562         -** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] error code
  5563         -** is returned. In this case the error code and an error message are
  5564         -** written to the destination [database connection].
         5450  +** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
         5451  +** sqlite3_backup_step() errors occurred, regardless or whether or not
         5452  +** sqlite3_backup_step() completed.
         5453  +** ^If an out-of-memory condition or IO error occurred during any prior
         5454  +** sqlite3_backup_step() call on the same [sqlite3_backup] object, then
         5455  +** sqlite3_backup_finish() returns the corresponding [error code].
  5565   5456   **
  5566         -** A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step() is
  5567         -** not a permanent error and does not affect the return value of
         5457  +** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
         5458  +** is not a permanent error and does not affect the return value of
  5568   5459   ** sqlite3_backup_finish().
  5569   5460   **
  5570   5461   ** <b>sqlite3_backup_remaining(), sqlite3_backup_pagecount()</b>
  5571   5462   **
  5572         -** Each call to sqlite3_backup_step() sets two values stored internally
  5573         -** by an [sqlite3_backup] object. The number of pages still to be backed
  5574         -** up, which may be queried by sqlite3_backup_remaining(), and the total
  5575         -** number of pages in the source database file, which may be queried by
  5576         -** sqlite3_backup_pagecount().
         5463  +** ^Each call to sqlite3_backup_step() sets two values inside
         5464  +** the [sqlite3_backup] object: the number of pages still to be backed
         5465  +** up and the total number of pages in the source databae file.
         5466  +** The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces
         5467  +** retrieve these two values, respectively.
  5577   5468   **
  5578         -** The values returned by these functions are only updated by
  5579         -** sqlite3_backup_step(). If the source database is modified during a backup
         5469  +** ^The values returned by these functions are only updated by
         5470  +** sqlite3_backup_step(). ^If the source database is modified during a backup
  5580   5471   ** operation, then the values are not updated to account for any extra
  5581   5472   ** pages that need to be updated or the size of the source database file
  5582   5473   ** changing.
  5583   5474   **
  5584   5475   ** <b>Concurrent Usage of Database Handles</b>
  5585   5476   **
  5586         -** The source [database connection] may be used by the application for other
         5477  +** ^The source [database connection] may be used by the application for other
  5587   5478   ** purposes while a backup operation is underway or being initialized.
  5588         -** If SQLite is compiled and configured to support threadsafe database
         5479  +** ^If SQLite is compiled and configured to support threadsafe database
  5589   5480   ** connections, then the source database connection may be used concurrently
  5590   5481   ** from within other threads.
  5591   5482   **
  5592         -** However, the application must guarantee that the destination database
  5593         -** connection handle is not passed to any other API (by any thread) after 
         5483  +** However, the application must guarantee that the destination 
         5484  +** [database connection] is not passed to any other API (by any thread) after 
  5594   5485   ** sqlite3_backup_init() is called and before the corresponding call to
  5595         -** sqlite3_backup_finish(). Unfortunately SQLite does not currently check
  5596         -** for this, if the application does use the destination [database connection]
  5597         -** for some other purpose during a backup operation, things may appear to
  5598         -** work correctly but in fact be subtly malfunctioning.  Use of the
  5599         -** destination database connection while a backup is in progress might
  5600         -** also cause a mutex deadlock.
         5486  +** sqlite3_backup_finish().  SQLite does not currently check to see
         5487  +** if the application incorrectly accesses the destination [database connection]
         5488  +** and so no error code is reported, but the operations may malfunction
         5489  +** nevertheless.  Use of the destination database connection while a
         5490  +** backup is in progress might also also cause a mutex deadlock.
  5601   5491   **
  5602         -** Furthermore, if running in [shared cache mode], the application must
         5492  +** If running in [shared cache mode], the application must
  5603   5493   ** guarantee that the shared cache used by the destination database
  5604   5494   ** is not accessed while the backup is running. In practice this means
  5605         -** that the application must guarantee that the file-system file being 
         5495  +** that the application must guarantee that the disk file being 
  5606   5496   ** backed up to is not accessed by any connection within the process,
  5607   5497   ** not just the specific connection that was passed to sqlite3_backup_init().
  5608   5498   **
  5609   5499   ** The [sqlite3_backup] object itself is partially threadsafe. Multiple 
  5610   5500   ** threads may safely make multiple concurrent calls to sqlite3_backup_step().
  5611   5501   ** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
  5612   5502   ** APIs are not strictly speaking threadsafe. If they are invoked at the
................................................................................
  5624   5514   SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
  5625   5515   SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
  5626   5516   
  5627   5517   /*
  5628   5518   ** CAPI3REF: Unlock Notification
  5629   5519   ** EXPERIMENTAL
  5630   5520   **
  5631         -** When running in shared-cache mode, a database operation may fail with
         5521  +** ^When running in shared-cache mode, a database operation may fail with
  5632   5522   ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
  5633   5523   ** individual tables within the shared-cache cannot be obtained. See
  5634   5524   ** [SQLite Shared-Cache Mode] for a description of shared-cache locking. 
  5635         -** This API may be used to register a callback that SQLite will invoke 
         5525  +** ^This API may be used to register a callback that SQLite will invoke 
  5636   5526   ** when the connection currently holding the required lock relinquishes it.
  5637         -** This API is only available if the library was compiled with the
         5527  +** ^This API is only available if the library was compiled with the
  5638   5528   ** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
  5639   5529   **
  5640   5530   ** See Also: [Using the SQLite Unlock Notification Feature].
  5641   5531   **
  5642         -** Shared-cache locks are released when a database connection concludes
         5532  +** ^Shared-cache locks are released when a database connection concludes
  5643   5533   ** its current transaction, either by committing it or rolling it back. 
  5644   5534   **
  5645         -** When a connection (known as the blocked connection) fails to obtain a
         5535  +** ^When a connection (known as the blocked connection) fails to obtain a
  5646   5536   ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
  5647   5537   ** identity of the database connection (the blocking connection) that
  5648         -** has locked the required resource is stored internally. After an 
         5538  +** has locked the required resource is stored internally. ^After an 
  5649   5539   ** application receives an SQLITE_LOCKED error, it may call the
  5650   5540   ** sqlite3_unlock_notify() method with the blocked connection handle as 
  5651   5541   ** the first argument to register for a callback that will be invoked
  5652         -** when the blocking connections current transaction is concluded. The
         5542  +** when the blocking connections current transaction is concluded. ^The
  5653   5543   ** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
  5654   5544   ** call that concludes the blocking connections transaction.
  5655   5545   **
  5656         -** If sqlite3_unlock_notify() is called in a multi-threaded application,
         5546  +** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
  5657   5547   ** there is a chance that the blocking connection will have already
  5658   5548   ** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
  5659   5549   ** If this happens, then the specified callback is invoked immediately,
  5660         -** from within the call to sqlite3_unlock_notify().
         5550  +** from within the call to sqlite3_unlock_notify().)^
  5661   5551   **
  5662         -** If the blocked connection is attempting to obtain a write-lock on a
         5552  +** ^If the blocked connection is attempting to obtain a write-lock on a
  5663   5553   ** shared-cache table, and more than one other connection currently holds
  5664   5554   ** a read-lock on the same table, then SQLite arbitrarily selects one of 
  5665   5555   ** the other connections to use as the blocking connection.
  5666   5556   **
  5667         -** There may be at most one unlock-notify callback registered by a 
         5557  +** ^(There may be at most one unlock-notify callback registered by a 
  5668   5558   ** blocked connection. If sqlite3_unlock_notify() is called when the
  5669   5559   ** blocked connection already has a registered unlock-notify callback,
  5670         -** then the new callback replaces the old. If sqlite3_unlock_notify() is
         5560  +** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
  5671   5561   ** called with a NULL pointer as its second argument, then any existing
  5672         -** unlock-notify callback is cancelled. The blocked connections 
         5562  +** unlock-notify callback is cancelled. ^The blocked connections 
  5673   5563   ** unlock-notify callback may also be canceled by closing the blocked
  5674   5564   ** connection using [sqlite3_close()].
  5675   5565   **
  5676   5566   ** The unlock-notify callback is not reentrant. If an application invokes
  5677   5567   ** any sqlite3_xxx API functions from within an unlock-notify callback, a
  5678   5568   ** crash or deadlock may be the result.
  5679   5569   **
  5680         -** Unless deadlock is detected (see below), sqlite3_unlock_notify() always
         5570  +** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
  5681   5571   ** returns SQLITE_OK.
  5682   5572   **
  5683   5573   ** <b>Callback Invocation Details</b>
  5684   5574   **
  5685   5575   ** When an unlock-notify callback is registered, the application provides a 
  5686   5576   ** single void* pointer that is passed to the callback when it is invoked.
  5687   5577   ** However, the signature of the callback function allows SQLite to pass
  5688   5578   ** it an array of void* context pointers. The first argument passed to
  5689   5579   ** an unlock-notify callback is a pointer to an array of void* pointers,
  5690   5580   ** and the second is the number of entries in the array.
  5691   5581   **
  5692   5582   ** When a blocking connections transaction is concluded, there may be
  5693   5583   ** more than one blocked connection that has registered for an unlock-notify
  5694         -** callback. If two or more such blocked connections have specified the
         5584  +** callback. ^If two or more such blocked connections have specified the
  5695   5585   ** same callback function, then instead of invoking the callback function
  5696   5586   ** multiple times, it is invoked once with the set of void* context pointers
  5697   5587   ** specified by the blocked connections bundled together into an array.
  5698   5588   ** This gives the application an opportunity to prioritize any actions 
  5699   5589   ** related to the set of unblocked database connections.
  5700   5590   **
  5701   5591   ** <b>Deadlock Detection</b>
................................................................................
  5705   5595   ** action (a reasonable assumption), then using this API may cause the
  5706   5596   ** application to deadlock. For example, if connection X is waiting for
  5707   5597   ** connection Y's transaction to be concluded, and similarly connection
  5708   5598   ** Y is waiting on connection X's transaction, then neither connection
  5709   5599   ** will proceed and the system may remain deadlocked indefinitely.
  5710   5600   **
  5711   5601   ** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
  5712         -** detection. If a given call to sqlite3_unlock_notify() would put the
         5602  +** detection. ^If a given call to sqlite3_unlock_notify() would put the
  5713   5603   ** system in a deadlocked state, then SQLITE_LOCKED is returned and no
  5714   5604   ** unlock-notify callback is registered. The system is said to be in
  5715   5605   ** a deadlocked state if connection A has registered for an unlock-notify
  5716   5606   ** callback on the conclusion of connection B's transaction, and connection
  5717   5607   ** B has itself registered for an unlock-notify callback when connection
  5718         -** A's transaction is concluded. Indirect deadlock is also detected, so
         5608  +** A's transaction is concluded. ^Indirect deadlock is also detected, so
  5719   5609   ** the system is also considered to be deadlocked if connection B has
  5720   5610   ** registered for an unlock-notify callback on the conclusion of connection
  5721         -** C's transaction, where connection C is waiting on connection A. Any
         5611  +** C's transaction, where connection C is waiting on connection A. ^Any
  5722   5612   ** number of levels of indirection are allowed.
  5723   5613   **
  5724   5614   ** <b>The "DROP TABLE" Exception</b>
  5725   5615   **
  5726   5616   ** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost 
  5727   5617   ** always appropriate to call sqlite3_unlock_notify(). There is however,
  5728   5618   ** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
................................................................................
  5730   5620   ** that belong to the same connection. If there are, SQLITE_LOCKED is
  5731   5621   ** returned. In this case there is no "blocking connection", so invoking
  5732   5622   ** sqlite3_unlock_notify() results in the unlock-notify callback being
  5733   5623   ** invoked immediately. If the application then re-attempts the "DROP TABLE"
  5734   5624   ** or "DROP INDEX" query, an infinite loop might be the result.
  5735   5625   **
  5736   5626   ** One way around this problem is to check the extended error code returned
  5737         -** by an sqlite3_step() call. If there is a blocking connection, then the
         5627  +** by an sqlite3_step() call. ^(If there is a blocking connection, then the
  5738   5628   ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
  5739   5629   ** the special "DROP TABLE/INDEX" case, the extended error code is just 
  5740         -** SQLITE_LOCKED.
         5630  +** SQLITE_LOCKED.)^
  5741   5631   */
  5742   5632   SQLITE_API int sqlite3_unlock_notify(
  5743   5633     sqlite3 *pBlocked,                          /* Waiting connection */
  5744   5634     void (*xNotify)(void **apArg, int nArg),    /* Callback function to invoke */
  5745   5635     void *pNotifyArg                            /* Argument to pass to xNotify */
  5746   5636   );
  5747   5637   
  5748   5638   
  5749   5639   /*
  5750   5640   ** CAPI3REF: String Comparison
  5751   5641   ** EXPERIMENTAL
  5752   5642   **
  5753         -** The [sqlite3_strnicmp()] API allows applications and extensions to
         5643  +** ^The [sqlite3_strnicmp()] API allows applications and extensions to
  5754   5644   ** compare the contents of two buffers containing UTF-8 strings in a
  5755   5645   ** case-indendent fashion, using the same definition of case independence 
  5756   5646   ** that SQLite uses internally when comparing identifiers.
  5757   5647   */
  5758   5648   SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
  5759   5649   
  5760   5650   /*