Ignore:
Timestamp:
Feb 11, 2010, 11:19:06 PM (15 years ago)
Author:
Dmitry A. Kuminov
Message:

trunk: Merged in qt 4.6.1 sources.

Location:
trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk

  • trunk/src/3rdparty/sqlite/sqlite3.h

    r2 r561  
    1818** Some of the definitions that are in this file are marked as
    1919** "experimental".  Experimental interfaces are normally new
    20 ** features recently added to SQLite.  We do not anticipate changes 
    21 ** to experimental interfaces but reserve to make minor changes if
    22 ** experience from use "in the wild" suggest such changes are prudent.
     20** features recently added to SQLite.  We do not anticipate changes
     21** to experimental interfaces but reserve t
     22** experience from use "in the wild" suggest such changes are prudent.
    2323**
    2424** The official C-language API documentation for SQLite is derived
    … …  
    3030** the version number) and changes its name to "sqlite3.h" as
    3131** part of the build process.
    32 **
    33 ** @(#) $Id: sqlite.h.in,v 1.312 2008/05/12 12:39:56 drh Exp $
    3432*/
    3533#ifndef _SQLITE3_H_
    … …  
    5250#endif
    5351
    54 /*
    55 ** Make sure these symbols where not defined by some previous header
    56 ** file.
     52#ifndef SQLITE_API
     53# define SQLITE_API
     54#endif
     55
     56
     57/*
     58** These no-op macros are used in front of interfaces to mark those
     59** interfaces as either deprecated or experimental.  New applications
     60** should not use deprecated interfaces - they are support for backwards
     61** compatibility only.  Application writers should be aware that
     62** experimental interfaces are subject to change in point releases.
     63**
     64** These macros used to resolve to various kinds of compiler magic that
     65** would generate warning messages when they were used.  But that
     66** compiler magic ended up generating such a flurry of bug reports
     67** that we have taken it all out and gone back to using simple
     68** noop macros.
     69*/
     70#define SQLITE_DEPRECATED
     71#define SQLITE_EXPERIMENTAL
     72
     73/*
     74** Ensure these symbols were not defined by some previous header file.
    5775*/
    5876#ifdef SQLITE_VERSION
    … …  
    6482
    6583/*
    66 ** CAPI3REF: Compile-Time Library Version Numbers {F10010}
     84** CAPI3REF: Compile-Time Library Version Numbers {
    6785**
    6886** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in
    … …  
    7088** that header file is associated.
    7189**
    72 ** The "version" of SQLite is a string of the form "X.Y.Z".
    73 ** The phrase "alpha" or "beta" might be appended after the Z.
    74 ** The X value is major version number always 3 in SQLite3.
    75 ** The X value only changes when  backwards compatibility is
    76 ** broken and we intend to never break
    77 ** backwards compatibility.  The Y value is the minor version
    78 ** number and only changes when
     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
    7995** there are major feature enhancements that are forwards compatible
    80 ** but not backwards compatible.  The Z value is release number
    81 ** and is incremented with
    82 ** each release but resets back to 0 when Y is incremented.
    83 **
    84 ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
    85 **
    86 ** INVARIANTS:
    87 **
    88 ** {F10011} The SQLITE_VERSION #define in the sqlite3.h header file
    89 **          evaluates to a string literal that is the SQLite version
    90 **          with which the header file is associated.
    91 **
    92 ** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer
    93 **          with the value  (X*1000000 + Y*1000 + Z) where X, Y, and
    94 **          Z are the major version, minor version, and release number.
    95 */
    96 #define SQLITE_VERSION         "3.5.9"
    97 #define SQLITE_VERSION_NUMBER  3005009
    98 
    99 /*
    100 ** CAPI3REF: Run-Time Library Version Numbers {F10020}
     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>
     107**
     108** 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.
     115**
     116** See also: [sqlite3_libversion()],
     117** [sqlite3_libversion_number()], [sqlite3_sourceid()],
     118** [sqlite_version()] and [sqlite_source_id()].
     119**
     120** Requirements: [H10011] [H10014]
     121*/
     122#define SQLITE_VERSION        "3.6.19"
     123#define SQLITE_VERSION_NUMBER 3006019
     124#define SQLITE_SOURCE_ID      "2009-10-14 11:33:55 c1d499afc50d54b376945b4efb65c56c787a073d"
     125
     126/*
     127** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100>
    101128** KEYWORDS: sqlite3_version
    102129**
    103 ** These features provide the same information as the [SQLITE_VERSION]
    104 ** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated
    105 ** with the library instead of the header file.  Cautious programmers might
    106 ** include a check in their application to verify that
    107 ** sqlite3_libversion_number() always returns the value
    108 ** [SQLITE_VERSION_NUMBER].
     130** 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
     133** programmers might include assert() statements in their application to
     134** verify that values returned by these interfaces match the macros in
     135** the header, and thus insure that the application is
     136** compiled with matching library and header files.
     137**
     138** <blockquote><pre>
     139** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
     140** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
     141** assert( strcmp(sqlite3_libversion,SQLITE_VERSION)==0 );
     142** </pre></blockquote>
    109143**
    110144** The sqlite3_libversion() function returns the same information as is
    111145** in the sqlite3_version[] string constant.  The function is provided
    112146** for use in DLLs since DLL users usually do not have direct access to string
    113 ** constants within the DLL.
    114 **
    115 ** INVARIANTS:
    116 **
    117 ** {F10021} The [sqlite3_libversion_number()] interface returns an integer
    118 **          equal to [SQLITE_VERSION_NUMBER].
    119 **
    120 ** {F10022} The [sqlite3_version] string constant contains the text of the
    121 **          [SQLITE_VERSION] string.
    122 **
    123 ** {F10023} The [sqlite3_libversion()] function returns
    124 **          a pointer to the [sqlite3_version] string constant.
    125 */
    126 SQLITE_EXTERN const char sqlite3_version[];
    127 const char *sqlite3_libversion(void);
    128 int sqlite3_libversion_number(void);
    129 
    130 /*
    131 ** CAPI3REF: Test To See If The Library Is Threadsafe {F10100}
     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.
     150**
     151** See also: [sqlite_version()] and [sqlite_source_id()].
     152**
     153** Requirements: [H10021] [H10022] [H10023]
     154*/
     155SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
     156SQLITE_API const char *sqlite3_libversion(void);
     157SQLITE_API const char *sqlite3_sourceid(void);
     158SQLITE_API int sqlite3_libversion_number(void);
     159
     160/*
     161** CAPI3REF: Test To See If The Library Is Threadsafe {H10100} <S60100>
    132162**
    133163** SQLite can be compiled with or without mutexes.  When
    134 ** the SQLITE_THREADSAFE C preprocessor macro is true, mutexes
    135 ** are enabled and SQLite is threadsafe.  When that macro is false,
     164** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
     165** are enabled and SQLite is threadsafe.  When the
     166** [SQLITE_THREADSAFE] macro is 0,
    136167** the mutexes are omitted.  Without the mutexes, it is not safe
    137 ** to use SQLite from more than one thread.
    138 **
    139 ** There is a measurable performance penalty for enabling mutexes.
     168** to use SQLite from more than one thread.
     169**
     170** .
    140171** So if speed is of utmost importance, it makes sense to disable
    141172** the mutexes.  But for maximum safety, mutexes should be enabled.
    142173** The default behavior is for mutexes to be enabled.
    143174**
    144 ** This interface can be used by a program to make sure that the
     175** This interface can be used by a to make sure that the
    145176** version of SQLite that it is linking against was compiled with
    146 ** the desired setting of the SQLITE_THREADSAFE macro.
    147 **
    148 ** INVARIANTS:
    149 **
    150 ** {F10101} The [sqlite3_threadsafe()] function returns nonzero if
    151 **          SQLite was compiled with its mutexes enabled or zero
    152 **          if SQLite was compiled with mutexes disabled.
    153 */
    154 int sqlite3_threadsafe(void);
    155 
    156 /*
    157 ** CAPI3REF: Database Connection Handle {F12000}
     177** the desired setting of the [SQLITE_THREADSAFE] macro.
     178**
     179** This interface only reports on the compile-time mutex setting
     180** of the [SQLITE_THREADSAFE] flag.  If SQLite is compiled with
     181** SQLITE_THREADSAFE=1 then mutexes are enabled by default but
     182** can be fully or partially disabled using a call to [sqlite3_config()]
     183** 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.
     187**
     188** See the [threading mode] documentation for additional information.
     189**
     190** Requirements: [H10101] [H10102]
     191*/
     192SQLITE_API int sqlite3_threadsafe(void);
     193
     194/*
     195** CAPI3REF: Database Connection Handle {H12000} <S40200>
    158196** KEYWORDS: {database connection} {database connections}
    159197**
    160 ** Each open SQLite database is represented by pointer to an instance of the
    161 ** opaque structure named "sqlite3".  It is useful to think of an sqlite3
     198** Each open SQLite database is represented by
     199** opaque structure named "sqlite3".  It is useful to think of an sqlite3
    162200** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and
    163 ** [sqlite3_open_v2()] interfaces are its constructors
    164 ** and [sqlite3_close()] is its destructor.  There are many other interfaces
    165 ** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and
    166 ** [sqlite3_busy_timeout()] to name but three) that are methods on this
    167 ** object.
     201** [sqlite3_open_v2()] interfaces are its constructors
     202** s
     203** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
     204** [sqlite3_busy_timeout()] to name but three) that are methods on
     205** object.
    168206*/
    169207typedef struct sqlite3 sqlite3;
    170208
    171 
    172 /*
    173 ** CAPI3REF: 64-Bit Integer Types {F10200}
     209/*
     210** CAPI3REF: 64-Bit Integer Types {H10200} <S10110>
    174211** KEYWORDS: sqlite_int64 sqlite_uint64
    175212**
    … …  
    177214** SQLite includes typedefs for 64-bit signed and unsigned integers.
    178215**
    179 ** The sqlite3_int64 and sqlite3_uint64 are the preferred type
    180 ** definitions.  The sqlite_int64 and sqlite_uint64 types are
    181 ** supported for backwards compatibility only.
    182 **
    183 ** INVARIANTS:
    184 **
    185 ** {F10201} The [sqlite_int64] and [sqlite3_int64] types specify a
    186 **          64-bit signed integer.
    187 **
    188 ** {F10202} The [sqlite_uint64] and [sqlite3_uint64] types specify
    189 **          a 64-bit unsigned integer.
     216** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
     217** The sqlite_int64 and sqlite_uint64 types are supported for backwards
     218** compatibility only.
     219**
     220** Requirements: [H10201] [H10202]
    190221*/
    191222#ifdef SQLITE_INT64_TYPE
    … …  
    204235/*
    205236** If compiling for a processor that lacks floating point support,
    206 ** substitute integer for floating-point
     237** substitute integer for floating-point
    207238*/
    208239#ifdef SQLITE_OMIT_FLOATING_POINT
    … …  
    211242
    212243/*
    213 ** CAPI3REF: Closing A Database Connection {F12010}
    214 **
    215 ** This routine is the destructor for the [sqlite3] object. 
    216 **
    217 ** Applications should [sqlite3_finalize | finalize] all
    218 ** [prepared statements] and
    219 ** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs]
    220 ** associated with the [sqlite3] object prior
    221 ** to attempting to close the [sqlite3] object.
    222 **
    223 ** <todo>What happens to pending transactions?  Are they
    224 ** rolled back, or abandoned?</todo>
    225 **
    226 ** INVARIANTS:
    227 **
    228 ** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object
    229 **          allocated by a prior call to [sqlite3_open()],
    230 **          [sqlite3_open16()], or [sqlite3_open_v2()].
    231 **
    232 ** {F12012} The [sqlite3_close()] function releases all memory used by the
    233 **          connection and closes all open files.
    234 **
    235 ** {F12013} If the database connection contains
    236 **          [prepared statements] that have not been
    237 **          finalized by [sqlite3_finalize()], then [sqlite3_close()]
    238 **          returns [SQLITE_BUSY] and leaves the connection open.
    239 **
    240 ** {F12014} Giving sqlite3_close() a NULL pointer is a harmless no-op.
    241 **
    242 ** LIMITATIONS:
    243 **
    244 ** {U12015} The parameter to [sqlite3_close()] must be an [sqlite3] object
    245 **          pointer previously obtained from [sqlite3_open()] or the
    246 **          equivalent, or NULL.
    247 **
    248 ** {U12016} The parameter to [sqlite3_close()] must not have been previously
    249 **          closed.
    250 */
    251 int sqlite3_close(sqlite3 *);
     244** CAPI3REF: Closing A Database Connection {H12010} <S30100><S40200>
     245**
     246** This routine is the destructor for the [sqlite3] object.
     247**
     248** Applications should [sqlite3_finalize | finalize] all [prepared statements]
     249** and [sqlite3_blob_close | close] all [BLOB handles] associated with
     250** the [sqlite3] object prior to attempting to close the object.
     251** The [sqlite3_next_stmt()] interface can be used to locate all
     252** [prepared statements] associated with a [database connection] if desired.
     253** Typical code might look like this:
     254**
     255** <blockquote><pre>
     256** sqlite3_stmt *pStmt;
     257** while( (pStmt = sqlite3_next_stmt(db, 0))!=0 ){
     258** &nbsp;   sqlite3_finalize(pStmt);
     259** }
     260** </pre></blockquote>
     261**
     262** If [sqlite3_close()] is invoked while a transaction is open,
     263** the transaction is automatically rolled back.
     264**
     265** The C parameter to [sqlite3_close(C)] must be either a NULL
     266** pointer or an [sqlite3] object pointer obtained
     267** from [sqlite3_open()], [sqlite3_open16()], or
     268** [sqlite3_open_v2()], and not previously closed.
     269**
     270** Requirements:
     271** [H12011] [H12012] [H12013] [H12014] [H12015] [H12019]
     272*/
     273SQLITE_API int sqlite3_close(sqlite3 *);
    252274
    253275/*
    … …  
    259281
    260282/*
    261 ** CAPI3REF: One-Step Query Execution Interface {F12100}
    262 **
    263 ** The sqlite3_exec() interface is a convenient way of running
    264 ** one or more SQL statements without a lot of C code.  The
    265 ** SQL statements are passed in as the second parameter to
    266 ** sqlite3_exec().  The statements are evaluated one by one
    267 ** until either an error or an interrupt is encountered or
    268 ** until they are all done.  The 3rd parameter is an optional
    269 ** callback that is invoked once for each row of any query results
    270 ** produced by the SQL statements.  The 5th parameter tells where
     283** CAPI3REF: One-Step Query Execution Interface {H12100} <S10000>
     284**
     285** The sqlite3_exec() interface is a convenient way of running one or more
     286** SQL statements without having to write a lot of C code.  The UTF-8 encoded
     287** SQL statements are passed in as the second parameter to sqlite3_exec().
     288** The statements are evaluated one by one until either an error or
     289** an interrupt is encountered, or until they are all done.  The 3rd parameter
     290** is an optional callback that is invoked once for each row of any query
     291** results produced by the SQL statements.  The 5th parameter tells where
    271292** to write any error messages.
     293
     294
     295
     296
     297
     298
     299
     300
     301
     302
    272303**
    273304** The sqlite3_exec() interface is implemented in terms of
    274305** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
    275 ** The sqlite3_exec() routine does nothing that cannot be done
     306** The sqlite3_exec() routine does nothing that cannot be done
    276307** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
    277 ** The sqlite3_exec() is just a convenient wrapper.
    278 **
    279 ** INVARIANTS:
    280 **
    281 ** {F12101} The [sqlite3_exec()] interface evaluates zero or more UTF-8
    282 **          encoded, semicolon-separated, SQL statements in the
    283 **          zero-terminated string of its 2nd parameter within the
    284 **          context of the [sqlite3] object given in the 1st parameter.
    285 **
    286 ** {F12104} The return value of [sqlite3_exec()] is SQLITE_OK if all
    287 **          SQL statements run successfully.
    288 **
    289 ** {F12105} The return value of [sqlite3_exec()] is an appropriate
    290 **          non-zero error code if any SQL statement fails.
    291 **
    292 ** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()]
    293 **          return results and the 3rd parameter is not NULL, then
    294 **          the callback function specified by the 3rd parameter is
    295 **          invoked once for each row of result.
    296 **
    297 ** {F12110} If the callback returns a non-zero value then [sqlite3_exec()]
    298 **          will aborted the SQL statement it is currently evaluating,
    299 **          skip all subsequent SQL statements, and return [SQLITE_ABORT].
    300 **          <todo>What happens to *errmsg here?  Does the result code for
    301 **          sqlite3_errcode() get set?</todo>
    302 **
    303 ** {F12113} The [sqlite3_exec()] routine will pass its 4th parameter through
    304 **          as the 1st parameter of the callback.
    305 **
    306 ** {F12116} The [sqlite3_exec()] routine sets the 2nd parameter of its
    307 **          callback to be the number of columns in the current row of
    308 **          result.
    309 **
    310 ** {F12119} The [sqlite3_exec()] routine sets the 3rd parameter of its
    311 **          callback to be an array of pointers to strings holding the
    312 **          values for each column in the current result set row as
    313 **          obtained from [sqlite3_column_text()].
    314 **
    315 ** {F12122} The [sqlite3_exec()] routine sets the 4th parameter of its
    316 **          callback to be an array of pointers to strings holding the
    317 **          names of result columns as obtained from [sqlite3_column_name()].
    318 **
    319 ** {F12125} If the 3rd parameter to [sqlite3_exec()] is NULL then
    320 **          [sqlite3_exec()] never invokes a callback.  All query
    321 **          results are silently discarded.
    322 **
    323 ** {F12128} If an error occurs while parsing or evaluating any of the SQL
    324 **          statements handed to [sqlite3_exec()] then [sqlite3_exec()] will
    325 **          return an [error code] other than [SQLITE_OK].
    326 **
    327 ** {F12131} If an error occurs while parsing or evaluating any of the SQL
    328 **          handed to [sqlite3_exec()] and if the 5th parameter (errmsg)
    329 **          to [sqlite3_exec()] is not NULL, then an error message is
    330 **          allocated using the equivalent of [sqlite3_mprintf()] and
    331 **          *errmsg is made to point to that message.
    332 **
    333 ** {F12134} The [sqlite3_exec()] routine does not change the value of
    334 **          *errmsg if errmsg is NULL or if there are no errors.
    335 **
    336 ** {F12137} The [sqlite3_exec()] function sets the error code and message
    337 **          accessible via [sqlite3_errcode()], [sqlite3_errmsg()], and
    338 **          [sqlite3_errmsg16()].
    339 **
    340 ** LIMITATIONS:
    341 **
    342 ** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open
    343 **          [database connection].
    344 **
    345 ** {U12142} The database connection must not be closed while
    346 **          [sqlite3_exec()] is running.
    347 **
    348 ** {U12143} The calling function is should use [sqlite3_free()] to free
    349 **          the memory that *errmsg is left pointing at once the error
    350 **          message is no longer needed.
    351 **
    352 ** {U12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()]
    353 **          must remain unchanged while [sqlite3_exec()] is running.
    354 */
    355 int sqlite3_exec(
     308**
     309** The first parameter to [sqlite3_exec()] must be an valid and open
     310** [database connection].
     311**
     312** The database connection must not be closed while
     313** [sqlite3_exec()] is running.
     314**
     315** The calling function should use [sqlite3_free()] to free
     316** the memory that *errmsg is left pointing at once the error
     317** message is no longer needed.
     318**
     319** The SQL statement text in the 2nd parameter to [sqlite3_exec()]
     320** must remain unchanged while [sqlite3_exec()] is running.
     321**
     322** Requirements:
     323** [H12101] [H12102] [H12104] [H12105] [H12107] [H12110] [H12113] [H12116]
     324** [H12119] [H12122] [H12125] [H12131] [H12134] [H12137] [H12138]
     325*/
     326SQLITE_API int sqlite3_exec(
    356327  sqlite3*,                                  /* An open database */
    357   const char *sql,                           /* SQL to be evaluted */
     328  const char *sql,                           /* SQL to be evaluted */
    358329  int (*callback)(void*,int,char**,char**),  /* Callback function */
    359330  void *,                                    /* 1st argument to callback */
    … …  
    362333
    363334/*
    364 ** CAPI3REF: Result Codes {F10210}
     335** CAPI3REF: Result Codes {
    365336** KEYWORDS: SQLITE_OK {error code} {error codes}
     337
    366338**
    367339** Many SQLite functions return an integer result code from the set shown
    368340** here in order to indicates success or failure.
     341
     342
    369343**
    370344** See also: [SQLITE_IOERR_READ | extended result codes]
    … …  
    403377
    404378/*
    405 ** CAPI3REF: Extended Result Codes {F10220}
     379** CAPI3REF: Extended Result Codes {
    406380** KEYWORDS: {extended error code} {extended error codes}
    407 ** KEYWORDS: {extended result codes}
     381** KEYWORDS: {extended result codes}
    408382**
    409383** In its default configuration, SQLite API routines return one of 26 integer
    410 ** [SQLITE_OK | result codes].  However, experience has shown that
    411 ** many of these result codes are too course-grained.  They do not provide as
     384** [SQLITE_OK | result codes].  However, experience has shown that
     385** rse-grained.  They do not provide as
    412386** much information about problems as programmers might like.  In an effort to
    413387** address this, newer versions of SQLite (version 3.3.8 and later) include
    414388** support for additional result codes that provide more detailed information
    415389** about errors. The extended result codes are enabled or disabled
    416 ** for each database connection using the [sqlite3_extended_result_codes()]
    417 ** API.
    418 ** 
     390**
     391** API.
     392**
    419393** Some of the available extended result codes are listed here.
    420394** One may expect the number of extended result codes will be expand
    … …  
    424398** The SQLITE_OK result code will never be extended.  It will always
    425399** be exactly zero.
    426 **
    427 ** INVARIANTS:
    428 **
    429 ** {F10223} The symbolic name for an extended result code always contains
    430 **          a related primary result code as a prefix.
    431 **
    432 ** {F10224} Primary result code names contain a single "_" character.
    433 **
    434 ** {F10225} Extended result code names contain two or more "_" characters.
    435 **
    436 ** {F10226} The numeric value of an extended result code contains the
    437 **          numeric value of its corresponding primary result code in
    438 **          its least significant 8 bits.
    439 */
    440 #define SQLITE_IOERR_READ          (SQLITE_IOERR | (1<<8))
    441 #define SQLITE_IOERR_SHORT_READ    (SQLITE_IOERR | (2<<8))
    442 #define SQLITE_IOERR_WRITE         (SQLITE_IOERR | (3<<8))
    443 #define SQLITE_IOERR_FSYNC         (SQLITE_IOERR | (4<<8))
    444 #define SQLITE_IOERR_DIR_FSYNC     (SQLITE_IOERR | (5<<8))
    445 #define SQLITE_IOERR_TRUNCATE      (SQLITE_IOERR | (6<<8))
    446 #define SQLITE_IOERR_FSTAT         (SQLITE_IOERR | (7<<8))
    447 #define SQLITE_IOERR_UNLOCK        (SQLITE_IOERR | (8<<8))
    448 #define SQLITE_IOERR_RDLOCK        (SQLITE_IOERR | (9<<8))
    449 #define SQLITE_IOERR_DELETE        (SQLITE_IOERR | (10<<8))
    450 #define SQLITE_IOERR_BLOCKED       (SQLITE_IOERR | (11<<8))
    451 #define SQLITE_IOERR_NOMEM         (SQLITE_IOERR | (12<<8))
    452 
    453 /*
    454 ** CAPI3REF: Flags For File Open Operations {F10230}
     400*/
     401#define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
     402#define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
     403#define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
     404#define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
     405#define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
     406#define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
     407#define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
     408#define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))
     409#define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))
     410#define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))
     411#define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))
     412#define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))
     413#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
     414#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
     415#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
     416#define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
     417#define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
     418#define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED | (1<<8) )
     419
     420/*
     421** CAPI3REF: Flags For File Open Operations {H10230} <H11120> <H12700>
    455422**
    456423** These bit values are intended for use in the
    … …  
    459426** [sqlite3_vfs] object.
    460427*/
    461 #define SQLITE_OPEN_READONLY         0x00000001
    462 #define SQLITE_OPEN_READWRITE        0x00000002
    463 #define SQLITE_OPEN_CREATE           0x00000004
    464 #define SQLITE_OPEN_DELETEONCLOSE    0x00000008
    465 #define SQLITE_OPEN_EXCLUSIVE        0x00000010
    466 #define SQLITE_OPEN_MAIN_DB          0x00000100
    467 #define SQLITE_OPEN_TEMP_DB          0x00000200
    468 #define SQLITE_OPEN_TRANSIENT_DB     0x00000400
    469 #define SQLITE_OPEN_MAIN_JOURNAL     0x00000800
    470 #define SQLITE_OPEN_TEMP_JOURNAL     0x00001000
    471 #define SQLITE_OPEN_SUBJOURNAL       0x00002000
    472 #define SQLITE_OPEN_MASTER_JOURNAL   0x00004000
    473 
    474 /*
    475 ** CAPI3REF: Device Characteristics {F10240}
     428#define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */
     429#define SQLITE_OPEN_READWRITE        0x00000002  /* Ok for sqlite3_open_v2() */
     430#define SQLITE_OPEN_CREATE           0x00000004  /* Ok for sqlite3_open_v2() */
     431#define SQLITE_OPEN_DELETEONCLOSE    0x00000008  /* VFS only */
     432#define SQLITE_OPEN_EXCLUSIVE        0x00000010  /* VFS only */
     433#define SQLITE_OPEN_MAIN_DB          0x00000100  /* VFS only */
     434#define SQLITE_OPEN_TEMP_DB          0x00000200  /* VFS only */
     435#define SQLITE_OPEN_TRANSIENT_DB     0x00000400  /* VFS only */
     436#define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  /* VFS only */
     437#define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  /* VFS only */
     438#define SQLITE_OPEN_SUBJOURNAL       0x00002000  /* VFS only */
     439#define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */
     440#define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
     441#define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
     442#define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */
     443#define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */
     444
     445/*
     446** CAPI3REF: Device Characteristics {H10240} <H11120>
    476447**
    477448** The xDeviceCapabilities method of the [sqlite3_io_methods]
    … …  
    505476
    506477/*
    507 ** CAPI3REF: File Locking Levels {F10250}
     478** CAPI3REF: File Locking Levels {
    508479**
    509480** SQLite uses one of these integer values as the second
    … …  
    518489
    519490/*
    520 ** CAPI3REF: Synchronization Type Flags {F10260}
     491** CAPI3REF: Synchronization Type Flags {
    521492**
    522493** When SQLite invokes the xSync() method of an
    … …  
    526497** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
    527498** sync operation only needs to flush data to mass storage.  Inode
    528 ** information need not be flushed. The SQLITE_SYNC_NORMAL flag means
    529 ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means
    530 ** to use Mac OS-X style fullsync instead of fsync().
     499** information need not be flushed. If the lower four bits of the flag
     500** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
     501** If the lower four bits equal SQLITE_SYNC_FULL, that means
     502** to use Mac OS X style fullsync instead of fsync().
    531503*/
    532504#define SQLITE_SYNC_NORMAL        0x00002
    … …  
    534506#define SQLITE_SYNC_DATAONLY      0x00010
    535507
    536 
    537 /*
    538 ** CAPI3REF: OS Interface Open File Handle {F11110}
    539 **
    540 ** An [sqlite3_file] object represents an open file in the OS
    541 ** interface layer.  Individual OS interface implementations will
     508/*
     509** CAPI3REF: OS Interface Open File Handle {H11110} <S20110>
     510**
     511**
     512**
     513** implementations will
    542514** want to subclass this object by appending additional fields
    543515** for their own use.  The pMethods entry is a pointer to an
    … …  
    551523
    552524/*
    553 ** CAPI3REF: OS Interface File Virtual Methods Object {F11120}
    554 **
    555 ** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to
    556 ** an instance of this object.  This object defines the
    557 ** methods used to perform various operations against the open file.
     525** CAPI3REF: OS Interface File Virtual Methods Object {H11120} <S20110>
     526**
     527** Every file opened by the [sqlite3_vfs] xOpen method populates an
     528** [sqlite3_file] object (or, more commonly, a subclass of the
     529** [sqlite3_file] object) with a pointer to an instance of this object.
     530** This object defines the methods used to perform various operations
     531** against the open file represented by the [sqlite3_file] object.
     532**
     533** If the xOpen method sets the sqlite3_file.pMethods element
     534** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
     535** may be invoked even if the xOpen reported that it failed.  The
     536** only way to prevent a call to xClose following a failed xOpen
     537** is for the xOpen to set the sqlite3_file.pMethods element to NULL.
    558538**
    559539** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
    560540** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().
    561 *  The second choice is an
    562 ** OS-X style fullsync.  The SQLITE_SYNC_DATA flag may be ORed in to
    563 ** indicate that only the data of the file and not its inode needs to be
    564 ** synced.
    565 **
     541** The second choice is a Mac OS X style fullsync.  The [SQLITE_SYNC_DATAONLY]
     542** flag may be ORed in to indicate that only the data of the file
     543** and not its inode needs to be synced.
     544**
    566545** The integer values to xLock() and xUnlock() are one of
    567546** <ul>
    … …  
    572551** <li> [SQLITE_LOCK_EXCLUSIVE].
    573552** </ul>
    574 ** xLock() increases the lock. xUnlock() decreases the lock. 
    575 ** The xCheckReservedLock() method looks
    576 ** to see if any database connection, either in this
    577 ** process or in some other process, is holding an RESERVED,
     553** xLock() increases the lock. xUnlock() decreases the lock.
     554** The xCheckReservedLock() method checks whether any database connection,
     555** either in this process or in some other process, is holding a RESERVED,
    578556** PENDING, or EXCLUSIVE lock on the file.  It returns true
    579 ** if such a lock exists and false if not.
    580 ** 
     557** if such a lock exists and false .
     558**
    581559** The xFileControl() method is a generic interface that allows custom
    582560** VFS implementations to directly control an open file using the
    583 ** [sqlite3_file_control()] interface.  The second "op" argument
    584 ** is an integer opcode.   The third
    585 ** argument is a generic pointer which is intended to be a pointer
    586 ** to a structure that may contain arguments or space in which to
     561** [sqlite3_file_control()] interface.  The second "op" argument is an
     562** integer opcode.  The third argument is a generic pointer intended to
     563** point to a structure that may contain arguments or space in which to
    587564** write return values.  Potential uses for xFileControl() might be
    588565** functions to enable blocking locks with timeouts, to change the
    589566** locking strategy (for example to use dot-file locks), to inquire
    590567** about the status of a lock, or to break stale locks.  The SQLite
    591 ** core reserves opcodes less than 100 for its own use.
     568** core reserves
    592569** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
    593 ** Applications that define a custom xFileControl method should use opcodes 
     570** Applications that define a custom xFileControl method should use opcodes
    594571** greater than 100 to avoid conflicts.
    595572**
    … …  
    625602** information is written to disk in the same order as calls
    626603** to xWrite().
     604
     605
     606
     607
     608
     609
    627610*/
    628611typedef struct sqlite3_io_methods sqlite3_io_methods;
    … …  
    637620  int (*xLock)(sqlite3_file*, int);
    638621  int (*xUnlock)(sqlite3_file*, int);
    639   int (*xCheckReservedLock)(sqlite3_file*);
     622  int (*xCheckReservedLock)(sqlite3_file*);
    640623  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
    641624  int (*xSectorSize)(sqlite3_file*);
    … …  
    645628
    646629/*
    647 ** CAPI3REF: Standard File Control Opcodes {F11310}
     630** CAPI3REF: Standard File Control Opcodes {
    648631**
    649632** These integer constants are opcodes for the xFileControl method
    650 ** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()]
     633** of the [sqlite3_io_methods] object and the [sqlite3_file_control()]
    651634** interface.
    652635**
    … …  
    660643*/
    661644#define SQLITE_FCNTL_LOCKSTATE        1
    662 
    663 /*
    664 ** CAPI3REF: Mutex Handle {F17110}
     645#define SQLITE_GET_LOCKPROXYFILE      2
     646#define SQLITE_SET_LOCKPROXYFILE      3
     647#define SQLITE_LAST_ERRNO             4
     648
     649/*
     650** CAPI3REF: Mutex Handle {H17110} <S20130>
    665651**
    666652** The mutex module within SQLite defines [sqlite3_mutex] to be an
    … …  
    674660
    675661/*
    676 ** CAPI3REF: OS Interface Object {F11140}
    677 **
    678 ** An instance of this object defines the interface between the
    679 ** SQLite core and the underlying operating system.  The "vfs"
     662** CAPI3REF: OS Interface Object {
     663**
     664** An instance of th
     665** SQLite core and the underlying operating system.  The "vfs"
    680666** in the name of the object stands for "virtual file system".
    681667**
    682 ** The iVersion field is initially 1 but may be larger for future
    683 ** versions of SQLite.  Additional fields may be appended to this
    684 ** object when the iVersion value is increased.
     668** The value of the iVersion field is initially 1 but may be larger in
     669** future versions of SQLite.  Additional fields may be appended to this
     670** object when the iVersion value is increased.  Note that the structure
     671** of the sqlite3_vfs object changes in the transaction between
     672** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
     673** modified.
    685674**
    686675** The szOsFile field is the size of the subclassed [sqlite3_file]
    … …  
    692681** and [sqlite3_vfs_unregister()] interfaces manage this list
    693682** in a thread-safe way.  The [sqlite3_vfs_find()] interface
    694 ** searches the list.
    695 **
    696 ** The pNext field is the only field in the sqlite3_vfs
     683** searches the list.  Neither the application code nor the VFS
     684** implementation should use the pNext pointer.
     685**
     686** The pNext field is the only field in the sqlite3_vfs
    697687** structure that SQLite will ever modify.  SQLite will only access
    698688** or modify this field while holding a particular static mutex.
    … …  
    703693** be unique across all VFS modules.
    704694**
    705 ** {F11141} SQLite will guarantee that the zFilename string passed to
    706 ** xOpen() is a full pathname as generated by xFullPathname() and
    707 ** that the string will be valid and unchanged until xClose() is
    708 ** called.  {END} So the [sqlite3_file] can store a pointer to the
     695** SQLite will guarantee that the zFilename parameter to xOpen
     696** is either a NULL pointer or string obtained
     697** from xFullPathname().  SQLite further guarantees that
     698** the string will be valid and unchanged until xClose() is
     699** called. Because of the previous sentence,
     700** the [sqlite3_file] can safely store a pointer to the
    709701** filename if it needs to remember the filename for some reason.
    710 **
    711 ** {F11142} The flags argument to xOpen() includes all bits set in
     702** If the zFilename parameter is xOpen is a NULL pointer then xOpen
     703** must invent its own temporary name for the file.  Whenever the
     704** xFilename parameter is NULL it will also be the case that the
     705** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
     706**
     707** The flags argument to xOpen() includes all bits set in
    712708** the flags argument to [sqlite3_open_v2()].  Or if [sqlite3_open()]
    713709** or [sqlite3_open16()] is used, then flags includes at least
    714 ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END}
     710** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
    715711** If xOpen() opens a file read-only then it sets *pOutFlags to
    716 ** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be
    717 ** set.
    718 **
    719 ** {F11143} SQLite will also add one of the following flags to the xOpen()
     712** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be set.
     713**
     714** SQLite will also add one of the following flags to the xOpen()
    720715** call, depending on the object being opened:
    721 ** 
     716**
    722717** <ul>
    723718** <li>  [SQLITE_OPEN_MAIN_DB]
    … …  
    728723** <li>  [SQLITE_OPEN_SUBJOURNAL]
    729724** <li>  [SQLITE_OPEN_MASTER_JOURNAL]
    730 ** </ul> {END}
     725** </ul>
    731726**
    732727** The file I/O implementation can use the object type flags to
    733 ** changes the way it deals with files.  For example, an application
     728** change the way it deals with files.  For example, an application
    734729** that does not care about crash recovery or rollback might make
    735730** the open of a journal file a no-op.  Writes to this journal would
    736 ** also be no-ops, and any attempt to read the journal would return 
    737 ** SQLITE_IOERR.  Or the implementation might recognize that a database 
    738 ** file will be doing page-aligned sector reads and writes in a random 
     731** also be no-ops, and any attempt to read the journal would return
     732** SQLITE_IOERR.  Or the implementation might recognize that a database
     733** file will be doing page-aligned sector reads and writes in a random
    739734** order and set up its I/O subsystem accordingly.
    740 **
    741 ** SQLite might also add one of the following flags to the xOpen
    742 ** method:
    743 **
     735**
     736** SQLite might also add one of the following flags to the xOpen method:
     737**
    744738** <ul>
    745739** <li> [SQLITE_OPEN_DELETEONCLOSE]
    746740** <li> [SQLITE_OPEN_EXCLUSIVE]
    747741** </ul>
    748 **
    749 ** {F11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
    750 ** deleted when it is closed.  {F11146} The [SQLITE_OPEN_DELETEONCLOSE]
    751 ** will be set for TEMP  databases, journals and for subjournals.
    752 ** {F11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
    753 ** for exclusive access.  This flag is set for all files except
    754 ** for the main database file. {END}
    755 **
    756 ** {F11148} At least szOsFile bytes of memory are allocated by SQLite
    757 ** to hold the  [sqlite3_file] structure passed as the third
    758 ** argument to xOpen.  {END}  The xOpen method does not have to
    759 ** allocate the structure; it should just fill it in.
    760 **
    761 ** {F11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
    762 ** to test for the existance of a file,
    763 ** or [SQLITE_ACCESS_READWRITE] to test to see
    764 ** if a file is readable and writable, or [SQLITE_ACCESS_READ]
    765 ** to test to see if a file is at least readable.  {END} The file can be a
     742**
     743** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
     744** deleted when it is closed.  The [SQLITE_OPEN_DELETEONCLOSE]
     745** will be set for TEMP  databases, journals and for subjournals.
     746**
     747** The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
     748** with the [SQLITE_OPEN_CREATE] flag, which are both directly
     749** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
     750** API.  The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
     751** SQLITE_OPEN_CREATE, is used to indicate that file should always
     752** be created, and that it is an error if it already exists.
     753** It is <i>not</i> used to indicate the file should be opened
     754** for exclusive access.
     755**
     756** At least szOsFile bytes of memory are allocated by SQLite
     757** to hold the  [sqlite3_file] structure passed as the third
     758** argument to xOpen.  The xOpen method does not have to
     759** allocate the structure; it should just fill it in.  Note that
     760** the xOpen method must set the sqlite3_file.pMethods to either
     761** a valid [sqlite3_io_methods] object or to NULL.  xOpen must do
     762** this even if the open fails.  SQLite expects that the sqlite3_file.pMethods
     763** element will be valid after xOpen returns regardless of the success
     764** or failure of the xOpen call.
     765**
     766** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
     767** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
     768** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
     769** to test whether a file is at least readable.   The file can be a
    766770** directory.
    767 **
    768 ** {F11150} SQLite will always allocate at least mxPathname+1 bytes for
    769 ** the output buffers for xGetTempname and xFullPathname. {F11151} The exact
    770 ** size of the output buffer is also passed as a parameter to both
    771 ** methods. {END} If the output buffer is not large enough, SQLITE_CANTOPEN
    772 ** should be returned. As this is handled as a fatal error by SQLite,
    773 ** vfs implementations should endeavor to prevent this by setting
    774 ** mxPathname to a sufficiently large value.
    775 **
     771**
     772** SQLite will always allocate at least mxPathname+1 bytes for the
     773** output buffer xFullPathname.  The exact size of the output buffer
     774** is also passed as a parameter to both  methods. If the output buffer
     775** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
     776** handled as a fatal error by SQLite, vfs implementations should endeavor
     777** to prevent this by setting mxPathname to a sufficiently large value.
     778**
    776779** The xRandomness(), xSleep(), and xCurrentTime() interfaces
    777780** are not strictly a part of the filesystem, but they are
    … …  
    779782** The xRandomness() function attempts to return nBytes bytes
    780783** of good-quality randomness into zOut.  The return value is
    781 ** the actual number of bytes of randomness obtained.  The
    782 ** xSleep() method causes the calling thread to sleep for at
     784** the actual number of bytes of randomness obtained.
     785** xSleep() method causes the calling thread to sleep for at
    783786** least the number of microseconds given.  The xCurrentTime()
    784 ** method returns a Julian Day Number for the current date and
    785 ** time.
     787** method returns a Julian Day Number for the current date and
     788**
    786789*/
    787790typedef struct sqlite3_vfs sqlite3_vfs;
    … …  
    796799               int flags, int *pOutFlags);
    797800  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
    798   int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
    799   int (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut);
     801  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
    800802  int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
    801803  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
    802804  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
    803   void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
     805  void );
    804806  void (*xDlClose)(sqlite3_vfs*, void*);
    805807  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
    806808  int (*xSleep)(sqlite3_vfs*, int microseconds);
    807809  int (*xCurrentTime)(sqlite3_vfs*, double*);
     810
    808811  /* New fields may be appended in figure versions.  The iVersion
    809812  ** value will increment whenever this happens. */
    … …  
    811814
    812815/*
    813 ** CAPI3REF: Flags for the xAccess VFS method {F11190}
    814 **
    815 ** {F11191} These integer constants can be used as the third parameter to
     816** CAPI3REF: Flags for the xAccess VFS method {
     817**
     818** These integer constants can be used as the third parameter to
    816819** the xAccess method of an [sqlite3_vfs] object. {END}  They determine
    817 ** what kind of permissions the xAccess method is
    818 ** looking for.  {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method
    819 ** simply checks to see if the file exists. {F11193} With
    820 ** SQLITE_ACCESS_READWRITE, the xAccess method checks to see
    821 ** if the file is both readable and writable.  {F11194} With
    822 ** SQLITE_ACCESS_READ the xAccess method
    823 ** checks to see if the file is readable.
     820** what kind of permissions the xAccess method is
     821** With SQLITE_ACCESS_EXISTS, the xAccess method
     822** simply checks
     823**
     824**
     825** the xAccess method
     826** checks the file is readable.
    824827*/
    825828#define SQLITE_ACCESS_EXISTS    0
    … …  
    828831
    829832/*
    830 ** CAPI3REF: Enable Or Disable Extended Result Codes {F12200}
     833** CAPI3REF: Initialize The SQLite Library {H10130} <S20000><S30100>
     834**
     835** The sqlite3_initialize() routine initializes the
     836** SQLite library.  The sqlite3_shutdown() routine
     837** deallocates any resources that were allocated by sqlite3_initialize().
     838**
     839** A call to sqlite3_initialize() is an "effective" call if it is
     840** the first time sqlite3_initialize() is invoked during the lifetime of
     841** the process, or if it is the first time sqlite3_initialize() is invoked
     842** following a call to sqlite3_shutdown().  Only an effective call
     843** of sqlite3_initialize() does any initialization.  All other calls
     844** are harmless no-ops.
     845**
     846** A call to sqlite3_shutdown() is an "effective" call if it is the first
     847** call to sqlite3_shutdown() since the last sqlite3_initialize().  Only
     848** an effective call to sqlite3_shutdown() does any deinitialization.
     849** All other calls to sqlite3_shutdown() are harmless no-ops.
     850**
     851** Among other things, sqlite3_initialize() shall invoke
     852** sqlite3_os_init().  Similarly, sqlite3_shutdown()
     853** shall invoke sqlite3_os_end().
     854**
     855** The sqlite3_initialize() routine returns [SQLITE_OK] on success.
     856** If for some reason, sqlite3_initialize() is unable to initialize
     857** the library (perhaps it is unable to allocate a needed resource such
     858** as a mutex) it returns an [error code] other than [SQLITE_OK].
     859**
     860** The sqlite3_initialize() routine is called internally by many other
     861** SQLite interfaces so that an application usually does not need to
     862** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]
     863** calls sqlite3_initialize() so the SQLite library will be automatically
     864** initialized when [sqlite3_open()] is called if it has not be initialized
     865** already.  However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
     866** compile-time option, then the automatic calls to sqlite3_initialize()
     867** are omitted and the application must call sqlite3_initialize() directly
     868** prior to using any other SQLite interface.  For maximum portability,
     869** it is recommended that applications always invoke sqlite3_initialize()
     870** directly prior to using any other SQLite interface.  Future releases
     871** of SQLite may require this.  In other words, the behavior exhibited
     872** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
     873** default behavior in some future release of SQLite.
     874**
     875** The sqlite3_os_init() routine does operating-system specific
     876** initialization of the SQLite library.  The sqlite3_os_end()
     877** routine undoes the effect of sqlite3_os_init().  Typical tasks
     878** performed by these routines include allocation or deallocation
     879** of static resources, initialization of global variables,
     880** setting up a default [sqlite3_vfs] module, or setting up
     881** a default configuration using [sqlite3_config()].
     882**
     883** The application should never invoke either sqlite3_os_init()
     884** or sqlite3_os_end() directly.  The application should only invoke
     885** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()
     886** interface is called automatically by sqlite3_initialize() and
     887** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate
     888** implementations for sqlite3_os_init() and sqlite3_os_end()
     889** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
     890** When [custom builds | built for other platforms]
     891** (using the [SQLITE_OS_OTHER=1] compile-time
     892** option) the application must supply a suitable implementation for
     893** sqlite3_os_init() and sqlite3_os_end().  An application-supplied
     894** implementation of sqlite3_os_init() or sqlite3_os_end()
     895** must return [SQLITE_OK] on success and some other [error code] upon
     896** failure.
     897*/
     898SQLITE_API int sqlite3_initialize(void);
     899SQLITE_API int sqlite3_shutdown(void);
     900SQLITE_API int sqlite3_os_init(void);
     901SQLITE_API int sqlite3_os_end(void);
     902
     903/*
     904** CAPI3REF: Configuring The SQLite Library {H14100} <S20000><S30200>
     905** EXPERIMENTAL
     906**
     907** The sqlite3_config() interface is used to make global configuration
     908** changes to SQLite in order to tune SQLite to the specific needs of
     909** the application.  The default configuration is recommended for most
     910** applications and so this routine is usually not necessary.  It is
     911** provided to support rare applications with unusual needs.
     912**
     913** The sqlite3_config() interface is not threadsafe.  The application
     914** must insure that no other SQLite interfaces are invoked by other
     915** threads while sqlite3_config() is running.  Furthermore, sqlite3_config()
     916** may only be invoked prior to library initialization using
     917** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
     918** Note, however, that sqlite3_config() can be called as part of the
     919** implementation of an application-defined [sqlite3_os_init()].
     920**
     921** The first argument to sqlite3_config() is an integer
     922** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines
     923** what property of SQLite is to be configured.  Subsequent arguments
     924** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option]
     925** in the first argument.
     926**
     927** When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
     928** If the option is unknown or SQLite is unable to set the option
     929** then this routine returns a non-zero [error code].
     930**
     931** Requirements:
     932** [H14103] [H14106] [H14120] [H14123] [H14126] [H14129] [H14132] [H14135]
     933** [H14138] [H14141] [H14144] [H14147] [H14150] [H14153] [H14156] [H14159]
     934** [H14162] [H14165] [H14168]
     935*/
     936SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_config(int, ...);
     937
     938/*
     939** CAPI3REF: Configure database connections  {H14200} <S20000>
     940** EXPERIMENTAL
     941**
     942** The sqlite3_db_config() interface is used to make configuration
     943** changes to a [database connection].  The interface is similar to
     944** [sqlite3_config()] except that the changes apply to a single
     945** [database connection] (specified in the first argument).  The
     946** sqlite3_db_config() interface can only be used immediately after
     947** the database connection is created using [sqlite3_open()],
     948** [sqlite3_open16()], or [sqlite3_open_v2()]. 
     949**
     950** The second argument to sqlite3_db_config(D,V,...)  is the
     951** configuration verb - an integer code that indicates what
     952** aspect of the [database connection] is being configured.
     953** The only choice for this value is [SQLITE_DBCONFIG_LOOKASIDE].
     954** New verbs are likely to be added in future releases of SQLite.
     955** Additional arguments depend on the verb.
     956**
     957** Requirements:
     958** [H14203] [H14206] [H14209] [H14212] [H14215]
     959*/
     960SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
     961
     962/*
     963** CAPI3REF: Memory Allocation Routines {H10155} <S20120>
     964** EXPERIMENTAL
     965**
     966** An instance of this object defines the interface between SQLite
     967** and low-level memory allocation routines.
     968**
     969** This object is used in only one place in the SQLite interface.
     970** A pointer to an instance of this object is the argument to
     971** [sqlite3_config()] when the configuration option is
     972** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC]. 
     973** By creating an instance of this object
     974** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
     975** during configuration, an application can specify an alternative
     976** memory allocation subsystem for SQLite to use for all of its
     977** dynamic memory needs.
     978**
     979** Note that SQLite comes with several [built-in memory allocators]
     980** that are perfectly adequate for the overwhelming majority of applications
     981** and that this object is only useful to a tiny minority of applications
     982** with specialized memory allocation requirements.  This object is
     983** also used during testing of SQLite in order to specify an alternative
     984** memory allocator that simulates memory out-of-memory conditions in
     985** order to verify that SQLite recovers gracefully from such
     986** conditions.
     987**
     988** The xMalloc and xFree methods must work like the
     989** malloc() and free() functions from the standard C library.
     990** The xRealloc method must work like realloc() from the standard C library
     991** with the exception that if the second argument to xRealloc is zero,
     992** xRealloc must be a no-op - it must not perform any allocation or
     993** deallocation.  SQLite guaranteeds that the second argument to
     994** xRealloc is always a value returned by a prior call to xRoundup.
     995** And so in cases where xRoundup always returns a positive number,
     996** xRealloc can perform exactly as the standard library realloc() and
     997** still be in compliance with this specification.
     998**
     999** xSize should return the allocated size of a memory allocation
     1000** previously obtained from xMalloc or xRealloc.  The allocated size
     1001** is always at least as big as the requested size but may be larger.
     1002**
     1003** The xRoundup method returns what would be the allocated size of
     1004** a memory allocation given a particular requested size.  Most memory
     1005** allocators round up memory allocations at least to the next multiple
     1006** of 8.  Some allocators round up to a larger multiple or to a power of 2.
     1007** Every memory allocation request coming in through [sqlite3_malloc()]
     1008** or [sqlite3_realloc()] first calls xRoundup.  If xRoundup returns 0,
     1009** that causes the corresponding memory allocation to fail.
     1010**
     1011** The xInit method initializes the memory allocator.  (For example,
     1012** it might allocate any require mutexes or initialize internal data
     1013** structures.  The xShutdown method is invoked (indirectly) by
     1014** [sqlite3_shutdown()] and should deallocate any resources acquired
     1015** by xInit.  The pAppData pointer is used as the only parameter to
     1016** xInit and xShutdown.
     1017**
     1018** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
     1019** the xInit method, so the xInit method need not be threadsafe.  The
     1020** xShutdown method is only called from [sqlite3_shutdown()] so it does
     1021** not need to be threadsafe either.  For all other methods, SQLite
     1022** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
     1023** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
     1024** it is by default) and so the methods are automatically serialized.
     1025** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
     1026** methods must be threadsafe or else make their own arrangements for
     1027** serialization.
     1028**
     1029** SQLite will never invoke xInit() more than once without an intervening
     1030** call to xShutdown().
     1031*/
     1032typedef struct sqlite3_mem_methods sqlite3_mem_methods;
     1033struct sqlite3_mem_methods {
     1034  void *(*xMalloc)(int);         /* Memory allocation function */
     1035  void (*xFree)(void*);          /* Free a prior allocation */
     1036  void *(*xRealloc)(void*,int);  /* Resize an allocation */
     1037  int (*xSize)(void*);           /* Return the size of an allocation */
     1038  int (*xRoundup)(int);          /* Round up request size to allocation size */
     1039  int (*xInit)(void*);           /* Initialize the memory allocator */
     1040  void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
     1041  void *pAppData;                /* Argument to xInit() and xShutdown() */
     1042};
     1043
     1044/*
     1045** CAPI3REF: Configuration Options {H10160} <S20000>
     1046** EXPERIMENTAL
     1047**
     1048** These constants are the available integer configuration options that
     1049** can be passed as the first argument to the [sqlite3_config()] interface.
     1050**
     1051** New configuration options may be added in future releases of SQLite.
     1052** Existing configuration options might be discontinued.  Applications
     1053** should check the return code from [sqlite3_config()] to make sure that
     1054** the call worked.  The [sqlite3_config()] interface will return a
     1055** non-zero [error code] if a discontinued or unsupported configuration option
     1056** is invoked.
     1057**
     1058** <dl>
     1059** <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
     1060** <dd>There are no arguments to this option.  This option disables
     1061** all mutexing and puts SQLite into a mode where it can only be used
     1062** by a single thread.</dd>
     1063**
     1064** <dt>SQLITE_CONFIG_MULTITHREAD</dt>
     1065** <dd>There are no arguments to this option.  This option disables
     1066** mutexing on [database connection] and [prepared statement] objects.
     1067** The application is responsible for serializing access to
     1068** [database connections] and [prepared statements].  But other mutexes
     1069** are enabled so that SQLite will be safe to use in a multi-threaded
     1070** environment as long as no two threads attempt to use the same
     1071** [database connection] at the same time.  See the [threading mode]
     1072** documentation for additional information.</dd>
     1073**
     1074** <dt>SQLITE_CONFIG_SERIALIZED</dt>
     1075** <dd>There are no arguments to this option.  This option enables
     1076** all mutexes including the recursive
     1077** mutexes on [database connection] and [prepared statement] objects.
     1078** In this mode (which is the default when SQLite is compiled with
     1079** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
     1080** to [database connections] and [prepared statements] so that the
     1081** application is free to use the same [database connection] or the
     1082** same [prepared statement] in different threads at the same time.
     1083** See the [threading mode] documentation for additional information.</dd>
     1084**
     1085** <dt>SQLITE_CONFIG_MALLOC</dt>
     1086** <dd>This option takes a single argument which is a pointer to an
     1087** instance of the [sqlite3_mem_methods] structure.  The argument specifies
     1088** alternative low-level memory allocation routines to be used in place of
     1089** the memory allocation routines built into SQLite.</dd>
     1090**
     1091** <dt>SQLITE_CONFIG_GETMALLOC</dt>
     1092** <dd>This option takes a single argument which is a pointer to an
     1093** instance of the [sqlite3_mem_methods] structure.  The [sqlite3_mem_methods]
     1094** structure is filled with the currently defined memory allocation routines.
     1095** This option can be used to overload the default memory allocation
     1096** routines with a wrapper that simulations memory allocation failure or
     1097** tracks memory usage, for example.</dd>
     1098**
     1099** <dt>SQLITE_CONFIG_MEMSTATUS</dt>
     1100** <dd>This option takes single argument of type int, interpreted as a
     1101** boolean, which enables or disables the collection of memory allocation
     1102** statistics. When disabled, the following SQLite interfaces become
     1103** non-operational:
     1104**   <ul>
     1105**   <li> [sqlite3_memory_used()]
     1106**   <li> [sqlite3_memory_highwater()]
     1107**   <li> [sqlite3_soft_heap_limit()]
     1108**   <li> [sqlite3_status()]
     1109**   </ul>
     1110** </dd>
     1111**
     1112** <dt>SQLITE_CONFIG_SCRATCH</dt>
     1113** <dd>This option specifies a static memory buffer that SQLite can use for
     1114** scratch memory.  There are three arguments:  A pointer an 8-byte
     1115** aligned memory buffer from which the scrach allocations will be
     1116** drawn, the size of each scratch allocation (sz),
     1117** and the maximum number of scratch allocations (N).  The sz
     1118** argument must be a multiple of 16. The sz parameter should be a few bytes
     1119** larger than the actual scratch space required due to internal overhead.
     1120** The first argument should pointer to an 8-byte aligned buffer
     1121** of at least sz*N bytes of memory.
     1122** SQLite will use no more than one scratch buffer at once per thread, so
     1123** N should be set to the expected maximum number of threads.  The sz
     1124** parameter should be 6 times the size of the largest database page size.
     1125** Scratch buffers are used as part of the btree balance operation.  If
     1126** The btree balancer needs additional memory beyond what is provided by
     1127** scratch buffers or if no scratch buffer space is specified, then SQLite
     1128** goes to [sqlite3_malloc()] to obtain the memory it needs.</dd>
     1129**
     1130** <dt>SQLITE_CONFIG_PAGECACHE</dt>
     1131** <dd>This option specifies a static memory buffer that SQLite can use for
     1132** the database page cache with the default page cache implemenation. 
     1133** This configuration should not be used if an application-define page
     1134** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option.
     1135** There are three arguments to this option: A pointer to 8-byte aligned
     1136** memory, the size of each page buffer (sz), and the number of pages (N).
     1137** The sz argument should be the size of the largest database page
     1138** (a power of two between 512 and 32768) plus a little extra for each
     1139** page header.  The page header size is 20 to 40 bytes depending on
     1140** the host architecture.  It is harmless, apart from the wasted memory,
     1141** to make sz a little too large.  The first
     1142** argument should point to an allocation of at least sz*N bytes of memory.
     1143** SQLite will use the memory provided by the first argument to satisfy its
     1144** memory needs for the first N pages that it adds to cache.  If additional
     1145** page cache memory is needed beyond what is provided by this option, then
     1146** SQLite goes to [sqlite3_malloc()] for the additional storage space.
     1147** The implementation might use one or more of the N buffers to hold
     1148** memory accounting information. The pointer in the first argument must
     1149** be aligned to an 8-byte boundary or subsequent behavior of SQLite
     1150** will be undefined.</dd>
     1151**
     1152** <dt>SQLITE_CONFIG_HEAP</dt>
     1153** <dd>This option specifies a static memory buffer that SQLite will use
     1154** for all of its dynamic memory allocation needs beyond those provided
     1155** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
     1156** There are three arguments: An 8-byte aligned pointer to the memory,
     1157** the number of bytes in the memory buffer, and the minimum allocation size.
     1158** If the first pointer (the memory pointer) is NULL, then SQLite reverts
     1159** to using its default memory allocator (the system malloc() implementation),
     1160** undoing any prior invocation of [SQLITE_CONFIG_MALLOC].  If the
     1161** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
     1162** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory
     1163** allocator is engaged to handle all of SQLites memory allocation needs.
     1164** The first pointer (the memory pointer) must be aligned to an 8-byte
     1165** boundary or subsequent behavior of SQLite will be undefined.</dd>
     1166**
     1167** <dt>SQLITE_CONFIG_MUTEX</dt>
     1168** <dd>This option takes a single argument which is a pointer to an
     1169** instance of the [sqlite3_mutex_methods] structure.  The argument specifies
     1170** alternative low-level mutex routines to be used in place
     1171** the mutex routines built into SQLite.</dd>
     1172**
     1173** <dt>SQLITE_CONFIG_GETMUTEX</dt>
     1174** <dd>This option takes a single argument which is a pointer to an
     1175** instance of the [sqlite3_mutex_methods] structure.  The
     1176** [sqlite3_mutex_methods]
     1177** structure is filled with the currently defined mutex routines.
     1178** This option can be used to overload the default mutex allocation
     1179** routines with a wrapper used to track mutex usage for performance
     1180** profiling or testing, for example.</dd>
     1181**
     1182** <dt>SQLITE_CONFIG_LOOKASIDE</dt>
     1183** <dd>This option takes two arguments that determine the default
     1184** memory allocation lookaside optimization.  The first argument is the
     1185** size of each lookaside buffer slot and the second is the number of
     1186** slots allocated to each database connection.  This option sets the
     1187** <i>default</i> lookaside size.  The [SQLITE_DBCONFIG_LOOKASIDE]
     1188** verb to [sqlite3_db_config()] can be used to change the lookaside
     1189** configuration on individual connections.</dd>
     1190**
     1191** <dt>SQLITE_CONFIG_PCACHE</dt>
     1192** <dd>This option takes a single argument which is a pointer to
     1193** an [sqlite3_pcache_methods] object.  This object specifies the interface
     1194** to a custom page cache implementation.  SQLite makes a copy of the
     1195** object and uses it for page cache memory allocations.</dd>
     1196**
     1197** <dt>SQLITE_CONFIG_GETPCACHE</dt>
     1198** <dd>This option takes a single argument which is a pointer to an
     1199** [sqlite3_pcache_methods] object.  SQLite copies of the current
     1200** page cache implementation into that object.</dd>
     1201**
     1202** </dl>
     1203*/
     1204#define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
     1205#define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
     1206#define SQLITE_CONFIG_SERIALIZED    3  /* nil */
     1207#define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
     1208#define SQLITE_CONFIG_GETMALLOC     5  /* sqlite3_mem_methods* */
     1209#define SQLITE_CONFIG_SCRATCH       6  /* void*, int sz, int N */
     1210#define SQLITE_CONFIG_PAGECACHE     7  /* void*, int sz, int N */
     1211#define SQLITE_CONFIG_HEAP          8  /* void*, int nByte, int min */
     1212#define SQLITE_CONFIG_MEMSTATUS     9  /* boolean */
     1213#define SQLITE_CONFIG_MUTEX        10  /* sqlite3_mutex_methods* */
     1214#define SQLITE_CONFIG_GETMUTEX     11  /* sqlite3_mutex_methods* */
     1215/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
     1216#define SQLITE_CONFIG_LOOKASIDE    13  /* int int */
     1217#define SQLITE_CONFIG_PCACHE       14  /* sqlite3_pcache_methods* */
     1218#define SQLITE_CONFIG_GETPCACHE    15  /* sqlite3_pcache_methods* */
     1219
     1220/*
     1221** CAPI3REF: Configuration Options {H10170} <S20000>
     1222** EXPERIMENTAL
     1223**
     1224** These constants are the available integer configuration options that
     1225** can be passed as the second argument to the [sqlite3_db_config()] interface.
     1226**
     1227** New configuration options may be added in future releases of SQLite.
     1228** Existing configuration options might be discontinued.  Applications
     1229** should check the return code from [sqlite3_db_config()] to make sure that
     1230** the call worked.  The [sqlite3_db_config()] interface will return a
     1231** non-zero [error code] if a discontinued or unsupported configuration option
     1232** is invoked.
     1233**
     1234** <dl>
     1235** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
     1236** <dd>This option takes three additional arguments that determine the
     1237** [lookaside memory allocator] configuration for the [database connection].
     1238** The first argument (the third parameter to [sqlite3_db_config()] is a
     1239** pointer to an memory buffer to use for lookaside memory.
     1240** The first argument may be NULL in which case SQLite will allocate the
     1241** lookaside buffer itself using [sqlite3_malloc()].  The second argument is the
     1242** size of each lookaside buffer slot and the third argument is the number of
     1243** slots.  The size of the buffer in the first argument must be greater than
     1244** or equal to the product of the second and third arguments.  The buffer
     1245** must be aligned to an 8-byte boundary.  If the second argument is not
     1246** a multiple of 8, it is internally rounded down to the next smaller
     1247** multiple of 8.  See also: [SQLITE_CONFIG_LOOKASIDE]</dd>
     1248**
     1249** </dl>
     1250*/
     1251#define SQLITE_DBCONFIG_LOOKASIDE    1001  /* void* int int */
     1252
     1253
     1254/*
     1255** CAPI3REF: Enable Or Disable Extended Result Codes {H12200} <S10700>
    8311256**
    8321257** The sqlite3_extended_result_codes() routine enables or disables the
    833 ** [SQLITE_IOERR_READ | extended result codes] feature of SQLite.
    834 ** The extended result codes are disabled by default for historical
    835 ** compatibility.
    836 **
    837 ** INVARIANTS:
    838 **
    839 ** {F12201} Each new [database connection] has the
    840 **          [extended result codes] feature
    841 **          disabled by default.
    842 **
    843 ** {F12202} The [sqlite3_extended_result_codes(D,F)] interface will enable
    844 **          [extended result codes] for the
    845 **          [database connection] D if the F parameter
    846 **          is true, or disable them if F is false.
    847 */
    848 int sqlite3_extended_result_codes(sqlite3*, int onoff);
    849 
    850 /*
    851 ** CAPI3REF: Last Insert Rowid {F12220}
     1258** [extended result codes] feature of SQLite. The extended result
     1259** codes are disabled by default for historical compatibility considerations.
     1260**
     1261** Requirements:
     1262** [H12201] [H12202]
     1263*/
     1264SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
     1265
     1266/*
     1267** CAPI3REF: Last Insert Rowid {H12220} <S10700>
    8521268**
    8531269** Each entry in an SQLite table has a unique 64-bit signed
    854 ** integer key called the "rowid". The rowid is always available
     1270** integer key called the . The rowid is always available
    8551271** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
    8561272** names are not also used by explicitly declared columns. If
    857 ** the table has a column of type INTEGER PRIMARY KEY then that column
     1273** the table has a column of type then that column
    8581274** is another alias for the rowid.
    8591275**
    860 ** This routine returns the rowid of the most recent
    861 ** successful INSERT into the database from the database connection
    862 ** shown in the first argument.  If no successful inserts
    863 ** have ever occurred on this database connection, zero is returned.
    864 **
    865 ** If an INSERT occurs within a trigger, then the rowid of the
    866 ** inserted row is returned by this routine as long as the trigger
    867 ** is running.  But once the trigger terminates, the value returned
    868 ** by this routine reverts to the last value inserted before the
    869 ** trigger fired.
    870 **
    871 ** An INSERT that fails due to a constraint violation is not a
    872 ** successful insert and does not change the value returned by this
     1276** This routine returns the [rowid] of the most recent
     1277** successful [INSERT] into the database from the [database connection]
     1278** in the first argument.  If no successful [INSERT]s
     1279** have ever occurred on that database connection, zero is returned.
     1280**
     1281** If an [INSERT] occurs within a trigger, then the [rowid] of the inserted
     1282** row is returned by this routine as long as the trigger is running.
     1283** But once the trigger terminates, the value returned by this routine
     1284** reverts to the last value inserted before the trigger fired.
     1285**
     1286** An [INSERT] that fails due to a constraint violation is not a
     1287** successful [INSERT] and does not change the value returned by this
    8731288** routine.  Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
    8741289** and INSERT OR ABORT make no changes to the return value of this
    875 ** routine when their insertion fails.  When INSERT OR REPLACE 
     1290** routine when their insertion fails.  When INSERT OR REPLACE
    8761291** encounters a constraint violation, it does not fail.  The
    8771292** INSERT continues to completion after deleting rows that caused
    8781293** the constraint problem so INSERT OR REPLACE will always change
    879 ** the return value of this interface. 
    880 **
    881 ** For the purposes of this routine, an insert is considered to
     1294** the return value of this interface.
     1295**
     1296** For the purposes of this routine, an is considered to
    8821297** be successful even if it is subsequently rolled back.
    8831298**
    884 ** INVARIANTS:
    885 **
    886 ** {F12221} The [sqlite3_last_insert_rowid()] function returns the
    887 **          rowid of the most recent successful insert done
    888 **          on the same database connection and within the same
    889 **          trigger context, or zero if there have
    890 **          been no qualifying inserts on that connection.
    891 **
    892 ** {F12223} The [sqlite3_last_insert_rowid()] function returns
    893 **          same value when called from the same trigger context
    894 **          immediately before and after a ROLLBACK.
    895 **
    896 ** LIMITATIONS:
    897 **
    898 ** {U12232} If a separate thread does a new insert on the same
    899 **          database connection while the [sqlite3_last_insert_rowid()]
    900 **          function is running and thus changes the last insert rowid,
    901 **          then the value returned by [sqlite3_last_insert_rowid()] is
    902 **          unpredictable and might not equal either the old or the new
    903 **          last insert rowid.
    904 */
    905 sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
    906 
    907 /*
    908 ** CAPI3REF: Count The Number Of Rows Modified {F12240}
     1299** Requirements:
     1300** [H12221] [H12223]
     1301**
     1302** If a separate thread performs a new [INSERT] on the same
     1303** database connection while the [sqlite3_last_insert_rowid()]
     1304** function is running and thus changes the last insert [rowid],
     1305** then the value returned by [sqlite3_last_insert_rowid()] is
     1306** unpredictable and might not equal either the old or the new
     1307** last insert [rowid].
     1308*/
     1309SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
     1310
     1311/*
     1312** CAPI3REF: Count The Number Of Rows Modified {H12240} <S10600>
    9091313**
    9101314** This function returns the number of database rows that were changed
    9111315** or inserted or deleted by the most recently completed SQL statement
    912 ** on the connection specified by the first parameter.  Only
    913 ** changes that are directly specified by the INSERT, UPDATE, or
    914 ** DELETE statement are counted.  Auxiliary changes caused by
    915 ** triggers are not counted. Use the [sqlite3_total_changes()] function
    916 ** to find the total number of changes including changes caused by triggers.
     1316** on the [database connection] specified by the first parameter.
     1317** Only changes that are directly specified by the [INSERT], [UPDATE],
     1318** or [DELETE] statement are counted.  Auxiliary changes caused by
     1319** triggers or [foreign key actions] are not counted. Use the
     1320** [sqlite3_total_changes()] function to find the total number of changes
     1321** including changes caused by triggers and foreign key actions.
     1322**
     1323** Changes to a view that are simulated by an [INSTEAD OF trigger]
     1324** are not counted.  Only real table changes are counted.
    9171325**
    9181326** A "row change" is a change to a single row of a single table
    9191327** caused by an INSERT, DELETE, or UPDATE statement.  Rows that
    920 ** are changed as side effects of REPLACE constraint resolution,
    921 ** rollback, ABORT processing, DROP TABLE, or by any other
     1328** are changed as side effects of constraint resolution,
     1329** rollback, ABORT processing, , or by any other
    9221330** mechanisms do not count as direct row changes.
    9231331**
    9241332** A "trigger context" is a scope of execution that begins and
    925 ** ends with the script of a trigger.  Most SQL statements are
     1333** ends with the script of a [CREATE TRIGGER | trigger].
     1334** Most SQL statements are
    9261335** evaluated outside of any trigger.  This is the "top level"
    9271336** trigger context.  If a trigger fires from the top level, a
    … …  
    9361345** trigger context.
    9371346**
    938 ** So when called from the top level, this function returns the
     1347** when called from the top level, this function returns the
    9391348** number of changes in the most recent INSERT, UPDATE, or DELETE
    940 ** that also occurred at the top level.
    941 ** Within the body of a trigger, the sqlite3_changes() interface
    942 ** can be called to find the number of
     1349** that also occurred at the top level.  Within the body of a trigger,
     1350** the sqlite3_changes() interface can be called to find the number of
    9431351** changes in the most recently completed INSERT, UPDATE, or DELETE
    9441352** statement within the body of the same trigger.
    945 ** However, the number returned does not include in changes
    946 ** caused by subtriggers since they have their own context.
    947 **
    948 ** SQLite implements the command "DELETE FROM table" without
    949 ** a WHERE clause by dropping and recreating the table.  (This is much
    950 ** faster than going through and deleting individual elements from the
    951 ** table.)  Because of this optimization, the deletions in
    952 ** "DELETE FROM table" are not row changes and will not be counted
    953 ** by the sqlite3_changes() or [sqlite3_total_changes()] functions.
    954 ** To get an accurate count of the number of rows deleted, use
    955 ** "DELETE FROM table WHERE 1" instead.
    956 **
    957 ** INVARIANTS:
    958 **
    959 ** {F12241} The [sqlite3_changes()] function returns the number of
    960 **          row changes caused by the most recent INSERT, UPDATE,
    961 **          or DELETE statement on the same database connection and
    962 **          within the same trigger context, or zero if there have
    963 **          not been any qualifying row changes.
    964 **
    965 ** LIMITATIONS:
    966 **
    967 ** {U12252} If a separate thread makes changes on the same database connection
    968 **          while [sqlite3_changes()] is running then the value returned
    969 **          is unpredictable and unmeaningful.
    970 */
    971 int sqlite3_changes(sqlite3*);
    972 
    973 /*
    974 ** CAPI3REF: Total Number Of Rows Modified {F12260}
    975 ***
    976 ** This function returns the number of row changes caused
    977 ** by INSERT, UPDATE or DELETE statements since the database handle
    978 ** was opened.  The count includes all changes from all trigger
    979 ** contexts.  But the count does not include changes used to
    980 ** implement REPLACE constraints, do rollbacks or ABORT processing,
    981 ** or DROP table processing.
    982 ** The changes
    983 ** are counted as soon as the statement that makes them is completed
    984 ** (when the statement handle is passed to [sqlite3_reset()] or
     1353** However, the number returned does not include changes
     1354** caused by subtriggers since those have their own context.
     1355**
     1356** See also the [sqlite3_total_changes()] interface and the
     1357** [count_changes pragma].
     1358**
     1359** Requirements:
     1360** [H12241] [H12243]
     1361**
     1362** If a separate thread makes changes on the same database connection
     1363** while [sqlite3_changes()] is running then the value returned
     1364** is unpredictable and not meaningful.
     1365*/
     1366SQLITE_API int sqlite3_changes(sqlite3*);
     1367
     1368/*
     1369** CAPI3REF: Total Number Of Rows Modified {H12260} <S10600>
     1370**
     1371** This function returns the number of row changes caused by [INSERT],
     1372** [UPDATE] or [DELETE] statements since the [database connection] was opened.
     1373** The count includes all changes from all [CREATE TRIGGER | trigger]
     1374** contexts and changes made by [foreign key actions]. However,
     1375** the count does not include changes used to implement [REPLACE] constraints,
     1376** do rollbacks or ABORT processing, or [DROP TABLE] processing.  The
     1377** count does not include rows of views that fire an [INSTEAD OF trigger],
     1378** though if the INSTEAD OF trigger makes changes of its own, those changes
     1379** are counted.
     1380** The changes are counted as soon as the statement that makes them is
     1381** completed (when the statement handle is passed to [sqlite3_reset()] or
    9851382** [sqlite3_finalize()]).
    9861383**
    987 ** SQLite implements the command "DELETE FROM table" without
    988 ** a WHERE clause by dropping and recreating the table.  (This is much
    989 ** faster than going
    990 ** through and deleting individual elements from the table.)  Because of
    991 ** this optimization, the change count for "DELETE FROM table" will be
    992 ** zero regardless of the number of elements that were originally in the
    993 ** table. To get an accurate count of the number of rows deleted, use
    994 ** "DELETE FROM table WHERE 1" instead.
    995 **
    996 ** See also the [sqlite3_changes()] interface.
    997 **
    998 ** INVARIANTS:
    999 **
    1000 ** {F12261} The [sqlite3_total_changes()] returns the total number
    1001 **          of row changes caused by INSERT, UPDATE, and/or DELETE
    1002 **          statements on the same [database connection], in any
    1003 **          trigger context, since the database connection was
    1004 **          created.
    1005 **
    1006 ** LIMITATIONS:
    1007 **
    1008 ** {U12264} If a separate thread makes changes on the same database connection
    1009 **          while [sqlite3_total_changes()] is running then the value
    1010 **          returned is unpredictable and unmeaningful.
    1011 */
    1012 int sqlite3_total_changes(sqlite3*);
    1013 
    1014 /*
    1015 ** CAPI3REF: Interrupt A Long-Running Query {F12270}
     1384** See also the [sqlite3_changes()] interface and the
     1385** [count_changes pragma].
     1386**
     1387** Requirements:
     1388** [H12261] [H12263]
     1389**
     1390** If a separate thread makes changes on the same database connection
     1391** while [sqlite3_total_changes()] is running then the value
     1392** returned is unpredictable and not meaningful.
     1393*/
     1394SQLITE_API int sqlite3_total_changes(sqlite3*);
     1395
     1396/*
     1397** CAPI3REF: Interrupt A Long-Running Query {H12270} <S30500>
    10161398**
    10171399** This function causes any pending database operation to abort and
    … …  
    10231405** It is safe to call this routine from a thread different from the
    10241406** thread that is currently running the database operation.  But it
    1025 ** is not safe to call this routine with a database connection that
     1407** is not safe to call this routine with a that
    10261408** is closed or might close before sqlite3_interrupt() returns.
    10271409**
    1028 ** If an SQL is very nearly finished at the time when sqlite3_interrupt()
    1029 ** is called, then it might not have an opportunity to be interrupted.
    1030 ** It might continue to completion.
    1031 ** An SQL operation that is interrupted will return
    1032 ** [SQLITE_INTERRUPT].  If the interrupted SQL operation is an
    1033 ** INSERT, UPDATE, or DELETE that is inside an explicit transaction,
    1034 ** then the entire transaction will be rolled back automatically.
    1035 ** A call to sqlite3_interrupt() has no effect on SQL statements
    1036 ** that are started after sqlite3_interrupt() returns.
    1037 **
    1038 ** INVARIANTS:
    1039 **
    1040 ** {F12271} The [sqlite3_interrupt()] interface will force all running
    1041 **          SQL statements associated with the same database connection
    1042 **          to halt after processing at most one additional row of
    1043 **          data.
    1044 **
    1045 ** {F12272} Any SQL statement that is interrupted by [sqlite3_interrupt()]
    1046 **          will return [SQLITE_INTERRUPT].
    1047 **
    1048 ** LIMITATIONS:
    1049 **
    1050 ** {U12279} If the database connection closes while [sqlite3_interrupt()]
    1051 **          is running then bad things will likely happen.
    1052 */
    1053 void sqlite3_interrupt(sqlite3*);
    1054 
    1055 /*
    1056 ** CAPI3REF: Determine If An SQL Statement Is Complete {F10510}
    1057 **
    1058 ** These routines are useful for command-line input to determine if the
    1059 ** currently entered text seems to form complete a SQL statement or
     1410** If an SQL operation is very nearly finished at the time when
     1411** sqlite3_interrupt() is called, then it might not have an opportunity
     1412** to be interrupted and might continue to completion.
     1413**
     1414** An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
     1415** If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
     1416** that is inside an explicit transaction, then the entire transaction
     1417** will be rolled back automatically.
     1418**
     1419** The sqlite3_interrupt(D) call is in effect until all currently running
     1420** SQL statements on [database connection] D complete.  Any new SQL statements
     1421** that are started after the sqlite3_interrupt() call and before the
     1422** running statements reaches zero are interrupted as if they had been
     1423** running prior to the sqlite3_interrupt() call.  New SQL statements
     1424** that are started after the running statement count reaches zero are
     1425** not effected by the sqlite3_interrupt().
     1426** A call to sqlite3_interrupt(D) that occurs when there are no running
     1427** SQL statements is a no-op and has no effect on SQL statements
     1428** that are started after the sqlite3_interrupt() call returns.
     1429**
     1430** Requirements:
     1431** [H12271] [H12272]
     1432**
     1433** If the database connection closes while [sqlite3_interrupt()]
     1434** is running then bad things will likely happen.
     1435*/
     1436SQLITE_API void sqlite3_interrupt(sqlite3*);
     1437
     1438/*
     1439** CAPI3REF: Determine If An SQL Statement Is Complete {H10510} <S70200>
     1440**
     1441** These routines are useful during command-line input to determine if the
     1442** currently entered text seems to form a complete SQL statement or
    10601443** if additional input is needed before sending the text into
    1061 ** SQLite for parsing.  These routines return true if the input string
     1444** SQLite for parsing.  These routines return if the input string
    10621445** appears to be a complete SQL statement.  A statement is judged to be
    1063 ** complete if it ends with a semicolon token and is not a fragment of a
    1064 ** CREATE TRIGGER statement.  Semicolons that are embedded within
     1446** complete if it ends with a semicolon token and is not a of a
     1447** CREATE TRIGGER statement.  Semicolons that are embedded within
    10651448** string literals or quoted identifier names or comments are not
    10661449** independent tokens (they are part of the token in which they are
    1067 ** embedded) and thus do not count as a statement terminator.
    1068 **
    1069 ** These routines do not parse the SQL and
    1070 ** so will not detect syntactically incorrect SQL.
    1071 **
    1072 ** INVARIANTS:
    1073 **
    1074 ** {F10511} The sqlite3_complete() and sqlite3_complete16() functions
    1075 **          return true (non-zero) if and only if the last
    1076 **          non-whitespace token in their input is a semicolon that
    1077 **          is not in between the BEGIN and END of a CREATE TRIGGER
    1078 **          statement.
    1079 **
    1080 ** LIMITATIONS:
    1081 **
    1082 ** {U10512} The input to sqlite3_complete() must be a zero-terminated
    1083 **          UTF-8 string.
    1084 **
    1085 ** {U10513} The input to sqlite3_complete16() must be a zero-terminated
    1086 **          UTF-16 string in native byte order.
    1087 */
    1088 int sqlite3_complete(const char *sql);
    1089 int sqlite3_complete16(const void *sql);
    1090 
    1091 /*
    1092 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {F12310}
    1093 **
    1094 ** This routine identifies a callback function that might be
    1095 ** invoked whenever an attempt is made to open a database table
    1096 ** that another thread or process has locked.
    1097 ** If the busy callback is NULL, then [SQLITE_BUSY]
    1098 ** or [SQLITE_IOERR_BLOCKED]
    1099 ** is returned immediately upon encountering the lock.
    1100 ** If the busy callback is not NULL, then the
    1101 ** callback will be invoked with two arguments.  The
    1102 ** first argument to the handler is a copy of the void* pointer which
    1103 ** is the third argument to this routine.  The second argument to
    1104 ** the handler is the number of times that the busy handler has
    1105 ** been invoked for this locking event.   If the
     1450** embedded) and thus do not count as a statement terminator.  Whitespace
     1451** and comments that follow the final semicolon are ignored.
     1452**
     1453** These routines return 0 if the statement is incomplete.  If a
     1454** memory allocation fails, then SQLITE_NOMEM is returned.
     1455**
     1456** These routines do not parse the SQL statements thus
     1457** will not detect syntactically incorrect SQL.
     1458**
     1459** If SQLite has not been initialized using [sqlite3_initialize()] prior
     1460** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
     1461** automatically by sqlite3_complete16().  If that initialization fails,
     1462** then the return value from sqlite3_complete16() will be non-zero
     1463** regardless of whether or not the input SQL is complete.
     1464**
     1465** Requirements: [H10511] [H10512]
     1466**
     1467** The input to [sqlite3_complete()] must be a zero-terminated
     1468** UTF-8 string.
     1469**
     1470** The input to [sqlite3_complete16()] must be a zero-terminated
     1471** UTF-16 string in native byte order.
     1472*/
     1473SQLITE_API int sqlite3_complete(const char *sql);
     1474SQLITE_API int sqlite3_complete16(const void *sql);
     1475
     1476/*
     1477** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {H12310} <S40400>
     1478**
     1479** This routine sets a callback function that might be invoked whenever
     1480** an attempt is made to open a database table that another thread
     1481** or process has locked.
     1482**
     1483** If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]
     1484** is returned immediately upon encountering the lock. If the busy callback
     1485** is not NULL, then the callback will be invoked with two arguments.
     1486**
     1487** The first argument to the handler is a copy of the void* pointer which
     1488** is the third argument to sqlite3_busy_handler().  The second argument to
     1489** the handler callback is the number of times that the busy handler has
     1490** been invoked for this locking event.  If the
    11061491** busy callback returns 0, then no additional attempts are made to
    11071492** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
    … …  
    11091494** is made to open the database for reading and the cycle repeats.
    11101495**
    1111 ** The presence of a busy handler does not guarantee that
    1112 ** it will be invoked when there is lock contention.
    1113 ** If SQLite determines that invoking the busy handler could result in
    1114 ** a deadlock, it will go ahead and return [SQLITE_BUSY] or
    1115 ** [SQLITE_IOERR_BLOCKED] instead of invoking the
    1116 ** busy handler.
     1496** The presence of a busy handler does not guarantee that it will be invoked
     1497** when there is lock contention. If SQLite determines that invoking the busy
     1498** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
     1499** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler.
    11171500** Consider a scenario where one process is holding a read lock that
    11181501** it is trying to promote to a reserved lock and
    … …  
    11391522** the more severe [SQLITE_IOERR_BLOCKED].  This error code promotion
    11401523** forces an automatic rollback of the changes.  See the
    1141 ** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
     1524** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">
    11421525** CorruptionFollowingBusyError</a> wiki page for a discussion of why
    11431526** this is important.
    1144 **     
    1145 ** There can only be a single busy handler defined for each database
    1146 ** connection.  Setting a new busy handler clears any previous one.
    1147 ** Note that calling [sqlite3_busy_timeout()] will also set or clear
    1148 ** the busy handler.
    1149 **
    1150 ** INVARIANTS:
    1151 **
    1152 ** {F12311} The [sqlite3_busy_handler()] function replaces the busy handler
    1153 **          callback in the database connection identified by the 1st
    1154 **          parameter with a new busy handler identified by the 2nd and 3rd
    1155 **          parameters.
    1156 **
    1157 ** {F12312} The default busy handler for new database connections is NULL.
    1158 **
    1159 ** {F12314} When two or more database connection share a common cache,
    1160 **          the busy handler for the database connection currently using
    1161 **          the cache is invoked when the cache encounters a lock.
    1162 **
    1163 ** {F12316} If a busy handler callback returns zero, then the SQLite
    1164 **          interface that provoked the locking event will return
    1165 **          [SQLITE_BUSY].
    1166 **
    1167 ** {F12318} SQLite will invokes the busy handler with two argument which
    1168 **          are a copy of the pointer supplied by the 3rd parameter to
    1169 **          [sqlite3_busy_handler()] and a count of the number of prior
    1170 **          invocations of the busy handler for the same locking event.
    1171 **
    1172 ** LIMITATIONS:
    1173 **
    1174 ** {U12319} A busy handler should not call close the database connection
    1175 **          or prepared statement that invoked the busy handler.
    1176 */
    1177 int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
    1178 
    1179 /*
    1180 ** CAPI3REF: Set A Busy Timeout {F12340}
    1181 **
    1182 ** This routine sets a [sqlite3_busy_handler | busy handler]
    1183 ** that sleeps for a while when a
    1184 ** table is locked.  The handler will sleep multiple times until
    1185 ** at least "ms" milliseconds of sleeping have been done. {F12343} After
    1186 ** "ms" milliseconds of sleeping, the handler returns 0 which
    1187 ** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
     1527**
     1528** There can only be a single busy handler defined for each
     1529** [database connection].  Setting a new busy handler clears any
     1530** previously set handler.  Note that calling [sqlite3_busy_timeout()]
     1531** will also set or clear the busy handler.
     1532**
     1533** The busy callback should not take any actions which modify the
     1534** database connection that invoked the busy handler.  Any such actions
     1535** result in undefined behavior.
     1536**
     1537** Requirements:
     1538** [H12311] [H12312] [H12314] [H12316] [H12318]
     1539**
     1540** A busy handler must not close the database connection
     1541** or [prepared statement] that invoked the busy handler.
     1542*/
     1543SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
     1544
     1545/*
     1546** CAPI3REF: Set A Busy Timeout {H12340} <S40410>
     1547**
     1548** This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
     1549** for a specified amount of time when a table is locked.  The handler
     1550** will sleep multiple times until at least "ms" milliseconds of sleeping
     1551** have accumulated. {H12343} After "ms" milliseconds of sleeping,
     1552** the handler returns 0 which causes [sqlite3_step()] to return
     1553** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
    11881554**
    11891555** Calling this routine with an argument less than or equal to zero
    11901556** turns off all busy handlers.
    11911557**
    1192 ** There can only be a single busy handler for a particular database
    1193 ** connection.  If another busy handler was defined 
    1194 ** (using [sqlite3_busy_handler()]) prior to calling
     1558** There can only be a single busy handler for a particular
     1559**
     1560** (using [sqlite3_busy_handler()]) prior to calling
    11951561** this routine, that other busy handler is cleared.
    11961562**
    1197 ** INVARIANTS:
    1198 **
    1199 ** {F12341} The [sqlite3_busy_timeout()] function overrides any prior
    1200 **          [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting
    1201 **          on the same database connection.
    1202 **
    1203 ** {F12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than
    1204 **          or equal to zero, then the busy handler is cleared so that
    1205 **          all subsequent locking events immediately return [SQLITE_BUSY].
    1206 **
    1207 ** {F12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive
    1208 **          number N, then a busy handler is set that repeatedly calls
    1209 **          the xSleep() method in the VFS interface until either the
    1210 **          lock clears or until the cumulative sleep time reported back
    1211 **          by xSleep() exceeds N milliseconds.
    1212 */
    1213 int sqlite3_busy_timeout(sqlite3*, int ms);
    1214 
    1215 /*
    1216 ** CAPI3REF: Convenience Routines For Running Queries {F12370}
     1563** Requirements:
     1564** [H12341] [H12343] [H12344]
     1565*/
     1566SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
     1567
     1568/*
     1569** CAPI3REF: Convenience Routines For Running Queries {H12370} <S10000>
    12171570**
    12181571** Definition: A <b>result table</b> is memory data structure created by the
    … …  
    12251578** and M be the number of columns.
    12261579**
    1227 ** A result table is an array of pointers to zero-terminated
    1228 ** UTF-8 strings.  There are (N+1)*M elements in the array. 
    1229 ** The first M pointers point to zero-terminated strings that
    1230 ** contain the names of the columns.
    1231 ** The remaining entries all point to query results.  NULL
    1232 ** values are give a NULL pointer.  All other values are in
    1233 ** their UTF-8 zero-terminated string representation as returned by
    1234 ** [sqlite3_column_text()].
    1235 **
    1236 ** A result table might consists of one or more memory allocations.
     1580** A result table is an array of pointers to zero-terminated UTF-8 strings.
     1581** There are (N+1)*M elements in the array.  The first M pointers point
     1582** to zero-terminated strings that  contain the names of the columns.
     1583** The remaining entries all point to query results.  NULL values result
     1584** in NULL pointers.  All other values are in their UTF-8 zero-terminated
     1585** string representation as returned by [sqlite3_column_text()].
     1586**
     1587** A result table might consist of one or more memory allocations.
    12371588** It is not safe to pass a result table directly to [sqlite3_free()].
    12381589** A result table should be deallocated using [sqlite3_free_table()].
    … …  
    12691620** pointer given in its 3rd parameter.
    12701621**
    1271 ** After the calling function has finished using the result, it should 
    1272 ** pass the pointer to the result table to sqlite3_free_table() in order to 
    1273 ** release the memory that was malloc-ed.  Because of the way the
     1622** After the calling function has finished using the result, it should
     1623** pass the pointer to the result table to sqlite3_free_table() in order to
     1624** release the memory that was malloc
    12741625** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
    1275 ** function must not try to call [sqlite3_free()] directly.  Only 
     1626** function must not try to call [sqlite3_free()] directly.  Only
    12761627** [sqlite3_free_table()] is able to release the memory properly and safely.
    12771628**
    … …  
    12811632** interface defined here.  As a consequence, errors that occur in the
    12821633** wrapper layer outside of the internal [sqlite3_exec()] call are not
    1283 ** reflected in subsequent calls to [sqlite3_errcode()] or
    1284 ** [sqlite3_errmsg()].
    1285 **
    1286 ** INVARIANTS:
    1287 **
    1288 ** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then
    1289 **          it frees the result table under construction, aborts the
    1290 **          query in process, skips any subsequent queries, sets the
    1291 **          *resultp output pointer to NULL and returns [SQLITE_NOMEM].
    1292 **
    1293 ** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL
    1294 **          then [sqlite3_get_table()] write the number of columns in the
    1295 **          result set of the query into *ncolumn if the query is
    1296 **          successful (if the function returns SQLITE_OK).
    1297 **
    1298 ** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL
    1299 **          then [sqlite3_get_table()] write the number of rows in the
    1300 **          result set of the query into *nrow if the query is
    1301 **          successful (if the function returns SQLITE_OK).
    1302 **
    1303 ** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value
    1304 **          to the number of columns in the result set of the query in the
    1305 **          sql parameter, or to zero if the query in sql has an empty
    1306 **          result set.
    1307 */
    1308 int sqlite3_get_table(
    1309   sqlite3*,             /* An open database */
    1310   const char *sql,      /* SQL to be evaluated */
    1311   char ***pResult,      /* Results of the query */
    1312   int *nrow,            /* Number of result rows written here */
    1313   int *ncolumn,         /* Number of result columns written here */
    1314   char **errmsg         /* Error msg written here */
     1634** reflected in subsequent calls to [sqlite3_errcode()] or [sqlite3_errmsg()].
     1635**
     1636** Requirements:
     1637** [H12371] [H12373] [H12374] [H12376] [H12379] [H12382]
     1638*/
     1639SQLITE_API int sqlite3_get_table(
     1640  sqlite3 *db,          /* An open database */
     1641  const char *zSql,     /* SQL to be evaluated */
     1642  char ***pazResult,    /* Results of the query */
     1643  int *pnRow,           /* Number of result rows written here */
     1644  int *pnColumn,        /* Number of result columns written here */
     1645  char **pzErrmsg       /* Error msg written here */
    13151646);
    1316 void sqlite3_free_table(char **result);
    1317 
    1318 /*
    1319 ** CAPI3REF: Formatted String Printing Functions {F17400}
    1320 **
    1321 ** These routines are workalikes of the "printf()" family of functions
     1647void sqlite3_free_table(char **result);
     1648
     1649/*
     1650** CAPI3REF: Formatted String Printing Functions {
     1651**
     1652** These routines are workalikes of the "printf()" family of functions
    13221653** from the standard C library.
    13231654**
    … …  
    13251656** results into memory obtained from [sqlite3_malloc()].
    13261657** The strings returned by these two routines should be
    1327 ** released by [sqlite3_free()].   Both routines return a
     1658** released by [sqlite3_free()].  Both routines return a
    13281659** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
    13291660** memory to hold the resulting string.
    … …  
    13501681** These routines all implement some additional formatting
    13511682** options that are useful for constructing SQL statements.
    1352 ** All of the usual printf formatting options apply.  In addition, there
     1683** All of the usual printf formatting options apply.  In addition, there
    13531684** is are "%q", "%Q", and "%z" options.
    13541685**
    … …  
    13591690** the string.
    13601691**
    1361 ** For example, so some string variable contains text as follows:
     1692** For example, contains text as follows:
    13621693**
    13631694** <blockquote><pre>
    … …  
    13871718** </pre></blockquote>
    13881719**
    1389 ** This second example is an SQL syntax error.  As a general rule you
    1390 ** should always use %q instead of %s when inserting text into a string
    1391 ** literal.
     1720** This second example is an SQL syntax error.  As a general rule you should
     1721** always use %q instead of %s when inserting text into a string literal.
    13921722**
    13931723** The %Q option works like %q except it also adds single quotes around
    1394 ** the outside of the total string.  Or if the parameter in the argument
    1395 ** list is a NULL pointer, %Q substitutes the text "NULL" (without single
    1396 ** quotes) in place of the %Q option. {END}  So, for example, one could say:
     1724** the outside of the total string. 
     1725**
     1726**   So, for example, one could say:
    13971727**
    13981728** <blockquote><pre>
    … …  
    14091739** the result, [sqlite3_free()] is called on the input string. {END}
    14101740**
    1411 ** INVARIANTS:
    1412 **
    1413 ** {F17403}  The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces
    1414 **           return either pointers to zero-terminated UTF-8 strings held in
    1415 **           memory obtained from [sqlite3_malloc()] or NULL pointers if
    1416 **           a call to [sqlite3_malloc()] fails.
    1417 **
    1418 ** {F17406}  The [sqlite3_snprintf()] interface writes a zero-terminated
    1419 **           UTF-8 string into the buffer pointed to by the second parameter
    1420 **           provided that the first parameter is greater than zero.
    1421 **
    1422 ** {F17407}  The [sqlite3_snprintf()] interface does not writes slots of
    1423 **           its output buffer (the second parameter) outside the range
    1424 **           of 0 through N-1 (where N is the first parameter)
    1425 **           regardless of the length of the string
    1426 **           requested by the format specification.
    1427 **   
    1428 */
    1429 char *sqlite3_mprintf(const char*,...);
    1430 char *sqlite3_vmprintf(const char*, va_list);
    1431 char *sqlite3_snprintf(int,char*,const char*, ...);
    1432 
    1433 /*
    1434 ** CAPI3REF: Memory Allocation Subsystem {F17300}
     1741** Requirements:
     1742** [H17403] [H17406] [H17407]
     1743*/
     1744SQLITE_API char *sqlite3_mprintf(const char*,...);
     1745SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
     1746SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
     1747
     1748/*
     1749** CAPI3REF: Memory Allocation Subsystem {H17300} <S20000>
    14351750**
    14361751** The SQLite core  uses these three routines for all of its own
    14371752** internal memory allocation needs. "Core" in the previous sentence
    14381753** does not include operating-system specific VFS implementation.  The
    1439 ** windows VFS uses native malloc and free for some operations.
     1754** for some operations.
    14401755**
    14411756** The sqlite3_malloc() routine returns a pointer to a block
    … …  
    14551770** Memory corruption, a segmentation fault, or other severe error
    14561771** might result if sqlite3_free() is called with a non-NULL pointer that
    1457 ** was not obtained from sqlite3_malloc() or sqlite3_free().
     1772** was not obtained from sqlite3_malloc() or sqlite3_().
    14581773**
    14591774** The sqlite3_realloc() interface attempts to resize a
    … …  
    14661781** negative then the behavior is exactly the same as calling
    14671782** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
    1468 ** Sqlite3_realloc() returns a pointer to a memory allocation
     1783** qlite3_realloc() returns a pointer to a memory allocation
    14691784** of at least N bytes in size or NULL if sufficient memory is unavailable.
    14701785** If M is the size of the prior allocation, then min(N,M) bytes
    … …  
    14771792** is always aligned to at least an 8 byte boundary. {END}
    14781793**
    1479 ** The default implementation
    1480 ** of the memory allocation subsystem uses the malloc(), realloc()
    1481 ** and free() provided by the standard C library. {F17382} However, if
    1482 ** SQLite is compiled with the following C preprocessor macro
    1483 **
    1484 ** <blockquote> SQLITE_MEMORY_SIZE=<i>NNN</i> </blockquote>
    1485 **
    1486 ** where <i>NNN</i> is an integer, then SQLite create a static
    1487 ** array of at least <i>NNN</i> bytes in size and use that array
    1488 ** for all of its dynamic memory allocation needs. {END}  Additional
    1489 ** memory allocator options may be added in future releases.
     1794** The default implementation of the memory allocation subsystem uses
     1795** the malloc(), realloc() and free() provided by the standard C library.
     1796** {H17382} However, if SQLite is compiled with the
     1797** SQLITE_MEMORY_SIZE=<i>NNN</i> C preprocessor macro (where <i>NNN</i>
     1798** is an integer), then SQLite create a static array of at least
     1799** <i>NNN</i> bytes in size and uses that array for all of its dynamic
     1800** memory allocation needs. {END}  Additional memory allocator options
     1801** may be added in future releases.
    14901802**
    14911803** In SQLite version 3.5.0 and 3.5.1, it was possible to define
    14921804** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
    14931805** implementation of these routines to be omitted.  That capability
    1494 ** is no longer provided.  Only built-in memory allocators can be
    1495 ** used.
    1496 **
    1497 ** The windows OS interface layer calls
     1806** is no longer provided.  Only built-in memory allocators can be used.
     1807**
     1808** The Windows OS interface layer calls
    14981809** the system malloc() and free() directly when converting
    14991810** filenames between the UTF-8 encoding used by SQLite
    1500 ** and whatever filename encoding is used by the particular windows
     1811** and whatever filename encoding is used by the particular indows
    15011812** installation.  Memory allocation errors are detected, but
    15021813** they are reported back as [SQLITE_CANTOPEN] or
    15031814** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
    15041815**
    1505 ** INVARIANTS:
    1506 **
    1507 ** {F17303}  The [sqlite3_malloc(N)] interface returns either a pointer to
    1508 **           newly checked-out block of at least N bytes of memory
    1509 **           that is 8-byte aligned,
    1510 **           or it returns NULL if it is unable to fulfill the request.
    1511 **
    1512 ** {F17304}  The [sqlite3_malloc(N)] interface returns a NULL pointer if
    1513 **           N is less than or equal to zero.
    1514 **
    1515 ** {F17305}  The [sqlite3_free(P)] interface releases memory previously
    1516 **           returned from [sqlite3_malloc()] or [sqlite3_realloc()],
    1517 **           making it available for reuse.
    1518 **
    1519 ** {F17306}  A call to [sqlite3_free(NULL)] is a harmless no-op.
    1520 **
    1521 ** {F17310}  A call to [sqlite3_realloc(0,N)] is equivalent to a call
    1522 **           to [sqlite3_malloc(N)].
    1523 **
    1524 ** {F17312}  A call to [sqlite3_realloc(P,0)] is equivalent to a call
    1525 **           to [sqlite3_free(P)].
    1526 **
    1527 ** {F17315}  The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()],
    1528 **           and [sqlite3_free()] for all of its memory allocation and
    1529 **           deallocation needs.
    1530 **
    1531 ** {F17318}  The [sqlite3_realloc(P,N)] interface returns either a pointer
    1532 **           to a block of checked-out memory of at least N bytes in size
    1533 **           that is 8-byte aligned, or a NULL pointer.
    1534 **
    1535 ** {F17321}  When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
    1536 **           copies the first K bytes of content from P into the newly allocated
    1537 **           where K is the lessor of N and the size of the buffer P.
    1538 **
    1539 ** {F17322}  When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
    1540 **           releases the buffer P.
    1541 **
    1542 ** {F17323}  When [sqlite3_realloc(P,N)] returns NULL, the buffer P is
    1543 **           not modified or released.
    1544 **
    1545 ** LIMITATIONS:
    1546 **
    1547 ** {U17350}  The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
    1548 **           must be either NULL or else a pointer obtained from a prior
    1549 **           invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that has
    1550 **           not been released.
    1551 **
    1552 ** {U17351}  The application must not read or write any part of
    1553 **           a block of memory after it has been released using
    1554 **           [sqlite3_free()] or [sqlite3_realloc()].
    1555 **
    1556 */
    1557 void *sqlite3_malloc(int);
    1558 void *sqlite3_realloc(void*, int);
    1559 void sqlite3_free(void*);
    1560 
    1561 /*
    1562 ** CAPI3REF: Memory Allocator Statistics {F17370}
     1816** Requirements:
     1817** [H17303] [H17304] [H17305] [H17306] [H17310] [H17312] [H17315] [H17318]
     1818** [H17321] [H17322] [H17323]
     1819**
     1820** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
     1821** must be either NULL or else pointers obtained from a prior
     1822** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
     1823** not yet been released.
     1824**
     1825** The application must not read or write any part of
     1826** a block of memory after it has been released using
     1827** [sqlite3_free()] or [sqlite3_realloc()].
     1828*/
     1829SQLITE_API void *sqlite3_malloc(int);
     1830SQLITE_API void *sqlite3_realloc(void*, int);
     1831SQLITE_API void sqlite3_free(void*);
     1832
     1833/*
     1834** CAPI3REF: Memory Allocator Statistics {H17370} <S30210>
    15631835**
    15641836** SQLite provides these two interfaces for reporting on the status
    15651837** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
    1566 ** the memory allocation subsystem included within the SQLite.
    1567 **
    1568 ** INVARIANTS:
    1569 **
    1570 ** {F17371} The [sqlite3_memory_used()] routine returns the
    1571 **          number of bytes of memory currently outstanding
    1572 **          (malloced but not freed).
    1573 **
    1574 ** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum
    1575 **          value of [sqlite3_memory_used()]
    1576 **          since the highwater mark was last reset.
    1577 **
    1578 ** {F17374} The values returned by [sqlite3_memory_used()] and
    1579 **          [sqlite3_memory_highwater()] include any overhead
    1580 **          added by SQLite in its implementation of [sqlite3_malloc()],
    1581 **          but not overhead added by the any underlying system library
    1582 **          routines that [sqlite3_malloc()] may call.
    1583 **
    1584 ** {F17375} The memory highwater mark is reset to the current value of
    1585 **          [sqlite3_memory_used()] if and only if the parameter to
    1586 **          [sqlite3_memory_highwater()] is true.  The value returned
    1587 **          by [sqlite3_memory_highwater(1)] is the highwater mark
    1588 **          prior to the reset.
    1589 */
    1590 sqlite3_int64 sqlite3_memory_used(void);
    1591 sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
    1592 
    1593 /*
    1594 ** CAPI3REF: Pseudo-Random Number Generator {F17390}
     1838** routines, which form the built-in memory allocation subsystem.
     1839**
     1840** Requirements:
     1841** [H17371] [H17373] [H17374] [H17375]
     1842*/
     1843SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
     1844SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
     1845
     1846/*
     1847** CAPI3REF: Pseudo-Random Number Generator {H17390} <S20000>
    15951848**
    15961849** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
    1597 ** select random ROWIDs when inserting new records into a table that
    1598 ** already uses the largest possible ROWID.  The PRNG is also used for
     1850** select random when inserting new records into a table that
     1851** already uses the largest possible .  The PRNG is also used for
    15991852** the build-in random() and randomblob() SQL functions.  This interface allows
    1600 ** appliations to access the same PRNG for other purposes.
     1853** appliations to access the same PRNG for other purposes.
    16011854**
    16021855** A call to this routine stores N bytes of randomness into buffer P.
    … …  
    16091862** method.
    16101863**
    1611 ** INVARIANTS:
    1612 **
    1613 ** {F17392} The [sqlite3_randomness(N,P)] interface writes N bytes of
    1614 **          high-quality pseudo-randomness into buffer P.
    1615 */
    1616 void sqlite3_randomness(int N, void *P);
    1617 
    1618 /*
    1619 ** CAPI3REF: Compile-Time Authorization Callbacks {F12500}
     1864** Requirements:
     1865** [H17392]
     1866*/
     1867SQLITE_API void sqlite3_randomness(int N, void *P);
     1868
     1869/*
     1870** CAPI3REF: Compile-Time Authorization Callbacks {H12500} <S70100>
    16201871**
    16211872** This routine registers a authorizer callback with a particular
    … …  
    16301881** specific action but allow the SQL statement to continue to be
    16311882** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
    1632 ** rejected with an error.   If the authorizer callback returns
     1883** rejected with an error.  If the authorizer callback returns
    16331884** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
    1634 ** then [sqlite3_prepare_v2()] or equivalent call that triggered
     1885** then [sqlite3_prepare_v2()] or equivalent call that triggered
    16351886** the authorizer will fail with an error message.
    16361887**
    … …  
    16391890** [sqlite3_prepare_v2()] or equivalent call that triggered the
    16401891** authorizer will fail with an error message explaining that
    1641 ** access is denied.  If the authorizer code is [SQLITE_READ]
     1892** access is denied.
     1893**
     1894** The first parameter to the authorizer callback is a copy of the third
     1895** parameter to the sqlite3_set_authorizer() interface. The second parameter
     1896** to the callback is an integer [SQLITE_COPY | action code] that specifies
     1897** the particular action to be authorized. The third through sixth parameters
     1898** to the callback are zero-terminated strings that contain additional
     1899** details about the action to be authorized.
     1900**
     1901** If the action code is [SQLITE_READ]
    16421902** and the callback returns [SQLITE_IGNORE] then the
    16431903** [prepared statement] statement is constructed to substitute
    … …  
    16461906** return can be used to deny an untrusted user access to individual
    16471907** columns of a table.
    1648 **
    1649 ** The first parameter to the authorizer callback is a copy of
    1650 ** the third parameter to the sqlite3_set_authorizer() interface.
    1651 ** The second parameter to the callback is an integer
    1652 ** [SQLITE_COPY | action code] that specifies the particular action
    1653 ** to be authorized. The third through sixth
    1654 ** parameters to the callback are zero-terminated strings that contain
    1655 ** additional details about the action to be authorized.
     1908** If the action code is [SQLITE_DELETE] and the callback returns
     1909** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
     1910** [truncate optimization] is disabled and all rows are deleted individually.
    16561911**
    16571912** An authorizer is used when [sqlite3_prepare | preparing]
    1658 ** SQL statements from an untrusted
    1659 ** source, to ensure that the SQL statements do not try to access data
    1660 ** that they are not allowed to see, or that they do not try to
    1661 ** execute malicious statements that damage the database.  For
     1913** SQL statements from an untrusted source, to ensure that the SQL statements
     1914** do not try to access data they are not allowed to see, or that they do not
     1915** try to execute malicious statements that damage the database.  For
    16621916** example, an application may allow a user to enter arbitrary
    16631917** SQL queries for evaluation by a database.  But the application does
    … …  
    16771931** The authorizer is disabled by default.
    16781932**
    1679 ** Note that the authorizer callback is invoked only during
     1933** The authorizer callback must not do anything that will modify
     1934** the database connection that invoked the authorizer callback.
     1935** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
     1936** database connections for the meaning of "modify" in this paragraph.
     1937**
     1938** When [sqlite3_prepare_v2()] is used to prepare a statement, the
     1939** statement might be re-prepared during [sqlite3_step()] due to a
     1940** schema change.  Hence, the application should ensure that the
     1941** correct authorizer callback remains in place during the [sqlite3_step()].
     1942**
     1943** Note that the authorizer callback is invoked only during
    16801944** [sqlite3_prepare()] or its variants.  Authorization is not
    1681 ** performed during statement evaluation in [sqlite3_step()].
    1682 **
    1683 ** INVARIANTS:
    1684 **
    1685 ** {F12501} The [sqlite3_set_authorizer(D,...)] interface registers a
    1686 **          authorizer callback with database connection D.
    1687 **
    1688 ** {F12502} The authorizer callback is invoked as SQL statements are
    1689 **          being compiled
    1690 **
    1691 ** {F12503} If the authorizer callback returns any value other than
    1692 **          [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] then
    1693 **          the [sqlite3_prepare_v2()] or equivalent call that caused
    1694 **          the authorizer callback to run shall fail with an
    1695 **          [SQLITE_ERROR] error code and an appropriate error message.
    1696 **
    1697 ** {F12504} When the authorizer callback returns [SQLITE_OK], the operation
    1698 **          described is coded normally.
    1699 **
    1700 ** {F12505} When the authorizer callback returns [SQLITE_DENY], the
    1701 **          [sqlite3_prepare_v2()] or equivalent call that caused the
    1702 **          authorizer callback to run shall fail
    1703 **          with an [SQLITE_ERROR] error code and an error message
    1704 **          explaining that access is denied.
    1705 **
    1706 ** {F12506} If the authorizer code (the 2nd parameter to the authorizer
    1707 **          callback) is [SQLITE_READ] and the authorizer callback returns
    1708 **          [SQLITE_IGNORE] then the prepared statement is constructed to
    1709 **          insert a NULL value in place of the table column that would have
    1710 **          been read if [SQLITE_OK] had been returned.
    1711 **
    1712 ** {F12507} If the authorizer code (the 2nd parameter to the authorizer
    1713 **          callback) is anything other than [SQLITE_READ], then
    1714 **          a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY].
    1715 **
    1716 ** {F12510} The first parameter to the authorizer callback is a copy of
    1717 **          the third parameter to the [sqlite3_set_authorizer()] interface.
    1718 **
    1719 ** {F12511} The second parameter to the callback is an integer
    1720 **          [SQLITE_COPY | action code] that specifies the particular action
    1721 **          to be authorized.
    1722 **
    1723 ** {F12512} The third through sixth parameters to the callback are
    1724 **          zero-terminated strings that contain
    1725 **          additional details about the action to be authorized.
    1726 **
    1727 ** {F12520} Each call to [sqlite3_set_authorizer()] overrides the
    1728 **          any previously installed authorizer.
    1729 **
    1730 ** {F12521} A NULL authorizer means that no authorization
    1731 **          callback is invoked.
    1732 **
    1733 ** {F12522} The default authorizer is NULL.
    1734 */
    1735 int sqlite3_set_authorizer(
     1945** performed during statement evaluation in [sqlite3_step()], unless
     1946** as stated in the previous paragraph, sqlite3_step() invokes
     1947** sqlite3_prepare_v2() to reprepare a statement after a schema change.
     1948**
     1949** Requirements:
     1950** [H12501] [H12502] [H12503] [H12504] [H12505] [H12506] [H12507] [H12510]
     1951** [H12511] [H12512] [H12520] [H12521] [H12522]
     1952*/
     1953SQLITE_API int sqlite3_set_authorizer(
    17361954  sqlite3*,
    17371955  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
    … …  
    17401958
    17411959/*
    1742 ** CAPI3REF: Authorizer Return Codes {F12590}
     1960** CAPI3REF: Authorizer Return Codes {
    17431961**
    17441962** The [sqlite3_set_authorizer | authorizer callback function] must
    … …  
    17521970
    17531971/*
    1754 ** CAPI3REF: Authorizer Action Codes {F12550}
     1972** CAPI3REF: Authorizer Action Codes {
    17551973**
    17561974** The [sqlite3_set_authorizer()] interface registers a callback function
    1757 ** that is invoked to authorizer certain SQL statement actions.  The
     1975** that is invoked to authorize certain SQL statement actions.  The
    17581976** second parameter to the callback is an integer code that specifies
    17591977** what action is being authorized.  These are the integer action codes that
    17601978** the authorizer callback may be passed.
    17611979**
    1762 ** These action code values signify what kind of operation is to be 
     1980** These action code values signify what kind of operation is to be
    17631981** authorized.  The 3rd and 4th parameters to the authorization
    17641982** callback function will be parameters or NULL depending on which of these
    17651983** codes is used as the second parameter.  The 5th parameter to the
    1766 ** authorizer callback is the name of the database ("main", "temp", 
     1984** authorizer callback is the name of the database ("main", "temp",
    17671985** etc.) if applicable.  The 6th parameter to the authorizer callback
    17681986** is the name of the inner-most trigger or view that is responsible for
    1769 ** the access attempt or NULL if this access attempt is directly from 
     1987** the access attempt or NULL if this access attempt is directly from
    17701988** top-level SQL code.
    17711989**
    1772 ** INVARIANTS:
    1773 **
    1774 ** {F12551} The second parameter to an
    1775 **          [sqlite3_set_authorizer | authorizer callback is always an integer
    1776 **          [SQLITE_COPY | authorizer code] that specifies what action
    1777 **          is being authorized.
    1778 **
    1779 ** {F12552} The 3rd and 4th parameters to the
    1780 **          [sqlite3_set_authorizer | authorization callback function]
    1781 **          will be parameters or NULL depending on which
    1782 **          [SQLITE_COPY | authorizer code] is used as the second parameter.
    1783 **
    1784 ** {F12553} The 5th parameter to the
    1785 **          [sqlite3_set_authorizer | authorizer callback] is the name
    1786 **          of the database (example: "main", "temp", etc.) if applicable.
    1787 **
    1788 ** {F12554} The 6th parameter to the
    1789 **          [sqlite3_set_authorizer | authorizer callback] is the name
    1790 **          of the inner-most trigger or view that is responsible for
    1791 **          the access attempt or NULL if this access attempt is directly from
    1792 **          top-level SQL code.
     1990** Requirements:
     1991** [H12551] [H12552] [H12553] [H12554]
    17931992*/
    17941993/******************************************* 3rd ************ 4th ***********/
    … …  
    18142013#define SQLITE_READ                 20   /* Table Name      Column Name     */
    18152014#define SQLITE_SELECT               21   /* NULL            NULL            */
    1816 #define SQLITE_TRANSACTION          22   /* NULL            NULL            */
     2015#define SQLITE_TRANSACTION          22   /*        NULL            */
    18172016#define SQLITE_UPDATE               23   /* Table Name      Column Name     */
    18182017#define SQLITE_ATTACH               24   /* Filename        NULL            */
    … …  
    18232022#define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
    18242023#define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
    1825 #define SQLITE_FUNCTION             31   /* Function Name   NULL            */
     2024#define SQLITE_FUNCTION             31   /* NULL            Function Name   */
     2025#define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
    18262026#define SQLITE_COPY                  0   /* No longer used */
    18272027
    18282028/*
    1829 ** CAPI3REF: Tracing And Profiling Functions {F12280}
     2029** CAPI3REF: Tracing And Profiling Functions {H12280} <S60400>
     2030** EXPERIMENTAL
    18302031**
    18312032** These routines register callback functions that can be used for
    … …  
    18362037** The callback returns a UTF-8 rendering of the SQL statement text
    18372038** as the statement first begins executing.  Additional callbacks occur
    1838 ** as each triggersubprogram is entered.  The callbacks for triggers
     2039** as each triggersubprogram is entered.  The callbacks for triggers
    18392040** contain a UTF-8 SQL comment that identifies the trigger.
    1840 ** 
     2041**
    18412042** The callback function registered by sqlite3_profile() is invoked
    18422043** as each SQL statement finishes.  The profile callback contains
    … …  
    18442045** of how long that statement took to run.
    18452046**
    1846 ** The sqlite3_profile() API is currently considered experimental and
    1847 ** is subject to change or removal in a future release.
    1848 **
    1849 ** The trigger reporting feature of the trace callback is considered
    1850 ** experimental and is subject to change or removal in future releases.
    1851 ** Future versions of SQLite might also add new trace callback
    1852 ** invocations.
    1853 **
    1854 ** INVARIANTS:
    1855 **
    1856 ** {F12281} The callback function registered by [sqlite3_trace()] is
    1857 **          whenever an SQL statement first begins to execute and
    1858 **          whenever a trigger subprogram first begins to run.
    1859 **
    1860 ** {F12282} Each call to [sqlite3_trace()] overrides the previously
    1861 **          registered trace callback.
    1862 **
    1863 ** {F12283} A NULL trace callback disables tracing.
    1864 **
    1865 ** {F12284} The first argument to the trace callback is a copy of
    1866 **          the pointer which was the 3rd argument to [sqlite3_trace()].
    1867 **
    1868 ** {F12285} The second argument to the trace callback is a
    1869 **          zero-terminated UTF8 string containing the original text
    1870 **          of the SQL statement as it was passed into [sqlite3_prepare_v2()]
    1871 **          or the equivalent, or an SQL comment indicating the beginning
    1872 **          of a trigger subprogram.
    1873 **
    1874 ** {F12287} The callback function registered by [sqlite3_profile()] is invoked
    1875 **          as each SQL statement finishes.
    1876 **
    1877 ** {F12288} The first parameter to the profile callback is a copy of
    1878 **          the 3rd parameter to [sqlite3_profile()].
    1879 **
    1880 ** {F12289} The second parameter to the profile callback is a
    1881 **          zero-terminated UTF-8 string that contains the complete text of
    1882 **          the SQL statement as it was processed by [sqlite3_prepare_v2()]
    1883 **          or the equivalent.
    1884 **
    1885 ** {F12290} The third parameter to the profile  callback is an estimate
    1886 **          of the number of nanoseconds of wall-clock time required to
    1887 **          run the SQL statement from start to finish.
    1888 */
    1889 void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
    1890 void *sqlite3_profile(sqlite3*,
     2047** Requirements:
     2048** [H12281] [H12282] [H12283] [H12284] [H12285] [H12287] [H12288] [H12289]
     2049** [H12290]
     2050*/
     2051SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
     2052SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
    18912053   void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
    18922054
    18932055/*
    1894 ** CAPI3REF: Query Progress Callbacks {F12910}
     2056** CAPI3REF: Query Progress Callbacks {
    18952057**
    18962058** This routine configures a callback function - the
    18972059** progress callback - that is invoked periodically during long
    18982060** running calls to [sqlite3_exec()], [sqlite3_step()] and
    1899 ** [sqlite3_get_table()].   An example use for this
     2061** [sqlite3_get_table()]. 
    19002062** interface is to keep a GUI updated during a large query.
    19012063**
    1902 ** If the progress callback returns non-zero, the opertion is
     2064** If the progress callback returns non-zero, the opertion is
    19032065** interrupted.  This feature can be used to implement a
    1904 ** "Cancel" button on a GUI dialog box.
    1905 **
    1906 ** INVARIANTS:
    1907 **
    1908 ** {F12911} The callback function registered by [sqlite3_progress_handler()]
    1909 **          is invoked periodically during long running calls to
    1910 **          [sqlite3_step()].
    1911 **
    1912 ** {F12912} The progress callback is invoked once for every N virtual
    1913 **          machine opcodes, where N is the second argument to
    1914 **          the [sqlite3_progress_handler()] call that registered
    1915 **          the callback.  <todo>What if N is less than 1?</todo>
    1916 **
    1917 ** {F12913} The progress callback itself is identified by the third
    1918 **          argument to [sqlite3_progress_handler()].
    1919 **
    1920 ** {F12914} The fourth argument [sqlite3_progress_handler()] is a
    1921 ***         void pointer passed to the progress callback
    1922 **          function each time it is invoked.
    1923 **
    1924 ** {F12915} If a call to [sqlite3_step()] results in fewer than
    1925 **          N opcodes being executed,
    1926 **          then the progress callback is never invoked. {END}
    1927 **
    1928 ** {F12916} Every call to [sqlite3_progress_handler()]
    1929 **          overwrites any previously registere progress handler.
    1930 **
    1931 ** {F12917} If the progress handler callback is NULL then no progress
    1932 **          handler is invoked.
    1933 **
    1934 ** {F12918} If the progress callback returns a result other than 0, then
    1935 **          the behavior is a if [sqlite3_interrupt()] had been called.
    1936 */
    1937 void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
    1938 
    1939 /*
    1940 ** CAPI3REF: Opening A New Database Connection {F12700}
    1941 **
    1942 ** These routines open an SQLite database file whose name
    1943 ** is given by the filename argument.
    1944 ** The filename argument is interpreted as UTF-8
    1945 ** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16
    1946 ** in the native byte order for [sqlite3_open16()].
    1947 ** An [sqlite3*] handle is usually returned in *ppDb, even
    1948 ** if an error occurs.  The only exception is if SQLite is unable
    1949 ** to allocate memory to hold the [sqlite3] object, a NULL will
    1950 ** be written into *ppDb instead of a pointer to the [sqlite3] object.
    1951 ** If the database is opened (and/or created)
    1952 ** successfully, then [SQLITE_OK] is returned.  Otherwise an
    1953 ** error code is returned.  The
    1954 ** [sqlite3_errmsg()] or [sqlite3_errmsg16()]  routines can be used to obtain
     2066** "Cancel" button on a GUI progress dialog box.
     2067**
     2068** The progress handler must not do anything that will modify
     2069** the database connection that invoked the progress handler.
     2070** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
     2071** database connections for the meaning of "modify" in this paragraph.
     2072**
     2073** Requirements:
     2074** [H12911] [H12912] [H12913] [H12914] [H12915] [H12916] [H12917] [H12918]
     2075**
     2076*/
     2077SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
     2078
     2079/*
     2080** CAPI3REF: Opening A New Database Connection {H12700} <S40200>
     2081**
     2082** These routines open an SQLite database file whose name is given by the
     2083** filename argument. The filename argument is interpreted as UTF-8 for
     2084** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
     2085** order for sqlite3_open16(). A [database connection] handle is usually
     2086** returned in *ppDb, even if an error occurs.  The only exception is that
     2087** if SQLite is unable to allocate memory to hold the [sqlite3] object,
     2088** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
     2089** object. If the database is opened (and/or created) successfully, then
     2090** [SQLITE_OK] is returned.  Otherwise an [error code] is returned.  The
     2091** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
    19552092** an English language description of the error.
    19562093**
    19572094** The default encoding for the database will be UTF-8 if
    1958 ** [sqlite3_open()] or [sqlite3_open_v2()] is called and
    1959 ** UTF-16 in the native byte order if [sqlite3_open16()] is used.
     2095** is called and
     2096** UTF-16 in the native byte order if is used.
    19602097**
    19612098** Whether or not an error occurs when it is opened, resources
    1962 ** associated with the [sqlite3*] handle should be released by passing it
    1963 ** to [sqlite3_close()] when it is no longer required.
    1964 **
    1965 ** The [sqlite3_open_v2()] interface works like [sqlite3_open()]
    1966 ** except that it acccepts two additional parameters for additional control
    1967 ** over the new database connection.  The flags parameter can be
    1968 ** one of:
    1969 **
    1970 ** <ol>
    1971 ** <li>  [SQLITE_OPEN_READONLY]
    1972 ** <li>  [SQLITE_OPEN_READWRITE]
    1973 ** <li>  [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]
    1974 ** </ol>
    1975 **
    1976 ** The first value opens the database read-only.
    1977 ** If the database does not previously exist, an error is returned.
    1978 ** The second option opens
    1979 ** the database for reading and writing if possible, or reading only if
    1980 ** if the file is write protected.  In either case the database
    1981 ** must already exist or an error is returned.  The third option
    1982 ** opens the database for reading and writing and creates it if it does
    1983 ** not already exist.
    1984 ** The third options is behavior that is always used for [sqlite3_open()]
    1985 ** and [sqlite3_open16()].
    1986 **
    1987 ** If the 3rd parameter to [sqlite3_open_v2()] is not one of the
    1988 ** combinations shown above then the behavior is undefined.
    1989 **
    1990 ** If the filename is ":memory:", then an private
    1991 ** in-memory database is created for the connection.  This in-memory
    1992 ** database will vanish when the database connection is closed.  Future
    1993 ** version of SQLite might make use of additional special filenames
    1994 ** that begin with the ":" character.  It is recommended that
    1995 ** when a database filename really does begin with
    1996 ** ":" that you prefix the filename with a pathname like "./" to
    1997 ** avoid ambiguity.
    1998 **
    1999 ** If the filename is an empty string, then a private temporary
     2099** associated with the [database connection] handle should be released by
     2100** passing it to [sqlite3_close()] when it is no longer required.
     2101**
     2102** The sqlite3_open_v2() interface works like sqlite3_open()
     2103** except that it accepts two additional parameters for additional control
     2104** over the new database connection.  The flags parameter can take one of
     2105** the following three values, optionally combined with the
     2106** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
     2107** and/or [SQLITE_OPEN_PRIVATECACHE] flags:
     2108**
     2109** <dl>
     2110** <dt>[SQLITE_OPEN_READONLY]</dt>
     2111** <dd>The database is opened in read-only mode.  If the database does not
     2112** already exist, an error is returned.</dd>
     2113**
     2114** <dt>[SQLITE_OPEN_READWRITE]</dt>
     2115** <dd>The database is opened for reading and writing if possible, or reading
     2116** only if the file is write protected by the operating system.  In either
     2117** case the database must already exist, otherwise an error is returned.</dd>
     2118**
     2119** <dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
     2120** <dd>The database is opened for reading and writing, and is creates it if
     2121** it does not already exist. This is the behavior that is always used for
     2122** sqlite3_open() and sqlite3_open16().</dd>
     2123** </dl>
     2124**
     2125** If the 3rd parameter to sqlite3_open_v2() is not one of the
     2126** combinations shown above or one of the combinations shown above combined
     2127** with the [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX],
     2128** [SQLITE_OPEN_SHAREDCACHE] and/or [SQLITE_OPEN_SHAREDCACHE] flags,
     2129** then the behavior is undefined.
     2130**
     2131** If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
     2132** opens in the multi-thread [threading mode] as long as the single-thread
     2133** mode has not been set at compile-time or start-time.  If the
     2134** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
     2135** in the serialized [threading mode] unless single-thread was
     2136** previously selected at compile-time or start-time.
     2137** The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
     2138** eligible to use [shared cache mode], regardless of whether or not shared
     2139** cache is enabled using [sqlite3_enable_shared_cache()].  The
     2140** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
     2141** participate in [shared cache mode] even if it is enabled.
     2142**
     2143** If the filename is ":memory:", then a private, temporary in-memory database
     2144** is created for the connection.  This in-memory database will vanish when
     2145** the database connection is closed.  Future versions of SQLite might
     2146** make use of additional special filenames that begin with the ":" character.
     2147** It is recommended that when a database filename actually does begin with
     2148** a ":" character you should prefix the filename with a pathname such as
     2149** "./" to avoid ambiguity.
     2150**
     2151** If the filename is an empty string, then a private, temporary
    20002152** on-disk database will be created.  This private database will be
    20012153** automatically deleted as soon as the database connection is closed.
    20022154**
    20032155** The fourth parameter to sqlite3_open_v2() is the name of the
    2004 ** [sqlite3_vfs] object that defines the operating system
    2005 ** interface that the new database connection should use.  If the
    2006 ** fourth parameter is a NULL pointer then the default [sqlite3_vfs]
    2007 ** object is used.
    2008 **
    2009 ** <b>Note to windows users:</b>  The encoding used for the filename argument
    2010 ** of [sqlite3_open()] and [sqlite3_open_v2()] must be UTF-8, not whatever
     2156** [sqlite3_vfs] object that defines the operating system interface that
     2157** the new database connection should use.  If the fourth parameter is
     2158** a NULL pointer then the default [sqlite3_vfs] object is used.
     2159**
     2160** <b>Note to Windows users:</b>  The encoding used for the filename argument
     2161** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
    20112162** codepage is currently defined.  Filenames containing international
    20122163** characters must be converted to UTF-8 prior to passing them into
    2013 ** [sqlite3_open()] or [sqlite3_open_v2()].
    2014 **
    2015 ** INVARIANTS:
    2016 **
    2017 ** {F12701} The [sqlite3_open()], [sqlite3_open16()], and
    2018 **          [sqlite3_open_v2()] interfaces create a new
    2019 **          [database connection] associated with
    2020 **          the database file given in their first parameter.
    2021 **
    2022 ** {F12702} The filename argument is interpreted as UTF-8
    2023 **          for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16
    2024 **          in the native byte order for [sqlite3_open16()].
    2025 **
    2026 ** {F12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()],
    2027 **          or [sqlite3_open_v2()] writes a pointer to a new
    2028 **          [database connection] into *ppDb.
    2029 **
    2030 ** {F12704} The [sqlite3_open()], [sqlite3_open16()], and
    2031 **          [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success,
    2032 **          or an appropriate [error code] on failure.
    2033 **
    2034 ** {F12706} The default text encoding for a new database created using
    2035 **          [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8.
    2036 **
    2037 ** {F12707} The default text encoding for a new database created using
    2038 **          [sqlite3_open16()] will be UTF-16.
    2039 **
    2040 ** {F12709} The [sqlite3_open(F,D)] interface is equivalent to
    2041 **          [sqlite3_open_v2(F,D,G,0)] where the G parameter is
    2042 **          [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE].
    2043 **
    2044 ** {F12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
    2045 **          bit value [SQLITE_OPEN_READONLY] then the database is opened
    2046 **          for reading only.
    2047 **
    2048 ** {F12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
    2049 **          bit value [SQLITE_OPEN_READWRITE] then the database is opened
    2050 **          reading and writing if possible, or for reading only if the
    2051 **          file is write protected by the operating system.
    2052 **
    2053 ** {F12713} If the G parameter to [sqlite3_open(v2(F,D,G,V)] omits the
    2054 **          bit value [SQLITE_OPEN_CREATE] and the database does not
    2055 **          previously exist, an error is returned.
    2056 **
    2057 ** {F12714} If the G parameter to [sqlite3_open(v2(F,D,G,V)] contains the
    2058 **          bit value [SQLITE_OPEN_CREATE] and the database does not
    2059 **          previously exist, then an attempt is made to create and
    2060 **          initialize the database.
    2061 **
    2062 ** {F12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()],
    2063 **          or [sqlite3_open_v2()] is ":memory:", then an private,
    2064 **          ephemeral, in-memory database is created for the connection.
    2065 **          <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
    2066 **          in sqlite3_open_v2()?</todo>
    2067 **
    2068 ** {F12719} If the filename is NULL or an empty string, then a private,
    2069 **          ephermeral on-disk database will be created.
    2070 **          <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
    2071 **          in sqlite3_open_v2()?</todo>
    2072 **
    2073 ** {F12721} The [database connection] created by
    2074 **          [sqlite3_open_v2(F,D,G,V)] will use the
    2075 **          [sqlite3_vfs] object identified by the V parameter, or
    2076 **          the default [sqlite3_vfs] object is V is a NULL pointer.
    2077 */
    2078 int sqlite3_open(
     2164** sqlite3_open() or sqlite3_open_v2().
     2165**
     2166** Requirements:
     2167** [H12701] [H12702] [H12703] [H12704] [H12706] [H12707] [H12709] [H12711]
     2168** [H12712] [H12713] [H12714] [H12717] [H12719] [H12721] [H12723]
     2169*/
     2170SQLITE_API int sqlite3_open(
    20792171  const char *filename,   /* Database filename (UTF-8) */
    20802172  sqlite3 **ppDb          /* OUT: SQLite db handle */
    20812173);
    2082 int sqlite3_open16(
     2174int sqlite3_open16(
    20832175  const void *filename,   /* Database filename (UTF-16) */
    20842176  sqlite3 **ppDb          /* OUT: SQLite db handle */
    20852177);
    2086 int sqlite3_open_v2(
     2178int sqlite3_open_v2(
    20872179  const char *filename,   /* Database filename (UTF-8) */
    20882180  sqlite3 **ppDb,         /* OUT: SQLite db handle */
    … …  
    20922184
    20932185/*
    2094 ** CAPI3REF: Error Codes And Messages {F12800}
    2095 **
    2096 ** The sqlite3_errcode() interface returns the numeric
    2097 ** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code]
    2098 ** for the most recent failed sqlite3_* API call associated
    2099 ** with [sqlite3] handle 'db'. If a prior API call failed but the
    2100 ** most recent API call succeeded, the return value from sqlite3_errcode()
    2101 ** is undefined.
     2186** CAPI3REF: Error Codes And Messages {H12800} <S60200>
     2187**
     2188** The sqlite3_errcode() interface returns the numeric [result code] or
     2189** [extended result code] for the most recent failed sqlite3_* API call
     2190** associated with a [database connection]. If a prior API call failed
     2191** but the most recent API call succeeded, the return value from
     2192** sqlite3_errcode() is undefined.  The sqlite3_extended_errcode()
     2193** interface is the same except that it always returns the
     2194** [extended result code] even when extended result codes are
     2195** disabled.
    21022196**
    21032197** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
    2104 ** text that describes the error, as either UTF8 or UTF16 respectively.
     2198** text that describes the error, as either UTF16 respectively.
    21052199** Memory to hold the error message string is managed internally.
    2106 ** The application does not need to worry with freeing the result.
     2200** The application does not need to worry freeing the result.
    21072201** However, the error string might be overwritten or deallocated by
    21082202** subsequent calls to other SQLite interface functions.
    21092203**
    2110 ** INVARIANTS:
    2111 **
    2112 ** {F12801} The [sqlite3_errcode(D)] interface returns the numeric
    2113 **          [SQLITE_OK | result code] or
    2114 **          [SQLITE_IOERR_READ | extended result code]
    2115 **          for the most recently failed interface call associated
    2116 **          with [database connection] D.
    2117 **
    2118 ** {F12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)]
    2119 **          interfaces return English-language text that describes
    2120 **          the error in the mostly recently failed interface call,
    2121 **          encoded as either UTF8 or UTF16 respectively.
    2122 **
    2123 ** {F12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]
    2124 **          are valid until the next SQLite interface call.
    2125 **
    2126 ** {F12808} Calls to API routines that do not return an error code
    2127 **          (example: [sqlite3_data_count()]) do not
    2128 **          change the error code or message returned by
    2129 **          [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
    2130 **
    2131 ** {F12809} Interfaces that are not associated with a specific
    2132 **          [database connection] (examples:
    2133 **          [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()]
    2134 **          do not change the values returned by
    2135 **          [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
    2136 */
    2137 int sqlite3_errcode(sqlite3 *db);
    2138 const char *sqlite3_errmsg(sqlite3*);
    2139 const void *sqlite3_errmsg16(sqlite3*);
    2140 
    2141 /*
    2142 ** CAPI3REF: SQL Statement Object {F13000}
     2204** When the serialized [threading mode] is in use, it might be the
     2205** case that a second error occurs on a separate thread in between
     2206** the time of the first error and the call to these interfaces.
     2207** When that happens, the second error will be reported since these
     2208** interfaces always report the most recent result.  To avoid
     2209** this, each thread can obtain exclusive use of the [database connection] D
     2210** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
     2211** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
     2212** all calls to the interfaces listed here are completed.
     2213**
     2214** If an interface fails with SQLITE_MISUSE, that means the interface
     2215** was invoked incorrectly by the application.  In that case, the
     2216** error code and message may or may not be set.
     2217**
     2218** Requirements:
     2219** [H12801] [H12802] [H12803] [H12807] [H12808] [H12809]
     2220*/
     2221SQLITE_API int sqlite3_errcode(sqlite3 *db);
     2222SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
     2223SQLITE_API const char *sqlite3_errmsg(sqlite3*);
     2224SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
     2225
     2226/*
     2227** CAPI3REF: SQL Statement Object {H13000} <H13010>
    21432228** KEYWORDS: {prepared statement} {prepared statements}
    21442229**
    2145 ** An instance of this object represent single SQL statements.  This
    2146 ** object is variously known as a "prepared statement" or a
     2230** An instance of this object represent
     2231**
    21472232** "compiled SQL statement" or simply as a "statement".
    2148 ** 
     2233**
    21492234** The life of a statement object goes something like this:
    21502235**
    … …  
    21522237** <li> Create the object using [sqlite3_prepare_v2()] or a related
    21532238**      function.
    2154 ** <li> Bind values to host parameters using
    2155 **      [sqlite3_bind_blob | sqlite3_bind_* interfaces].
     2239** <li> Bind values to
     2240**      .
    21562241** <li> Run the SQL by calling [sqlite3_step()] one or more times.
    21572242** <li> Reset the statement using [sqlite3_reset()] then go back
    … …  
    21662251
    21672252/*
    2168 ** CAPI3REF: Run-time Limits {F12760}
     2253** CAPI3REF: Run-time Limits {
    21692254**
    21702255** This interface allows the size of various constructs to be limited
    … …  
    21762261**
    21772262** If the new limit is a negative number, the limit is unchanged.
    2178 ** For the limit category of SQLITE_LIMIT_XYZ there is a hard upper
    2179 ** bound set by a compile-time C-preprocess macro named SQLITE_MAX_XYZ.
     2263** For the limit category of SQLITE_LIMIT_XYZ there is a
     2264** [limits | hard upper bound]
     2265** set by a compile-time C preprocessor macro named
     2266** [limits | SQLITE_MAX_XYZ].
    21802267** (The "_LIMIT_" in the name is changed to "_MAX_".)
    21812268** Attempts to increase a limit above its hard upper bound are
    … …  
    21852272** both their own internal database and also databases that are controlled
    21862273** by untrusted external sources.  An example application might be a
    2187 ** webbrowser that has its own databases for storing history and
    2188 ** separate databases controlled by javascript applications downloaded
    2189 ** off the internet.  The internal databases can be given the
     2274** webbrowser that has its own databases for storing history and
     2275** separate databases controlled by cript applications downloaded
     2276** off the nternet.  The internal databases can be given the
    21902277** large, default limits.  Databases managed by external sources can
    21912278** be given much smaller limits designed to prevent a denial of service
    2192 ** attach.  Developers might also want to use the [sqlite3_set_authorizer()]
     2279** attac.  Developers might also want to use the [sqlite3_set_authorizer()]
    21932280** interface to further control untrusted SQL.  The size of the database
    21942281** created by an untrusted script can be contained using the
    21952282** [max_page_count] [PRAGMA].
    21962283**
    2197 ** This interface is currently considered experimental and is subject
    2198 ** to change or removal without prior notice.
    2199 **
    2200 ** INVARIANTS:
    2201 **
    2202 ** {F12762} A successful call to [sqlite3_limit(D,C,V)] where V is
    2203 **          positive changes the
    2204 **          limit on the size of construct C in [database connection] D
    2205 **          to the lessor of V and the hard upper bound on the size
    2206 **          of C that is set at compile-time.
    2207 **
    2208 ** {F12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative
    2209 **          leaves the state of [database connection] D unchanged.
    2210 **
    2211 ** {F12769} A successful call to [sqlite3_limit(D,C,V)] returns the
    2212 **          value of the limit on the size of construct C in
    2213 **          in [database connection] D as it was prior to the call.
    2214 */
    2215 int sqlite3_limit(sqlite3*, int id, int newVal);
    2216 
    2217 /*
    2218 ** CAPI3REF: Run-Time Limit Categories {F12790}
     2284** New run-time limit categories may be added in future releases.
     2285**
     2286** Requirements:
     2287** [H12762] [H12766] [H12769]
     2288*/
     2289SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
     2290
     2291/*
     2292** CAPI3REF: Run-Time Limit Categories {H12790} <H12760>
    22192293** KEYWORDS: {limit category} {limit categories}
    2220 **
    2221 ** These constants define various aspects of a [database connection]
    2222 ** that can be limited in size by calls to [sqlite3_limit()].
    2223 ** The meanings of the various limits are as follows:
     2294**
     2295** These constants define various performance limits
     2296** that can be lowered at run-time using [sqlite3_limit()].
     2297** The synopsis of the meanings of the various limits is shown below.
     2298** Additional information is available at [limits | Limits in SQLite].
    22242299**
    22252300** <dl>
    22262301** <dt>SQLITE_LIMIT_LENGTH</dt>
    2227 ** <dd>The maximum size of any
    2228 ** string or blob or table row.<dd>
     2302** <dd>The maximum size of any string or BLOB or table row.<dd>
    22292303**
    22302304** <dt>SQLITE_LIMIT_SQL_LENGTH</dt>
    … …  
    22332307** <dt>SQLITE_LIMIT_COLUMN</dt>
    22342308** <dd>The maximum number of columns in a table definition or in the
    2235 ** result set of a SELECT or the maximum number of columns in an index
     2309** result set of a or the maximum number of columns in an index
    22362310** or in an ORDER BY or GROUP BY clause.</dd>
    22372311**
    … …  
    22502324**
    22512325** <dt>SQLITE_LIMIT_ATTACHED</dt>
    2252 ** <dd>The maximum number of attached databases.</dd>
     2326** <dd>The maximum number of .</dd>
    22532327**
    22542328** <dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
    2255 ** <dd>The maximum length of the pattern argument to the LIKE or
    2256 ** GLOB operators.</dd>
     2329** <dd>The maximum length of the pattern argument to the or
     2330** operators.</dd>
    22572331**
    22582332** <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
    22592333** <dd>The maximum number of variables in an SQL statement that can
    22602334** be bound.</dd>
     2335
     2336
     2337
    22612338** </dl>
    22622339*/
    … …  
    22712348#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
    22722349#define SQLITE_LIMIT_VARIABLE_NUMBER           9
    2273 
    2274 /*
    2275 ** CAPI3REF: Compiling An SQL Statement {F13010}
     2350#define SQLITE_LIMIT_TRIGGER_DEPTH            10
     2351
     2352/*
     2353** CAPI3REF: Compiling An SQL Statement {H13010} <S10000>
     2354** KEYWORDS: {SQL statement compiler}
    22762355**
    22772356** To execute an SQL query, it must first be compiled into a byte-code
    2278 ** program using one of these routines.
    2279 **
    2280 ** The first argument "db" is an [database connection]
    2281 ** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()]
    2282 ** or [sqlite3_open16()].
    2283 ** The second argument "zSql" is the statement to be compiled, encoded
     2357** program using one of these routines.
     2358**
     2359** The first argument, "db", is a [database connection] obtained from a
     2360** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
     2361** [sqlite3_open16()].  The database connection must not have been closed.
     2362**
     2363** The second argument, "zSql", is the statement to be compiled, encoded
    22842364** as either UTF-8 or UTF-16.  The sqlite3_prepare() and sqlite3_prepare_v2()
    2285 ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2()
    2286 ** use UTF-16. {END}
    2287 **
    2288 ** If the nByte argument is less
    2289 ** than zero, then zSql is read up to the first zero terminator.
    2290 ** If nByte is non-negative, then it is the maximum number of
    2291 ** bytes read from zSql.  When nByte is non-negative, the
    2292 ** zSql string ends at either the first '\000' or '\u0000' character or
     2365** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
     2366** use UTF-16.
     2367**
     2368** If the nByte argument is less than zero, then zSql is read up to the
     2369** first zero terminator. If nByte is non-negative, then it is the maximum
     2370** number of  bytes read from zSql.  When nByte is non-negative, the
     2371** zSql string ends at either the first '\000' or '\u0000' character or
    22932372** the nByte-th byte, whichever comes first. If the caller knows
    22942373** that the supplied string is nul-terminated, then there is a small
    2295 ** performance advantage to be had by passing an nByte parameter that
    2296 ** is equal to the number of bytes in the input string <i>including</i> 
    2297 ** the nul-terminator bytes.{END}
    2298 **
    2299 ** *pzTail is made to point to the first byte past the end of the
    2300 ** first SQL statement in zSql.  These routines only compiles the first
    2301 ** statement in zSql, so *pzTail is left pointing to what remains
    2302 ** uncompiled.
     2374** performance advantage to be
     2375** is equal to the number of bytes in the input string <i>including</i>
     2376** the nul-terminator bytes.
     2377**
     2378** e
     2379**
     2380**
     2381** uncompiled.
    23032382**
    23042383** *ppStmt is left pointing to a compiled [prepared statement] that can be
    2305 ** executed using [sqlite3_step()].  Or if there is an error, *ppStmt is
    2306 ** set to NULL.  If the input text contains no SQL (if the input
    2307 ** is and empty string or a comment) then *ppStmt is set to NULL.
    2308 ** {U13018} The calling procedure is responsible for deleting the
    2309 ** compiled SQL statement
    2310 ** using [sqlite3_finalize()] after it has finished with it.
    2311 **
    2312 ** On success, [SQLITE_OK] is returned.  Otherwise an
    2313 ** [error code] is returned.
     2384** executed using [sqlite3_step()].  If there is an error, *ppStmt is set
     2385** to NULL.  If the input text contains no SQL (if the input is an empty
     2386** string or a comment) then *ppStmt is set to NULL.
     2387** The calling procedure is responsible for deleting the compiled
     2388** SQL statement using [sqlite3_finalize()] after it has finished with it.
     2389** ppStmt may not be NULL.
     2390**
     2391** On success, [SQLITE_OK] is returned, otherwise an [error code] is returned.
    23142392**
    23152393** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
    … …  
    23172395** for backwards compatibility, but their use is discouraged.
    23182396** In the "v2" interfaces, the prepared statement
    2319 ** that is returned (the [sqlite3_stmt] object) contains a copy of the 
    2320 ** original SQL text. {END} This causes the [sqlite3_step()] interface to
     2397** that is returned (the [sqlite3_stmt] object) contains a copy of the
     2398** original SQL text. This causes the [sqlite3_step()] interface to
    23212399** behave a differently in two ways:
    23222400**
    … …  
    23272405** statement and try to run it again.  If the schema has changed in
    23282406** a way that makes the statement no longer valid, [sqlite3_step()] will still
    2329 ** return [SQLITE_SCHEMA].  But unlike the legacy behavior,
    2330 ** [SQLITE_SCHEMA] is now a fatal error.  Calling
    2331 ** [sqlite3_prepare_v2()] again will not make the
     2407** return [SQLITE_SCHEMA].  But unlike the legacy behavior, [SQLITE_SCHEMA] is
     2408** now a fatal error.  Calling [sqlite3_prepare_v2()] again will not make the
    23322409** error go away.  Note: use [sqlite3_errmsg()] to find the text
    2333 ** of the parsing error that results in an [SQLITE_SCHEMA] return. {END}
     2410** of the parsing error that results in an [SQLITE_SCHEMA] return.
    23342411** </li>
    23352412**
    23362413** <li>
    2337 ** When an error occurs,
    2338 ** [sqlite3_step()] will return one of the detailed
    2339 ** [error codes] or [extended error codes].
    2340 ** The legacy behavior was that [sqlite3_step()] would only return a generic
    2341 ** [SQLITE_ERROR] result code and you would have to make a second call to
    2342 ** [sqlite3_reset()] in order to find the underlying cause of the problem.
    2343 ** With the "v2" prepare interfaces, the underlying reason for the error is
    2344 ** returned immediately.
     2414** When an error occurs, [sqlite3_step()] will return one of the detailed
     2415** [error codes] or [extended error codes].  The legacy behavior was that
     2416** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
     2417** and you would have to make a second call to [sqlite3_reset()] in order
     2418** to find the underlying cause of the problem. With the "v2" prepare
     2419** interfaces, the underlying reason for the error is returned immediately.
    23452420** </li>
    23462421** </ol>
    23472422**
    2348 ** INVARIANTS:
    2349 **
    2350 ** {F13011} The [sqlite3_prepare(db,zSql,...)] and
    2351 **          [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the
    2352 **          text in their zSql parameter as UTF-8.
    2353 **
    2354 ** {F13012} The [sqlite3_prepare16(db,zSql,...)] and
    2355 **          [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the
    2356 **          text in their zSql parameter as UTF-16 in the native byte order.
    2357 **
    2358 ** {F13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
    2359 **          and its variants is less than zero, then SQL text is
    2360 **          read from zSql is read up to the first zero terminator.
    2361 **
    2362 ** {F13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
    2363 **          and its variants is non-negative, then at most nBytes bytes
    2364 **          SQL text is read from zSql.
    2365 **
    2366 ** {F13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants
    2367 **          if the zSql input text contains more than one SQL statement
    2368 **          and pzTail is not NULL, then *pzTail is made to point to the
    2369 **          first byte past the end of the first SQL statement in zSql.
    2370 **          <todo>What does *pzTail point to if there is one statement?</todo>
    2371 **
    2372 ** {F13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)]
    2373 **          or one of its variants writes into *ppStmt a pointer to a new
    2374 **          [prepared statement] or a pointer to NULL
    2375 **          if zSql contains nothing other than whitespace or comments.
    2376 **
    2377 ** {F13019} The [sqlite3_prepare_v2()] interface and its variants return
    2378 **          [SQLITE_OK] or an appropriate [error code] upon failure.
    2379 **
    2380 ** {F13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its
    2381 **          variants returns an error (any value other than [SQLITE_OK])
    2382 **          it first sets *ppStmt to NULL.
    2383 */
    2384 int sqlite3_prepare(
     2423** Requirements:
     2424** [H13011] [H13012] [H13013] [H13014] [H13015] [H13016] [H13019] [H13021]
     2425**
     2426*/
     2427SQLITE_API int sqlite3_prepare(
    23852428  sqlite3 *db,            /* Database handle */
    23862429  const char *zSql,       /* SQL statement, UTF-8 encoded */
    … …  
    23892432  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
    23902433);
    2391 int sqlite3_prepare_v2(
     2434int sqlite3_prepare_v2(
    23922435  sqlite3 *db,            /* Database handle */
    23932436  const char *zSql,       /* SQL statement, UTF-8 encoded */
    … …  
    23962439  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
    23972440);
    2398 int sqlite3_prepare16(
     2441int sqlite3_prepare16(
    23992442  sqlite3 *db,            /* Database handle */
    24002443  const void *zSql,       /* SQL statement, UTF-16 encoded */
    … …  
    24032446  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
    24042447);
    2405 int sqlite3_prepare16_v2(
     2448int sqlite3_prepare16_v2(
    24062449  sqlite3 *db,            /* Database handle */
    24072450  const void *zSql,       /* SQL statement, UTF-16 encoded */
    … …  
    24122455
    24132456/*
    2414 ** CAPIREF: Retrieving Statement SQL {F13100}
    2415 **
    2416 ** This intereface can be used to retrieve a saved copy of the original
    2417 ** SQL text used to create a [prepared statement].
    2418 **
    2419 ** INVARIANTS:
    2420 **
    2421 ** {F13101} If the [prepared statement] passed as
    2422 **          the an argument to [sqlite3_sql()] was compiled
    2423 **          compiled using either [sqlite3_prepare_v2()] or
    2424 **          [sqlite3_prepare16_v2()],
    2425 **          then [sqlite3_sql()] function returns a pointer to a
    2426 **          zero-terminated string containing a UTF-8 rendering
    2427 **          of the original SQL statement.
    2428 **
    2429 ** {F13102} If the [prepared statement] passed as
    2430 **          the an argument to [sqlite3_sql()] was compiled
    2431 **          compiled using either [sqlite3_prepare()] or
    2432 **          [sqlite3_prepare16()],
    2433 **          then [sqlite3_sql()] function returns a NULL pointer.
    2434 **
    2435 ** {F13103} The string returned by [sqlite3_sql(S)] is valid until the
    2436 **          [prepared statement] S is deleted using [sqlite3_finalize(S)].
    2437 */
    2438 const char *sqlite3_sql(sqlite3_stmt *pStmt);
    2439 
    2440 /*
    2441 ** CAPI3REF:  Dynamically Typed Value Object  {F15000}
     2457** CAPI3REF: Retrieving Statement SQL {H13100} <H13000>
     2458**
     2459** This interface can be used to retrieve a saved copy of the original
     2460** SQL text used to create a [prepared statement] if that statement was
     2461** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
     2462**
     2463** Requirements:
     2464** [H13101] [H13102] [H13103]
     2465*/
     2466SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
     2467
     2468/*
     2469** CAPI3REF: Dynamically Typed Value Object {H15000} <S20200>
    24422470** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
    24432471**
    24442472** SQLite uses the sqlite3_value object to represent all values
    2445 ** that can be stored in a database table.
    2446 ** SQLite uses dynamic typing for the values it stores. 
    2447 ** Values stored in sqlite3_value objects can be
    2448 ** be integers, floating point values, strings, BLOBs, or NULL.
     2473** that can be stored in a database table. SQLite uses dynamic typing
     2474** for the values it stores. Values stored in sqlite3_value objects
     2475** can be integers, floating point values, strings, BLOBs, or NULL.
    24492476**
    24502477** An sqlite3_value object may be either "protected" or "unprotected".
    24512478** Some interfaces require a protected sqlite3_value.  Other interfaces
    24522479** will accept either a protected or an unprotected sqlite3_value.
    2453 ** Every interface that accepts sqlite3_value arguments specifies 
     2480** Every interface that accepts sqlite3_value arguments specifies
    24542481** whether or not it requires a protected sqlite3_value.
    24552482**
    … …  
    24582485** sqlite3_value object but no mutex is held for an unprotected
    24592486** sqlite3_value object.  If SQLite is compiled to be single-threaded
    2460 ** (with SQLITE_THREADSAFE=0 and with [sqlite3_threadsafe()] returning 0)
    2461 ** then there is no distinction between
    2462 ** protected and unprotected sqlite3_value objects and they can be
    2463 ** used interchangable.  However, for maximum code portability it
    2464 ** is recommended that applications make the distinction between
    2465 ** between protected and unprotected sqlite3_value objects even if
    2466 ** they are single threaded.
     2487** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
     2488** or if SQLite is run in one of reduced mutex modes
     2489** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
     2490** then there is no distinction between protected and unprotected
     2491** sqlite3_value objects and they can be used interchangeably.  However,
     2492** for maximum code portability it is recommended that applications
     2493** still make the distinction between between protected and unprotected
     2494** sqlite3_value objects even when not strictly required.
    24672495**
    24682496** The sqlite3_value objects that are passed as parameters into the
    2469 ** implementation of application-defined SQL functions are protected.
     2497** implementation of are protected.
    24702498** The sqlite3_value object returned by
    24712499** [sqlite3_column_value()] is unprotected.
    24722500** Unprotected sqlite3_value objects may only be used with
    2473 ** [sqlite3_result_value()] and [sqlite3_bind_value()].  All other
    2474 ** interfaces that use sqlite3_value require protected sqlite3_value objects.
     2501** [sqlite3_result_value()] and [sqlite3_bind_value()].
     2502** The [sqlite3_value_blob | sqlite3_value_type()] family of
     2503** interfaces require protected sqlite3_value objects.
    24752504*/
    24762505typedef struct Mem sqlite3_value;
    24772506
    24782507/*
    2479 ** CAPI3REF:  SQL Function Context Object {F16001}
     2508** CAPI3REF:
    24802509**
    24812510** The context in which an SQL function executes is stored in an
    2482 ** sqlite3_context object.  A pointer to an sqlite3_context
    2483 ** object is always first parameter to application-defined SQL functions.
     2511** sqlite3_context object.  A pointer to an sqlite3_context object
     2512** is always first parameter to [application-defined SQL functions].
     2513** The application-defined SQL function implementation will pass this
     2514** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
     2515** [sqlite3_aggregate_context()], [sqlite3_user_data()],
     2516** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
     2517** and/or [sqlite3_set_auxdata()].
    24842518*/
    24852519typedef struct sqlite3_context sqlite3_context;
    24862520
    24872521/*
    2488 ** CAPI3REF:  Binding Values To Prepared Statements {F13500}
    2489 **
    2490 ** In the SQL strings input to [sqlite3_prepare_v2()] and its
    2491 ** variants, literals may be replace by a parameter in one
    2492 ** of these forms:
     2522** CAPI3REF: Binding Values To Prepared Statements {H13500} <S70300>
     2523** KEYWORDS: {host parameter} {host parameters} {host parameter name}
     2524** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
     2525**
     2526** In the SQL strings input to [sqlite3_prepare_v2()] and its variants,
     2527** literals may be replaced by a [parameter] that matches one of following
     2528** templates:
    24932529**
    24942530** <ul>
    … …  
    25002536** </ul>
    25012537**
    2502 ** In the parameter forms shown above NNN is an integer literal,
    2503 ** VVV alpha-numeric parameter name.
    2504 ** The values of these parameters (also called "host parameter names"
    2505 ** or "SQL parameters")
     2538** In the templates above, NNN represents an integer literal,
     2539** and VVV represents an alphanumeric identifer.  The values of these
     2540** parameters (also called "host parameter names" or "SQL parameters")
    25062541** can be set using the sqlite3_bind_*() routines defined here.
    25072542**
    2508 ** The first argument to the sqlite3_bind_*() routines always
    2509 ** is a pointer to the [sqlite3_stmt] object returned from
    2510 ** [sqlite3_prepare_v2()] or its variants. The second
    2511 ** argument is the index of the parameter to be set. The
    2512 ** first parameter has an index of 1.  When the same named
    2513 ** parameter is used more than once, second and subsequent
    2514 ** occurrences have the same index as the first occurrence.
     2543** The first argument to the sqlite3_bind_*() routines is always
     2544** a pointer to the [sqlite3_stmt] object returned from
     2545** [sqlite3_prepare_v2()] or its variants.
     2546**
     2547** The second argument is the index of the SQL parameter to be set.
     2548** The leftmost SQL parameter has an index of 1.  When the same named
     2549** SQL parameter is used more than once, second and subsequent
     2550** occurrences have the same index as the first occurrence.
    25152551** The index for named parameters can be looked up using the
    2516 ** [sqlite3_bind_parameter_name()] API if desired.  The index
     2552** [sqlite3_bind_parameter_()] API if desired.  The index
    25172553** for "?NNN" parameters is the value of NNN.
    2518 ** The NNN value must be between 1 and the compile-time
    2519 ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999).
     2554** The NNN value must be between 1 and the
     2555** parameter (default value: 999).
    25202556**
    25212557** The third argument is the value to bind to the parameter.
    25222558**
    2523 ** In those
    2524 ** routines that have a fourth argument, its value is the number of bytes
    2525 ** in the parameter.  To be clear: the value is the number of <u>bytes</u>
    2526 ** in the value, not the number of characters.
     2559** In those routines that have a fourth argument, its value is the
     2560** number of bytes in the parameter.  To be clear: the value is the
     2561** number of <u>bytes</u> in the value, not the number of characters.
    25272562** If the fourth parameter is negative, the length of the string is
    2528 ** number of bytes up to the first zero terminator.
     2563** number of bytes up to the first zero terminator.
    25292564**
    25302565** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
    … …  
    25382573**
    25392574** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
    2540 ** is filled with zeros.  A zeroblob uses a fixed amount of memory
    2541 ** (just an integer to hold it size) while it is being processed.
    2542 ** Zeroblobs are intended to serve as place-holders for BLOBs whose
    2543 ** content is later written using 
    2544 ** [sqlite3_blob_open | increment BLOB I/O] routines. A negative
    2545 ** value for the zeroblob results in a zero-length BLOB.
     2575** is filled with zeros.  A zeroblob uses a fixed amount of memory
     2576** (just an integer to hold it size) while it is being processed.
     2577** Zeroblobs are intended to serve as placeholders for BLOBs whose
     2578** content is later written using
     2579** [sqlite3_blob_open | increment
     2580** value for the zeroblob results in a zero-length BLOB.
    25462581**
    25472582** The sqlite3_bind_*() routines must be called after
    … …  
    25532588** These routines return [SQLITE_OK] on success or an error code if
    25542589** anything goes wrong.  [SQLITE_RANGE] is returned if the parameter
    2555 ** index is out of range.  [SQLITE_NOMEM] is returned if malloc fails.
     2590** index is out of range.  [SQLITE_NOMEM] is returned if malloc fails.
    25562591** [SQLITE_MISUSE] might be returned if these routines are called on a
    25572592** virtual machine that is the wrong state or which has already been finalized.
    … …  
    25622597**
    25632598** See also: [sqlite3_bind_parameter_count()],
    2564 ** [sqlite3_bind_parameter_name()], and
    2565 ** [sqlite3_bind_parameter_index()].
    2566 **
    2567 ** INVARIANTS:
    2568 **
    2569 ** {F13506} The [sqlite3_prepare | SQL statement compiler] recognizes
    2570 **          tokens of the forms "?", "?NNN", "$VVV", ":VVV", and "@VVV"
    2571 **          as SQL parameters, where NNN is any sequence of one or more
    2572 **          digits and where VVV is any sequence of one or more
    2573 **          alphanumeric characters or "::" optionally followed by
    2574 **          a string containing no spaces and contained within parentheses.
    2575 **
    2576 ** {F13509} The initial value of an SQL parameter is NULL.
    2577 **
    2578 ** {F13512} The index of an "?" SQL parameter is one larger than the
    2579 **          largest index of SQL parameter to the left, or 1 if
    2580 **          the "?" is the leftmost SQL parameter.
    2581 **
    2582 ** {F13515} The index of an "?NNN" SQL parameter is the integer NNN.
    2583 **
    2584 ** {F13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is
    2585 **          the same as the index of leftmost occurances of the same
    2586 **          parameter, or one more than the largest index over all
    2587 **          parameters to the left if this is the first occurrance
    2588 **          of this parameter, or 1 if this is the leftmost parameter.
    2589 **
    2590 ** {F13521} The [sqlite3_prepare | SQL statement compiler] fail with
    2591 **          an [SQLITE_RANGE] error if the index of an SQL parameter
    2592 **          is less than 1 or greater than SQLITE_MAX_VARIABLE_NUMBER.
    2593 **
    2594 ** {F13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)]
    2595 **          associate the value V with all SQL parameters having an
    2596 **          index of N in the [prepared statement] S.
    2597 **
    2598 ** {F13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)]
    2599 **          override prior calls with the same values of S and N.
    2600 **
    2601 ** {F13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)]
    2602 **          persist across calls to [sqlite3_reset(S)].
    2603 **
    2604 ** {F13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
    2605 **          [sqlite3_bind_text(S,N,V,L,D)], or
    2606 **          [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L
    2607 **          bytes of the blob or string pointed to by V, when L
    2608 **          is non-negative.
    2609 **
    2610 ** {F13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or
    2611 **          [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters
    2612 **          from V through the first zero character when L is negative.
    2613 **
    2614 ** {F13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
    2615 **          [sqlite3_bind_text(S,N,V,L,D)], or
    2616 **          [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
    2617 **          constant [SQLITE_STATIC], SQLite assumes that the value V
    2618 **          is held in static unmanaged space that will not change
    2619 **          during the lifetime of the binding.
    2620 **
    2621 ** {F13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
    2622 **          [sqlite3_bind_text(S,N,V,L,D)], or
    2623 **          [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
    2624 **          constant [SQLITE_TRANSIENT], the routine makes a
    2625 **          private copy of V value before it returns.
    2626 **
    2627 ** {F13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
    2628 **          [sqlite3_bind_text(S,N,V,L,D)], or
    2629 **          [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to
    2630 **          a function, SQLite invokes that function to destroy the
    2631 **          V value after it has finished using the V value.
    2632 **
    2633 ** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound
    2634 **          is a blob of L bytes, or a zero-length blob if L is negative.
    2635 **
    2636 ** {F13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may
    2637 **          be either a [protected sqlite3_value] object or an
    2638 **          [unprotected sqlite3_value] object.
    2639 */
    2640 int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
    2641 int sqlite3_bind_double(sqlite3_stmt*, int, double);
    2642 int sqlite3_bind_int(sqlite3_stmt*, int, int);
    2643 int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
    2644 int sqlite3_bind_null(sqlite3_stmt*, int);
    2645 int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
    2646 int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
    2647 int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
    2648 int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
    2649 
    2650 /*
    2651 ** CAPI3REF: Number Of SQL Parameters {F13600}
    2652 **
    2653 ** This routine can be used to find the number of SQL parameters
    2654 ** in a prepared statement.  SQL parameters are tokens of the
     2599** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
     2600**
     2601** Requirements:
     2602** [H13506] [H13509] [H13512] [H13515] [H13518] [H13521] [H13524] [H13527]
     2603** [H13530] [H13533] [H13536] [H13539] [H13542] [H13545] [H13548] [H13551]
     2604**
     2605*/
     2606SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
     2607SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
     2608SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
     2609SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
     2610SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
     2611SQLITE_API int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
     2612SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
     2613SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
     2614SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
     2615
     2616/*
     2617** CAPI3REF: Number Of SQL Parameters {H13600} <S70300>
     2618**
     2619** This routine can be used to find the number of [SQL parameters]
     2620** in a [prepared statement].  SQL parameters are tokens of the
    26552621** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
    2656 ** place-holders for values that are [sqlite3_bind_blob | bound]
     2622** placeholders for values that are [sqlite3_bind_blob | bound]
    26572623** to the parameters at a later time.
    26582624**
    2659 ** This routine actually returns the index of the largest parameter.
    2660 ** For all forms except ?NNN, this will correspond to the number of
    2661 ** unique parameters.  If parameters of the ?NNN are used, there may
    2662 ** be gaps in the list.
     2625** This routine actually returns the index of the largest
     2626**
     2627**
     2628** be gaps in the list.
    26632629**
    26642630** See also: [sqlite3_bind_blob|sqlite3_bind()],
    … …  
    26662632** [sqlite3_bind_parameter_index()].
    26672633**
    2668 ** INVARIANTS:
    2669 **
    2670 ** {F13601} The [sqlite3_bind_parameter_count(S)] interface returns
    2671 **          the largest index of all SQL parameters in the
    2672 **          [prepared statement] S, or 0 if S
    2673 **          contains no SQL parameters.
    2674 */
    2675 int sqlite3_bind_parameter_count(sqlite3_stmt*);
    2676 
    2677 /*
    2678 ** CAPI3REF: Name Of A Host Parameter {F13620}
     2634** Requirements:
     2635** [H13601]
     2636*/
     2637SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
     2638
     2639/*
     2640** CAPI3REF: Name Of A Host Parameter {H13620} <S70300>
    26792641**
    26802642** This routine returns a pointer to the name of the n-th
    2681 ** SQL parameter in a [prepared statement].
     2643** in a [prepared statement].
    26822644** SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
    26832645** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
    … …  
    26852647** In other words, the initial ":" or "$" or "@" or "?"
    26862648** is included as part of the name.
    2687 ** Parameters of the form "?" without a following integer have no name.
     2649** Parameters of the form "?" without a following integer have no name
     2650** and are also referred to as "anonymous parameters".
    26882651**
    26892652** The first host parameter has an index of 1, not 0.
    … …  
    26912654** If the value n is out of range or if the n-th parameter is
    26922655** nameless, then NULL is returned.  The returned string is
    2693 ** always in the UTF-8 encoding even if the named parameter was
     2656** always in UTF-8 encoding even if the named parameter was
    26942657** originally specified as UTF-16 in [sqlite3_prepare16()] or
    26952658** [sqlite3_prepare16_v2()].
    … …  
    26992662** [sqlite3_bind_parameter_index()].
    27002663**
    2701 ** INVARIANTS:
    2702 **
    2703 ** {F13621} The [sqlite3_bind_parameter_name(S,N)] interface returns
    2704 **          a UTF-8 rendering of the name of the SQL parameter in
    2705 **          [prepared statement] S having index N, or
    2706 **          NULL if there is no SQL parameter with index N or if the
    2707 **          parameter with index N is an anonymous parameter "?".
    2708 */
    2709 const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
    2710 
    2711 /*
    2712 ** CAPI3REF: Index Of A Parameter With A Given Name {F13640}
     2664** Requirements:
     2665** [H13621]
     2666*/
     2667SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
     2668
     2669/*
     2670** CAPI3REF: Index Of A Parameter With A Given Name {H13640} <S70300>
    27132671**
    27142672** Return the index of an SQL parameter given its name.  The
    … …  
    27232681** [sqlite3_bind_parameter_index()].
    27242682**
    2725 ** INVARIANTS:
    2726 **
    2727 ** {F13641} The [sqlite3_bind_parameter_index(S,N)] interface returns
    2728 **          the index of SQL parameter in [prepared statement]
    2729 **          S whose name matches the UTF-8 string N, or 0 if there is
    2730 **          no match.
    2731 */
    2732 int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
    2733 
    2734 /*
    2735 ** CAPI3REF: Reset All Bindings On A Prepared Statement {F13660}
    2736 **
    2737 ** Contrary to the intuition of many, [sqlite3_reset()] does not
    2738 ** reset the [sqlite3_bind_blob | bindings] on a
    2739 ** [prepared statement].  Use this routine to
    2740 ** reset all host parameters to NULL.
    2741 **
    2742 ** INVARIANTS:
    2743 **
    2744 ** {F13661} The [sqlite3_clear_bindings(S)] interface resets all
    2745 **          SQL parameter bindings in [prepared statement] S
    2746 **          back to NULL.
    2747 */
    2748 int sqlite3_clear_bindings(sqlite3_stmt*);
    2749 
    2750 /*
    2751 ** CAPI3REF: Number Of Columns In A Result Set {F13710}
    2752 **
    2753 ** Return the number of columns in the result set returned by the
    2754 ** [prepared statement]. This routine returns 0
    2755 ** if pStmt is an SQL statement that does not return data (for
    2756 ** example an UPDATE).
    2757 **
    2758 ** INVARIANTS:
    2759 **
    2760 ** {F13711} The [sqlite3_column_count(S)] interface returns the number of
    2761 **          columns in the result set generated by the
    2762 **          [prepared statement] S, or 0 if S does not generate
    2763 **          a result set.
    2764 */
    2765 int sqlite3_column_count(sqlite3_stmt *pStmt);
    2766 
    2767 /*
    2768 ** CAPI3REF: Column Names In A Result Set {F13720}
     2683** Requirements:
     2684** [H13641]
     2685*/
     2686SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
     2687
     2688/*
     2689** CAPI3REF: Reset All Bindings On A Prepared Statement {H13660} <S70300>
     2690**
     2691** Contrary to the intuition of many, [sqlite3_reset()] does not reset
     2692** the [sqlite3_bind_blob | bindings] on a [prepared statement].
     2693** Use this routine to reset all host parameters to NULL.
     2694**
     2695** Requirements:
     2696** [H13661]
     2697*/
     2698SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
     2699
     2700/*
     2701** CAPI3REF: Number Of Columns In A Result Set {H13710} <S10700>
     2702**
     2703** Return the number of columns in the result set returned by the
     2704** [prepared statement]. This routine returns 0 if pStmt is an SQL
     2705** statement that does not return data (for example an [UPDATE]).
     2706**
     2707** Requirements:
     2708** [H13711]
     2709*/
     2710SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
     2711
     2712/*
     2713** CAPI3REF: Column Names In A Result Set {H13720} <S10700>
    27692714**
    27702715** These routines return the name assigned to a particular column
    2771 ** in the result set of a SELECT statement.  The sqlite3_column_name()
    2772 ** interface returns a pointer to a zero-terminated UTF8 string
     2716** in the result set of a statement.  The sqlite3_column_name()
     2717** interface returns a pointer to a zero-terminated UTF8 string
    27732718** and sqlite3_column_name16() returns a pointer to a zero-terminated
    2774 ** UTF16 string.  The first parameter is the
    2775 ** [prepared statement] that implements the SELECT statement.
    2776 ** The second parameter is the column number.  The left-most column is
    2777 ** number 0.
    2778 **
    2779 ** The returned string pointer is valid until either the
    2780 ** [prepared statement] is destroyed by [sqlite3_finalize()]
    2781 ** or until the next call sqlite3_column_name() or sqlite3_column_name16()
    2782 ** on the same column.
     2719** UTF-16 string.  The first parameter is the [prepared statement]
     2720** that implements the [SELECT] statement. The second parameter is the
     2721** column number.  The leftmost column is number 0.
     2722**
     2723** The returned string pointer is valid until either the [prepared statement]
     2724** is destroyed by [sqlite3_finalize()] or until the next call to
     2725** sqlite3_column_name() or sqlite3_column_name16() on the same column.
    27832726**
    27842727** If sqlite3_malloc() fails during the processing of either routine
    … …  
    27912734** one release of SQLite to the next.
    27922735**
    2793 ** INVARIANTS:
    2794 **
    2795 ** {F13721} A successful invocation of the [sqlite3_column_name(S,N)]
    2796 **          interface returns the name
    2797 **          of the Nth column (where 0 is the left-most column) for the
    2798 **          result set of [prepared statement] S as a
    2799 **          zero-terminated UTF-8 string.
    2800 **
    2801 ** {F13723} A successful invocation of the [sqlite3_column_name16(S,N)]
    2802 **          interface returns the name
    2803 **          of the Nth column (where 0 is the left-most column) for the
    2804 **          result set of [prepared statement] S as a
    2805 **          zero-terminated UTF-16 string in the native byte order.
    2806 **
    2807 ** {F13724} The [sqlite3_column_name()] and [sqlite3_column_name16()]
    2808 **          interfaces return a NULL pointer if they are unable to
    2809 **          allocate memory memory to hold there normal return strings.
    2810 **
    2811 ** {F13725} If the N parameter to [sqlite3_column_name(S,N)] or
    2812 **          [sqlite3_column_name16(S,N)] is out of range, then the
    2813 **          interfaces returns a NULL pointer.
    2814 **
    2815 ** {F13726} The strings returned by [sqlite3_column_name(S,N)] and
    2816 **          [sqlite3_column_name16(S,N)] are valid until the next
    2817 **          call to either routine with the same S and N parameters
    2818 **          or until [sqlite3_finalize(S)] is called.
    2819 **
    2820 ** {F13727} When a result column of a [SELECT] statement contains
    2821 **          an AS clause, the name of that column is the indentifier
    2822 **          to the right of the AS keyword.
    2823 */
    2824 const char *sqlite3_column_name(sqlite3_stmt*, int N);
    2825 const void *sqlite3_column_name16(sqlite3_stmt*, int N);
    2826 
    2827 /*
    2828 ** CAPI3REF: Source Of Data In A Query Result {F13740}
     2736** Requirements:
     2737** [H13721] [H13723] [H13724] [H13725] [H13726] [H13727]
     2738*/
     2739SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
     2740SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
     2741
     2742/*
     2743** CAPI3REF: Source Of Data In A Query Result {H13740} <S10700>
    28292744**
    28302745** These routines provide a means to determine what column of what
    2831 ** table in which database a result of a SELECT statement comes from.
     2746** table in which database a result of a statement comes from.
    28322747** The name of the database or table or column can be returned as
    2833 ** either a UTF8 or UTF16 string.  The _database_ routines return
     2748** either a UTF16 string.  The _database_ routines return
    28342749** the database name, the _table_ routines return the table name, and
    28352750** the origin_ routines return the column name.
    2836 ** The returned string is valid until
    2837 ** the [prepared statement] is destroyed using
    2838 ** [sqlite3_finalize()] or until the same information is requested
     2751** The returned string is valid until the [prepared statement] is destroyed
     2752** using [sqlite3_finalize()] or until the same information is requested
    28392753** again in a different encoding.
    28402754**
    … …  
    28432757**
    28442758** The first argument to the following calls is a [prepared statement].
    2845 ** These functions return information about the Nth column returned by 
     2759** These functions return information about the Nth column returned by
    28462760** the statement, where N is the second function argument.
    28472761**
    2848 ** If the Nth column returned by the statement is an expression
    2849 ** or subquery and is not a column value, then all of these functions
    2850 ** return NULL.  These routine might also return NULL if a memory
    2851 ** allocation error occurs.  Otherwise, they return the
    2852 ** name of the attached database, table and column that query result
    2853 ** column was extracted from.
     2762** If the Nth column returned by the statement is an expression or
     2763** subquery and is not a column value, then all of these functions return
     2764** NULL.  These routine might also return NULL if a memory allocation error
     2765** occurs.  Otherwise, they return the name of the attached database, table
     2766** and column that query result column was extracted from.
    28542767**
    28552768** As with all other SQLite APIs, those postfixed with "16" return
    28562769** UTF-16 encoded strings, the other functions return UTF-8. {END}
    28572770**
    2858 ** These APIs are only available if the library was compiled with the 
    2859 ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
    2860 **
    2861 ** {U13751}
     2771** These APIs are only available if the library was compiled with the
     2772** preprocessor symbol defined.
     2773**
     2774** {13751}
    28622775** If two or more threads call one or more of these routines against the same
    28632776** prepared statement and column at the same time then the results are
    28642777** undefined.
    28652778**
    2866 ** INVARIANTS:
    2867 **
    2868 ** {F13741} The [sqlite3_column_database_name(S,N)] interface returns either
    2869 **          the UTF-8 zero-terminated name of the database from which the
    2870 **          Nth result column of [prepared statement] S
    2871 **          is extracted, or NULL if the the Nth column of S is a
    2872 **          general expression or if unable to allocate memory
    2873 **          to store the name.
    2874 **         
    2875 ** {F13742} The [sqlite3_column_database_name16(S,N)] interface returns either
    2876 **          the UTF-16 native byte order
    2877 **          zero-terminated name of the database from which the
    2878 **          Nth result column of [prepared statement] S
    2879 **          is extracted, or NULL if the the Nth column of S is a
    2880 **          general expression or if unable to allocate memory
    2881 **          to store the name.
    2882 **         
    2883 ** {F13743} The [sqlite3_column_table_name(S,N)] interface returns either
    2884 **          the UTF-8 zero-terminated name of the table from which the
    2885 **          Nth result column of [prepared statement] S
    2886 **          is extracted, or NULL if the the Nth column of S is a
    2887 **          general expression or if unable to allocate memory
    2888 **          to store the name.
    2889 **         
    2890 ** {F13744} The [sqlite3_column_table_name16(S,N)] interface returns either
    2891 **          the UTF-16 native byte order
    2892 **          zero-terminated name of the table from which the
    2893 **          Nth result column of [prepared statement] S
    2894 **          is extracted, or NULL if the the Nth column of S is a
    2895 **          general expression or if unable to allocate memory
    2896 **          to store the name.
    2897 **         
    2898 ** {F13745} The [sqlite3_column_origin_name(S,N)] interface returns either
    2899 **          the UTF-8 zero-terminated name of the table column from which the
    2900 **          Nth result column of [prepared statement] S
    2901 **          is extracted, or NULL if the the Nth column of S is a
    2902 **          general expression or if unable to allocate memory
    2903 **          to store the name.
    2904 **         
    2905 ** {F13746} The [sqlite3_column_origin_name16(S,N)] interface returns either
    2906 **          the UTF-16 native byte order
    2907 **          zero-terminated name of the table column from which the
    2908 **          Nth result column of [prepared statement] S
    2909 **          is extracted, or NULL if the the Nth column of S is a
    2910 **          general expression or if unable to allocate memory
    2911 **          to store the name.
    2912 **         
    2913 ** {F13748} The return values from
    2914 **          [sqlite3_column_database_name|column metadata interfaces]
    2915 **          are valid
    2916 **          for the lifetime of the [prepared statement]
    2917 **          or until the encoding is changed by another metadata
    2918 **          interface call for the same prepared statement and column.
    2919 **
    2920 ** LIMITATIONS:
    2921 **
    2922 ** {U13751} If two or more threads call one or more
    2923 **          [sqlite3_column_database_name|column metadata interfaces]
    2924 **          the same [prepared statement] and result column
    2925 **          at the same time then the results are undefined.
    2926 */
    2927 const char *sqlite3_column_database_name(sqlite3_stmt*,int);
    2928 const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
    2929 const char *sqlite3_column_table_name(sqlite3_stmt*,int);
    2930 const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
    2931 const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
    2932 const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
    2933 
    2934 /*
    2935 ** CAPI3REF: Declared Datatype Of A Query Result {F13760}
    2936 **
    2937 ** The first parameter is a [prepared statement].
    2938 ** If this statement is a SELECT statement and the Nth column of the
    2939 ** returned result set of that SELECT is a table column (not an
     2779** Requirements:
     2780** [H13741] [H13742] [H13743] [H13744] [H13745] [H13746] [H13748]
     2781**
     2782** If two or more threads call one or more
     2783** [sqlite3_column_database_name | column metadata interfaces]
     2784** for the same [prepared statement] and result column
     2785** at the same time then the results are undefined.
     2786*/
     2787SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
     2788SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
     2789SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
     2790SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
     2791SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
     2792SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
     2793
     2794/*
     2795** CAPI3REF: Declared Datatype Of A Query Result {H13760} <S10700>
     2796**
     2797** The first parameter is a [prepared statement].
     2798** If this statement is a [SELECT] statement and the Nth column of the
     2799** returned result set of that [SELECT] is a table column (not an
    29402800** expression or subquery) then the declared type of the table
    29412801** column is returned.  If the Nth column of the result set is an
    29422802** expression or subquery, then a NULL pointer is returned.
    2943 ** The returned string is always UTF-8 encoded.  {END}
    2944 ** For example, in the database schema:
     2803** The returned string is always UTF-8 encoded. {END}
     2804**
     2805** For example, given the database schema:
    29452806**
    29462807** CREATE TABLE t1(c1 VARIANT);
    29472808**
    2948 ** And the following statement compiled:
     2809** compiled:
    29492810**
    29502811** SELECT c1 + 1, c1 FROM t1;
    29512812**
    2952 ** Then this routine would return the string "VARIANT" for the second
    2953 ** result column (i==1), and a NULL pointer for the first result column
    2954 ** (i==0).
     2813** this routine would return the string "VARIANT" for the second result
     2814** column (i==1), and a NULL pointer for the first result column (i==0).
    29552815**
    29562816** SQLite uses dynamic run-time typing.  So just because a column
    … …  
    29612821** used to hold those values.
    29622822**
    2963 ** INVARIANTS:
    2964 **
    2965 ** {F13761}  A successful call to [sqlite3_column_decltype(S,N)]
    2966 **           returns a zero-terminated UTF-8 string containing the
    2967 **           the declared datatype of the table column that appears
    2968 **           as the Nth column (numbered from 0) of the result set to the
    2969 **           [prepared statement] S.
    2970 **
    2971 ** {F13762}  A successful call to [sqlite3_column_decltype16(S,N)]
    2972 **           returns a zero-terminated UTF-16 native byte order string
    2973 **           containing the declared datatype of the table column that appears
    2974 **           as the Nth column (numbered from 0) of the result set to the
    2975 **           [prepared statement] S.
    2976 **
    2977 ** {F13763}  If N is less than 0 or N is greater than or equal to
    2978 **           the number of columns in [prepared statement] S
    2979 **           or if the Nth column of S is an expression or subquery rather
    2980 **           than a table column or if a memory allocation failure
    2981 **           occurs during encoding conversions, then
    2982 **           calls to [sqlite3_column_decltype(S,N)] or
    2983 **           [sqlite3_column_decltype16(S,N)] return NULL.
    2984 */
    2985 const char *sqlite3_column_decltype(sqlite3_stmt*,int);
    2986 const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
    2987 
    2988 /*
    2989 ** CAPI3REF:  Evaluate An SQL Statement {F13200}
    2990 **
    2991 ** After an [prepared statement] has been prepared with a call
    2992 ** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of
    2993 ** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()],
    2994 ** then this function must be called one or more times to evaluate the
    2995 ** statement.
    2996 **
    2997 ** The details of the behavior of this sqlite3_step() interface depend
     2823** Requirements:
     2824** [H13761] [H13762] [H13763]
     2825*/
     2826SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
     2827SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
     2828
     2829/*
     2830** CAPI3REF: Evaluate An SQL Statement {H13200} <S10000>
     2831**
     2832** After a [prepared statement] has been prepared using either
     2833** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
     2834** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
     2835** must be called one or more times to evaluate the statement.
     2836**
     2837** The details of the behavior of the sqlite3_step() interface depend
    29982838** on whether the statement was prepared using the newer "v2" interface
    29992839** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
    … …  
    30022842** interface will continue to be supported.
    30032843**
    3004 ** In the legacy interface, the return value will be either [SQLITE_BUSY], 
     2844** In the legacy interface, the return value will be either [SQLITE_BUSY],
    30052845** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
    3006 ** With the "v2" interface, any of the other [SQLITE_OK | result code]
    3007 ** or [SQLITE_IOERR_READ | extended result code] might be returned as
    3008 ** well.
     2846** With the "v2" interface, any of the other [result codes] or
     2847** [extended result codes] might be returned as well.
    30092848**
    30102849** [SQLITE_BUSY] means that the database engine was unable to acquire the
    3011 ** database locks it needs to do its job.  If the statement is a COMMIT
     2850** database locks it needs to do its job.  If the statement is a
    30122851** or occurs outside of an explicit transaction, then you can retry the
    3013 ** statement.  If the statement is not a COMMIT and occurs within a
     2852** statement.  If the statement is not a and occurs within a
    30142853** explicit transaction then you should rollback the transaction before
    30152854** continuing.
    … …  
    30202859** machine back to its initial state.
    30212860**
    3022 ** If the SQL statement being executed returns any data, then
    3023 ** [SQLITE_ROW] is returned each time a new row of data is ready
    3024 ** for processing by the caller. The values may be accessed using
    3025 ** the [sqlite3_column_int | column access functions].
     2861** If the SQL statement being executed returns any data, then [SQLITE_ROW]
     2862** is returned each time a new row of data is ready for processing by the
     2863** caller. The values may be accessed using the [column access functions].
    30262864** sqlite3_step() is called again to retrieve the next row of data.
    3027 ** 
     2865**
    30282866** [SQLITE_ERROR] means that a run-time error (such as a constraint
    30292867** violation) has occurred.  sqlite3_step() should not be called again on
    30302868** the VM. More information may be found by calling [sqlite3_errmsg()].
    3031 ** With the legacy interface, a more specific error code (example:
     2869** With the legacy interface, a more specific error code (
    30322870** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
    30332871** can be obtained by calling [sqlite3_reset()] on the
    … …  
    30372875** [SQLITE_MISUSE] means that the this routine was called inappropriately.
    30382876** Perhaps it was called on a [prepared statement] that has
    3039 ** already been [sqlite3_finalize | finalized] or on one that had 
     2877** already been [sqlite3_finalize | finalized] or on one that had
    30402878** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
    30412879** be the case that the same database connection is being used by two or
    30422880** more threads at the same moment in time.
    30432881**
    3044 ** <b>Goofy Interface Alert:</b>
    3045 ** In the legacy interface,
    3046 ** the sqlite3_step() API always returns a generic error code,
    3047 ** [SQLITE_ERROR], following any error other than [SQLITE_BUSY]
    3048 ** and [SQLITE_MISUSE].  You must call [sqlite3_reset()] or
    3049 ** [sqlite3_finalize()] in order to find one of the specific
    3050 ** [error codes] that better describes the error.
     2882** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
     2883** API always returns a generic error code, [SQLITE_ERROR], following any
     2884** error other than [SQLITE_BUSY] and [SQLITE_MISUSE].  You must call
     2885** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
     2886** specific [error codes] that better describes the error.
    30512887** We admit that this is a goofy design.  The problem has been fixed
    30522888** with the "v2" interface.  If you prepare all of your SQL statements
    30532889** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
    3054 ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the
    3055 ** more specific [error codes] are returned directly
     2890** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()]
     2891** more specific [error codes] are returned directly
    30562892** by sqlite3_step().  The use of the "v2" interface is recommended.
    30572893**
    3058 ** INVARIANTS:
    3059 **
    3060 ** {F13202}  If [prepared statement] S is ready to be
    3061 **           run, then [sqlite3_step(S)] advances that prepared statement
    3062 **           until to completion or until it is ready to return another
    3063 **           row of the result set or an interrupt or run-time error occurs.
    3064 **
    3065 ** {F15304}  When a call to [sqlite3_step(S)] causes the
    3066 **           [prepared statement] S to run to completion,
    3067 **           the function returns [SQLITE_DONE].
    3068 **
    3069 ** {F15306}  When a call to [sqlite3_step(S)] stops because it is ready
    3070 **           to return another row of the result set, it returns
    3071 **           [SQLITE_ROW].
    3072 **
    3073 ** {F15308}  If a call to [sqlite3_step(S)] encounters an
    3074 **           [sqlite3_interrupt|interrupt] or a run-time error,
    3075 **           it returns an appropraite error code that is not one of
    3076 **           [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE].
    3077 **
    3078 ** {F15310}  If an [sqlite3_interrupt|interrupt] or run-time error
    3079 **           occurs during a call to [sqlite3_step(S)]
    3080 **           for a [prepared statement] S created using
    3081 **           legacy interfaces [sqlite3_prepare()] or
    3082 **           [sqlite3_prepare16()] then the function returns either
    3083 **           [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE].
    3084 */
    3085 int sqlite3_step(sqlite3_stmt*);
    3086 
    3087 /*
    3088 ** CAPI3REF: Number of columns in a result set {F13770}
    3089 **
    3090 ** Return the number of values in the current row of the result set.
    3091 **
    3092 ** INVARIANTS:
    3093 **
    3094 ** {F13771}  After a call to [sqlite3_step(S)] that returns
    3095 **           [SQLITE_ROW], the [sqlite3_data_count(S)] routine
    3096 **           will return the same value as the
    3097 **           [sqlite3_column_count(S)] function.
    3098 **
    3099 ** {F13772}  After [sqlite3_step(S)] has returned any value other than
    3100 **           [SQLITE_ROW] or before [sqlite3_step(S)] has been
    3101 **           called on the [prepared statement] for
    3102 **           the first time since it was [sqlite3_prepare|prepared]
    3103 **           or [sqlite3_reset|reset], the [sqlite3_data_count(S)]
    3104 **           routine returns zero.
    3105 */
    3106 int sqlite3_data_count(sqlite3_stmt *pStmt);
    3107 
    3108 /*
    3109 ** CAPI3REF: Fundamental Datatypes {F10265}
     2894** Requirements:
     2895** [H13202] [H15304] [H15306] [H15308] [H15310]
     2896*/
     2897SQLITE_API int sqlite3_step(sqlite3_stmt*);
     2898
     2899/*
     2900** CAPI3REF: Number of columns in a result set {H13770} <S10700>
     2901**
     2902** Returns the number of values in the current row of the result set.
     2903**
     2904** Requirements:
     2905** [H13771] [H13772]
     2906*/
     2907SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
     2908
     2909/*
     2910** CAPI3REF: Fundamental Datatypes {H10265} <S10110><S10120>
    31102911** KEYWORDS: SQLITE_TEXT
    31112912**
    3112 ** {F10266}Every value in SQLite has one of five fundamental datatypes:
     2913** {Every value in SQLite has one of five fundamental datatypes:
    31132914**
    31142915** <ul>
    … …  
    31242925** Note that the SQLITE_TEXT constant was also used in SQLite version 2
    31252926** for a completely different meaning.  Software that links against both
    3126 ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not
     2927** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not
    31272928** SQLITE_TEXT.
    31282929*/
    … …  
    31392940
    31402941/*
    3141 ** CAPI3REF: Results Values From A Query {F13800}
     2942** CAPI3REF: Result Values From A Query {H13800} <S10700>
     2943** KEYWORDS: {column access functions}
    31422944**
    31432945** These routines form the "result set query" interface.
    31442946**
    3145 ** These routines return information about
    3146 ** a single column of the current result row of a query.  In every
    3147 ** case the first argument is a pointer to the
    3148 ** [prepared statement] that is being
    3149 ** evaluated (the [sqlite3_stmt*] that was returned from
    3150 ** [sqlite3_prepare_v2()] or one of its variants) and
    3151 ** the second argument is the index of the column for which information
    3152 ** should be returned.  The left-most column of the result set
    3153 ** has an index of 0.
    3154 **
    3155 ** If the SQL statement is not currently point to a valid row, or if the
    3156 ** the column index is out of range, the result is undefined.
     2947** These routines return information about a single column of the current
     2948** result row of a query.  In every case the first argument is a pointer
     2949** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
     2950** that was returned from [sqlite3_prepare_v2()] or one of its variants)
     2951** and the second argument is the index of the column for which information
     2952** should be returned.  The leftmost column of the result set has the index 0.
     2953**
     2954** If the SQL statement does not currently point to a valid row, or if the
     2955** column index is out of range, the result is undefined.
    31572956** These routines may only be called when the most recent call to
    31582957** [sqlite3_step()] has returned [SQLITE_ROW] and neither
    3159 ** [sqlite3_reset()] nor [sqlite3_finalize()] has been call subsequently.
     2958** [sqlite3_reset()] nor [sqlite3_finalize()] ha subsequently.
    31602959** If any of these routines are called after [sqlite3_reset()] or
    31612960** [sqlite3_finalize()] or after [sqlite3_step()] has returned
    … …  
    31632962** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
    31642963** are called from a different thread while any of these routines
    3165 ** are pending, then the results are undefined. 
    3166 **
    3167 ** The sqlite3_column_type() routine returns
     2964** are pending, then the results are undefined.
     2965**
     2966** The sqlite3_column_type() routine returns
    31682967** [SQLITE_INTEGER | datatype code] for the initial data type
    31692968** of the result column.  The returned value is one of [SQLITE_INTEGER],
    … …  
    31752974** following a type conversion.
    31762975**
    3177 ** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 
     2976** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
    31782977** routine returns the number of bytes in that BLOB or string.
    31792978** If the result is a UTF-16 string, then sqlite3_column_bytes() converts
    … …  
    31882987** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
    31892988** even empty strings, are always zero terminated.  The return
    3190 ** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
     2989** value from sqlite3_column_blob() for a zero-length is an arbitrary
    31912990** pointer, possibly even a NULL pointer.
    31922991**
    31932992** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
    3194 ** but leaves the result in UTF-16 in native byte order instead of UTF-8. 
     2993** but leaves the result in UTF-16 in native byte order instead of UTF-8.
    31952994** The zero terminator is not included in this count.
    31962995**
    … …  
    32002999** If the [unprotected sqlite3_value] object returned by
    32013000** [sqlite3_column_value()] is used in any other way, including calls
    3202 ** to routines like
    3203 ** [sqlite3_value_int()], [sqlite3_value_text()], or [sqlite3_value_bytes()],
    3204 ** then the behavior is undefined.
     3001** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
     3002** or [sqlite3_value_bytes()], then the behavior is undefined.
    32053003**
    32063004** These routines attempt to convert the value where appropriate.  For
    32073005** example, if the internal representation is FLOAT and a text result
    3208 ** is requested, [sqlite3_snprintf()] is used internally to do the conversion
    3209 ** automatically.  The following table details the conversions that
    3210 ** are applied:
     3006** is requested, [sqlite3_snprintf()] is used internally to
     3007**
     3008** are applied:
    32113009**
    32123010** <blockquote>
    … …  
    32203018** <tr><td> INTEGER  <td>  FLOAT    <td> Convert from integer to float
    32213019** <tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering of the integer
    3222 ** <tr><td> INTEGER  <td>   BLOB    <td> Same as for INTEGER->TEXT
     3020** <tr><td> INTEGER  <td>   BLOB    <td> Same as INTEGER->TEXT
    32233021** <tr><td>  FLOAT   <td> INTEGER   <td> Convert from float to integer
    32243022** <tr><td>  FLOAT   <td>   TEXT    <td> ASCII rendering of the float
    … …  
    32353033** The table above makes reference to standard C library functions atoi()
    32363034** and atof().  SQLite does not really use these functions.  It has its
    3237 ** on equavalent internal routines.  The atoi() and atof() names are
     3035** ovalent internal routines.  The atoi() and atof() names are
    32383036** used in the table for brevity and because they are familiar to most
    32393037** C programmers.
    … …  
    32413039** Note that when type conversions occur, pointers returned by prior
    32423040** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
    3243 ** sqlite3_column_text16() may be invalidated. 
     3041** sqlite3_column_text16() may be invalidated.
    32443042** Type conversions and pointer invalidations might occur
    32453043** in the following cases:
    32463044**
    32473045** <ul>
    3248 ** <li><p>  The initial content is a BLOB and sqlite3_column_text()
    3249 **          or sqlite3_column_text16() is called.  A zero-terminator might
    3250 **          need to be added to the string.</p></li>
    3251 **
    3252 ** <li><p>  The initial content is UTF-8 text and sqlite3_column_bytes16() or
    3253 **          sqlite3_column_text16() is called.  The content must be converted
    3254 **          to UTF-16.</p></li>
    3255 **
    3256 ** <li><p>  The initial content is UTF-16 text and sqlite3_column_bytes() or
    3257 **          sqlite3_column_text() is called.  The content must be converted
    3258 **          to UTF-8.</p></li>
     3046** <li> The initial content is a BLOB and sqlite3_column_text() or
     3047**      sqlite3_column_text16() is called.  A zero-terminator might
     3048**      need to be added to the string.</li>
     3049** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
     3050**      sqlite3_column_text16() is called.  The content must be converted
     3051**      to UTF-16.</li>
     3052** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
     3053**      sqlite3_column_text() is called.  The content must be converted
     3054**      to UTF-8.</li>
    32593055** </ul>
    32603056**
    … …  
    32623058** not invalidate a prior pointer, though of course the content of the buffer
    32633059** that the prior pointer points to will have been modified.  Other kinds
    3264 ** of conversion are done in place when it is possible, but sometime it is
    3265 ** not possible and in those cases prior pointers are invalidated. 
     3060** of conversion are done in place when it is possible, but sometime
     3061**
    32663062**
    32673063** The safest and easiest to remember policy is to invoke these routines
    32683064** in one of the following ways:
    32693065**
    3270 **  <ul>
     3066** <ul>
    32713067**  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
    32723068**  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
    32733069**  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
    3274 **  </ul>
    3275 **
    3276 ** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),
    3277 ** or sqlite3_column_text16() first to force the result into the desired
    3278 ** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to
    3279 ** find the size of the result.  Do not mix call to sqlite3_column_text() or
    3280 ** sqlite3_column_blob() with calls to sqlite3_column_bytes16().  And do not
    3281 ** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
     3070** </ul>
     3071**
     3072** In other words, you should call sqlite3_column_text(),
     3073** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
     3074** into the desired format, then invoke sqlite3_column_bytes() or
     3075** sqlite3_column_bytes16() to find the size of the result.  Do not mix calls
     3076** to sqlite3_column_text() or sqlite3_column_blob() with calls to
     3077** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
     3078** with calls to sqlite3_column_bytes().
    32823079**
    32833080** The pointers returned are valid until a type conversion occurs as
    32843081** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
    32853082** [sqlite3_finalize()] is called.  The memory space used to hold strings
    3286 ** and blobs is freed automatically.  Do <b>not</b> pass the pointers returned
    3287 ** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into 
     3083** and s is freed automatically.  Do <b>not</b> pass the pointers returned
     3084** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
    32883085** [sqlite3_free()].
    32893086**
    … …  
    32943091** [SQLITE_NOMEM].
    32953092**
    3296 ** INVARIANTS:
    3297 **
    3298 ** {F13803} The [sqlite3_column_blob(S,N)] interface converts the
    3299 **          Nth column in the current row of the result set for
    3300 **          [prepared statement] S into a blob and then returns a
    3301 **          pointer to the converted value.
    3302 **
    3303 ** {F13806} The [sqlite3_column_bytes(S,N)] interface returns the
    3304 **          number of bytes in the blob or string (exclusive of the
    3305 **          zero terminator on the string) that was returned by the
    3306 **          most recent call to [sqlite3_column_blob(S,N)] or
    3307 **          [sqlite3_column_text(S,N)].
    3308 **
    3309 ** {F13809} The [sqlite3_column_bytes16(S,N)] interface returns the
    3310 **          number of bytes in the string (exclusive of the
    3311 **          zero terminator on the string) that was returned by the
    3312 **          most recent call to [sqlite3_column_text16(S,N)].
    3313 **
    3314 ** {F13812} The [sqlite3_column_double(S,N)] interface converts the
    3315 **          Nth column in the current row of the result set for
    3316 **          [prepared statement] S into a floating point value and
    3317 **          returns a copy of that value.
    3318 **
    3319 ** {F13815} The [sqlite3_column_int(S,N)] interface converts the
    3320 **          Nth column in the current row of the result set for
    3321 **          [prepared statement] S into a 64-bit signed integer and
    3322 **          returns the lower 32 bits of that integer.
    3323 **
    3324 ** {F13818} The [sqlite3_column_int64(S,N)] interface converts the
    3325 **          Nth column in the current row of the result set for
    3326 **          [prepared statement] S into a 64-bit signed integer and
    3327 **          returns a copy of that integer.
    3328 **
    3329 ** {F13821} The [sqlite3_column_text(S,N)] interface converts the
    3330 **          Nth column in the current row of the result set for
    3331 **          [prepared statement] S into a zero-terminated UTF-8
    3332 **          string and returns a pointer to that string.
    3333 **
    3334 ** {F13824} The [sqlite3_column_text16(S,N)] interface converts the
    3335 **          Nth column in the current row of the result set for
    3336 **          [prepared statement] S into a zero-terminated 2-byte
    3337 **          aligned UTF-16 native byte order
    3338 **          string and returns a pointer to that string.
    3339 **
    3340 ** {F13827} The [sqlite3_column_type(S,N)] interface returns
    3341 **          one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
    3342 **          [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
    3343 **          the Nth column in the current row of the result set for
    3344 **          [prepared statement] S.
    3345 **
    3346 ** {F13830} The [sqlite3_column_value(S,N)] interface returns a
    3347 **          pointer to an [unprotected sqlite3_value] object for the
    3348 **          Nth column in the current row of the result set for
    3349 **          [prepared statement] S.
    3350 */
    3351 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
    3352 int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
    3353 int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
    3354 double sqlite3_column_double(sqlite3_stmt*, int iCol);
    3355 int sqlite3_column_int(sqlite3_stmt*, int iCol);
    3356 sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
    3357 const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
    3358 const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
    3359 int sqlite3_column_type(sqlite3_stmt*, int iCol);
    3360 sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
    3361 
    3362 /*
    3363 ** CAPI3REF: Destroy A Prepared Statement Object {F13300}
    3364 **
    3365 ** The sqlite3_finalize() function is called to delete a
    3366 ** [prepared statement]. If the statement was
    3367 ** executed successfully, or not executed at all, then SQLITE_OK is returned.
    3368 ** If execution of the statement failed then an
    3369 ** [error code] or [extended error code]
    3370 ** is returned.
     3093** Requirements:
     3094** [H13803] [H13806] [H13809] [H13812] [H13815] [H13818] [H13821] [H13824]
     3095** [H13827] [H13830]
     3096*/
     3097SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
     3098SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
     3099SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
     3100SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
     3101SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
     3102SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
     3103SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
     3104SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
     3105SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
     3106SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
     3107
     3108/*
     3109** CAPI3REF: Destroy A Prepared Statement Object {H13300} <S70300><S30100>
     3110**
     3111** The sqlite3_finalize() function is called to delete a [prepared statement].
     3112** If the statement was executed successfully or not executed at all, then
     3113** SQLITE_OK is returned. If execution of the statement failed then an
     3114** [error code] or [extended error code] is returned.
    33713115**
    33723116** This routine can be called at any point during the execution of the
    3373 ** [prepared statement].  If the virtual machine has not 
     3117** [prepared statement].  If the virtual machine has not
    33743118** completed execution when this routine is called, that is like
    3375 ** encountering an error or an interrupt.  (See [sqlite3_interrupt()].)
    3376 ** Incomplete updates may be rolled back and transactions cancelled, 
    3377 ** depending on the circumstances, and the 
     3119** encountering an error or an
     3120** Incomplete updates may be rolled back and transactions cancel
     3121** depending on the circumstances, and the
    33783122** [error code] returned will be [SQLITE_ABORT].
    33793123**
    3380 ** INVARIANTS:
    3381 **
    3382 ** {F11302} The [sqlite3_finalize(S)] interface destroys the
    3383 **          [prepared statement] S and releases all
    3384 **          memory and file resources held by that object.
    3385 **
    3386 ** {F11304} If the most recent call to [sqlite3_step(S)] for the
    3387 **          [prepared statement] S returned an error,
    3388 **          then [sqlite3_finalize(S)] returns that same error.
    3389 */
    3390 int sqlite3_finalize(sqlite3_stmt *pStmt);
    3391 
    3392 /*
    3393 ** CAPI3REF: Reset A Prepared Statement Object {F13330}
    3394 **
    3395 ** The sqlite3_reset() function is called to reset a
    3396 ** [prepared statement] object.
    3397 ** back to its initial state, ready to be re-executed.
     3124** Requirements:
     3125** [H11302] [H11304]
     3126*/
     3127SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
     3128
     3129/*
     3130** CAPI3REF: Reset A Prepared Statement Object {H13330} <S70300>
     3131**
     3132** The sqlite3_reset() function is called to reset a [prepared statement]
     3133** object back to its initial state, ready to be re-executed.
    33983134** Any SQL statement variables that had values bound to them using
    33993135** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
    34003136** Use [sqlite3_clear_bindings()] to reset the bindings.
    34013137**
    3402 ** {F11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S
     3138** {11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S
    34033139**          back to the beginning of its program.
    34043140**
    3405 ** {F11334} If the most recent call to [sqlite3_step(S)] for
     3141** {
    34063142**          [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
    34073143**          or if [sqlite3_step(S)] has never before been called on S,
    34083144**          then [sqlite3_reset(S)] returns [SQLITE_OK].
    34093145**
    3410 ** {F11336} If the most recent call to [sqlite3_step(S)] for
     3146** {
    34113147**          [prepared statement] S indicated an error, then
    34123148**          [sqlite3_reset(S)] returns an appropriate [error code].
    34133149**
    3414 ** {F11338} The [sqlite3_reset(S)] interface does not change the values
    3415 **          of any [sqlite3_bind_blob|bindings] on [prepared statement] S.
    3416 */
    3417 int sqlite3_reset(sqlite3_stmt *pStmt);
    3418 
    3419 /*
    3420 ** CAPI3REF: Create Or Redefine SQL Functions {F16100}
    3421 ** KEYWORDS: {function creation routines}
    3422 **
    3423 ** These two functions (collectively known as
    3424 ** "function creation routines") are used to add SQL functions or aggregates
    3425 ** or to redefine the behavior of existing SQL functions or aggregates.  The
    3426 ** difference only between the two is that the second parameter, the
    3427 ** name of the (scalar) function or aggregate, is encoded in UTF-8 for
    3428 ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
     3150** {H11338} The [sqlite3_reset(S)] interface does not change the values
     3151**          of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
     3152*/
     3153SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
     3154
     3155/*
     3156** CAPI3REF: Create Or Redefine SQL Functions {H16100} <S20200>
     3157** KEYWORDS: {function creation routines}
     3158** KEYWORDS: {application-defined SQL function}
     3159** KEYWORDS: {application-defined SQL functions}
     3160**
     3161** These two functions (collectively known as "function creation routines")
     3162** are used to add SQL functions or aggregates or to redefine the behavior
     3163** of existing SQL functions or aggregates.  The only difference between the
     3164** two is that the second parameter, the name of the (scalar) function or
     3165** aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16
     3166** for sqlite3_create_function16().
    34293167**
    34303168** The first parameter is the [database connection] to which the SQL
    3431 ** function is to be added.  If a single
    3432 ** program uses more than one [database connection] internally, then SQL
    3433 ** functions must be added individually to each [database connection].
    3434 **
    3435 ** The second parameter is the name of the SQL function to be created
    3436 ** or redefined.
    3437 ** The length of the name is limited to 255 bytes, exclusive of the
    3438 ** zero-terminator.  Note that the name length limit is in bytes, not
     3169** function is to be added.  If a single program uses more than one database
     3170** connection internally, then SQL functions must be added individually to
     3171** each database connection.
     3172**
     3173** The second parameter is the name of the SQL function to be created or
     3174** redefined.  The length of the name is limited to 255 bytes, exclusive of
     3175** the zero-terminator.  Note that the name length limit is in bytes, not
    34393176** characters.  Any attempt to create a function with a longer name
    3440 ** will result in an SQLITE_ERROR error.
    3441 **
    3442 ** The third parameter is the number of arguments that the SQL function or
    3443 ** aggregate takes. If this parameter is negative, then the SQL function or
    3444 ** aggregate may take any number of arguments.
    3445 **
    3446 ** The fourth parameter, eTextRep, specifies what
     3177** will result in [SQLITE_ERROR] being returned.
     3178**
     3179** The third parameter (nArg)
     3180** is the number of arguments that the SQL function or
     3181** aggregate takes. If this parameter is -1, then the SQL function or
     3182** aggregate may take any number of arguments between 0 and the limit
     3183** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]).  If the third
     3184** parameter is less than -1 or greater than 127 then the behavior is
     3185** undefined.
     3186**
     3187** The fourth parameter, eTextRep, specifies what
    34473188** [SQLITE_UTF8 | text encoding] this SQL function prefers for
    34483189** its parameters.  Any SQL function implementation should be able to work
    34493190** work with UTF-8, UTF-16le, or UTF-16be.  But some implementations may be
    3450 ** more efficient with one encoding than another.  It is allowed to
     3191** more efficient with one encoding than another. 
    34513192** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
    34523193** times with the same function but with different values of eTextRep.
    34533194** When multiple implementations of the same function are available, SQLite
    34543195** will pick the one that involves the least amount of data conversion.
    3455 ** If there is only a single implementation which does not care what
    3456 ** text encoding is used, then the fourth argument should be
    3457 ** [SQLITE_ANY].
    3458 **
    3459 ** The fifth parameter is an arbitrary pointer.  The implementation
    3460 ** of the function can gain access to this pointer using
    3461 ** [sqlite3_user_data()].
     3196** If there is only a single implementation which does not care what text
     3197** encoding is used, then the fourth argument should be [SQLITE_ANY].
     3198**
     3199** The fifth parameter is an arbitrary pointer.  The implementation of the
     3200** function can gain access to this pointer using [sqlite3_user_data()].
    34623201**
    34633202** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
    3464 ** pointers to C-language functions that implement the SQL
    3465 ** function or aggregate. A scalar SQL function requires an implementation of
    3466 ** the xFunc callback only, NULL pointers should be passed as the xStep
    3467 ** and xFinal parameters. An aggregate SQL function requires an implementation
    3468 ** of xStep and xFinal and NULL should be passed for xFunc. To delete an
    3469 ** existing SQL function or aggregate, pass NULL for all three function
    3470 ** callback.
     3203** pointers to C-language functions that implement the SQL function or
     3204** aggregate. A scalar SQL function requires an implementation of the xFunc
     3205** callback only, NULL pointers should be passed as the xStep and xFinal
     3206** parameters. An aggregate SQL function requires an implementation of xStep
     3207** and xFinal and NULL should be passed for xFunc. To delete an existing
     3208** SQL function or aggregate, pass NULL for all three function callbacks.
    34713209**
    34723210** It is permitted to register multiple implementations of the same
    34733211** functions with the same name but with either differing numbers of
    3474 ** arguments or differing perferred text encodings.  SQLite will use
    3475 ** the implementation most closely matches the way in which the
    3476 ** SQL function is used.
    3477 **
    3478 ** INVARIANTS:
    3479 **
    3480 ** {F16103} The [sqlite3_create_function16()] interface behaves exactly
    3481 **          like [sqlite3_create_function()] in every way except that it
    3482 **          interprets the zFunctionName argument as
    3483 **          zero-terminated UTF-16 native byte order instead of as a
    3484 **          zero-terminated UTF-8.
    3485 **
    3486 ** {F16106} A successful invocation of
    3487 **          the [sqlite3_create_function(D,X,N,E,...)] interface registers
    3488 **          or replaces callback functions in [database connection] D
    3489 **          used to implement the SQL function named X with N parameters
    3490 **          and having a perferred text encoding of E.
    3491 **
    3492 ** {F16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)]
    3493 **          replaces the P, F, S, and L values from any prior calls with
    3494 **          the same D, X, N, and E values.
    3495 **
    3496 ** {F16112} The [sqlite3_create_function(D,X,...)] interface fails with
    3497 **          a return code of [SQLITE_ERROR] if the SQL function name X is
    3498 **          longer than 255 bytes exclusive of the zero terminator.
    3499 **
    3500 ** {F16118} Either F must be NULL and S and L are non-NULL or else F
    3501 **          is non-NULL and S and L are NULL, otherwise
    3502 **          [sqlite3_create_function(D,X,N,E,P,F,S,L)] returns [SQLITE_ERROR].
    3503 **
    3504 ** {F16121} The [sqlite3_create_function(D,...)] interface fails with an
    3505 **          error code of [SQLITE_BUSY] if there exist [prepared statements]
    3506 **          associated with the [database connection] D.
    3507 **
    3508 ** {F16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an
    3509 **          error code of [SQLITE_ERROR] if parameter N (specifying the number
    3510 **          of arguments to the SQL function being registered) is less
    3511 **          than -1 or greater than 127.
    3512 **
    3513 ** {F16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)]
    3514 **          interface causes callbacks to be invoked for the SQL function
    3515 **          named X when the number of arguments to the SQL function is
    3516 **          exactly N.
    3517 **
    3518 ** {F16130} When N is -1, the [sqlite3_create_function(D,X,N,...)]
    3519 **          interface causes callbacks to be invoked for the SQL function
    3520 **          named X with any number of arguments.
    3521 **
    3522 ** {F16133} When calls to [sqlite3_create_function(D,X,N,...)]
    3523 **          specify multiple implementations of the same function X
    3524 **          and when one implementation has N>=0 and the other has N=(-1)
    3525 **          the implementation with a non-zero N is preferred.
    3526 **
    3527 ** {F16136} When calls to [sqlite3_create_function(D,X,N,E,...)]
    3528 **          specify multiple implementations of the same function X with
    3529 **          the same number of arguments N but with different
    3530 **          encodings E, then the implementation where E matches the
    3531 **          database encoding is preferred.
    3532 **
    3533 ** {F16139} For an aggregate SQL function created using
    3534 **          [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finializer
    3535 **          function L will always be invoked exactly once if the
    3536 **          step function S is called one or more times.
    3537 **
    3538 ** {F16142} When SQLite invokes either the xFunc or xStep function of
    3539 **          an application-defined SQL function or aggregate created
    3540 **          by [sqlite3_create_function()] or [sqlite3_create_function16()],
    3541 **          then the array of [sqlite3_value] objects passed as the
    3542 **          third parameter are always [protected sqlite3_value] objects.
    3543 */
    3544 int sqlite3_create_function(
     3212** arguments or differing preferred text encodings.  SQLite will use
     3213** the implementation that most closely matches the way in which the
     3214** SQL function is used.  A function implementation with a non-negative
     3215** nArg parameter is a better match than a function implementation with
     3216** a negative nArg.  A function where the preferred text encoding
     3217** matches the database encoding is a better
     3218** match than a function where the encoding is different. 
     3219** A function where the encoding difference is between UTF16le and UTF16be
     3220** is a closer match than a function where the encoding difference is
     3221** between UTF8 and UTF16.
     3222**
     3223** Built-in functions may be overloaded by new application-defined functions.
     3224** The first application-defined function with a given name overrides all
     3225** built-in functions in the same [database connection] with the same name.
     3226** Subsequent application-defined functions of the same name only override
     3227** prior application-defined functions that are an exact match for the
     3228** number of parameters and preferred encoding.
     3229**
     3230** An application-defined function is permitted to call other
     3231** SQLite interfaces.  However, such calls must not
     3232** close the database connection nor finalize or reset the prepared
     3233** statement in which the function is running.
     3234**
     3235** Requirements:
     3236** [H16103] [H16106] [H16109] [H16112] [H16118] [H16121] [H16127]
     3237** [H16130] [H16133] [H16136] [H16139] [H16142]
     3238*/
     3239SQLITE_API int sqlite3_create_function(
    35453240  sqlite3 *db,
    35463241  const char *zFunctionName,
    … …  
    35523247  void (*xFinal)(sqlite3_context*)
    35533248);
    3554 int sqlite3_create_function16(
     3249int sqlite3_create_function16(
    35553250  sqlite3 *db,
    35563251  const void *zFunctionName,
    … …  
    35643259
    35653260/*
    3566 ** CAPI3REF: Text Encodings {F10267}
     3261** CAPI3REF: Text Encodings {
    35673262**
    35683263** These constant define integer codes that represent the various
    … …  
    35773272
    35783273/*
    3579 ** CAPI3REF: Obsolete Functions
    3580 **
    3581 ** These functions are all now obsolete.  In order to maintain
    3582 ** backwards compatibility with older code, we continue to support
    3583 ** these functions.  However, new development projects should avoid
     3274** CAPI3REF: Deprecated Functions
     3275** DEPRECATED
     3276**
     3277** These functions are [deprecated].  In order to maintain
     3278** backwards compatibility with older code, these functions continue
     3279** to be supported.  However, new applications should avoid
    35843280** the use of these functions.  To help encourage people to avoid
    3585 ** using these functions, we are not going to tell you want they do.
    3586 */
    3587 int sqlite3_aggregate_count(sqlite3_context*);
    3588 int sqlite3_expired(sqlite3_stmt*);
    3589 int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
    3590 int sqlite3_global_recover(void);
    3591 void sqlite3_thread_cleanup(void);
    3592 int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
    3593 
    3594 /*
    3595 ** CAPI3REF: Obtaining SQL Function Parameter Values {F15100}
     3281** using these functions, we are not going to tell you what they do.
     3282*/
     3283#ifndef SQLITE_OMIT_DEPRECATED
     3284SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
     3285SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
     3286SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
     3287SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
     3288SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
     3289SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
     3290#endif
     3291
     3292/*
     3293** CAPI3REF: Obtaining SQL Function Parameter Values {H15100} <S20200>
    35963294**
    35973295** The C-language implementation of SQL functions and aggregates uses
    … …  
    36113309** object results in undefined behavior.
    36123310**
    3613 ** These routines work just like the corresponding
    3614 ** [sqlite3_column_blob | sqlite3_column_* routines] except that
    3615 ** these routines take a single [protected sqlite3_value] object pointer
    3616 ** instead of an [sqlite3_stmt*] pointer and an integer column number.
    3617 **
    3618 ** The sqlite3_value_text16() interface extracts a UTF16 string
     3311** These routines work just like the corresponding [column access functions]
     3312** except that  these routines take a single [protected sqlite3_value] object
     3313** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
     3314**
     3315** The sqlite3_value_text16() interface extracts a UTF-16 string
    36193316** in the native byte-order of the host machine.  The
    36203317** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
    3621 ** extract UTF16 strings as big-endian and little-endian respectively.
     3318** extract UTF16 strings as big-endian and little-endian respectively.
    36223319**
    36233320** The sqlite3_value_numeric_type() interface attempts to apply
    … …  
    36253322** made to convert the value to an integer or floating point.  If
    36263323** such a conversion is possible without loss of information (in other
    3627 ** words if the value is a string that looks like a number)
    3628 ** then the conversion is done.  Otherwise no conversion occurs.  The
    3629 ** [SQLITE_INTEGER | datatype] after conversion is returned.
    3630 **
    3631 ** Please pay particular attention to the fact that the pointer that
    3632 ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or
     3324** words if the value is a string that looks like a number)
     3325** then the conversion is
     3326** [SQLITE_INTEGER | datatype] after conversion is returned.
     3327**
     3328** Please pay particular attention to the fact that the pointer
     3329** from [sqlite3_value_blob()], [sqlite3_value_text()], or
    36333330** [sqlite3_value_text16()] can be invalidated by a subsequent call to
    36343331** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
    3635 ** or [sqlite3_value_text16()]. 
     3332** or [sqlite3_value_text16()].
    36363333**
    36373334** These routines must be called from the same thread as
    36383335** the SQL function that supplied the [sqlite3_value*] parameters.
    36393336**
    3640 **
    3641 ** INVARIANTS:
    3642 **
    3643 ** {F15103} The [sqlite3_value_blob(V)] interface converts the
    3644 **          [protected sqlite3_value] object V into a blob and then returns a
    3645 **          pointer to the converted value.
    3646 **
    3647 ** {F15106} The [sqlite3_value_bytes(V)] interface returns the
    3648 **          number of bytes in the blob or string (exclusive of the
    3649 **          zero terminator on the string) that was returned by the
    3650 **          most recent call to [sqlite3_value_blob(V)] or
    3651 **          [sqlite3_value_text(V)].
    3652 **
    3653 ** {F15109} The [sqlite3_value_bytes16(V)] interface returns the
    3654 **          number of bytes in the string (exclusive of the
    3655 **          zero terminator on the string) that was returned by the
    3656 **          most recent call to [sqlite3_value_text16(V)],
    3657 **          [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)].
    3658 **
    3659 ** {F15112} The [sqlite3_value_double(V)] interface converts the
    3660 **          [protected sqlite3_value] object V into a floating point value and
    3661 **          returns a copy of that value.
    3662 **
    3663 ** {F15115} The [sqlite3_value_int(V)] interface converts the
    3664 **          [protected sqlite3_value] object V into a 64-bit signed integer and
    3665 **          returns the lower 32 bits of that integer.
    3666 **
    3667 ** {F15118} The [sqlite3_value_int64(V)] interface converts the
    3668 **          [protected sqlite3_value] object V into a 64-bit signed integer and
    3669 **          returns a copy of that integer.
    3670 **
    3671 ** {F15121} The [sqlite3_value_text(V)] interface converts the
    3672 **          [protected sqlite3_value] object V into a zero-terminated UTF-8
    3673 **          string and returns a pointer to that string.
    3674 **
    3675 ** {F15124} The [sqlite3_value_text16(V)] interface converts the
    3676 **          [protected sqlite3_value] object V into a zero-terminated 2-byte
    3677 **          aligned UTF-16 native byte order
    3678 **          string and returns a pointer to that string.
    3679 **
    3680 ** {F15127} The [sqlite3_value_text16be(V)] interface converts the
    3681 **          [protected sqlite3_value] object V into a zero-terminated 2-byte
    3682 **          aligned UTF-16 big-endian
    3683 **          string and returns a pointer to that string.
    3684 **
    3685 ** {F15130} The [sqlite3_value_text16le(V)] interface converts the
    3686 **          [protected sqlite3_value] object V into a zero-terminated 2-byte
    3687 **          aligned UTF-16 little-endian
    3688 **          string and returns a pointer to that string.
    3689 **
    3690 ** {F15133} The [sqlite3_value_type(V)] interface returns
    3691 **          one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
    3692 **          [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
    3693 **          the [sqlite3_value] object V.
    3694 **
    3695 ** {F15136} The [sqlite3_value_numeric_type(V)] interface converts
    3696 **          the [protected sqlite3_value] object V into either an integer or
    3697 **          a floating point value if it can do so without loss of
    3698 **          information, and returns one of [SQLITE_NULL],
    3699 **          [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or
    3700 **          [SQLITE_BLOB] as appropriate for
    3701 **          the [protected sqlite3_value] object V after the conversion attempt.
    3702 */
    3703 const void *sqlite3_value_blob(sqlite3_value*);
    3704 int sqlite3_value_bytes(sqlite3_value*);
    3705 int sqlite3_value_bytes16(sqlite3_value*);
    3706 double sqlite3_value_double(sqlite3_value*);
    3707 int sqlite3_value_int(sqlite3_value*);
    3708 sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
    3709 const unsigned char *sqlite3_value_text(sqlite3_value*);
    3710 const void *sqlite3_value_text16(sqlite3_value*);
    3711 const void *sqlite3_value_text16le(sqlite3_value*);
    3712 const void *sqlite3_value_text16be(sqlite3_value*);
    3713 int sqlite3_value_type(sqlite3_value*);
    3714 int sqlite3_value_numeric_type(sqlite3_value*);
    3715 
    3716 /*
    3717 ** CAPI3REF: Obtain Aggregate Function Context {F16210}
     3337** Requirements:
     3338** [H15103] [H15106] [H15109] [H15112] [H15115] [H15118] [H15121] [H15124]
     3339** [H15127] [H15130] [H15133] [H15136]
     3340*/
     3341SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
     3342SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
     3343SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
     3344SQLITE_API double sqlite3_value_double(sqlite3_value*);
     3345SQLITE_API int sqlite3_value_int(sqlite3_value*);
     3346SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
     3347SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
     3348SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
     3349SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
     3350SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
     3351SQLITE_API int sqlite3_value_type(sqlite3_value*);
     3352SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
     3353
     3354/*
     3355** CAPI3REF: Obtain Aggregate Function Context {H16210} <S20200>
    37183356**
    37193357** The implementation of aggregate SQL functions use this routine to allocate
    3720 ** a structure for storing their state. 
    3721 ** The first time the sqlite3_aggregate_context() routine is
    3722 ** is called for a particular aggregate, SQLite allocates nBytes of memory
    3723 ** zeros that memory, and returns a pointer to it.
    3724 ** On second and subsequent calls to sqlite3_aggregate_context()
    3725 ** for the same aggregate function index, the same buffer is returned.
    3726 ** The implementation
    3727 ** of the aggregate can use the returned buffer to accumulate data.
     3358** a structure for storing their state.
     3359**
     3360**
     3361**
     3362**
     3363**
     3364**
     3365** the returned buffer to accumulate data.
    37283366**
    37293367** SQLite automatically frees the allocated buffer when the aggregate
    37303368** query concludes.
    37313369**
    3732 ** The first parameter should be a copy of the
    3733 ** [sqlite3_context | SQL function context] that is the first
    3734 ** parameter to the callback routine that implements the aggregate
    3735 ** function.
     3370** The first parameter should be a copy of the
     3371** [sqlite3_context | SQL function context] that is the first parameter
     3372** to the callback routine that implements the aggregate function.
    37363373**
    37373374** This routine must be called from the same thread in which
    37383375** the aggregate SQL function is running.
    37393376**
    3740 ** INVARIANTS:
    3741 **
    3742 ** {F16211} The first invocation of [sqlite3_aggregate_context(C,N)] for
    3743 **          a particular instance of an aggregate function (for a particular
    3744 **          context C) causes SQLite to allocation N bytes of memory,
    3745 **          zero that memory, and return a pointer to the allocationed
    3746 **          memory.
    3747 **
    3748 ** {F16213} If a memory allocation error occurs during
    3749 **          [sqlite3_aggregate_context(C,N)] then the function returns 0.
    3750 **
    3751 ** {F16215} Second and subsequent invocations of
    3752 **          [sqlite3_aggregate_context(C,N)] for the same context pointer C
    3753 **          ignore the N parameter and return a pointer to the same
    3754 **          block of memory returned by the first invocation.
    3755 **
    3756 ** {F16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is
    3757 **          automatically freed on the next call to [sqlite3_reset()]
    3758 **          or [sqlite3_finalize()] for the [prepared statement] containing
    3759 **          the aggregate function associated with context C.
    3760 */
    3761 void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
    3762 
    3763 /*
    3764 ** CAPI3REF: User Data For Functions {F16240}
     3377** Requirements:
     3378** [H16211] [H16213] [H16215] [H16217]
     3379*/
     3380SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
     3381
     3382/*
     3383** CAPI3REF: User Data For Functions {H16240} <S20200>
    37653384**
    37663385** The sqlite3_user_data() interface returns a copy of
    37673386** the pointer that was the pUserData parameter (the 5th parameter)
    3768 ** of the the [sqlite3_create_function()]
     3387** of the [sqlite3_create_function()]
    37693388** and [sqlite3_create_function16()] routines that originally
    37703389** registered the application defined function. {END}
    … …  
    37733392** the application-defined function is running.
    37743393**
    3775 ** INVARIANTS:
    3776 **
    3777 ** {F16243} The [sqlite3_user_data(C)] interface returns a copy of the
    3778 **          P pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]
    3779 **          or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that
    3780 **          registered the SQL function associated with
    3781 **          [sqlite3_context] C.
    3782 */
    3783 void *sqlite3_user_data(sqlite3_context*);
    3784 
    3785 /*
    3786 ** CAPI3REF: Database Connection For Functions {F16250}
     3394** Requirements:
     3395** [H16243]
     3396*/
     3397SQLITE_API void *sqlite3_user_data(sqlite3_context*);
     3398
     3399/*
     3400** CAPI3REF: Database Connection For Functions {H16250} <S60600><S20200>
    37873401**
    37883402** The sqlite3_context_db_handle() interface returns a copy of
    37893403** the pointer to the [database connection] (the 1st parameter)
    3790 ** of the the [sqlite3_create_function()]
     3404** of the [sqlite3_create_function()]
    37913405** and [sqlite3_create_function16()] routines that originally
    37923406** registered the application defined function.
    37933407**
    3794 ** INVARIANTS:
    3795 **
    3796 ** {F16253} The [sqlite3_context_db_handle(C)] interface returns a copy of the
    3797 **          D pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]
    3798 **          or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that
    3799 **          registered the SQL function associated with
    3800 **          [sqlite3_context] C.
    3801 */
    3802 sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
    3803 
    3804 /*
    3805 ** CAPI3REF: Function Auxiliary Data {F16270}
     3408** Requirements:
     3409** [H16253]
     3410*/
     3411SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
     3412
     3413/*
     3414** CAPI3REF: Function Auxiliary Data {H16270} <S20200>
    38063415**
    38073416** The following two functions may be used by scalar SQL functions to
    3808 ** associate meta-data with argument values. If the same value is passed to
     3417** associate metadata with argument values. If the same value is passed to
    38093418** multiple invocations of the same SQL function during query execution, under
    3810 ** some circumstances the associated meta-data may be preserved. This may
     3419** some circumstances the associated metadata may be preserved. This may
    38113420** be used, for example, to add a regular-expression matching scalar
    38123421** function. The compiled version of the regular expression is stored as
    3813 ** meta-data associated with the SQL value passed as the regular expression
     3422** metadata associated with the SQL value passed as the regular expression
    38143423** pattern.  The compiled regular expression can be reused on multiple
    38153424** invocations of the same function so that the original pattern string
    38163425** does not need to be recompiled on each invocation.
    38173426**
    3818 ** The sqlite3_get_auxdata() interface returns a pointer to the meta-data
     3427** The sqlite3_get_auxdata() interface returns a pointer to the metadata
    38193428** associated by the sqlite3_set_auxdata() function with the Nth argument
    3820 ** value to the application-defined function.
    3821 ** If no meta-data has been ever been set for the Nth
    3822 ** argument of the function, or if the cooresponding function parameter
    3823 ** has changed since the meta-data was set, then sqlite3_get_auxdata()
    3824 ** returns a NULL pointer.
    3825 **
    3826 ** The sqlite3_set_auxdata() interface saves the meta-data
    3827 ** pointed to by its 3rd parameter as the meta-data for the N-th
     3429** value to the application-defined function. If no metadata has been ever
     3430** been set for the Nth argument of the function, or if the corresponding
     3431** function parameter has changed since the meta-data was set,
     3432** then sqlite3_get_auxdata() returns a NULL pointer.
     3433**
     3434** The sqlite3_set_auxdata() interface saves the metadata
     3435** pointed to by its 3rd parameter as the metadata for the N-th
    38283436** argument of the application-defined function.  Subsequent
    38293437** calls to sqlite3_get_auxdata() might return this data, if it has
    3830 ** not been destroyed. 
    3831 ** If it is not NULL, SQLite will invoke the destructor 
     3438** not been destroyed.
     3439** If it is not NULL, SQLite will invoke the destructor
    38323440** function given by the 4th parameter to sqlite3_set_auxdata() on
    3833 ** the meta-data when the corresponding function parameter changes
     3441** the metadata when the corresponding function parameter changes
    38343442** or when the SQL statement completes, whichever comes first.
    38353443**
    3836 ** SQLite is free to call the destructor and drop meta-data on
    3837 ** any parameter of any function at any time.  The only guarantee
    3838 ** is that the destructor will be called before the metadata is
    3839 ** dropped.
    3840 **
    3841 ** In practice, meta-data is preserved between function calls for
     3444** SQLite is free to call the destructor and drop metadata on any
     3445** parameter of any function at any time.  The only guarantee is that
     3446** the destructor will be called before the metadata is dropped.
     3447**
     3448** In practice, metadata is preserved between function calls for
    38423449** expressions that are constant at compile time. This includes literal
    38433450** values and SQL variables.
    … …  
    38463453** the SQL function is running.
    38473454**
    3848 ** INVARIANTS:
    3849 **
    3850 ** {F16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer
    3851 **          to metadata associated with the Nth parameter of the SQL function
    3852 **          whose context is C, or NULL if there is no metadata associated
    3853 **          with that parameter.
    3854 **
    3855 ** {F16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata
    3856 **          pointer P to the Nth parameter of the SQL function with context
    3857 **          C.
    3858 **
    3859 ** {F16276} SQLite will invoke the destructor D with a single argument
    3860 **          which is the metadata pointer P following a call to
    3861 **          [sqlite3_set_auxdata(C,N,P,D)] when SQLite ceases to hold
    3862 **          the metadata.
    3863 **
    3864 ** {F16277} SQLite ceases to hold metadata for an SQL function parameter
    3865 **          when the value of that parameter changes.
    3866 **
    3867 ** {F16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor
    3868 **          is called for any prior metadata associated with the same function
    3869 **          context C and parameter N.
    3870 **
    3871 ** {F16279} SQLite will call destructors for any metadata it is holding
    3872 **          in a particular [prepared statement] S when either
    3873 **          [sqlite3_reset(S)] or [sqlite3_finalize(S)] is called.
    3874 */
    3875 void *sqlite3_get_auxdata(sqlite3_context*, int N);
    3876 void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
    3877 
    3878 
    3879 /*
    3880 ** CAPI3REF: Constants Defining Special Destructor Behavior {F10280}
    3881 **
    3882 ** These are special value for the destructor that is passed in as the
     3455** Requirements:
     3456** [H16272] [H16274] [H16276] [H16277] [H16278] [H16279]
     3457*/
     3458SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
     3459SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
     3460
     3461
     3462/*
     3463** CAPI3REF: Constants Defining Special Destructor Behavior {H10280} <S30100>
     3464**
     3465** These are special values for the destructor that is passed in as the
    38833466** final argument to routines like [sqlite3_result_blob()].  If the destructor
    38843467** argument is SQLITE_STATIC, it means that the content pointer is constant
    3885 ** and will never change.  It does not need to be destroyed.  The 
     3468** and will never change.  It does not need to be destroyed.  The
    38863469** SQLITE_TRANSIENT value means that the content will likely change in
    38873470** the near future and that SQLite should make its own private copy of
    … …  
    38963479
    38973480/*
    3898 ** CAPI3REF: Setting The Result Of An SQL Function {F16400}
     3481** CAPI3REF: Setting The Result Of An SQL Function {
    38993482**
    39003483** These routines are used by the xFunc or xFinal callbacks that
    … …  
    39033486** for additional information.
    39043487**
    3905 ** These functions work very much like the
    3906 ** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used
    3907 ** to bind values to host parameters in prepared statements.
    3908 ** Refer to the
    3909 ** [sqlite3_bind_blob | sqlite3_bind_* documentation] for
    3910 ** additional information.
     3488** These functions work very much like the [parameter binding] family of
     3489** functions used to bind values to host parameters in prepared statements.
     3490** Refer to the [SQL parameter] documentation for additional information.
    39113491**
    39123492** The sqlite3_result_blob() interface sets the result from
    3913 ** an application defined function to be the BLOB whose content is pointed
     3493** an applicationdefined function to be the BLOB whose content is pointed
    39143494** to by the second parameter and which is N bytes long where N is the
    3915 ** third parameter.
    3916 ** The sqlite3_result_zeroblob() inerfaces set the result of
    3917 ** the application defined function to be a BLOB containing all zero
     3495** third parameter.
     3496**
     3497** The sqlite3_result_zeroblob() interfaces set the result of
     3498** the application-defined function to be a BLOB containing all zero
    39183499** bytes and N bytes in size, where N is the value of the 2nd parameter.
    39193500**
    39203501** The sqlite3_result_double() interface sets the result from
    3921 ** an application defined function to be a floating point value specified
     3502** an applicationdefined function to be a floating point value specified
    39223503** by its 2nd argument.
    39233504**
    … …  
    39273508** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
    39283509** as the text of an error message.  SQLite interprets the error
    3929 ** message string from sqlite3_result_error() as UTF8. SQLite
    3930 ** interprets the string from sqlite3_result_error16() as UTF16 in native
     3510** message string from sqlite3_result_error() as UTF8. SQLite
     3511** interprets the string from sqlite3_result_error16() as UTF16 in native
    39313512** byte order.  If the third parameter to sqlite3_result_error()
    39323513** or sqlite3_result_error16() is negative then SQLite takes as the error
    … …  
    39363517** bytes (not characters) from the 2nd parameter as the error message.
    39373518** The sqlite3_result_error() and sqlite3_result_error16()
    3938 ** routines make a copy private copy of the error message text before
     3519** routines make a private copy of the error message text before
    39393520** they return.  Hence, the calling function can deallocate or
    39403521** modify the text after they return without harm.
    … …  
    39443525** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
    39453526**
    3946 ** The sqlite3_result_toobig() interface causes SQLite
    3947 ** to throw an error indicating that a string or BLOB is to long
    3948 ** to represent.  The sqlite3_result_nomem() interface
    3949 ** causes SQLite to throw an exception indicating that the a
    3950 ** memory allocation failed.
     3527** The sqlite3_result_toobig() interface causes SQLite
     3528**
     3529**
     3530**
     3531** memory allocation failed.
    39513532**
    39523533** The sqlite3_result_int() interface sets the return value
    … …  
    39603541** of the application-defined function to be NULL.
    39613542**
    3962 ** The sqlite3_result_text(), sqlite3_result_text16(), 
     3543** The sqlite3_result_text(), sqlite3_result_text16(),
    39633544** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
    39643545** set the return value of the application-defined function to be
    … …  
    39683549** the 2nd parameter of the sqlite3_result_text* interfaces.
    39693550** If the 3rd parameter to the sqlite3_result_text* interfaces
    3970 ** is negative, then SQLite takes result text from the 2nd parameter 
     3551** is negative, then SQLite takes result text from the 2nd parameter
    39713552** through the first zero character.
    39723553** If the 3rd parameter to the sqlite3_result_text* interfaces
    … …  
    39763557** If the 4th parameter to the sqlite3_result_text* interfaces
    39773558** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
    3978 ** function as the destructor on the text or blob result when it has
     3559** function as the destructor on the text or result when it has
    39793560** finished using that result.
    3980 ** If the 4th parameter to the sqlite3_result_text* interfaces
    3981 ** or sqlite3_result_blob is the special constant SQLITE_STATIC, then
    3982 ** SQLite assumes that the text or blob result is constant space and
    3983 ** does not copy the space or call a destructor when it has
    3984 ** finished using that result.
     3561** If the 4th parameter to the sqlite3_result_text* interfaces
     3562**
     3563**
     3564**
     3565** finished using that result.
    39853566** If the 4th parameter to the sqlite3_result_text* interfaces
    39863567** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
    … …  
    39923573** [unprotected sqlite3_value] object specified by the 2nd parameter.  The
    39933574** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
    3994 ** so that [sqlite3_value] specified in the parameter may change or
     3575** so that [sqlite3_value] specified in the parameter may change or
    39953576** be deallocated after sqlite3_result_value() returns without harm.
    39963577** A [protected sqlite3_value] object may always be used where an
    … …  
    39983579** kind of [sqlite3_value] object can be used with this interface.
    39993580**
    4000 ** If these routines are called from within the different thread 
    4001 ** than the one containing the application-defined function that recieved
     3581** If these routines are called from within the different thread
     3582** than the one containing the application-defined function that recved
    40023583** the [sqlite3_context] pointer, the results are undefined.
    40033584**
    4004 ** INVARIANTS:
    4005 **
    4006 ** {F16403} The default return value from any SQL function is NULL.
    4007 **
    4008 ** {F16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the
    4009 **          return value of function C to be a blob that is N bytes
    4010 **          in length and with content pointed to by V.
    4011 **
    4012 ** {F16409} The [sqlite3_result_double(C,V)] interface changes the
    4013 **          return value of function C to be the floating point value V.
    4014 **
    4015 ** {F16412} The [sqlite3_result_error(C,V,N)] interface changes the return
    4016 **          value of function C to be an exception with error code
    4017 **          [SQLITE_ERROR] and a UTF8 error message copied from V up to the
    4018 **          first zero byte or until N bytes are read if N is positive.
    4019 **
    4020 ** {F16415} The [sqlite3_result_error16(C,V,N)] interface changes the return
    4021 **          value of function C to be an exception with error code
    4022 **          [SQLITE_ERROR] and a UTF16 native byte order error message
    4023 **          copied from V up to the first zero terminator or until N bytes
    4024 **          are read if N is positive.
    4025 **
    4026 ** {F16418} The [sqlite3_result_error_toobig(C)] interface changes the return
    4027 **          value of the function C to be an exception with error code
    4028 **          [SQLITE_TOOBIG] and an appropriate error message.
    4029 **
    4030 ** {F16421} The [sqlite3_result_error_nomem(C)] interface changes the return
    4031 **          value of the function C to be an exception with error code
    4032 **          [SQLITE_NOMEM] and an appropriate error message.
    4033 **
    4034 ** {F16424} The [sqlite3_result_error_code(C,E)] interface changes the return
    4035 **          value of the function C to be an exception with error code E.
    4036 **          The error message text is unchanged.
    4037 **
    4038 ** {F16427} The [sqlite3_result_int(C,V)] interface changes the
    4039 **          return value of function C to be the 32-bit integer value V.
    4040 **
    4041 ** {F16430} The [sqlite3_result_int64(C,V)] interface changes the
    4042 **          return value of function C to be the 64-bit integer value V.
    4043 **
    4044 ** {F16433} The [sqlite3_result_null(C)] interface changes the
    4045 **          return value of function C to be NULL.
    4046 **
    4047 ** {F16436} The [sqlite3_result_text(C,V,N,D)] interface changes the
    4048 **          return value of function C to be the UTF8 string
    4049 **          V up to the first zero if N is negative
    4050 **          or the first N bytes of V if N is non-negative.
    4051 **
    4052 ** {F16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the
    4053 **          return value of function C to be the UTF16 native byte order
    4054 **          string V up to the first zero if N is
    4055 **          negative or the first N bytes of V if N is non-negative.
    4056 **
    4057 ** {F16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the
    4058 **          return value of function C to be the UTF16 big-endian
    4059 **          string V up to the first zero if N is
    4060 **          is negative or the first N bytes or V if N is non-negative.
    4061 **
    4062 ** {F16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the
    4063 **          return value of function C to be the UTF16 little-endian
    4064 **          string V up to the first zero if N is
    4065 **          negative or the first N bytes of V if N is non-negative.
    4066 **
    4067 ** {F16448} The [sqlite3_result_value(C,V)] interface changes the
    4068 **          return value of function C to be [unprotected sqlite3_value]
    4069 **          object V.
    4070 **
    4071 ** {F16451} The [sqlite3_result_zeroblob(C,N)] interface changes the
    4072 **          return value of function C to be an N-byte blob of all zeros.
    4073 **
    4074 ** {F16454} The [sqlite3_result_error()] and [sqlite3_result_error16()]
    4075 **          interfaces make a copy of their error message strings before
    4076 **          returning.
    4077 **
    4078 ** {F16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
    4079 **          [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
    4080 **          [sqlite3_result_text16be(C,V,N,D)], or
    4081 **          [sqlite3_result_text16le(C,V,N,D)] is the constant [SQLITE_STATIC]
    4082 **          then no destructor is ever called on the pointer V and SQLite
    4083 **          assumes that V is immutable.
    4084 **
    4085 ** {F16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
    4086 **          [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
    4087 **          [sqlite3_result_text16be(C,V,N,D)], or
    4088 **          [sqlite3_result_text16le(C,V,N,D)] is the constant
    4089 **          [SQLITE_TRANSIENT] then the interfaces makes a copy of the
    4090 **          content of V and retains the copy.
    4091 **
    4092 ** {F16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
    4093 **          [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
    4094 **          [sqlite3_result_text16be(C,V,N,D)], or
    4095 **          [sqlite3_result_text16le(C,V,N,D)] is some value other than
    4096 **          the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then
    4097 **          SQLite will invoke the destructor D with V as its only argument
    4098 **          when it has finished with the V value.
    4099 */
    4100 void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
    4101 void sqlite3_result_double(sqlite3_context*, double);
    4102 void sqlite3_result_error(sqlite3_context*, const char*, int);
    4103 void sqlite3_result_error16(sqlite3_context*, const void*, int);
    4104 void sqlite3_result_error_toobig(sqlite3_context*);
    4105 void sqlite3_result_error_nomem(sqlite3_context*);
    4106 void sqlite3_result_error_code(sqlite3_context*, int);
    4107 void sqlite3_result_int(sqlite3_context*, int);
    4108 void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
    4109 void sqlite3_result_null(sqlite3_context*);
    4110 void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
    4111 void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
    4112 void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
    4113 void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
    4114 void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
    4115 void sqlite3_result_zeroblob(sqlite3_context*, int n);
    4116 
    4117 /*
    4118 ** CAPI3REF: Define New Collating Sequences {F16600}
     3585** Requirements:
     3586** [H16403] [H16406] [H16409] [H16412] [H16415] [H16418] [H16421] [H16424]
     3587** [H16427] [H16430] [H16433] [H16436] [H16439] [H16442] [H16445] [H16448]
     3588** [H16451] [H16454] [H16457] [H16460] [H16463]
     3589*/
     3590SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
     3591SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
     3592SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
     3593SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
     3594SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
     3595SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
     3596SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
     3597SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
     3598SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
     3599SQLITE_API void sqlite3_result_null(sqlite3_context*);
     3600SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
     3601SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
     3602SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
     3603SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
     3604SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
     3605SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
     3606
     3607/*
     3608** CAPI3REF: Define New Collating Sequences {H16600} <S20300>
    41193609**
    41203610** These functions are used to add new collation sequences to the
    4121 ** [sqlite3*] handle specified as the first argument.
     3611** [
    41223612**
    41233613** The name of the new collation sequence is specified as a UTF-8 string
    … …  
    41273617**
    41283618** The third argument may be one of the constants [SQLITE_UTF8],
    4129 ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied
     3619** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied
    41303620** routine expects to be passed pointers to strings encoded using UTF-8,
    4131 ** UTF-16 little-endian or UTF-16 big-endian respectively. The
    4132 ** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that
     3621** UTF-16 little-endian, or UTF-16 big-endian, respectively. The
     3622** third argument might also be [SQLITE_UTF16] to indicate that the routine
     3623** expects pointers to be UTF-16 strings in the native byte order, or the
     3624** argument can be [SQLITE_UTF16_ALIGNED] if the
    41333625** the routine expects pointers to 16-bit word aligned strings
    4134 ** of UTF16 in the native byte order of the host computer.
     3626** of UTFer.
    41353627**
    41363628** A pointer to the user supplied routine must be passed as the fifth
    41373629** argument.  If it is NULL, this is the same as deleting the collation
    41383630** sequence (so that SQLite cannot call it anymore).
    4139 ** Each time the application
    4140 ** supplied function is invoked, it is passed a copy of the void* passed as
    4141 ** the fourth argument to sqlite3_create_collation() or
    4142 ** sqlite3_create_collation16() as its first parameter.
     3631** Each time the application supplied function is invoked, it is passed
     3632** as its first parameter a copy of the void* passed as the fourth argument
     3633** to sqlite3_create_collation() or sqlite3_create_collation16().
    41433634**
    41443635** The remaining arguments to the application-supplied routine are two strings,
    41453636** each represented by a (length, data) pair and encoded in the encoding
    41463637** that was passed as the third argument when the collation sequence was
    4147 ** registered. {END} The application defined collation routine should
    4148 ** return negative, zero or positive if
    4149 ** the first string is less than, equal to, or greater than the second
    4150 ** string. i.e. (STRING1 - STRING2).
     3638** registered. {END}  The application defined collation routine should
     3639** return negative, zero or positive if the first string is less than,
     3640** equal to, or greater than the second string. i.e. (STRING1 - STRING2).
    41513641**
    41523642** The sqlite3_create_collation_v2() works like sqlite3_create_collation()
    4153 ** excapt that it takes an extra argument which is a destructor for
     3643** excpt that it takes an extra argument which is a destructor for
    41543644** the collation.  The destructor is called when the collation is
    41553645** destroyed and is passed a copy of the fourth parameter void* pointer
    41563646** of the sqlite3_create_collation_v2().
    4157 ** Collations are destroyed when
    4158 ** they are overridden by later calls to the collation creation functions
    4159 ** or when the [sqlite3*] database handle is closed using [sqlite3_close()].
    4160 **
    4161 ** INVARIANTS:
    4162 **
    4163 ** {F16603} A successful call to the
    4164 **          [sqlite3_create_collation_v2(B,X,E,P,F,D)] interface
    4165 **          registers function F as the comparison function used to
    4166 **          implement collation X on [database connection] B for
    4167 **          databases having encoding E.
    4168 **
    4169 ** {F16604} SQLite understands the X parameter to
    4170 **          [sqlite3_create_collation_v2(B,X,E,P,F,D)] as a zero-terminated
    4171 **          UTF-8 string in which case is ignored for ASCII characters and
    4172 **          is significant for non-ASCII characters.
    4173 **
    4174 ** {F16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)]
    4175 **          with the same values for B, X, and E, override prior values
    4176 **          of P, F, and D.
    4177 **
    4178 ** {F16609} The destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
    4179 **          is not NULL then it is called with argument P when the
    4180 **          collating function is dropped by SQLite.
    4181 **
    4182 ** {F16612} A collating function is dropped when it is overloaded.
    4183 **
    4184 ** {F16615} A collating function is dropped when the database connection
    4185 **          is closed using [sqlite3_close()].
    4186 **
    4187 ** {F16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
    4188 **          is passed through as the first parameter to the comparison
    4189 **          function F for all subsequent invocations of F.
    4190 **
    4191 ** {F16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly
    4192 **          the same as a call to [sqlite3_create_collation_v2()] with
    4193 **          the same parameters and a NULL destructor.
    4194 **
    4195 ** {F16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)],
    4196 **          SQLite uses the comparison function F for all text comparison
    4197 **          operations on [database connection] B on text values that
    4198 **          use the collating sequence name X.
    4199 **
    4200 ** {F16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same
    4201 **          as [sqlite3_create_collation(B,X,E,P,F)] except that the
    4202 **          collation name X is understood as UTF-16 in native byte order
    4203 **          instead of UTF-8.
    4204 **
    4205 ** {F16630} When multiple comparison functions are available for the same
    4206 **          collating sequence, SQLite chooses the one whose text encoding
    4207 **          requires the least amount of conversion from the default
    4208 **          text encoding of the database.
    4209 */
    4210 int sqlite3_create_collation(
     3647** Collations are destroyed when they are overridden by later calls to the
     3648** collation creation functions or when the [database connection] is closed
     3649** using [sqlite3_close()].
     3650**
     3651** See also:  [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
     3652**
     3653** Requirements:
     3654** [H16603] [H16604] [H16606] [H16609] [H16612] [H16615] [H16618] [H16621]
     3655** [H16624] [H16627] [H16630]
     3656*/
     3657SQLITE_API int sqlite3_create_collation(
    42113658  sqlite3*,
    42123659  const char *zName,
    … …  
    42153662  int(*xCompare)(void*,int,const void*,int,const void*)
    42163663);
    4217 int sqlite3_create_collation_v2(
     3664int sqlite3_create_collation_v2(
    42183665  sqlite3*,
    42193666  const char *zName,
    … …  
    42233670  void(*xDestroy)(void*)
    42243671);
    4225 int sqlite3_create_collation16(
     3672int sqlite3_create_collation16(
    42263673  sqlite3*,
    4227   const char *zName,
     3674  const
    42283675  int eTextRep,
    42293676  void*,
    … …  
    42323679
    42333680/*
    4234 ** CAPI3REF: Collation Needed Callbacks {F16700}
     3681** CAPI3REF: Collation Needed Callbacks {
    42353682**
    42363683** To avoid having to register all collation sequences before a database
    42373684** can be used, a single callback function may be registered with the
    4238 ** database handle to be called whenever an undefined collation sequence is
    4239 ** required.
     3685**
     3686** required.
    42403687**
    42413688** If the function is registered using the sqlite3_collation_needed() API,
    42423689** then it is passed the names of undefined collation sequences as strings
    4243 ** encoded in UTF-8. {F16703} If sqlite3_collation_needed16() is used, the names
    4244 ** are passed as UTF-16 in machine native byte order. A call to either
    4245 ** function replaces any existing callback.
     3690** encoded in UTF-8. {
     3691**
     3692** function replaces any existing callback.
    42463693**
    42473694** When the callback is invoked, the first argument passed is a copy
    42483695** of the second argument to sqlite3_collation_needed() or
    42493696** sqlite3_collation_needed16().  The second argument is the database
    4250 ** handle.  The third argument is one of [SQLITE_UTF8],
    4251 ** [SQLITE_UTF16BE], or [SQLITE_UTF16LE], indicating the most
    4252 ** desirable form of the collation sequence function required.
    4253 ** The fourth parameter is the name of the
     3697** connection.  The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
     3698** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
     3699** sequence function required.  The fourth parameter is the name of the
    42543700** required collation sequence.
    42553701**
    … …  
    42583704** [sqlite3_create_collation_v2()].
    42593705**
    4260 ** INVARIANTS:
    4261 **
    4262 ** {F16702} A successful call to [sqlite3_collation_needed(D,P,F)]
    4263 **          or [sqlite3_collation_needed16(D,P,F)] causes
    4264 **          the [database connection] D to invoke callback F with first
    4265 **          parameter P whenever it needs a comparison function for a
    4266 **          collating sequence that it does not know about.
    4267 **
    4268 ** {F16704} Each successful call to [sqlite3_collation_needed()] or
    4269 **          [sqlite3_collation_needed16()] overrides the callback registered
    4270 **          on the same [database connection] by prior calls to either
    4271 **          interface.
    4272 **
    4273 ** {F16706} The name of the requested collating function passed in the
    4274 **          4th parameter to the callback is in UTF-8 if the callback
    4275 **          was registered using [sqlite3_collation_needed()] and
    4276 **          is in UTF-16 native byte order if the callback was
    4277 **          registered using [sqlite3_collation_needed16()].
    4278 **
    4279 **
    4280 */
    4281 int sqlite3_collation_needed(
     3706** Requirements:
     3707** [H16702] [H16704] [H16706]
     3708*/
     3709SQLITE_API int sqlite3_collation_needed(
    42823710  sqlite3*,
    42833711  void*,
    42843712  void(*)(void*,sqlite3*,int eTextRep,const char*)
    42853713);
    4286 int sqlite3_collation_needed16(
     3714int sqlite3_collation_needed16(
    42873715  sqlite3*,
    42883716  void*,
    … …  
    42973725** of SQLite.
    42983726*/
    4299 int sqlite3_key(
     3727int sqlite3_key(
    43003728  sqlite3 *db,                   /* Database to be rekeyed */
    43013729  const void *pKey, int nKey     /* The key */
    … …  
    43103738** of SQLite.
    43113739*/
    4312 int sqlite3_rekey(
     3740int sqlite3_rekey(
    43133741  sqlite3 *db,                   /* Database to be rekeyed */
    43143742  const void *pKey, int nKey     /* The new key */
    … …  
    43163744
    43173745/*
    4318 ** CAPI3REF:  Suspend Execution For A Short Time {F10530}
    4319 **
    4320 ** The sqlite3_sleep() function
    4321 ** causes the current thread to suspend execution
     3746** CAPI3REF: Suspend Execution For A Short Time {H10530} <S40410>
     3747**
     3748** The sqlite3_sleep() function causes the current thread to suspend execution
    43223749** for at least a number of milliseconds specified in its parameter.
    43233750**
    4324 ** If the operating system does not support sleep requests with 
    4325 ** millisecond time resolution, then the time will be rounded up to 
    4326 ** the nearest second. The number of milliseconds of sleep actually 
     3751** If the operating system does not support sleep requests with
     3752** millisecond time resolution, then the time will be rounded up to
     3753** the nearest second. The number of milliseconds of sleep actually
    43273754** requested from the operating system is returned.
    43283755**
    … …  
    43303757** method of the default [sqlite3_vfs] object.
    43313758**
    4332 ** INVARIANTS:
    4333 **
    4334 ** {F10533} The [sqlite3_sleep(M)] interface invokes the xSleep
    4335 **          method of the default [sqlite3_vfs|VFS] in order to
    4336 **          suspend execution of the current thread for at least
    4337 **          M milliseconds.
    4338 **
    4339 ** {F10536} The [sqlite3_sleep(M)] interface returns the number of
    4340 **          milliseconds of sleep actually requested of the operating
    4341 **          system, which might be larger than the parameter M.
    4342 */
    4343 int sqlite3_sleep(int);
    4344 
    4345 /*
    4346 ** CAPI3REF:  Name Of The Folder Holding Temporary Files {F10310}
     3759** Requirements: [H10533] [H10536]
     3760*/
     3761SQLITE_API int sqlite3_sleep(int);
     3762
     3763/*
     3764** CAPI3REF: Name Of The Folder Holding Temporary Files {H10310} <S20000>
    43473765**
    43483766** If this global variable is made to point to a string which is
    4349 ** the name of a folder (a.ka. directory), then all temporary files
     3767** the name of a folder (a.ka. directory), then all temporary files
    43503768** created by SQLite will be placed in that directory.  If this variable
    4351 ** is NULL pointer, then SQLite does a search for an appropriate temporary
    4352 ** file directory.
    4353 **
    4354 ** It is not safe to modify this variable once a database connection
    4355 ** has been opened.  It is intended that this variable be set once
     3769** is a NULL pointer, then SQLite performs a search for an appropriate
     3770** temporary file directory.
     3771**
     3772** It is not safe to read or modify this variable in more than one
     3773** thread at a time.  It is not safe to read or modify this variable
     3774** if a [database connection] is being used at the same time in a separate
     3775** thread.
     3776** It is intended that this variable be set once
    43563777** as part of process initialization and before any SQLite interface
    4357 ** routines have been call and remain unchanged thereafter.
    4358 */
    4359 SQLITE_EXTERN char *sqlite3_temp_directory;
    4360 
    4361 /*
    4362 ** CAPI3REF:  Test To See If The Database Is In Auto-Commit Mode {F12930}
    4363 **
    4364 ** The sqlite3_get_autocommit() interfaces returns non-zero or
     3778** routines have been called and that this variable remain unchanged
     3779** thereafter.
     3780**
     3781** The [temp_store_directory pragma] may modify this variable and cause
     3782** it to point to memory obtained from [sqlite3_malloc].  Furthermore,
     3783** the [temp_store_directory pragma] always assumes that any string
     3784** that this variable points to is held in memory obtained from
     3785** [sqlite3_malloc] and the pragma may attempt to free that memory
     3786** using [sqlite3_free].
     3787** Hence, if this variable is modified directly, either it should be
     3788** made NULL or made to point to memory obtained from [sqlite3_malloc]
     3789** or else the use of the [temp_store_directory pragma] should be avoided.
     3790*/
     3791SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;
     3792
     3793/*
     3794** CAPI3REF: Test For Auto-Commit Mode {H12930} <S60200>
     3795** KEYWORDS: {autocommit mode}
     3796**
     3797** The sqlite3_get_autocommit() interface returns non-zero or
    43653798** zero if the given database connection is or is not in autocommit mode,
    4366 ** respectively.   Autocommit mode is on
    4367 ** by default.  Autocommit mode is disabled by a [BEGIN] statement.
    4368 ** Autocommit mode is reenabled by a [COMMIT] or [ROLLBACK].
     3799** respectively. 
     3800** Autocommit mode is disabled by a [BEGIN] statement.
     3801** Autocommit mode is reenabled by a [COMMIT] or [ROLLBACK].
    43693802**
    43703803** If certain kinds of errors occur on a statement within a multi-statement
    4371 ** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR],
     3804** transaction
    43723805** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
    43733806** transaction might be rolled back automatically.  The only way to
    4374 ** find out if SQLite automatically rolled back the transaction after
     3807** find out SQLite automatically rolled back the transaction after
    43753808** an error is to use this function.
    43763809**
    4377 ** INVARIANTS:
    4378 **
    4379 ** {F12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or
    4380 **          zero if the [database connection] D is or is not in autocommit
    4381 **          mode, respectively.
    4382 **
    4383 ** {F12932} Autocommit mode is on by default.
    4384 **
    4385 ** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement.
    4386 **
    4387 ** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK]
    4388 **          statement.
    4389 **
    4390 **
    4391 ** LIMITATIONS:
    4392 ***
    4393 ** {U12936} If another thread changes the autocommit status of the database
    4394 **          connection while this routine is running, then the return value
    4395 **          is undefined.
    4396 */
    4397 int sqlite3_get_autocommit(sqlite3*);
    4398 
    4399 /*
    4400 ** CAPI3REF:  Find The Database Handle Of A Prepared Statement {F13120}
    4401 **
    4402 ** The sqlite3_db_handle interface
    4403 ** returns the [sqlite3*] database handle to which a
    4404 ** [prepared statement] belongs.
    4405 ** The database handle returned by sqlite3_db_handle
    4406 ** is the same database handle that was
    4407 ** the first argument to the [sqlite3_prepare_v2()] or its variants
    4408 ** that was used to create the statement in the first place.
    4409 **
    4410 ** INVARIANTS:
    4411 **
    4412 ** {F13123} The [sqlite3_db_handle(S)] interface returns a pointer
    4413 **          to the [database connection] associated with
    4414 **          [prepared statement] S.
    4415 */
    4416 sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
    4417 
    4418 
    4419 /*
    4420 ** CAPI3REF: Commit And Rollback Notification Callbacks {F12950}
     3810** If another thread changes the autocommit status of the database
     3811** connection while this routine is running, then the return value
     3812** is undefined.
     3813**
     3814** Requirements: [H12931] [H12932] [H12933] [H12934]
     3815*/
     3816SQLITE_API int sqlite3_get_autocommit(sqlite3*);
     3817
     3818/*
     3819** CAPI3REF: Find The Database Handle Of A Prepared Statement {H13120} <S60600>
     3820**
     3821** The sqlite3_db_handle interface returns the [database connection] handle
     3822** to which a [prepared statement] belongs.  The [database connection]
     3823** returned by sqlite3_db_handle is the same [database connection] that was the first argument
     3824** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
     3825** create the statement in the first place.
     3826**
     3827** Requirements: [H13123]
     3828*/
     3829SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
     3830
     3831/*
     3832** CAPI3REF: Find the next prepared statement {H13140} <S60600>
     3833**
     3834** This interface returns a pointer to the next [prepared statement] after
     3835** pStmt associated with the [database connection] pDb.  If pStmt is NULL
     3836** then this interface returns a pointer to the first prepared statement
     3837** associated with the database connection pDb.  If no prepared statement
     3838** satisfies the conditions of this routine, it returns NULL.
     3839**
     3840** The [database connection] pointer D in a call to
     3841** [sqlite3_next_stmt(D,S)] must refer to an open database
     3842** connection and in particular must not be a NULL pointer.
     3843**
     3844** Requirements: [H13143] [H13146] [H13149] [H13152]
     3845*/
     3846SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
     3847
     3848/*
     3849** CAPI3REF: Commit And Rollback Notification Callbacks {H12950} <S60400>
    44213850**
    44223851** The sqlite3_commit_hook() interface registers a callback
    4423 ** function to be invoked whenever a transaction is committed.
     3852** function to be invoked whenever a transaction is .
    44243853** Any callback set by a previous call to sqlite3_commit_hook()
    44253854** for the same database connection is overridden.
    44263855** The sqlite3_rollback_hook() interface registers a callback
    4427 ** function to be invoked whenever a transaction is committed.
     3856** function to be invoked whenever a transaction is .
    44283857** Any callback set by a previous call to sqlite3_commit_hook()
    44293858** for the same database connection is overridden.
    4430 ** The pArg argument is passed through
    4431 ** to the callback.  If the callback on a commit hook function
    4432 ** returns non-zero, then the commit is converted into a rollback.
     3859** The pArg argument is passed through
     3860**
     3861** then the commit is converted into a rollback.
    44333862**
    44343863** If another function was previously registered, its
    44353864** pArg value is returned.  Otherwise NULL is returned.
    44363865**
     3866
     3867
     3868
     3869
     3870
     3871
     3872
     3873
    44373874** Registering a NULL function disables the callback.
    44383875**
    4439 ** For the purposes of this API, a transaction is said to have been
     3876** When the commit hook callback routine returns zero, the [COMMIT]
     3877** operation is allowed to continue normally.  If the commit hook
     3878** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
     3879** The rollback hook is invoked on a rollback that results from a commit
     3880** hook returning non-zero, just as it would be with any other rollback.
     3881**
     3882** For the purposes of this API, a transaction is said to have been
    44403883** rolled back if an explicit "ROLLBACK" statement is executed, or
    44413884** an error or constraint causes an implicit rollback to occur.
    … …  
    44463889** <todo> Check on this </todo>
    44473890**
    4448 ** These are experimental interfaces and are subject to change.
    4449 **
    4450 ** INVARIANTS:
    4451 **
    4452 ** {F12951} The [sqlite3_commit_hook(D,F,P)] interface registers the
    4453 **          callback function F to be invoked with argument P whenever
    4454 **          a transaction commits on [database connection] D.
    4455 **
    4456 ** {F12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P
    4457 **          argument from the previous call with the same
    4458 **          [database connection ] D , or NULL on the first call
    4459 **          for a particular [database connection] D.
    4460 **
    4461 ** {F12953} Each call to [sqlite3_commit_hook()] overwrites the callback
    4462 **          registered by prior calls.
    4463 **
    4464 ** {F12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL
    4465 **          then the commit hook callback is cancelled and no callback
    4466 **          is invoked when a transaction commits.
    4467 **
    4468 ** {F12955} If the commit callback returns non-zero then the commit is
    4469 **          converted into a rollback.
    4470 **
    4471 ** {F12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the
    4472 **          callback function F to be invoked with argument P whenever
    4473 **          a transaction rolls back on [database connection] D.
    4474 **
    4475 ** {F12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P
    4476 **          argument from the previous call with the same
    4477 **          [database connection ] D , or NULL on the first call
    4478 **          for a particular [database connection] D.
    4479 **
    4480 ** {F12963} Each call to [sqlite3_rollback_hook()] overwrites the callback
    4481 **          registered by prior calls.
    4482 **
    4483 ** {F12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL
    4484 **          then the rollback hook callback is cancelled and no callback
    4485 **          is invoked when a transaction rolls back.
    4486 */
    4487 void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
    4488 void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
    4489 
    4490 /*
    4491 ** CAPI3REF: Data Change Notification Callbacks {F12970}
    4492 **
    4493 ** The sqlite3_update_hook() interface
    4494 ** registers a callback function with the database connection identified by the
    4495 ** first argument to be invoked whenever a row is updated, inserted or deleted.
    4496 ** Any callback set by a previous call to this function for the same
    4497 ** database connection is overridden.
    4498 **
    4499 ** The second argument is a pointer to the function to invoke when a
    4500 ** row is updated, inserted or deleted.
    4501 ** The first argument to the callback is
    4502 ** a copy of the third argument to sqlite3_update_hook().
    4503 ** The second callback
    4504 ** argument is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
    4505 ** depending on the operation that caused the callback to be invoked.
    4506 ** The third and
    4507 ** fourth arguments to the callback contain pointers to the database and
    4508 ** table name containing the affected row.
    4509 ** The final callback parameter is
    4510 ** the rowid of the row.
    4511 ** In the case of an update, this is the rowid after
    4512 ** the update takes place.
     3891** See also the [sqlite3_update_hook()] interface.
     3892**
     3893** Requirements:
     3894** [H12951] [H12952] [H12953] [H12954] [H12955]
     3895** [H12961] [H12962] [H12963] [H12964]
     3896*/
     3897SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
     3898SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
     3899
     3900/*
     3901** CAPI3REF: Data Change Notification Callbacks {H12970} <S60400>
     3902**
     3903** The sqlite3_update_hook() interface registers a callback function
     3904** with the [database connection] identified by the first argument
     3905** to be invoked whenever a row is updated, inserted or deleted.
     3906** Any callback set by a previous call to this function
     3907** for the same database connection is overridden.
     3908**
     3909** The second argument is a pointer to the function to invoke when a
     3910** row is updated, inserted or deleted.
     3911** The first argument to the callback is a copy of the third argument
     3912** to sqlite3_update_hook().
     3913** The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
     3914** or [SQLITE_UPDATE], depending on the operation that caused the callback
     3915** to be invoked.
     3916** The third and fourth arguments to the callback contain pointers to the
     3917** database and table name containing the affected row.
     3918** The final callback parameter is the [rowid] of the row.
     3919** In the case of an update, this is the [rowid] after the update takes place.
    45133920**
    45143921** The update hook is not invoked when internal system tables are
    45153922** modified (i.e. sqlite_master and sqlite_sequence).
    45163923**
     3924
     3925
     3926
     3927
     3928
     3929
     3930
     3931
     3932
     3933
     3934
     3935
     3936
     3937
    45173938** If another function was previously registered, its pArg value
    45183939** is returned.  Otherwise NULL is returned.
    45193940**
    4520 ** INVARIANTS:
    4521 **
    4522 ** {F12971} The [sqlite3_update_hook(D,F,P)] interface causes callback
    4523 **          function F to be invoked with first parameter P whenever
    4524 **          a table row is modified, inserted, or deleted on
    4525 **          [database connection] D.
    4526 **
    4527 ** {F12973} The [sqlite3_update_hook(D,F,P)] interface returns the value
    4528 **          of P for the previous call on the same [database connection] D,
    4529 **          or NULL for the first call.
    4530 **
    4531 ** {F12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)]
    4532 **          is NULL then the no update callbacks are made.
    4533 **
    4534 ** {F12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls
    4535 **          to the same interface on the same [database connection] D.
    4536 **
    4537 ** {F12979} The update hook callback is not invoked when internal system
    4538 **          tables such as sqlite_master and sqlite_sequence are modified.
    4539 **
    4540 ** {F12981} The second parameter to the update callback
    4541 **          is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
    4542 **          depending on the operation that caused the callback to be invoked.
    4543 **
    4544 ** {F12983} The third and fourth arguments to the callback contain pointers
    4545 **          to zero-terminated UTF-8 strings which are the names of the
    4546 **          database and table that is being updated.
    4547 
    4548 ** {F12985} The final callback parameter is the rowid of the row after
    4549 **          the change occurs.
    4550 */
    4551 void *sqlite3_update_hook(
     3941** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()]
     3942** interfaces.
     3943**
     3944** Requirements:
     3945** [H12971] [H12973] [H12975] [H12977] [H12979] [H12981] [H12983] [H12986]
     3946*/
     3947SQLITE_API void *sqlite3_update_hook(
    45523948  sqlite3*,
    45533949  void(*)(void *,int ,char const *,char const *,sqlite3_int64),
    … …  
    45563952
    45573953/*
    4558 ** CAPI3REF:  Enable Or Disable Shared Pager Cache {F10330}
     3954** CAPI3REF: Enable Or Disable Shared Pager Cache {H10330} <S30900>
     3955** KEYWORDS: {shared cache}
    45593956**
    45603957** This routine enables or disables the sharing of the database cache
    4561 ** and schema data structures between connections to the same database.
    4562 ** Sharing is enabled if the argument is true and disabled if the argument
    4563 ** is false.
    4564 **
    4565 ** Cache sharing is enabled and disabled
    4566 ** for an entire process. {END} This is a change as of SQLite version 3.5.0.
    4567 ** In prior versions of SQLite, sharing was
    4568 ** enabled or disabled for each thread separately.
     3958** and schema data structures between [database connection | connections]
     3959** to the same database. Sharing is enabled if the argument is true
     3960** and disabled if the argument is false.
     3961**
     3962** Cache sharing is enabled and disabled for an entire process.
     3963** This is a change as of SQLite version 3.5.0. In prior versions of SQLite,
     3964** sharing was enabled or disabled for each thread separately.
    45693965**
    45703966** The cache sharing mode set by this interface effects all subsequent
    … …  
    45733969** that was in effect at the time they were opened.
    45743970**
    4575 ** Virtual tables cannot be used with a shared cache.   When shared
     3971** Virtual tables cannot be used with a shared cache.  When shared
    45763972** cache is enabled, the [sqlite3_create_module()] API used to register
    45773973** virtual tables will always return an error.
    45783974**
    4579 ** This routine returns [SQLITE_OK] if shared cache was
    4580 ** enabled or disabled successfully.  An [error code]
    4581 ** is returned otherwise.
     3975** This routine returns [SQLITE_OK] if shared cache was enabled or disabled
     3976** successfully.  An [error code] is returned otherwise.
    45823977**
    45833978** Shared cache is disabled by default. But this might change in
    … …  
    45853980** cache setting should set it explicitly.
    45863981**
    4587 ** INVARIANTS:
    4588 **
    4589 ** {F10331} A successful invocation of [sqlite3_enable_shared_cache(B)]
    4590 **          will enable or disable shared cache mode for any subsequently
    4591 **          created [database connection] in the same process.
    4592 **
    4593 ** {F10336} When shared cache is enabled, the [sqlite3_create_module()]
    4594 **          interface will always return an error.
    4595 **
    4596 ** {F10337} The [sqlite3_enable_shared_cache(B)] interface returns
    4597 **          [SQLITE_OK] if shared cache was enabled or disabled successfully.
    4598 **
    4599 ** {F10339} Shared cache is disabled by default.
    4600 */
    4601 int sqlite3_enable_shared_cache(int);
    4602 
    4603 /*
    4604 ** CAPI3REF:  Attempt To Free Heap Memory {F17340}
    4605 **
    4606 ** The sqlite3_release_memory() interface attempts to
    4607 ** free N bytes of heap memory by deallocating non-essential memory
    4608 ** allocations held by the database labrary. {END}  Memory used
    4609 ** to cache database pages to improve performance is an example of
    4610 ** non-essential memory.  Sqlite3_release_memory() returns
    4611 ** the number of bytes actually freed, which might be more or less
    4612 ** than the amount requested.
    4613 **
    4614 ** INVARIANTS:
    4615 **
    4616 ** {F17341} The [sqlite3_release_memory(N)] interface attempts to
    4617 **          free N bytes of heap memory by deallocating non-essential
    4618 **          memory allocations held by the database labrary.
    4619 **
    4620 ** {F16342} The [sqlite3_release_memory(N)] returns the number
    4621 **          of bytes actually freed, which might be more or less
    4622 **          than the amount requested.
    4623 */
    4624 int sqlite3_release_memory(int);
    4625 
    4626 /*
    4627 ** CAPI3REF:  Impose A Limit On Heap Size {F17350}
    4628 **
    4629 ** The sqlite3_soft_heap_limit() interface
    4630 ** places a "soft" limit on the amount of heap memory that may be allocated
    4631 ** by SQLite. If an internal allocation is requested
    4632 ** that would exceed the soft heap limit, [sqlite3_release_memory()] is
    4633 ** invoked one or more times to free up some space before the allocation
    4634 ** is made.
    4635 **
    4636 ** The limit is called "soft", because if
    4637 ** [sqlite3_release_memory()] cannot
    4638 ** free sufficient memory to prevent the limit from being exceeded,
     3982** See Also:  [SQLite Shared-Cache Mode]
     3983**
     3984** Requirements: [H10331] [H10336] [H10337] [H10339]
     3985*/
     3986SQLITE_API int sqlite3_enable_shared_cache(int);
     3987
     3988/*
     3989** CAPI3REF: Attempt To Free Heap Memory {H17340} <S30220>
     3990**
     3991** The sqlite3_release_memory() interface attempts to free N bytes
     3992** of heap memory by deallocating non-essential memory allocations
     3993** held by the database library. {END}  Memory used to cache database
     3994** pages to improve performance is an example of non-essential memory.
     3995** sqlite3_release_memory() returns the number of bytes actually freed,
     3996** which might be more or less than the amount requested.
     3997**
     3998** Requirements: [H17341] [H17342]
     3999*/
     4000SQLITE_API int sqlite3_release_memory(int);
     4001
     4002/*
     4003** CAPI3REF: Impose A Limit On Heap Size {H17350} <S30220>
     4004**
     4005** The sqlite3_soft_heap_limit() interface places a "soft" limit
     4006** on the amount of heap memory that may be allocated by SQLite.
     4007** If an internal allocation is requested that would exceed the
     4008** soft heap limit, [sqlite3_release_memory()] is invoked one or
     4009** more times to free up some space before the allocation is performed.
     4010**
     4011** The limit is called "soft", because if [sqlite3_release_memory()]
     4012** cannot free sufficient memory to prevent the limit from being exceeded,
    46394013** the memory is allocated anyway and the current operation proceeds.
    46404014**
    … …  
    46434017** The default value for the soft heap limit is zero.
    46444018**
    4645 ** SQLite makes a best effort to honor the soft heap limit. 
    4646 ** But if the soft heap limit cannot honored, execution will
    4647 ** continue without error or notification.  This is why the limit is 
     4019** SQLite makes a best effort to honor the soft heap limit.
     4020** But if the soft heap limit cannot honored, execution will
     4021** continue without error or notification.  This is why the limit is
    46484022** called a "soft" limit.  It is advisory only.
    46494023**
    … …  
    46564030** individual threads.
    46574031**
    4658 ** INVARIANTS:
    4659 **
    4660 ** {F16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit
    4661 **          of N bytes on the amount of heap memory that may be allocated
    4662 **          using [sqlite3_malloc()] or [sqlite3_realloc()] at any point
    4663 **          in time.
    4664 **
    4665 ** {F16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would
    4666 **          cause the total amount of allocated memory to exceed the
    4667 **          soft heap limit, then [sqlite3_release_memory()] is invoked
    4668 **          in an attempt to reduce the memory usage prior to proceeding
    4669 **          with the memory allocation attempt.
    4670 **
    4671 ** {F16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger
    4672 **          attempts to reduce memory usage through the soft heap limit
    4673 **          mechanism continue even if the attempt to reduce memory
    4674 **          usage is unsuccessful.
    4675 **
    4676 ** {F16354} A negative or zero value for N in a call to
    4677 **          [sqlite3_soft_heap_limit(N)] means that there is no soft
    4678 **          heap limit and [sqlite3_release_memory()] will only be
    4679 **          called when memory is completely exhausted.
    4680 **
    4681 ** {F16355} The default value for the soft heap limit is zero.
    4682 **
    4683 ** {F16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the
    4684 **          values set by all prior calls.
    4685 */
    4686 void sqlite3_soft_heap_limit(int);
    4687 
    4688 /*
    4689 ** CAPI3REF:  Extract Metadata About A Column Of A Table {F12850}
    4690 **
    4691 ** This routine
    4692 ** returns meta-data about a specific column of a specific database
    4693 ** table accessible using the connection handle passed as the first function
    4694 ** argument.
    4695 **
    4696 ** The column is identified by the second, third and fourth parameters to
     4032** Requirements:
     4033** [H16351] [H16352] [H16353] [H16354] [H16355] [H16358]
     4034*/
     4035SQLITE_API void sqlite3_soft_heap_limit(int);
     4036
     4037/*
     4038** CAPI3REF: Extract Metadata About A Column Of A Table {H12850} <S60300>
     4039**
     4040** This routine returns metadata about a specific column of a specific
     4041** database table accessible using the [database connection] handle
     4042** passed as the first function argument.
     4043**
     4044** The column is identified by the second, third and fourth parameters to
    46974045** this function. The second parameter is either the name of the database
    46984046** (i.e. "main", "temp" or an attached database) containing the specified
    46994047** table or NULL. If it is NULL, then all attached databases are searched
    4700 ** for the table using the same algorithm as the database engine uses to
     4048** for the table using the same algorithm
    47014049** resolve unqualified table references.
    47024050**
    4703 ** The third and fourth parameters to this function are the table and column 
    4704 ** name of the desired column, respectively. Neither of these parameters 
     4051** The third and fourth parameters to this function are the table and column
     4052** name of the desired column, respectively. Neither of these parameters
    47054053** may be NULL.
    47064054**
    4707 ** Meta information is returned by writing to the memory locations passed as
    4708 ** the 5th and subsequent parameters to this function. Any of these
    4709 ** arguments may be NULL, in which case the corresponding element of meta
    4710 ** information is ommitted.
    4711 **
    4712 ** <pre>
    4713 ** Parameter     Output Type      Description
    4714 ** -----------------------------------
    4715 **
    4716 **   5th         const char*      Data type
    4717 **   6th         const char*      Name of the default collation sequence
    4718 **   7th         int              True if the column has a NOT NULL constraint
    4719 **   8th         int              True if the column is part of the PRIMARY KEY
    4720 **   9th         int              True if the column is AUTOINCREMENT
    4721 ** </pre>
    4722 **
    4723 **
    4724 ** The memory pointed to by the character pointers returned for the
    4725 ** declaration type and collation sequence is valid only until the next
    4726 ** call to any sqlite API function.
    4727 **
    4728 ** If the specified table is actually a view, then an error is returned.
    4729 **
    4730 ** If the specified column is "rowid", "oid" or "_rowid_" and an
    4731 ** INTEGER PRIMARY KEY column has been explicitly declared, then the output
     4055** Metadata is returned by writing to the memory locations passed as the 5th
     4056** and subsequent parameters to this function. Any of these arguments may be
     4057** NULL, in which case the corresponding element of metadata is omitted.
     4058**
     4059** <blockquote>
     4060** <table border="1">
     4061** <tr><th> Parameter <th> Output<br>Type <th>  Description
     4062**
     4063** <tr><td> 5th <td> const char* <td> Data type
     4064** <tr><td> 6th <td> const char* <td> Name of default collation sequence
     4065** <tr><td> 7th <td> int         <td> True if column has a NOT NULL constraint
     4066** <tr><td> 8th <td> int         <td> True if column is part of the PRIMARY KEY
     4067** <tr><td> 9th <td> int         <td> True if column is [AUTOINCREMENT]
     4068** </table>
     4069** </blockquote>
     4070**
     4071** The memory pointed to by the character pointers returned for the
     4072** declaration type and collation sequence is valid only until the next
     4073** call to any SQLite API function.
     4074**
     4075** If the specified table is actually a view, an [error code] is returned.
     4076**
     4077** If the specified column is "rowid", "oid" or "_rowid_" and an
     4078** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output
    47324079** parameters are set for the explicitly declared column. If there is no
    4733 ** explicitly declared IPK column, then the output parameters are set as
    4734 ** follows:
     4080** explicitly declared
     4081** follows:
    47354082**
    47364083** <pre>
    … …  
    47444091** This function may load one or more schemas from database files. If an
    47454092** error occurs during this process, or if the requested table or column
    4746 ** cannot be found, an SQLITE error code is returned and an error message
    4747 ** left in the database handle (to be retrieved using sqlite3_errmsg()).
     4093** cannot be found, an
     4094** (to be retrieved using sqlite3_errmsg()).
    47484095**
    47494096** This API is only available if the library was compiled with the
    4750 ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
    4751 */
    4752 int sqlite3_table_column_metadata(
     4097** preprocessor symbol defined.
     4098*/
     4099int sqlite3_table_column_metadata(
    47534100  sqlite3 *db,                /* Connection handle */
    47544101  const char *zDbName,        /* Database name or NULL */
    … …  
    47634110
    47644111/*
    4765 ** CAPI3REF: Load An Extension {F12600}
    4766 **
    4767 ** {F12601} The sqlite3_load_extension() interface
    4768 ** attempts to load an SQLite extension library contained in the file
    4769 ** zFile. {F12602} The entry point is zProc. {F12603} zProc may be 0
    4770 ** in which case the name of the entry point defaults
    4771 ** to "sqlite3_extension_init".
    4772 **
    4773 ** {F12604} The sqlite3_load_extension() interface shall
    4774 ** return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
    4775 **
    4776 ** {F12605}
    4777 ** If an error occurs and pzErrMsg is not 0, then the
    4778 ** sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with
    4779 ** error message text stored in memory obtained from [sqlite3_malloc()].
    4780 ** {END}  The calling function should free this memory
    4781 ** by calling [sqlite3_free()].
    4782 **
    4783 ** {F12606}
    4784 ** Extension loading must be enabled using [sqlite3_enable_load_extension()]
    4785 ** prior to calling this API or an error will be returned.
    4786 */
    4787 int sqlite3_load_extension(
     4112** CAPI3REF: Load An Extension {H12600} <S20500>
     4113**
     4114** This interface loads an SQLite extension library from the named file.
     4115**
     4116** {H12601} The sqlite3_load_extension() interface attempts to load an
     4117**          SQLite extension library contained in the file zFile.
     4118**
     4119** {H12602} The entry point is zProc.
     4120**
     4121** {H12603} zProc may be 0, in which case the name of the entry point
     4122**          defaults to "sqlite3_extension_init".
     4123**
     4124** {H12604} The sqlite3_load_extension() interface shall return
     4125**          [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
     4126**
     4127** {H12605} If an error occurs and pzErrMsg is not 0, then the
     4128**          [sqlite3_load_extension()] interface shall attempt to
     4129**          fill *pzErrMsg with error message text stored in memory
     4130**          obtained from [sqlite3_malloc()]. {END}  The calling function
     4131**          should free this memory by calling [sqlite3_free()].
     4132**
     4133** {H12606} Extension loading must be enabled using
     4134**          [sqlite3_enable_load_extension()] prior to calling this API,
     4135**          otherwise an error will be returned.
     4136*/
     4137SQLITE_API int sqlite3_load_extension(
    47884138  sqlite3 *db,          /* Load the extension into this database connection */
    47894139  const char *zFile,    /* Name of the shared library containing extension */
    … …  
    47934143
    47944144/*
    4795 ** CAPI3REF:  Enable Or Disable Extension Loading {F12620}
     4145** CAPI3REF:
    47964146**
    47974147** So as not to open security holes in older applications that are
    47984148** unprepared to deal with extension loading, and as a means of disabling
    4799 ** extension loading while evaluating user-entered SQL, the following
    4800 ** API is provided to turn the [sqlite3_load_extension()] mechanism on and
    4801 ** off.  {F12622} It is off by default. {END} See ticket #1863.
    4802 **
    4803 ** {F12621} Call the sqlite3_enable_load_extension() routine
    4804 ** with onoff==1 to turn extension loading on
    4805 ** and call it with onoff==0 to turn it back off again. {END}
    4806 */
    4807 int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
    4808 
    4809 /*
    4810 ** CAPI3REF: Make Arrangements To Automatically Load An Extension {F12640}
    4811 **
    4812 ** {F12641} This function
    4813 ** registers an extension entry point that is automatically invoked
    4814 ** whenever a new database connection is opened using
    4815 ** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()]. {END}
     4149** extension loading while evaluating user-entered SQL, the following API
     4150** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
     4151**
     4152** Extension loading is off by default. See ticket #1863.
     4153**
     4154** {H12621} Call the sqlite3_enable_load_extension() routine with onoff==1
     4155**          to turn extension loading on and call it with onoff==0 to turn
     4156**          it back off again.
     4157**
     4158** {H12622} Extension loading is off by default.
     4159*/
     4160SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
     4161
     4162/*
     4163** CAPI3REF: Automatically Load An Extensions {H12640} <S20500>
    48164164**
    48174165** This API can be invoked at program startup in order to register
    48184166** one or more statically linked extensions that will be available
    4819 ** to all new database connections.
    4820 **
    4821 ** {F12642} Duplicate extensions are detected so calling this routine multiple
    4822 ** times with the same extension is harmless.
    4823 **
    4824 ** {F12643} This routine stores a pointer to the extension in an array
    4825 ** that is obtained from sqlite_malloc(). {END} If you run a memory leak
    4826 ** checker on your program and it reports a leak because of this
    4827 ** array, then invoke [sqlite3_reset_auto_extension()] prior
    4828 ** to shutdown to free the memory.
    4829 **
    4830 ** {F12644} Automatic extensions apply across all threads. {END}
    4831 **
    4832 ** This interface is experimental and is subject to change or
    4833 ** removal in future releases of SQLite.
    4834 */
    4835 int sqlite3_auto_extension(void *xEntryPoint);
    4836 
    4837 
    4838 /*
    4839 ** CAPI3REF: Reset Automatic Extension Loading {F12660}
    4840 **
    4841 ** {F12661} This function disables all previously registered
    4842 ** automatic extensions. {END}  This
    4843 ** routine undoes the effect of all prior [sqlite3_auto_extension()]
    4844 ** calls.
    4845 **
    4846 ** {F12662} This call disabled automatic extensions in all threads. {END}
    4847 **
    4848 ** This interface is experimental and is subject to change or
    4849 ** removal in future releases of SQLite.
    4850 */
    4851 void sqlite3_reset_auto_extension(void);
    4852 
     4167** to all new [database connections]. {END}
     4168**
     4169** This routine stores a pointer to the extension in an array that is
     4170** obtained from [sqlite3_malloc()].  If you run a memory leak checker
     4171** on your program and it reports a leak because of this array, invoke
     4172** [sqlite3_reset_auto_extension()] prior to shutdown to free the memory.
     4173**
     4174** {H12641} This function registers an extension entry point that is
     4175**          automatically invoked whenever a new [database connection]
     4176**          is opened using [sqlite3_open()], [sqlite3_open16()],
     4177**          or [sqlite3_open_v2()].
     4178**
     4179** {H12642} Duplicate extensions are detected so calling this routine
     4180**          multiple times with the same extension is harmless.
     4181**
     4182** {H12643} This routine stores a pointer to the extension in an array
     4183**          that is obtained from [sqlite3_malloc()].
     4184**
     4185** {H12644} Automatic extensions apply across all threads.
     4186*/
     4187SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void));
     4188
     4189/*
     4190** CAPI3REF: Reset Automatic Extension Loading {H12660} <S20500>
     4191**
     4192** This function disables all previously registered automatic
     4193** extensions. {END}  It undoes the effect of all prior
     4194** [sqlite3_auto_extension()] calls.
     4195**
     4196** {H12661} This function disables all previously registered
     4197**          automatic extensions.
     4198**
     4199** {H12662} This function disables automatic extensions in all threads.
     4200*/
     4201SQLITE_API void sqlite3_reset_auto_extension(void);
    48534202
    48544203/*
    … …  
    48594208** If this is a problem for you, do not use the interface at this time.
    48604209**
    4861 ** When the virtual-table mechanism stablizes, we will declare the
     4210** When the virtual-table mechanism stablizes, we will declare the
    48624211** interface fixed, support it indefinitely, and remove this comment.
    48634212*/
    … …  
    48724221
    48734222/*
    4874 ** CAPI3REF: Virtual Table Object {F18000}
    4875 ** KEYWORDS: sqlite3_module
    4876 **
    4877 ** A module is a class of virtual tables.  Each module is defined
    4878 ** by an instance of the following structure.  This structure consists
    4879 ** mostly of methods for the module.
     4223** CAPI3REF: Virtual Table Object {H18000} <S20400>
     4224** KEYWORDS: sqlite3_module {virtual table module}
     4225** EXPERIMENTAL
     4226**
     4227** This structure, sometimes called a a "virtual table module",
     4228** defines the implementation of a [virtual tables]. 
     4229** This structure consists mostly of methods for the module.
     4230**
     4231** A virtual table module is created by filling in a persistent
     4232** instance of this structure and passing a pointer to that instance
     4233** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].
     4234** The registration remains valid until it is replaced by a different
     4235** module or until the [database connection] closes.  The content
     4236** of this structure must not change while it is registered with
     4237** any database connection.
    48804238*/
    48814239struct sqlite3_module {
    … …  
    49064264                       void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
    49074265                       void **ppArg);
    4908 
    49094266  int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
    49104267};
    49114268
    49124269/*
    4913 ** CAPI3REF: Virtual Table Indexing Information {F18100}
     4270** CAPI3REF: Virtual Table Indexing Information {
    49144271** KEYWORDS: sqlite3_index_info
     4272
    49154273**
    49164274** The sqlite3_index_info structure and its substructures is used to
    4917 ** pass information into and receive the reply from the xBestIndex
    4918 ** method of an sqlite3_module.  The fields under **Inputs** are the
     4275** pass information into and receive the reply from the
     4276** method of a.  The fields under **Inputs** are the
    49194277** inputs to xBestIndex and are read-only.  xBestIndex inserts its
    49204278** results into the **Outputs** fields.
    49214279**
    4922 ** The aConstraint[] array records WHERE clause constraints of the
    4923 ** form:
    4924 **
    4925 **         column OP expr
    4926 **
    4927 ** Where OP is =, &lt;, &lt;=, &gt;, or &gt;=. 
    4928 ** The particular operator is stored
    4929 ** in aConstraint[].op.  The index of the column is stored in
     4280** The aConstraint[] array records WHERE clause constraints of the form:
     4281**
     4282** <pre>column OP expr</pre>
     4283**
     4284** where OP is =, &lt;, &lt;=, &gt;, or &gt;=.  The particular operator is
     4285** stored in aConstraint[].op.  The index of the column is stored in
    49304286** aConstraint[].iColumn.  aConstraint[].usable is TRUE if the
    49314287** expr on the right-hand side can be evaluated (and thus the constraint
    … …  
    49414297** Each term of aOrderBy records a column of the ORDER BY clause.
    49424298**
    4943 ** The xBestIndex method must fill aConstraintUsage[] with information
     4299** The method must fill aConstraintUsage[] with information
    49444300** about what parameters to pass to xFilter.  If argvIndex>0 then
    49454301** the right-hand side of the corresponding aConstraint[] is evaluated
    … …  
    49484304** virtual table and is not checked again by SQLite.
    49494305**
    4950 ** The idxNum and idxPtr values are recorded and passed into xFilter.
    4951 ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true.
    4952 **
    4953 ** The orderByConsumed means that output from xFilter will occur in
     4306** The idxNum and idxPtr values are recorded and passed into the
     4307** [xFilter] method.
     4308** [sqlite3_free()] is used to free idxPtr if and only iff
     4309** needToFreeIdxPtr is true.
     4310**
     4311** The orderByConsumed means that output from [xFilter]/[xNext] will occur in
    49544312** the correct order to satisfy the ORDER BY clause so that no separate
    49554313** sorting step is required.
    … …  
    49744332     unsigned char desc;       /* True for DESC.  False for ASC. */
    49754333  } *aOrderBy;               /* The ORDER BY clause */
    4976 
    49774334  /* Outputs */
    49784335  struct sqlite3_index_constraint_usage {
    … …  
    49944351
    49954352/*
    4996 ** CAPI3REF: Register A Virtual Table Implementation {F18200}
    4997 **
    4998 ** This routine is used to register a new module name with an SQLite
    4999 ** connection.  Module names must be registered before creating new
    5000 ** virtual tables on the module, or before using preexisting virtual
    5001 ** tables of the module.
    5002 */
    5003 int sqlite3_create_module(
     4353** CAPI3REF: Register A Virtual Table Implementation {H18200} <S20400>
     4354** EXPERIMENTAL
     4355**
     4356** This routine is used to register a new [virtual table module] name.
     4357** Module names must be registered before
     4358** creating a new [virtual table] using the module, or before using a
     4359** preexisting [virtual table] for the module.
     4360**
     4361** The module name is registered on the [database connection] specified
     4362** by the first parameter.  The name of the module is given by the
     4363** second parameter.  The third parameter is a pointer to
     4364** the implementation of the [virtual table module].   The fourth
     4365** parameter is an arbitrary client data pointer that is passed through
     4366** into the [xCreate] and [xConnect] methods of the virtual table module
     4367** when a new virtual table is be being created or reinitialized.
     4368**
     4369** This interface has exactly the same effect as calling
     4370** [sqlite3_create_module_v2()] with a NULL client data destructor.
     4371*/
     4372SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_create_module(
    50044373  sqlite3 *db,               /* SQLite connection to register module with */
    50054374  const char *zName,         /* Name of the module */
    5006   const sqlite3_module *,    /* Methods for the module */
    5007   void *                     /* Client data for xCreate/xConnect */
     4375  const sqlite3_module *   /* Methods for the module */
     4376  void *          /* Client data for xCreate/xConnect */
    50084377);
    50094378
    50104379/*
    5011 ** CAPI3REF: Register A Virtual Table Implementation {F18210}
    5012 **
    5013 ** This routine is identical to the sqlite3_create_module() method above,
    5014 ** except that it allows a destructor function to be specified. It is
    5015 ** even more experimental than the rest of the virtual tables API.
    5016 */
    5017 int sqlite3_create_module_v2(
     4380** CAPI3REF: Register A Virtual Table Implementation {H18210} <S20400>
     4381** EXPERIMENTAL
     4382**
     4383** This routine is identical to the [sqlite3_create_module()] method,
     4384** except that it has an extra parameter to specify
     4385** a destructor function for the client data pointer.  SQLite will
     4386** invoke the destructor function (if it is not NULL) when SQLite
     4387** no longer needs the pClientData pointer. 
     4388*/
     4389SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_create_module_v2(
    50184390  sqlite3 *db,               /* SQLite connection to register module with */
    50194391  const char *zName,         /* Name of the module */
    5020   const sqlite3_module *,    /* Methods for the module */
    5021   void *,                    /* Client data for xCreate/xConnect */
     4392  const sqlite3_module *   /* Methods for the module */
     4393  void *         /* Client data for xCreate/xConnect */
    50224394  void(*xDestroy)(void*)     /* Module destructor function */
    50234395);
    50244396
    50254397/*
    5026 ** CAPI3REF: Virtual Table Instance Object {F18010}
     4398** CAPI3REF: Virtual Table Instance Object {
    50274399** KEYWORDS: sqlite3_vtab
    5028 **
    5029 ** Every module implementation uses a subclass of the following structure
    5030 ** to describe a particular instance of the module.  Each subclass will
    5031 ** be tailored to the specific needs of the module implementation.   The
    5032 ** purpose of this superclass is to define certain fields that are common
    5033 ** to all module implementations.
     4400** EXPERIMENTAL
     4401**
     4402** Every [virtual table module] implementation uses a subclass
     4403** of the following structure to describe a particular instance
     4404** of the [virtual table].  Each subclass will
     4405** be tailored to the specific needs of the module implementation.
     4406** The purpose of this superclass is to define certain fields that are
     4407** common to all module implementations.
    50344408**
    50354409** Virtual tables methods can set an error message by assigning a
    5036 ** string obtained from sqlite3_mprintf() to zErrMsg.  The method should
    5037 ** take care that any prior string is freed by a call to sqlite3_free()
     4410** string obtained from to zErrMsg.  The method should
     4411** take care that any prior string is freed by a call to
    50384412** prior to assigning a new string to zErrMsg.  After the error message
    50394413** is delivered up to the client application, the string will be automatically
    5040 ** freed by sqlite3_free() and the zErrMsg field will be zeroed.  Note
    5041 ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field
    5042 ** since virtual tables are commonly implemented in loadable extensions which
    5043 ** do not have access to sqlite3MPrintf() or sqlite3Free().
     4414** freed by sqlite3_free() and the zErrMsg field will be zeroed.
    50444415*/
    50454416struct sqlite3_vtab {
    50464417  const sqlite3_module *pModule;  /* The module for this virtual table */
    5047   int nRef;                       /* Used internally */
     4418  int nRef;                       /* */
    50484419  char *zErrMsg;                  /* Error message from sqlite3_mprintf() */
    50494420  /* Virtual table implementations will typically add additional fields */
    … …  
    50514422
    50524423/*
    5053 ** CAPI3REF: Virtual Table Cursor Object  {F18020}
    5054 ** KEYWORDS: sqlite3_vtab_cursor
    5055 **
    5056 ** Every module implementation uses a subclass of the following structure
    5057 ** to describe cursors that point into the virtual table and are used
     4424** CAPI3REF: Virtual Table Cursor Object  {H18020} <S20400>
     4425** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
     4426** EXPERIMENTAL
     4427**
     4428** Every [virtual table module] implementation uses a subclass of the
     4429** following structure to describe cursors that point into the
     4430** [virtual table] and are used
    50584431** to loop through the virtual table.  Cursors are created using the
    5059 ** xOpen method of the module.  Each module implementation will define
     4432** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed
     4433** by the [sqlite3_module.xClose | xClose] method.  Cussors are used
     4434** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods
     4435** of the module.  Each module implementation will define
    50604436** the content of a cursor structure to suit its own needs.
    50614437**
    … …  
    50694445
    50704446/*
    5071 ** CAPI3REF: Declare The Schema Of A Virtual Table {F18280}
    5072 **
    5073 ** The xCreate and xConnect methods of a module use the following API
     4447** CAPI3REF: Declare The Schema Of A Virtual Table {H18280} <S20400>
     4448** EXPERIMENTAL
     4449**
     4450** The [xCreate] and [xConnect] methods of a
     4451** [virtual table module] call this interface
    50744452** to declare the format (the names and datatypes of the columns) of
    50754453** the virtual tables they implement.
    50764454*/
    5077 int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable);
    5078 
    5079 /*
    5080 ** CAPI3REF: Overload A Function For A Virtual Table {F18300}
     4455SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
     4456
     4457/*
     4458** CAPI3REF: Overload A Function For A Virtual Table {H18300} <S20400>
     4459** EXPERIMENTAL
    50814460**
    50824461** Virtual tables can provide alternative implementations of functions
    5083 ** using the xFindFunction method.  But global versions of those functions
     4462** using the [xFindFunction] method of the [virtual table module]. 
     4463** But global versions of those functions
    50844464** must exist in order to be overloaded.
    50854465**
    … …  
    50894469** of the new function always causes an exception to be thrown.  So
    50904470** the new function is not good for anything by itself.  Its only
    5091 ** purpose is to be a place-holder function that can be overloaded
    5092 ** by virtual tables.
    5093 **
    5094 ** This API should be considered part of the virtual table interface,
    5095 ** which is experimental and subject to change.
    5096 */
    5097 int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
     4471** purpose is to be a placeholder function that can be overloaded
     4472** by a [virtual table].
     4473*/
     4474SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
    50984475
    50994476/*
    … …  
    51104487
    51114488/*
    5112 ** CAPI3REF: A Handle To An Open BLOB {F17800}
     4489** CAPI3REF: A Handle To An Open BLOB {H17800} <S30230>
     4490** KEYWORDS: {BLOB handle} {BLOB handles}
    51134491**
    51144492** An instance of this object represents an open BLOB on which
    5115 ** incremental I/O can be preformed.
    5116 ** Objects of this type are created by
    5117 ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()].
     4493** formed.
     4494** Objects of this type are created by
     4495** and destroyed by [sqlite3_blob_close()].
    51184496** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
    5119 ** can be used to read or write small subsections of the blob.
    5120 ** The [sqlite3_blob_bytes()] interface returns the size of the
    5121 ** blob in bytes.
     4497** can be used to read or write small subsections of the BLOB.
     4498** The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.
    51224499*/
    51234500typedef struct sqlite3_blob sqlite3_blob;
    51244501
    51254502/*
    5126 ** CAPI3REF: Open A BLOB For Incremental I/O {F17810}
    5127 **
    5128 ** This interfaces opens a handle to the blob located
     4503** CAPI3REF: Open A BLOB For Incremental I/O {
     4504**
     4505** This interfaces opens a located
    51294506** in row iRow, column zColumn, table zTable in database zDb;
    5130 ** in other words,  the same blob that would be selected by:
     4507** in other words, that would be selected by:
    51314508**
    51324509** <pre>
    5133 **     SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
     4510**     SELECT zColumn FROM zDb.zTable WHERE = iRow;
    51344511** </pre> {END}
    51354512**
    5136 ** If the flags parameter is non-zero, the blob is opened for
    5137 ** read and write access. If it is zero, the blob is opened for read
    5138 ** access.
     4513** If the flags parameter is non-zero, then the BLOB is opened for read
     4514** and write access. If it is zero, the BLOB is opened for read access.
     4515** It is not possible to open a column that is part of an index or primary
     4516** key for writing. ^If [foreign key constraints] are enabled, it is
     4517** not possible to open a column that is part of a [child key] for writing.
    51394518**
    51404519** Note that the database name is not the filename that contains
    51414520** the database but rather the symbolic name of the database that
    51424521** is assigned when the database is connected using [ATTACH].
    5143 ** For the main database file, the database name is "main".  For
    5144 ** TEMP tables, the database name is "temp".
    5145 **
    5146 ** On success, [SQLITE_OK] is returned and the new
    5147 ** [sqlite3_blob | blob handle] is written to *ppBlob.
    5148 ** Otherwise an error code is returned and
    5149 ** any value written to *ppBlob should not be used by the caller.
    5150 ** This function sets the database-handle error code and message
    5151 ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
    5152 **
    5153 ** INVARIANTS:
    5154 **
    5155 ** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)]
    5156 **          interface opens an [sqlite3_blob] object P on the blob
    5157 **          in column C of table T in database B on [database connection] D.
    5158 **
    5159 ** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] starts
    5160 **          a new transaction on [database connection] D if that connection
    5161 **          is not already in a transaction.
    5162 **
    5163 ** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface opens the blob
    5164 **          for read and write access if and only if the F parameter
    5165 **          is non-zero.
    5166 **
    5167 ** {F17819} The [sqlite3_blob_open()] interface returns [SQLITE_OK] on
    5168 **          success and an appropriate [error code] on failure.
    5169 **
    5170 ** {F17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)]
    5171 **          then subsequent calls to [sqlite3_errcode(D)],
    5172 **          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
    5173 **          information approprate for that error.
    5174 */
    5175 int sqlite3_blob_open(
     4522** For the main database file, the database name is "main".
     4523** For TEMP tables, the database name is "temp".
     4524**
     4525** On success, [SQLITE_OK] is returned and the new [BLOB handle] is written
     4526** to *ppBlob. Otherwise an [error code] is returned and *ppBlob is set
     4527** to be a null pointer.
     4528** This function sets the [database connection] error code and message
     4529** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()] and related
     4530** functions.  Note that the *ppBlob variable is always initialized in a
     4531** way that makes it safe to invoke [sqlite3_blob_close()] on *ppBlob
     4532** regardless of the success or failure of this routine.
     4533**
     4534** If the row that a BLOB handle points to is modified by an
     4535** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
     4536** then the BLOB handle is marked as "expired".
     4537** This is true if any column of the row is changed, even a column
     4538** other than the one the BLOB handle is open on.
     4539** Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
     4540** a expired BLOB handle fail with an return code of [SQLITE_ABORT].
     4541** Changes written into a BLOB prior to the BLOB expiring are not
     4542** rollback by the expiration of the BLOB.  Such changes will eventually
     4543** commit if the transaction continues to completion.
     4544**
     4545** Use the [sqlite3_blob_bytes()] interface to determine the size of
     4546** the opened blob.  The size of a blob may not be changed by this
     4547** interface.  Use the [UPDATE] SQL command to change the size of a
     4548** blob.
     4549**
     4550** The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
     4551** and the built-in [zeroblob] SQL function can be used, if desired,
     4552** to create an empty, zero-filled blob in which to read or write using
     4553** this interface.
     4554**
     4555** To avoid a resource leak, every open [BLOB handle] should eventually
     4556** be released by a call to [sqlite3_blob_close()].
     4557**
     4558** Requirements:
     4559** [H17813] [H17814] [H17816] [H17819] [H17821] [H17824]
     4560*/
     4561SQLITE_API int sqlite3_blob_open(
    51764562  sqlite3*,
    51774563  const char *zDb,
    … …  
    51844570
    51854571/*
    5186 ** CAPI3REF:  Close A BLOB Handle {F17830}
    5187 **
    5188 ** Close an open [sqlite3_blob | blob handle].
     4572** CAPI3REF:
     4573**
     4574** Close handle].
    51894575**
    51904576** Closing a BLOB shall cause the current transaction to commit
    51914577** if there are no other BLOBs, no pending prepared statements, and the
    5192 ** database connection is in autocommit mode.
     4578** database connection is in .
    51934579** If any writes were made to the BLOB, they might be held in cache
    5194 ** until the close operation if they will fit. {END}
     4580** until the close operation if they will fit.
     4581**
    51954582** Closing the BLOB often forces the changes
    51964583** out to disk and so if any I/O errors occur, they will likely occur
    5197 ** at the time when the BLOB is closed.  {F17833} Any errors that occur during
     4584** at the time when the BLOB is closed.  Any errors that occur during
    51984585** closing are reported as a non-zero return value.
    51994586**
    … …  
    52014588** an error code, the BLOB is still closed.
    52024589**
    5203 ** INVARIANTS:
    5204 **
    5205 ** {F17833} The [sqlite3_blob_close(P)] interface closes an
    5206 **          [sqlite3_blob] object P previously opened using
    5207 **          [sqlite3_blob_open()].
    5208 **
    5209 ** {F17836} Closing an [sqlite3_blob] object using
    5210 **          [sqlite3_blob_close()] shall cause the current transaction to
    5211 **          commit if there are no other open [sqlite3_blob] objects
    5212 **          or [prepared statements] on the same [database connection] and
    5213 **          the [database connection] is in
    5214 **          [sqlite3_get_autocommit | autocommit mode].
    5215 **
    5216 ** {F17839} The [sqlite3_blob_close(P)] interfaces closes the
    5217 **          [sqlite3_blob] object P unconditionally, even if
    5218 **          [sqlite3_blob_close(P)] returns something other than [SQLITE_OK].
    5219 **         
    5220 */
    5221 int sqlite3_blob_close(sqlite3_blob *);
    5222 
    5223 /*
    5224 ** CAPI3REF:  Return The Size Of An Open BLOB {F17840}
    5225 **
    5226 ** Return the size in bytes of the blob accessible via the open
    5227 ** [sqlite3_blob] object in its only argument.
    5228 **
    5229 ** INVARIANTS:
    5230 **
    5231 ** {F17843} The [sqlite3_blob_bytes(P)] interface returns the size
    5232 **          in bytes of the BLOB that the [sqlite3_blob] object P
    5233 **          refers to.
    5234 */
    5235 int sqlite3_blob_bytes(sqlite3_blob *);
    5236 
    5237 /*
    5238 ** CAPI3REF:  Read Data From A BLOB Incrementally {F17850}
    5239 **
    5240 ** This function is used to read data from an open
    5241 ** [sqlite3_blob | blob-handle] into a caller supplied buffer.
    5242 ** N bytes of data are copied into buffer
    5243 ** Z from the open blob, starting at offset iOffset.
    5244 **
    5245 ** If offset iOffset is less than N bytes from the end of the blob,
     4590** Calling this routine with a null pointer (which as would be returned
     4591** by failed call to [sqlite3_blob_open()]) is a harmless no-op.
     4592**
     4593** Requirements:
     4594** [H17833] [H17836] [H17839]
     4595*/
     4596SQLITE_API int sqlite3_blob_close(sqlite3_blob *);
     4597
     4598/*
     4599** CAPI3REF: Return The Size Of An Open BLOB {H17840} <S30230>
     4600**
     4601** Returns the size in bytes of the BLOB accessible via the
     4602** successfully opened [BLOB handle] in its only argument.  The
     4603** incremental blob I/O routines can only read or overwriting existing
     4604** blob content; they cannot change the size of a blob.
     4605**
     4606** This routine only works on a [BLOB handle] which has been created
     4607** by a prior successful call to [sqlite3_blob_open()] and which has not
     4608** been closed by [sqlite3_blob_close()].  Passing any other pointer in
     4609** to this routine results in undefined and probably undesirable behavior.
     4610**
     4611** Requirements:
     4612** [H17843]
     4613*/
     4614SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *);
     4615
     4616/*
     4617** CAPI3REF: Read Data From A BLOB Incrementally {H17850} <S30230>
     4618**
     4619** This function is used to read data from an open [BLOB handle] into a
     4620** caller-supplied buffer. N bytes of data are copied into buffer Z
     4621** from the open BLOB, starting at offset iOffset.
     4622**
     4623** If offset iOffset is less than N bytes from the end of the BLOB,
    52464624** [SQLITE_ERROR] is returned and no data is read.  If N or iOffset is
    5247 ** less than zero [SQLITE_ERROR] is returned and no data is read.
    5248 **
    5249 ** On success, SQLITE_OK is returned. Otherwise, an
    5250 ** [error code] or an [extended error code] is returned.
    5251 **
    5252 ** INVARIANTS:
    5253 **
    5254 ** {F17853} The [sqlite3_blob_read(P,Z,N,X)] interface reads N bytes
    5255 **          beginning at offset X from
    5256 **          the blob that [sqlite3_blob] object P refers to
    5257 **          and writes those N bytes into buffer Z.
    5258 **
    5259 ** {F17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the blob
    5260 **          is less than N+X bytes, then the function returns [SQLITE_ERROR]
    5261 **          and nothing is read from the blob.
    5262 **
    5263 ** {F17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero
    5264 **          then the function returns [SQLITE_ERROR]
    5265 **          and nothing is read from the blob.
    5266 **
    5267 ** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface returns [SQLITE_OK]
    5268 **          if N bytes where successfully read into buffer Z.
    5269 **
    5270 ** {F17865} If the requested read could not be completed,
    5271 **          the [sqlite3_blob_read(P,Z,N,X)] interface returns an
    5272 **          appropriate [error code] or [extended error code].
    5273 **
    5274 ** {F17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)]
    5275 **          then subsequent calls to [sqlite3_errcode(D)],
    5276 **          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
    5277 **          information approprate for that error, where D is the
    5278 **          database handle that was used to open blob handle P.
    5279 */
    5280 int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
    5281 
    5282 /*
    5283 ** CAPI3REF:  Write Data Into A BLOB Incrementally {F17870}
    5284 **
    5285 ** This function is used to write data into an open
    5286 ** [sqlite3_blob | blob-handle] from a user supplied buffer.
    5287 ** n bytes of data are copied from the buffer
    5288 ** pointed to by z into the open blob, starting at offset iOffset.
    5289 **
    5290 ** If the [sqlite3_blob | blob-handle] passed as the first argument
    5291 ** was not opened for writing (the flags parameter to [sqlite3_blob_open()]
    5292 *** was zero), this function returns [SQLITE_READONLY].
    5293 **
    5294 ** This function may only modify the contents of the blob; it is
    5295 ** not possible to increase the size of a blob using this API.
    5296 ** If offset iOffset is less than n bytes from the end of the blob,
    5297 ** [SQLITE_ERROR] is returned and no data is written.  If n is
     4625** less than zero, [SQLITE_ERROR] is returned and no data is read.
     4626** The size of the blob (and hence the maximum value of N+iOffset)
     4627** can be determined using the [sqlite3_blob_bytes()] interface.
     4628**
     4629** An attempt to read from an expired [BLOB handle] fails with an
     4630** error code of [SQLITE_ABORT].
     4631**
     4632** On success, SQLITE_OK is returned.
     4633** Otherwise, an [error code] or an [extended error code] is returned.
     4634**
     4635** This routine only works on a [BLOB handle] which has been created
     4636** by a prior successful call to [sqlite3_blob_open()] and which has not
     4637** been closed by [sqlite3_blob_close()].  Passing any other pointer in
     4638** to this routine results in undefined and probably undesirable behavior.
     4639**
     4640** See also: [sqlite3_blob_write()].
     4641**
     4642** Requirements:
     4643** [H17853] [H17856] [H17859] [H17862] [H17863] [H17865] [H17868]
     4644*/
     4645SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
     4646
     4647/*
     4648** CAPI3REF: Write Data Into A BLOB Incrementally {H17870} <S30230>
     4649**
     4650** This function is used to write data into an open [BLOB handle] from a
     4651** caller-supplied buffer. N bytes of data are copied from the buffer Z
     4652** into the open BLOB, starting at offset iOffset.
     4653**
     4654** If the [BLOB handle] passed as the first argument was not opened for
     4655** writing (the flags parameter to [sqlite3_blob_open()] was zero),
     4656** this function returns [SQLITE_READONLY].
     4657**
     4658** This function may only modify the contents of the BLOB; it is
     4659** not possible to increase the size of a BLOB using this API.
     4660** If offset iOffset is less than N bytes from the end of the BLOB,
     4661** [SQLITE_ERROR] is returned and no data is written.  If N is
    52984662** less than zero [SQLITE_ERROR] is returned and no data is written.
    5299 **
    5300 ** On success, SQLITE_OK is returned. Otherwise, an
    5301 ** [error code] or an [extended error code] is returned.
    5302 **
    5303 ** INVARIANTS:
    5304 **
    5305 ** {F17873} The [sqlite3_blob_write(P,Z,N,X)] interface writes N bytes
    5306 **          from buffer Z into
    5307 **          the blob that [sqlite3_blob] object P refers to
    5308 **          beginning at an offset of X into the blob.
    5309 **
    5310 ** {F17875} The [sqlite3_blob_write(P,Z,N,X)] interface returns
    5311 **          [SQLITE_READONLY] if the [sqlite3_blob] object P was
    5312 **          [sqlite3_blob_open | opened] for reading only.
    5313 **
    5314 ** {F17876} In [sqlite3_blob_write(P,Z,N,X)] if the size of the blob
    5315 **          is less than N+X bytes, then the function returns [SQLITE_ERROR]
    5316 **          and nothing is written into the blob.
    5317 **
    5318 ** {F17879} In [sqlite3_blob_write(P,Z,N,X)] if X or N is less than zero
    5319 **          then the function returns [SQLITE_ERROR]
    5320 **          and nothing is written into the blob.
    5321 **
    5322 ** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface returns [SQLITE_OK]
    5323 **          if N bytes where successfully written into blob.
    5324 **
    5325 ** {F17885} If the requested write could not be completed,
    5326 **          the [sqlite3_blob_write(P,Z,N,X)] interface returns an
    5327 **          appropriate [error code] or [extended error code].
    5328 **
    5329 ** {F17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)]
    5330 **          then subsequent calls to [sqlite3_errcode(D)],
    5331 **          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
    5332 **          information approprate for that error.
    5333 */
    5334 int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
    5335 
    5336 /*
    5337 ** CAPI3REF:  Virtual File System Objects {F11200}
     4663** The size of the BLOB (and hence the maximum value of N+iOffset)
     4664** can be determined using the [sqlite3_blob_bytes()] interface.
     4665**
     4666** An attempt to write to an expired [BLOB handle] fails with an
     4667** error code of [SQLITE_ABORT].  Writes to the BLOB that occurred
     4668** before the [BLOB handle] expired are not rolled back by the
     4669** expiration of the handle, though of course those changes might
     4670** have been overwritten by the statement that expired the BLOB handle
     4671** or by other independent statements.
     4672**
     4673** On success, SQLITE_OK is returned.
     4674** Otherwise, an  [error code] or an [extended error code] is returned.
     4675**
     4676** This routine only works on a [BLOB handle] which has been created
     4677** by a prior successful call to [sqlite3_blob_open()] and which has not
     4678** been closed by [sqlite3_blob_close()].  Passing any other pointer in
     4679** to this routine results in undefined and probably undesirable behavior.
     4680**
     4681** See also: [sqlite3_blob_read()].
     4682**
     4683** Requirements:
     4684** [H17873] [H17874] [H17875] [H17876] [H17877] [H17879] [H17882] [H17885]
     4685** [H17888]
     4686*/
     4687SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
     4688
     4689/*
     4690** CAPI3REF: Virtual File System Objects {H11200} <S20100>
    53384691**
    53394692** A virtual filesystem (VFS) is an [sqlite3_vfs] object
    … …  
    53444697** The following interfaces are provided.
    53454698**
    5346 ** The sqlite3_vfs_find() interface returns a pointer to
    5347 ** a VFS given its name.  Names are case sensitive.
     4699** The sqlite3_vfs_find() interface returns a pointer to
     4700** Names are case sensitive.
    53484701** Names are zero-terminated UTF-8 strings.
    5349 ** If there is no match, a NULL
    5350 ** pointer is returned.  If zVfsName is NULL then the default
    5351 ** VFS is returned.
     4702** If there is no match, a NULL pointer is returned.
     4703** If zVfsName is NULL then the default VFS is returned.
    53524704**
    53534705** New VFSes are registered with sqlite3_vfs_register().
    … …  
    53594711** VFS is registered with a name that is NULL or an empty string,
    53604712** then the behavior is undefined.
    5361 ** 
     4713**
    53624714** Unregister a VFS with the sqlite3_vfs_unregister() interface.
    53634715** If the default VFS is unregistered, another VFS is chosen as
    53644716** the default.  The choice for the new VFS is arbitrary.
    53654717**
    5366 ** INVARIANTS:
    5367 **
    5368 ** {F11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the
    5369 **          registered [sqlite3_vfs] object whose name exactly matches
    5370 **          the zero-terminated UTF-8 string N, or it returns NULL if
    5371 **          there is no match.
    5372 **
    5373 ** {F11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then
    5374 **          the function returns a pointer to the default [sqlite3_vfs]
    5375 **          object if there is one, or NULL if there is no default
    5376 **          [sqlite3_vfs] object.
    5377 **
    5378 ** {F11209} The [sqlite3_vfs_register(P,F)] interface registers the
    5379 **          well-formed [sqlite3_vfs] object P using the name given
    5380 **          by the zName field of the object.
    5381 **
    5382 ** {F11212} Using the [sqlite3_vfs_register(P,F)] interface to register
    5383 **          the same [sqlite3_vfs] object multiple times is a harmless no-op.
    5384 **
    5385 ** {F11215} The [sqlite3_vfs_register(P,F)] interface makes the
    5386 **          the [sqlite3_vfs] object P the default [sqlite3_vfs] object
    5387 **          if F is non-zero.
    5388 **
    5389 ** {F11218} The [sqlite3_vfs_unregister(P)] interface unregisters the
    5390 **          [sqlite3_vfs] object P so that it is no longer returned by
    5391 **          subsequent calls to [sqlite3_vfs_find()].
    5392 */
    5393 sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
    5394 int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
    5395 int sqlite3_vfs_unregister(sqlite3_vfs*);
    5396 
    5397 /*
    5398 ** CAPI3REF: Mutexes {F17000}
     4718** Requirements:
     4719** [H11203] [H11206] [H11209] [H11212] [H11215] [H11218]
     4720*/
     4721SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
     4722SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
     4723SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
     4724
     4725/*
     4726** CAPI3REF: Mutexes {H17000} <S20000>
    53994727**
    54004728** The SQLite core uses these routines for thread
    5401 ** synchronization.  Though they are intended for internal
     4729** synchronization. Though they are intended for internal
    54024730** use by SQLite, code that links against SQLite is
    54034731** permitted to use any of these routines.
    54044732**
    5405 ** The SQLite source code contains multiple implementations 
     4733** The SQLite source code contains multiple implementations
    54064734** of these mutex routines.  An appropriate implementation
    54074735** is selected automatically at compile-time.  The following
    … …  
    54154743** </ul>
    54164744**
    5417 ** The SQLITE_MUTEX_NOOP implementation is a set of routines 
    5418 ** that does no real locking and is appropriate for use in 
     4745** The SQLITE_MUTEX_NOOP implementation is a set of routines
     4746** that does no real locking and is appropriate for use in
    54194747** a single-threaded application.  The SQLITE_MUTEX_OS2,
    54204748** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations
    5421 ** are appropriate for use on os/2, unix, and windows.
    5422 ** 
     4749** are appropriate for use on indows.
     4750**
    54234751** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
    54244752** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
    5425 ** implementation is included with the library.  The
    5426 ** mutex interface routines defined here become external
    5427 ** references in the SQLite library for which implementations
    5428 ** must be provided by the application.  This facility allows an
    5429 ** application that links against SQLite to provide its own mutex
    5430 ** implementation without having to modify the SQLite core.
    5431 **
    5432 ** {F17011} The sqlite3_mutex_alloc() routine allocates a new
    5433 ** mutex and returns a pointer to it. {F17012} If it returns NULL
    5434 ** that means that a mutex could not be allocated. {F17013} SQLite
    5435 ** will unwind its stack and return an error. {F17014} The argument
     4753** implementation is included with the library. In this case the
     4754** application must supply a custom mutex implementation using the
     4755** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function
     4756** before calling sqlite3_initialize() or any other public sqlite3_
     4757** function that calls sqlite3_initialize().
     4758**
     4759** {H17011} The sqlite3_mutex_alloc() routine allocates a new
     4760** mutex and returns a pointer to it. {H17012} If it returns NULL
     4761** that means that a mutex could not be allocated. {H17013} SQLite
     4762** will unwind its stack and return an error. {H17014} The argument
    54364763** to sqlite3_mutex_alloc() is one of these integer constants:
    54374764**
    … …  
    54454772** <li>  SQLITE_MUTEX_STATIC_LRU
    54464773** <li>  SQLITE_MUTEX_STATIC_LRU2
    5447 ** </ul> {END}
    5448 **
    5449 ** {F17015} The first two constants cause sqlite3_mutex_alloc() to create
     4774** </ul>
     4775**
     4776** {17015} The first two constants cause sqlite3_mutex_alloc() to create
    54504777** a new mutex.  The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
    54514778** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END}
    54524779** The mutex implementation does not need to make a distinction
    54534780** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
    5454 ** not want to.  {F17016} But SQLite will only request a recursive mutex in
     4781** not want to.  {17016} But SQLite will only request a recursive mutex in
    54554782** cases where it really needs one.  {END} If a faster non-recursive mutex
    54564783** implementation is available on the host platform, the mutex subsystem
    54574784** might return such a mutex in response to SQLITE_MUTEX_FAST.
    54584785**
    5459 ** {F17017} The other allowed parameters to sqlite3_mutex_alloc() each return
    5460 ** a pointer to a static preexisting mutex. {END}  Four static mutexes are
     4786** {17017} The other allowed parameters to sqlite3_mutex_alloc() each return
     4787** a pointer to a static preexisting mutex. {END}  static mutexes are
    54614788** used by the current version of SQLite.  Future versions of SQLite
    54624789** may add additional static mutexes.  Static mutexes are for internal
    … …  
    54654792** SQLITE_MUTEX_RECURSIVE.
    54664793**
    5467 ** {F17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
     4794** {17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
    54684795** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
    5469 ** returns a different mutex on every call.  {F17034} But for the static
     4796** returns a different mutex on every call.  {
    54704797** mutex types, the same mutex is returned on every call that has
    5471 ** the same type number. {END}
    5472 **
    5473 ** {F17019} The sqlite3_mutex_free() routine deallocates a previously
    5474 ** allocated dynamic mutex. {F17020} SQLite is careful to deallocate every
    5475 ** dynamic mutex that it allocates. {U17021} The dynamic mutexes must not be in
    5476 ** use when they are deallocated. {U17022} Attempting to deallocate a static
    5477 ** mutex results in undefined behavior. {F17023} SQLite never deallocates
     4798** the same type number.
     4799**
     4800** {17019} The sqlite3_mutex_free() routine deallocates a previously
     4801** allocated dynamic mutex. {17020} SQLite is careful to deallocate every
     4802** dynamic mutex that it allocates. {
     4803** use when they are deallocated. {17022} Attempting to deallocate a static
     4804** mutex results in undefined behavior. {17023} SQLite never deallocates
    54784805** a static mutex. {END}
    54794806**
    54804807** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
    5481 ** to enter a mutex. {F17024} If another thread is already within the mutex,
     4808** to enter a mutex. {17024} If another thread is already within the mutex,
    54824809** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
    5483 ** SQLITE_BUSY. {F17025}  The sqlite3_mutex_try() interface returns SQLITE_OK
    5484 ** upon successful entry.  {F17026} Mutexes created using
     4810** SQLITE_BUSY. {
     4811** upon successful entry.  {17026} Mutexes created using
    54854812** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
    5486 ** {F17027} In such cases the,
     4813** {17027} In such cases the,
    54874814** mutex must be exited an equal number of times before another thread
    5488 ** can enter.  {U17028} If the same thread tries to enter any other
     4815** can enter.  {17028} If the same thread tries to enter any other
    54894816** kind of mutex more than once, the behavior is undefined.
    5490 ** {F17029} SQLite will never exhibit
    5491 ** such behavior in its own use of mutexes. {END}
    5492 **
    5493 ** Some systems (ex: windows95) do not the operation implemented by
    5494 ** sqlite3_mutex_try().  On those systems, sqlite3_mutex_try() will
    5495 ** always return SQLITE_BUSY.  {F17030} The SQLite core only ever uses
    5496 ** sqlite3_mutex_try() as an optimization so this is acceptable behavior. {END}
    5497 **
    5498 ** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was
    5499 ** previously entered by the same thread.  {U17032} The behavior
     4817** {17029} SQLite will never exhibit
     4818** such behavior in its own use of mutexes.
     4819**
     4820** Some systems (
     4821**
     4822** 17030} The SQLite core only ever uses
     4823** sqlite3_mutex_try() as an optimization so this is acceptable behavior.
     4824**
     4825** {17031} The sqlite3_mutex_leave() routine exits a mutex that was
     4826** previously entered by the same thread.  {17032} The behavior
    55004827** is undefined if the mutex is not currently entered by the
    5501 ** calling thread or is not currently allocated.  {F17033} SQLite will
     4828** calling thread or is not currently allocated.  {17033} SQLite will
    55024829** never do either. {END}
    55034830**
     4831
     4832
     4833
     4834
    55044835** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
    55054836*/
    5506 sqlite3_mutex *sqlite3_mutex_alloc(int);
    5507 void sqlite3_mutex_free(sqlite3_mutex*);
    5508 void sqlite3_mutex_enter(sqlite3_mutex*);
    5509 int sqlite3_mutex_try(sqlite3_mutex*);
    5510 void sqlite3_mutex_leave(sqlite3_mutex*);
    5511 
    5512 /*
    5513 ** CAPI3REF: Mutex Verifcation Routines {F17080}
     4837SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);
     4838SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*);
     4839SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*);
     4840SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
     4841SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
     4842
     4843/*
     4844** CAPI3REF: Mutex Methods Object {H17120} <S20130>
     4845** EXPERIMENTAL
     4846**
     4847** An instance of this structure defines the low-level routines
     4848** used to allocate and use mutexes.
     4849**
     4850** Usually, the default mutex implementations provided by SQLite are
     4851** sufficient, however the user has the option of substituting a custom
     4852** implementation for specialized deployments or systems for which SQLite
     4853** does not provide a suitable implementation. In this case, the user
     4854** creates and populates an instance of this structure to pass
     4855** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
     4856** Additionally, an instance of this structure can be used as an
     4857** output variable when querying the system for the current mutex
     4858** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.
     4859**
     4860** The xMutexInit method defined by this structure is invoked as
     4861** part of system initialization by the sqlite3_initialize() function.
     4862** {H17001} The xMutexInit routine shall be called by SQLite once for each
     4863** effective call to [sqlite3_initialize()].
     4864**
     4865** The xMutexEnd method defined by this structure is invoked as
     4866** part of system shutdown by the sqlite3_shutdown() function. The
     4867** implementation of this method is expected to release all outstanding
     4868** resources obtained by the mutex methods implementation, especially
     4869** those obtained by the xMutexInit method. {H17003} The xMutexEnd()
     4870** interface shall be invoked once for each call to [sqlite3_shutdown()].
     4871**
     4872** The remaining seven methods defined by this structure (xMutexAlloc,
     4873** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
     4874** xMutexNotheld) implement the following interfaces (respectively):
     4875**
     4876** <ul>
     4877**   <li>  [sqlite3_mutex_alloc()] </li>
     4878**   <li>  [sqlite3_mutex_free()] </li>
     4879**   <li>  [sqlite3_mutex_enter()] </li>
     4880**   <li>  [sqlite3_mutex_try()] </li>
     4881**   <li>  [sqlite3_mutex_leave()] </li>
     4882**   <li>  [sqlite3_mutex_held()] </li>
     4883**   <li>  [sqlite3_mutex_notheld()] </li>
     4884** </ul>
     4885**
     4886** The only difference is that the public sqlite3_XXX functions enumerated
     4887** above silently ignore any invocations that pass a NULL pointer instead
     4888** of a valid mutex handle. The implementations of the methods defined
     4889** by this structure are not required to handle this case, the results
     4890** of passing a NULL pointer instead of a valid mutex handle are undefined
     4891** (i.e. it is acceptable to provide an implementation that segfaults if
     4892** it is passed a NULL pointer).
     4893**
     4894** The xMutexInit() method must be threadsafe.  It must be harmless to
     4895** invoke xMutexInit() mutiple times within the same process and without
     4896** intervening calls to xMutexEnd().  Second and subsequent calls to
     4897** xMutexInit() must be no-ops.
     4898**
     4899** xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
     4900** and its associates).  Similarly, xMutexAlloc() must not use SQLite memory
     4901** allocation for a static mutex.  However xMutexAlloc() may use SQLite
     4902** memory allocation for a fast or recursive mutex.
     4903**
     4904** SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
     4905** called, but only if the prior call to xMutexInit returned SQLITE_OK.
     4906** If xMutexInit fails in any way, it is expected to clean up after itself
     4907** prior to returning.
     4908*/
     4909typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
     4910struct sqlite3_mutex_methods {
     4911  int (*xMutexInit)(void);
     4912  int (*xMutexEnd)(void);
     4913  sqlite3_mutex *(*xMutexAlloc)(int);
     4914  void (*xMutexFree)(sqlite3_mutex *);
     4915  void (*xMutexEnter)(sqlite3_mutex *);
     4916  int (*xMutexTry)(sqlite3_mutex *);
     4917  void (*xMutexLeave)(sqlite3_mutex *);
     4918  int (*xMutexHeld)(sqlite3_mutex *);
     4919  int (*xMutexNotheld)(sqlite3_mutex *);
     4920};
     4921
     4922/*
     4923** CAPI3REF: Mutex Verification Routines {H17080} <S20130> <S30800>
    55144924**
    55154925** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
    5516 ** are intended for use inside assert() statements. {F17081} The SQLite core
     4926** are intended for use inside assert() statements. {17081} The SQLite core
    55174927** never uses these routines except inside an assert() and applications
    5518 ** are advised to follow the lead of the core.  {F17082} The core only
     4928** are advised to follow the lead of the core.  {17082} The core only
    55194929** provides implementations for these routines when it is compiled
    5520 ** with the SQLITE_DEBUG flag.  {U17087} External mutex implementations
     4930** with the SQLITE_DEBUG flag.  {17087} External mutex implementations
    55214931** are only required to provide these routines if SQLITE_DEBUG is
    55224932** defined and if NDEBUG is not defined.
    55234933**
    5524 ** {F17083} These routines should return true if the mutex in their argument
    5525 ** is held or not held, respectively, by the calling thread. {END}
     4934** {17083} These routines should return true if the mutex in their argument
     4935** is held or not held, respectively, by the calling thread.
    55264936**
    55274937** {X17084} The implementation is not required to provided versions of these
    5528 ** routines that actually work.
    5529 ** If the implementation does not provide working
    5530 ** versions of these routines, it should at least provide stubs
    5531 ** that always return true so that one does not get spurious
    5532 ** assertion failures. {END}
    5533 **
    5534 ** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then
     4938** routines that actually work. If the implementation does not provide working
     4939** versions of these routines, it should at least provide stubs that always
     4940** return true so that one does not get spurious assertion failures.
     4941**
     4942** {H17085} If the argument to sqlite3_mutex_held() is a NULL pointer then
    55354943** the routine should return 1.  {END} This seems counter-intuitive since
    55364944** clearly the mutex cannot be held if it does not exist.  But the
    … …  
    55384946** using mutexes.  And we do not want the assert() containing the
    55394947** call to sqlite3_mutex_held() to fail, so a non-zero return is
    5540 ** the appropriate thing to do.  {F17086} The sqlite3_mutex_notheld()
     4948** the appropriate thing to do.  {
    55414949** interface should also return 1 when given a NULL pointer.
    55424950*/
    5543 int sqlite3_mutex_held(sqlite3_mutex*);
    5544 int sqlite3_mutex_notheld(sqlite3_mutex*);
    5545 
    5546 /*
    5547 ** CAPI3REF: Mutex Types {F17001}
    5548 **
    5549 ** {F17002} The [sqlite3_mutex_alloc()] interface takes a single argument
    5550 ** which is one of these integer constants. {END}
     4951SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);
     4952SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
     4953
     4954/*
     4955** CAPI3REF: Mutex Types {H17001} <H17000>
     4956**
     4957** The [sqlite3_mutex_alloc()] interface takes a single argument
     4958** which is one of these integer constants.
     4959**
     4960** The set of static mutexes may change from one SQLite release to the
     4961** next.  Applications that override the built-in mutex logic must be
     4962** prepared to accommodate additional static mutexes.
    55514963*/
    55524964#define SQLITE_MUTEX_FAST             0
    … …  
    55544966#define SQLITE_MUTEX_STATIC_MASTER    2
    55554967#define SQLITE_MUTEX_STATIC_MEM       3  /* sqlite3_malloc() */
    5556 #define SQLITE_MUTEX_STATIC_MEM2      4  /* sqlite3_release_memory() */
     4968#define SQLITE_MUTEX_STATIC_MEM2      4  /* NOT USED */
     4969#define SQLITE_MUTEX_STATIC_OPEN      4  /* sqlite3BtreeOpen() */
    55574970#define SQLITE_MUTEX_STATIC_PRNG      5  /* sqlite3_random() */
    55584971#define SQLITE_MUTEX_STATIC_LRU       6  /* lru page list */
    … …  
    55604973
    55614974/*
    5562 ** CAPI3REF: Low-Level Control Of Database Files {F11300}
    5563 **
    5564 ** {F11301} The [sqlite3_file_control()] interface makes a direct call to the
     4975** CAPI3REF: Retrieve the mutex for a database connection {H17002} <H17000>
     4976**
     4977** This interface returns a pointer the [sqlite3_mutex] object that
     4978** serializes access to the [database connection] given in the argument
     4979** when the [threading mode] is Serialized.
     4980** If the [threading mode] is Single-thread or Multi-thread then this
     4981** routine returns a NULL pointer.
     4982*/
     4983SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
     4984
     4985/*
     4986** CAPI3REF: Low-Level Control Of Database Files {H11300} <S30800>
     4987**
     4988** {H11301} The [sqlite3_file_control()] interface makes a direct call to the
    55654989** xFileControl method for the [sqlite3_io_methods] object associated
    5566 ** with a particular database identified by the second argument. {F11302} The
     4990** with a particular database identified by the second argument. {11302} The
    55674991** name of the database is the name assigned to the database by the
    55684992** <a href="lang_attach.html">ATTACH</a> SQL command that opened the
    5569 ** database. {F11303} To control the main database file, use the name "main"
    5570 ** or a NULL pointer. {F11304} The third and fourth parameters to this routine
     4993** database. {11303} To control the main database file, use the name "main"
     4994** or a NULL pointer. {11304} The third and fourth parameters to this routine
    55714995** are passed directly through to the second and third parameters of
    5572 ** the xFileControl method.  {F11305} The return value of the xFileControl
     4996** the xFileControl method.  {11305} The return value of the xFileControl
    55734997** method becomes the return value of this routine.
    55744998**
    5575 ** {F11306} If the second parameter (zDbName) does not match the name of any
    5576 ** open database file, then SQLITE_ERROR is returned. {F11307} This error
     4999** {11306} If the second parameter (zDbName) does not match the name of any
     5000** open database file, then SQLITE_ERROR is returned. {11307} This error
    55775001** code is not remembered and will not be recalled by [sqlite3_errcode()]
    5578 ** or [sqlite3_errmsg()]. {U11308} The underlying xFileControl method might
    5579 ** also return SQLITE_ERROR.  {U11309} There is no way to distinguish between
     5002** or [sqlite3_errmsg()]. {11308} The underlying xFileControl method might
     5003** also return SQLITE_ERROR.  {11309} There is no way to distinguish between
    55805004** an incorrect zDbName and an SQLITE_ERROR return from the underlying
    55815005** xFileControl method. {END}
    … …  
    55835007** See also: [SQLITE_FCNTL_LOCKSTATE]
    55845008*/
    5585 int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
    5586 
    5587 /*
    5588 ** CAPI3REF: Testing Interface {F11400}
     5009int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
     5010
     5011/*
     5012** CAPI3REF: Testing Interface {
    55895013**
    55905014** The sqlite3_test_control() interface is used to read out internal
    55915015** state of SQLite and to inject faults into SQLite for testing
    5592 ** purposes.  The first parameter a operation code that determines
     5016** purposes.  The first parameter operation code that determines
    55935017** the number, meaning, and operation of all subsequent parameters.
    55945018**
    … …  
    56025026** operate consistently from one release to the next.
    56035027*/
    5604 int sqlite3_test_control(int op, ...);
    5605 
    5606 /*
    5607 ** CAPI3REF: Testing Interface Operation Codes {F11410}
     5028int sqlite3_test_control(int op, ...);
     5029
     5030/*
     5031** CAPI3REF: Testing Interface Operation Codes {
    56085032**
    56095033** These constants are the valid operation code parameters used
    56105034** as the first argument to [sqlite3_test_control()].
    56115035**
    5612 ** These parameters and their meansing are subject to change
     5036** These parameters and their mean are subject to change
    56135037** without notice.  These values are for testing purposes only.
    56145038** Applications should not use any of these parameters or the
    56155039** [sqlite3_test_control()] interface.
    56165040*/
    5617 #define SQLITE_TESTCTRL_FAULT_CONFIG             1
    5618 #define SQLITE_TESTCTRL_FAULT_FAILURES           2
    5619 #define SQLITE_TESTCTRL_FAULT_BENIGN_FAILURES    3
    5620 #define SQLITE_TESTCTRL_FAULT_PENDING            4
    56215041#define SQLITE_TESTCTRL_PRNG_SAVE                5
    56225042#define SQLITE_TESTCTRL_PRNG_RESTORE             6
    56235043#define SQLITE_TESTCTRL_PRNG_RESET               7
    56245044#define SQLITE_TESTCTRL_BITVEC_TEST              8
    5625 
     5045#define SQLITE_TESTCTRL_FAULT_INSTALL            9
     5046#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS     10
     5047#define SQLITE_TESTCTRL_PENDING_BYTE            11
     5048#define SQLITE_TESTCTRL_ASSERT                  12
     5049#define SQLITE_TESTCTRL_ALWAYS                  13
     5050#define SQLITE_TESTCTRL_RESERVE                 14
     5051
     5052/*
     5053** CAPI3REF: SQLite Runtime Status {H17200} <S60200>
     5054** EXPERIMENTAL
     5055**
     5056** This interface is used to retrieve runtime status information
     5057** about the preformance of SQLite, and optionally to reset various
     5058** highwater marks.  The first argument is an integer code for
     5059** the specific parameter to measure.  Recognized integer codes
     5060** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...].
     5061** The current value of the parameter is returned into *pCurrent.
     5062** The highest recorded value is returned in *pHighwater.  If the
     5063** resetFlag is true, then the highest record value is reset after
     5064** *pHighwater is written. Some parameters do not record the highest
     5065** value.  For those parameters
     5066** nothing is written into *pHighwater and the resetFlag is ignored.
     5067** Other parameters record only the highwater mark and not the current
     5068** value.  For these latter parameters nothing is written into *pCurrent.
     5069**
     5070** This routine returns SQLITE_OK on success and a non-zero
     5071** [error code] on failure.
     5072**
     5073** This routine is threadsafe but is not atomic.  This routine can be
     5074** called while other threads are running the same or different SQLite
     5075** interfaces.  However the values returned in *pCurrent and
     5076** *pHighwater reflect the status of SQLite at different points in time
     5077** and it is possible that another thread might change the parameter
     5078** in between the times when *pCurrent and *pHighwater are written.
     5079**
     5080** See also: [sqlite3_db_status()]
     5081*/
     5082SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
     5083
     5084
     5085/*
     5086** CAPI3REF: Status Parameters {H17250} <H17200>
     5087** EXPERIMENTAL
     5088**
     5089** These integer constants designate various run-time status parameters
     5090** that can be returned by [sqlite3_status()].
     5091**
     5092** <dl>
     5093** <dt>SQLITE_STATUS_MEMORY_USED</dt>
     5094** <dd>This parameter is the current amount of memory checked out
     5095** using [sqlite3_malloc()], either directly or indirectly.  The
     5096** figure includes calls made to [sqlite3_malloc()] by the application
     5097** and internal memory usage by the SQLite library.  Scratch memory
     5098** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache
     5099** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
     5100** this parameter.  The amount returned is the sum of the allocation
     5101** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>
     5102**
     5103** <dt>SQLITE_STATUS_MALLOC_SIZE</dt>
     5104** <dd>This parameter records the largest memory allocation request
     5105** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
     5106** internal equivalents).  Only the value returned in the
     5107** *pHighwater parameter to [sqlite3_status()] is of interest. 
     5108** The value written into the *pCurrent parameter is undefined.</dd>
     5109**
     5110** <dt>SQLITE_STATUS_PAGECACHE_USED</dt>
     5111** <dd>This parameter returns the number of pages used out of the
     5112** [pagecache memory allocator] that was configured using
     5113** [SQLITE_CONFIG_PAGECACHE].  The
     5114** value returned is in pages, not in bytes.</dd>
     5115**
     5116** <dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
     5117** <dd>This parameter returns the number of bytes of page cache
     5118** allocation which could not be statisfied by the [SQLITE_CONFIG_PAGECACHE]
     5119** buffer and where forced to overflow to [sqlite3_malloc()].  The
     5120** returned value includes allocations that overflowed because they
     5121** where too large (they were larger than the "sz" parameter to
     5122** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
     5123** no space was left in the page cache.</dd>
     5124**
     5125** <dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
     5126** <dd>This parameter records the largest memory allocation request
     5127** handed to [pagecache memory allocator].  Only the value returned in the
     5128** *pHighwater parameter to [sqlite3_status()] is of interest. 
     5129** The value written into the *pCurrent parameter is undefined.</dd>
     5130**
     5131** <dt>SQLITE_STATUS_SCRATCH_USED</dt>
     5132** <dd>This parameter returns the number of allocations used out of the
     5133** [scratch memory allocator] configured using
     5134** [SQLITE_CONFIG_SCRATCH].  The value returned is in allocations, not
     5135** in bytes.  Since a single thread may only have one scratch allocation
     5136** outstanding at time, this parameter also reports the number of threads
     5137** using scratch memory at the same time.</dd>
     5138**
     5139** <dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
     5140** <dd>This parameter returns the number of bytes of scratch memory
     5141** allocation which could not be statisfied by the [SQLITE_CONFIG_SCRATCH]
     5142** buffer and where forced to overflow to [sqlite3_malloc()].  The values
     5143** returned include overflows because the requested allocation was too
     5144** larger (that is, because the requested allocation was larger than the
     5145** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer
     5146** slots were available.
     5147** </dd>
     5148**
     5149** <dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
     5150** <dd>This parameter records the largest memory allocation request
     5151** handed to [scratch memory allocator].  Only the value returned in the
     5152** *pHighwater parameter to [sqlite3_status()] is of interest. 
     5153** The value written into the *pCurrent parameter is undefined.</dd>
     5154**
     5155** <dt>SQLITE_STATUS_PARSER_STACK</dt>
     5156** <dd>This parameter records the deepest parser stack.  It is only
     5157** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>
     5158** </dl>
     5159**
     5160** New status parameters may be added from time to time.
     5161*/
     5162#define SQLITE_STATUS_MEMORY_USED          0
     5163#define SQLITE_STATUS_PAGECACHE_USED       1
     5164#define SQLITE_STATUS_PAGECACHE_OVERFLOW   2
     5165#define SQLITE_STATUS_SCRATCH_USED         3
     5166#define SQLITE_STATUS_SCRATCH_OVERFLOW     4
     5167#define SQLITE_STATUS_MALLOC_SIZE          5
     5168#define SQLITE_STATUS_PARSER_STACK         6
     5169#define SQLITE_STATUS_PAGECACHE_SIZE       7
     5170#define SQLITE_STATUS_SCRATCH_SIZE         8
     5171
     5172/*
     5173** CAPI3REF: Database Connection Status {H17500} <S60200>
     5174** EXPERIMENTAL
     5175**
     5176** This interface is used to retrieve runtime status information
     5177** about a single [database connection].  The first argument is the
     5178** database connection object to be interrogated.  The second argument
     5179** is the parameter to interrogate.  Currently, the only allowed value
     5180** for the second parameter is [SQLITE_DBSTATUS_LOOKASIDE_USED].
     5181** Additional options will likely appear in future releases of SQLite.
     5182**
     5183** The current value of the requested parameter is written into *pCur
     5184** and the highest instantaneous value is written into *pHiwtr.  If
     5185** the resetFlg is true, then the highest instantaneous value is
     5186** reset back down to the current value.
     5187**
     5188** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
     5189*/
     5190SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
     5191
     5192/*
     5193** CAPI3REF: Status Parameters for database connections {H17520} <H17500>
     5194** EXPERIMENTAL
     5195**
     5196** These constants are the available integer "verbs" that can be passed as
     5197** the second argument to the [sqlite3_db_status()] interface.
     5198**
     5199** New verbs may be added in future releases of SQLite. Existing verbs
     5200** might be discontinued. Applications should check the return code from
     5201** [sqlite3_db_status()] to make sure that the call worked.
     5202** The [sqlite3_db_status()] interface will return a non-zero error code
     5203** if a discontinued or unsupported verb is invoked.
     5204**
     5205** <dl>
     5206** <dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
     5207** <dd>This parameter returns the number of lookaside memory slots currently
     5208** checked out.</dd>
     5209** </dl>
     5210*/
     5211#define SQLITE_DBSTATUS_LOOKASIDE_USED     0
     5212
     5213
     5214/*
     5215** CAPI3REF: Prepared Statement Status {H17550} <S60200>
     5216** EXPERIMENTAL
     5217**
     5218** Each prepared statement maintains various
     5219** [SQLITE_STMTSTATUS_SORT | counters] that measure the number
     5220** of times it has performed specific operations.  These counters can
     5221** be used to monitor the performance characteristics of the prepared
     5222** statements.  For example, if the number of table steps greatly exceeds
     5223** the number of table searches or result rows, that would tend to indicate
     5224** that the prepared statement is using a full table scan rather than
     5225** an index. 
     5226**
     5227** This interface is used to retrieve and reset counter values from
     5228** a [prepared statement].  The first argument is the prepared statement
     5229** object to be interrogated.  The second argument
     5230** is an integer code for a specific [SQLITE_STMTSTATUS_SORT | counter]
     5231** to be interrogated.
     5232** The current value of the requested counter is returned.
     5233** If the resetFlg is true, then the counter is reset to zero after this
     5234** interface call returns.
     5235**
     5236** See also: [sqlite3_status()] and [sqlite3_db_status()].
     5237*/
     5238SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
     5239
     5240/*
     5241** CAPI3REF: Status Parameters for prepared statements {H17570} <H17550>
     5242** EXPERIMENTAL
     5243**
     5244** These preprocessor macros define integer codes that name counter
     5245** values associated with the [sqlite3_stmt_status()] interface.
     5246** The meanings of the various counters are as follows:
     5247**
     5248** <dl>
     5249** <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>
     5250** <dd>This is the number of times that SQLite has stepped forward in
     5251** a table as part of a full table scan.  Large numbers for this counter
     5252** may indicate opportunities for performance improvement through
     5253** careful use of indices.</dd>
     5254**
     5255** <dt>SQLITE_STMTSTATUS_SORT</dt>
     5256** <dd>This is the number of sort operations that have occurred.
     5257** A non-zero value in this counter may indicate an opportunity to
     5258** improvement performance through careful use of indices.</dd>
     5259**
     5260** </dl>
     5261*/
     5262#define SQLITE_STMTSTATUS_FULLSCAN_STEP     1
     5263#define SQLITE_STMTSTATUS_SORT              2
     5264
     5265/*
     5266** CAPI3REF: Custom Page Cache Object
     5267** EXPERIMENTAL
     5268**
     5269** The sqlite3_pcache type is opaque.  It is implemented by
     5270** the pluggable module.  The SQLite core has no knowledge of
     5271** its size or internal structure and never deals with the
     5272** sqlite3_pcache object except by holding and passing pointers
     5273** to the object.
     5274**
     5275** See [sqlite3_pcache_methods] for additional information.
     5276*/
     5277typedef struct sqlite3_pcache sqlite3_pcache;
     5278
     5279/*
     5280** CAPI3REF: Application Defined Page Cache.
     5281** KEYWORDS: {page cache}
     5282** EXPERIMENTAL
     5283**
     5284** The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
     5285** register an alternative page cache implementation by passing in an
     5286** instance of the sqlite3_pcache_methods structure. The majority of the
     5287** heap memory used by SQLite is used by the page cache to cache data read
     5288** from, or ready to be written to, the database file. By implementing a
     5289** custom page cache using this API, an application can control more
     5290** precisely the amount of memory consumed by SQLite, the way in which
     5291** that memory is allocated and released, and the policies used to
     5292** determine exactly which parts of a database file are cached and for
     5293** how long.
     5294**
     5295** The contents of the sqlite3_pcache_methods structure are copied to an
     5296** internal buffer by SQLite within the call to [sqlite3_config].  Hence
     5297** the application may discard the parameter after the call to
     5298** [sqlite3_config()] returns.
     5299**
     5300** The xInit() method is called once for each call to [sqlite3_initialize()]
     5301** (usually only once during the lifetime of the process). It is passed
     5302** a copy of the sqlite3_pcache_methods.pArg value. It can be used to set
     5303** up global structures and mutexes required by the custom page cache
     5304** implementation.
     5305**
     5306** The xShutdown() method is called from within [sqlite3_shutdown()],
     5307** if the application invokes this API. It can be used to clean up
     5308** any outstanding resources before process shutdown, if required.
     5309**
     5310** SQLite holds a [SQLITE_MUTEX_RECURSIVE] mutex when it invokes
     5311** the xInit method, so the xInit method need not be threadsafe.  The
     5312** xShutdown method is only called from [sqlite3_shutdown()] so it does
     5313** not need to be threadsafe either.  All other methods must be threadsafe
     5314** in multithreaded applications.
     5315**
     5316** SQLite will never invoke xInit() more than once without an intervening
     5317** call to xShutdown().
     5318**
     5319** The xCreate() method is used to construct a new cache instance.  SQLite
     5320** will typically create one cache instance for each open database file,
     5321** though this is not guaranteed. The
     5322** first parameter, szPage, is the size in bytes of the pages that must
     5323** be allocated by the cache.  szPage will not be a power of two.  szPage
     5324** will the page size of the database file that is to be cached plus an
     5325** increment (here called "R") of about 100 or 200.  SQLite will use the
     5326** extra R bytes on each page to store metadata about the underlying
     5327** database page on disk.  The value of R depends
     5328** on the SQLite version, the target platform, and how SQLite was compiled.
     5329** R is constant for a particular build of SQLite.  The second argument to
     5330** xCreate(), bPurgeable, is true if the cache being created will
     5331** be used to cache database pages of a file stored on disk, or
     5332** false if it is used for an in-memory database. The cache implementation
     5333** does not have to do anything special based with the value of bPurgeable;
     5334** it is purely advisory.  On a cache where bPurgeable is false, SQLite will
     5335** never invoke xUnpin() except to deliberately delete a page.
     5336** In other words, a cache created with bPurgeable set to false will
     5337** never contain any unpinned pages.
     5338**
     5339** The xCachesize() method may be called at any time by SQLite to set the
     5340** suggested maximum cache-size (number of pages stored by) the cache
     5341** instance passed as the first argument. This is the value configured using
     5342** the SQLite "[PRAGMA cache_size]" command. As with the bPurgeable parameter,
     5343** the implementation is not required to do anything with this
     5344** value; it is advisory only.
     5345**
     5346** The xPagecount() method should return the number of pages currently
     5347** stored in the cache.
     5348**
     5349** The xFetch() method is used to fetch a page and return a pointer to it.
     5350** A 'page', in this context, is a buffer of szPage bytes aligned at an
     5351** 8-byte boundary. The page to be fetched is determined by the key. The
     5352** mimimum key value is 1. After it has been retrieved using xFetch, the page
     5353** is considered to be "pinned".
     5354**
     5355** If the requested page is already in the page cache, then the page cache
     5356** implementation must return a pointer to the page buffer with its content
     5357** intact.  If the requested page is not already in the cache, then the
     5358** behavior of the cache implementation is determined by the value of the
     5359** createFlag parameter passed to xFetch, according to the following table:
     5360**
     5361** <table border=1 width=85% align=center>
     5362** <tr><th> createFlag <th> Behaviour when page is not already in cache
     5363** <tr><td> 0 <td> Do not allocate a new page.  Return NULL.
     5364** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
     5365**                 Otherwise return NULL.
     5366** <tr><td> 2 <td> Make every effort to allocate a new page.  Only return
     5367**                 NULL if allocating a new page is effectively impossible.
     5368** </table>
     5369**
     5370** SQLite will normally invoke xFetch() with a createFlag of 0 or 1.  If
     5371** a call to xFetch() with createFlag==1 returns NULL, then SQLite will
     5372** attempt to unpin one or more cache pages by spilling the content of
     5373** pinned pages to disk and synching the operating system disk cache. After
     5374** attempting to unpin pages, the xFetch() method will be invoked again with
     5375** a createFlag of 2.
     5376**
     5377** xUnpin() is called by SQLite with a pointer to a currently pinned page
     5378** as its second argument. If the third parameter, discard, is non-zero,
     5379** then the page should be evicted from the cache. In this case SQLite
     5380** assumes that the next time the page is retrieved from the cache using
     5381** the xFetch() method, it will be zeroed. If the discard parameter is
     5382** zero, then the page is considered to be unpinned. The cache implementation
     5383** may choose to evict unpinned pages at any time.
     5384**
     5385** The cache is not required to perform any reference counting. A single
     5386** call to xUnpin() unpins the page regardless of the number of prior calls
     5387** to xFetch().
     5388**
     5389** The xRekey() method is used to change the key value associated with the
     5390** page passed as the second argument from oldKey to newKey. If the cache
     5391** previously contains an entry associated with newKey, it should be
     5392** discarded. Any prior cache entry associated with newKey is guaranteed not
     5393** to be pinned.
     5394**
     5395** When SQLite calls the xTruncate() method, the cache must discard all
     5396** existing cache entries with page numbers (keys) greater than or equal
     5397** to the value of the iLimit parameter passed to xTruncate(). If any
     5398** of these pages are pinned, they are implicitly unpinned, meaning that
     5399** they can be safely discarded.
     5400**
     5401** The xDestroy() method is used to delete a cache allocated by xCreate().
     5402** All resources associated with the specified cache should be freed. After
     5403** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
     5404** handle invalid, and will not use it with any other sqlite3_pcache_methods
     5405** functions.
     5406*/
     5407typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
     5408struct sqlite3_pcache_methods {
     5409  void *pArg;
     5410  int (*xInit)(void*);
     5411  void (*xShutdown)(void*);
     5412  sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);
     5413  void (*xCachesize)(sqlite3_pcache*, int nCachesize);
     5414  int (*xPagecount)(sqlite3_pcache*);
     5415  void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
     5416  void (*xUnpin)(sqlite3_pcache*, void*, int discard);
     5417  void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
     5418  void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
     5419  void (*xDestroy)(sqlite3_pcache*);
     5420};
     5421
     5422/*
     5423** CAPI3REF: Online Backup Object
     5424** EXPERIMENTAL
     5425**
     5426** The sqlite3_backup object records state information about an ongoing
     5427** online backup operation.  The sqlite3_backup object is created by
     5428** a call to [sqlite3_backup_init()] and is destroyed by a call to
     5429** [sqlite3_backup_finish()].
     5430**
     5431** See Also: [Using the SQLite Online Backup API]
     5432*/
     5433typedef struct sqlite3_backup sqlite3_backup;
     5434
     5435/*
     5436** CAPI3REF: Online Backup API.
     5437** EXPERIMENTAL
     5438**
     5439** This API is used to overwrite the contents of one database with that
     5440** of another. It is useful either for creating backups of databases or
     5441** for copying in-memory databases to or from persistent files.
     5442**
     5443** See Also: [Using the SQLite Online Backup API]
     5444**
     5445** Exclusive access is required to the destination database for the
     5446** duration of the operation. However the source database is only
     5447** read-locked while it is actually being read, it is not locked
     5448** continuously for the entire operation. Thus, the backup may be
     5449** performed on a live database without preventing other users from
     5450** writing to the database for an extended period of time.
     5451**
     5452** To perform a backup operation:
     5453**   <ol>
     5454**     <li><b>sqlite3_backup_init()</b> is called once to initialize the
     5455**         backup,
     5456**     <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
     5457**         the data between the two databases, and finally
     5458**     <li><b>sqlite3_backup_finish()</b> is called to release all resources
     5459**         associated with the backup operation.
     5460**   </ol>
     5461** There should be exactly one call to sqlite3_backup_finish() for each
     5462** successful call to sqlite3_backup_init().
     5463**
     5464** <b>sqlite3_backup_init()</b>
     5465**
     5466** The first two arguments passed to [sqlite3_backup_init()] are the database
     5467** handle associated with the destination database and the database name
     5468** used to attach the destination database to the handle. The database name
     5469** is "main" for the main database, "temp" for the temporary database, or
     5470** the name specified as part of the [ATTACH] statement if the destination is
     5471** an attached database. The third and fourth arguments passed to
     5472** sqlite3_backup_init() identify the [database connection]
     5473** and database name used
     5474** to access the source database. The values passed for the source and
     5475** destination [database connection] parameters must not be the same.
     5476**
     5477** If an error occurs within sqlite3_backup_init(), then NULL is returned
     5478** and an error code and error message written into the [database connection]
     5479** passed as the first argument. They may be retrieved using the
     5480** [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()] functions.
     5481** Otherwise, if successful, a pointer to an [sqlite3_backup] object is
     5482** returned. This pointer may be used with the sqlite3_backup_step() and
     5483** sqlite3_backup_finish() functions to perform the specified backup
     5484** operation.
     5485**
     5486** <b>sqlite3_backup_step()</b>
     5487**
     5488** Function [sqlite3_backup_step()] is used to copy up to nPage pages between
     5489** the source and destination databases, where nPage is the value of the
     5490** second parameter passed to sqlite3_backup_step(). If nPage is a negative
     5491** value, all remaining source pages are copied. If the required pages are
     5492** succesfully copied, but there are still more pages to copy before the
     5493** backup is complete, it returns [SQLITE_OK]. If no error occured and there
     5494** are no more pages to copy, then [SQLITE_DONE] is returned. If an error
     5495** occurs, then an SQLite error code is returned. As well as [SQLITE_OK] and
     5496** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
     5497** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
     5498** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
     5499**
     5500** As well as the case where the destination database file was opened for
     5501** read-only access, sqlite3_backup_step() may return [SQLITE_READONLY] if
     5502** the destination is an in-memory database with a different page size
     5503** from the source database.
     5504**
     5505** If sqlite3_backup_step() cannot obtain a required file-system lock, then
     5506** the [sqlite3_busy_handler | busy-handler function]
     5507** is invoked (if one is specified). If the
     5508** busy-handler returns non-zero before the lock is available, then
     5509** [SQLITE_BUSY] is returned to the caller. In this case the call to
     5510** sqlite3_backup_step() can be retried later. If the source
     5511** [database connection]
     5512** is being used to write to the source database when sqlite3_backup_step()
     5513** is called, then [SQLITE_LOCKED] is returned immediately. Again, in this
     5514** case the call to sqlite3_backup_step() can be retried later on. If
     5515** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
     5516** [SQLITE_READONLY] is returned, then
     5517** there is no point in retrying the call to sqlite3_backup_step(). These
     5518** errors are considered fatal. At this point the application must accept
     5519** that the backup operation has failed and pass the backup operation handle
     5520** to the sqlite3_backup_finish() to release associated resources.
     5521**
     5522** Following the first call to sqlite3_backup_step(), an exclusive lock is
     5523** obtained on the destination file. It is not released until either
     5524** sqlite3_backup_finish() is called or the backup operation is complete
     5525** and sqlite3_backup_step() returns [SQLITE_DONE]. Additionally, each time
     5526** a call to sqlite3_backup_step() is made a [shared lock] is obtained on
     5527** the source database file. This lock is released before the
     5528** sqlite3_backup_step() call returns. Because the source database is not
     5529** locked between calls to sqlite3_backup_step(), it may be modified mid-way
     5530** through the backup procedure. If the source database is modified by an
     5531** external process or via a database connection other than the one being
     5532** used by the backup operation, then the backup will be transparently
     5533** restarted by the next call to sqlite3_backup_step(). If the source
     5534** database is modified by the using the same database connection as is used
     5535** by the backup operation, then the backup database is transparently
     5536** updated at the same time.
     5537**
     5538** <b>sqlite3_backup_finish()</b>
     5539**
     5540** Once sqlite3_backup_step() has returned [SQLITE_DONE], or when the
     5541** application wishes to abandon the backup operation, the [sqlite3_backup]
     5542** object should be passed to sqlite3_backup_finish(). This releases all
     5543** resources associated with the backup operation. If sqlite3_backup_step()
     5544** has not yet returned [SQLITE_DONE], then any active write-transaction on the
     5545** destination database is rolled back. The [sqlite3_backup] object is invalid
     5546** and may not be used following a call to sqlite3_backup_finish().
     5547**
     5548** The value returned by sqlite3_backup_finish is [SQLITE_OK] if no error
     5549** occurred, regardless or whether or not sqlite3_backup_step() was called
     5550** a sufficient number of times to complete the backup operation. Or, if
     5551** an out-of-memory condition or IO error occured during a call to
     5552** sqlite3_backup_step() then [SQLITE_NOMEM] or an
     5553** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] error code
     5554** is returned. In this case the error code and an error message are
     5555** written to the destination [database connection].
     5556**
     5557** A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step() is
     5558** not a permanent error and does not affect the return value of
     5559** sqlite3_backup_finish().
     5560**
     5561** <b>sqlite3_backup_remaining(), sqlite3_backup_pagecount()</b>
     5562**
     5563** Each call to sqlite3_backup_step() sets two values stored internally
     5564** by an [sqlite3_backup] object. The number of pages still to be backed
     5565** up, which may be queried by sqlite3_backup_remaining(), and the total
     5566** number of pages in the source database file, which may be queried by
     5567** sqlite3_backup_pagecount().
     5568**
     5569** The values returned by these functions are only updated by
     5570** sqlite3_backup_step(). If the source database is modified during a backup
     5571** operation, then the values are not updated to account for any extra
     5572** pages that need to be updated or the size of the source database file
     5573** changing.
     5574**
     5575** <b>Concurrent Usage of Database Handles</b>
     5576**
     5577** The source [database connection] may be used by the application for other
     5578** purposes while a backup operation is underway or being initialized.
     5579** If SQLite is compiled and configured to support threadsafe database
     5580** connections, then the source database connection may be used concurrently
     5581** from within other threads.
     5582**
     5583** However, the application must guarantee that the destination database
     5584** connection handle is not passed to any other API (by any thread) after
     5585** sqlite3_backup_init() is called and before the corresponding call to
     5586** sqlite3_backup_finish(). Unfortunately SQLite does not currently check
     5587** for this, if the application does use the destination [database connection]
     5588** for some other purpose during a backup operation, things may appear to
     5589** work correctly but in fact be subtly malfunctioning.  Use of the
     5590** destination database connection while a backup is in progress might
     5591** also cause a mutex deadlock.
     5592**
     5593** Furthermore, if running in [shared cache mode], the application must
     5594** guarantee that the shared cache used by the destination database
     5595** is not accessed while the backup is running. In practice this means
     5596** that the application must guarantee that the file-system file being
     5597** backed up to is not accessed by any connection within the process,
     5598** not just the specific connection that was passed to sqlite3_backup_init().
     5599**
     5600** The [sqlite3_backup] object itself is partially threadsafe. Multiple
     5601** threads may safely make multiple concurrent calls to sqlite3_backup_step().
     5602** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
     5603** APIs are not strictly speaking threadsafe. If they are invoked at the
     5604** same time as another thread is invoking sqlite3_backup_step() it is
     5605** possible that they return invalid values.
     5606*/
     5607SQLITE_API sqlite3_backup *sqlite3_backup_init(
     5608  sqlite3 *pDest,                        /* Destination database handle */
     5609  const char *zDestName,                 /* Destination database name */
     5610  sqlite3 *pSource,                      /* Source database handle */
     5611  const char *zSourceName                /* Source database name */
     5612);
     5613SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
     5614SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
     5615SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
     5616SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
     5617
     5618/*
     5619** CAPI3REF: Unlock Notification
     5620** EXPERIMENTAL
     5621**
     5622** When running in shared-cache mode, a database operation may fail with
     5623** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
     5624** individual tables within the shared-cache cannot be obtained. See
     5625** [SQLite Shared-Cache Mode] for a description of shared-cache locking.
     5626** This API may be used to register a callback that SQLite will invoke
     5627** when the connection currently holding the required lock relinquishes it.
     5628** This API is only available if the library was compiled with the
     5629** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
     5630**
     5631** See Also: [Using the SQLite Unlock Notification Feature].
     5632**
     5633** Shared-cache locks are released when a database connection concludes
     5634** its current transaction, either by committing it or rolling it back.
     5635**
     5636** When a connection (known as the blocked connection) fails to obtain a
     5637** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
     5638** identity of the database connection (the blocking connection) that
     5639** has locked the required resource is stored internally. After an
     5640** application receives an SQLITE_LOCKED error, it may call the
     5641** sqlite3_unlock_notify() method with the blocked connection handle as
     5642** the first argument to register for a callback that will be invoked
     5643** when the blocking connections current transaction is concluded. The
     5644** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
     5645** call that concludes the blocking connections transaction.
     5646**
     5647** If sqlite3_unlock_notify() is called in a multi-threaded application,
     5648** there is a chance that the blocking connection will have already
     5649** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
     5650** If this happens, then the specified callback is invoked immediately,
     5651** from within the call to sqlite3_unlock_notify().
     5652**
     5653** If the blocked connection is attempting to obtain a write-lock on a
     5654** shared-cache table, and more than one other connection currently holds
     5655** a read-lock on the same table, then SQLite arbitrarily selects one of
     5656** the other connections to use as the blocking connection.
     5657**
     5658** There may be at most one unlock-notify callback registered by a
     5659** blocked connection. If sqlite3_unlock_notify() is called when the
     5660** blocked connection already has a registered unlock-notify callback,
     5661** then the new callback replaces the old. If sqlite3_unlock_notify() is
     5662** called with a NULL pointer as its second argument, then any existing
     5663** unlock-notify callback is cancelled. The blocked connections
     5664** unlock-notify callback may also be canceled by closing the blocked
     5665** connection using [sqlite3_close()].
     5666**
     5667** The unlock-notify callback is not reentrant. If an application invokes
     5668** any sqlite3_xxx API functions from within an unlock-notify callback, a
     5669** crash or deadlock may be the result.
     5670**
     5671** Unless deadlock is detected (see below), sqlite3_unlock_notify() always
     5672** returns SQLITE_OK.
     5673**
     5674** <b>Callback Invocation Details</b>
     5675**
     5676** When an unlock-notify callback is registered, the application provides a
     5677** single void* pointer that is passed to the callback when it is invoked.
     5678** However, the signature of the callback function allows SQLite to pass
     5679** it an array of void* context pointers. The first argument passed to
     5680** an unlock-notify callback is a pointer to an array of void* pointers,
     5681** and the second is the number of entries in the array.
     5682**
     5683** When a blocking connections transaction is concluded, there may be
     5684** more than one blocked connection that has registered for an unlock-notify
     5685** callback. If two or more such blocked connections have specified the
     5686** same callback function, then instead of invoking the callback function
     5687** multiple times, it is invoked once with the set of void* context pointers
     5688** specified by the blocked connections bundled together into an array.
     5689** This gives the application an opportunity to prioritize any actions
     5690** related to the set of unblocked database connections.
     5691**
     5692** <b>Deadlock Detection</b>
     5693**
     5694** Assuming that after registering for an unlock-notify callback a
     5695** database waits for the callback to be issued before taking any further
     5696** action (a reasonable assumption), then using this API may cause the
     5697** application to deadlock. For example, if connection X is waiting for
     5698** connection Y's transaction to be concluded, and similarly connection
     5699** Y is waiting on connection X's transaction, then neither connection
     5700** will proceed and the system may remain deadlocked indefinitely.
     5701**
     5702** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
     5703** detection. If a given call to sqlite3_unlock_notify() would put the
     5704** system in a deadlocked state, then SQLITE_LOCKED is returned and no
     5705** unlock-notify callback is registered. The system is said to be in
     5706** a deadlocked state if connection A has registered for an unlock-notify
     5707** callback on the conclusion of connection B's transaction, and connection
     5708** B has itself registered for an unlock-notify callback when connection
     5709** A's transaction is concluded. Indirect deadlock is also detected, so
     5710** the system is also considered to be deadlocked if connection B has
     5711** registered for an unlock-notify callback on the conclusion of connection
     5712** C's transaction, where connection C is waiting on connection A. Any
     5713** number of levels of indirection are allowed.
     5714**
     5715** <b>The "DROP TABLE" Exception</b>
     5716**
     5717** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
     5718** always appropriate to call sqlite3_unlock_notify(). There is however,
     5719** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
     5720** SQLite checks if there are any currently executing SELECT statements
     5721** that belong to the same connection. If there are, SQLITE_LOCKED is
     5722** returned. In this case there is no "blocking connection", so invoking
     5723** sqlite3_unlock_notify() results in the unlock-notify callback being
     5724** invoked immediately. If the application then re-attempts the "DROP TABLE"
     5725** or "DROP INDEX" query, an infinite loop might be the result.
     5726**
     5727** One way around this problem is to check the extended error code returned
     5728** by an sqlite3_step() call. If there is a blocking connection, then the
     5729** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
     5730** the special "DROP TABLE/INDEX" case, the extended error code is just
     5731** SQLITE_LOCKED.
     5732*/
     5733SQLITE_API int sqlite3_unlock_notify(
     5734  sqlite3 *pBlocked,                          /* Waiting connection */
     5735  void (*xNotify)(void **apArg, int nArg),    /* Callback function to invoke */
     5736  void *pNotifyArg                            /* Argument to pass to xNotify */
     5737);
     5738
     5739
     5740/*
     5741** CAPI3REF: String Comparison
     5742** EXPERIMENTAL
     5743**
     5744** The [sqlite3_strnicmp()] API allows applications and extensions to
     5745** compare the contents of two buffers containing UTF-8 strings in a
     5746** case-indendent fashion, using the same definition of case independence
     5747** that SQLite uses internally when comparing identifiers.
     5748*/
     5749SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
    56265750
    56275751/*
    … …  
    56375761#endif
    56385762#endif
     5763
Note: See TracChangeset for help on using the changeset viewer.