** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
@@ -1120,28 +1406,87 @@ void sqlite3_free_table(char **result);
**
** The "%z" formatting option works exactly like "%s" with the
** addition that after the string has been read and copied into
-** the result, [sqlite3_free()] is called on the input string.
+** the result, [sqlite3_free()] is called on the input string. {END}
+**
+** INVARIANTS:
+**
+** {F17403} The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces
+** return either pointers to zero-terminated UTF-8 strings held in
+** memory obtained from [sqlite3_malloc()] or NULL pointers if
+** a call to [sqlite3_malloc()] fails.
+**
+** {F17406} The [sqlite3_snprintf()] interface writes a zero-terminated
+** UTF-8 string into the buffer pointed to by the second parameter
+** provided that the first parameter is greater than zero.
+**
+** {F17407} The [sqlite3_snprintf()] interface does not writes slots of
+** its output buffer (the second parameter) outside the range
+** of 0 through N-1 (where N is the first parameter)
+** regardless of the length of the string
+** requested by the format specification.
+**
*/
char *sqlite3_mprintf(const char*,...);
char *sqlite3_vmprintf(const char*, va_list);
char *sqlite3_snprintf(int,char*,const char*, ...);
/*
-** CAPI3REF: Memory Allocation Subsystem
+** CAPI3REF: Memory Allocation Subsystem {F17300}
+**
+** The SQLite core uses these three routines for all of its own
+** internal memory allocation needs. "Core" in the previous sentence
+** does not include operating-system specific VFS implementation. The
+** windows VFS uses native malloc and free for some operations.
+**
+** The sqlite3_malloc() routine returns a pointer to a block
+** of memory at least N bytes in length, where N is the parameter.
+** If sqlite3_malloc() is unable to obtain sufficient free
+** memory, it returns a NULL pointer. If the parameter N to
+** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
+** a NULL pointer.
+**
+** Calling sqlite3_free() with a pointer previously returned
+** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
+** that it might be reused. The sqlite3_free() routine is
+** a no-op if is called with a NULL pointer. Passing a NULL pointer
+** to sqlite3_free() is harmless. After being freed, memory
+** should neither be read nor written. Even reading previously freed
+** memory might result in a segmentation fault or other severe error.
+** Memory corruption, a segmentation fault, or other severe error
+** might result if sqlite3_free() is called with a non-NULL pointer that
+** was not obtained from sqlite3_malloc() or sqlite3_free().
+**
+** The sqlite3_realloc() interface attempts to resize a
+** prior memory allocation to be at least N bytes, where N is the
+** second parameter. The memory allocation to be resized is the first
+** parameter. If the first parameter to sqlite3_realloc()
+** is a NULL pointer then its behavior is identical to calling
+** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
+** If the second parameter to sqlite3_realloc() is zero or
+** negative then the behavior is exactly the same as calling
+** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
+** Sqlite3_realloc() returns a pointer to a memory allocation
+** of at least N bytes in size or NULL if sufficient memory is unavailable.
+** If M is the size of the prior allocation, then min(N,M) bytes
+** of the prior allocation are copied into the beginning of buffer returned
+** by sqlite3_realloc() and the prior allocation is freed.
+** If sqlite3_realloc() returns NULL, then the prior allocation
+** is not freed.
**
-** The SQLite core uses these three routines for all of its own
-** internal memory allocation needs. (See the exception below.)
+** The memory returned by sqlite3_malloc() and sqlite3_realloc()
+** is always aligned to at least an 8 byte boundary. {END}
**
** The default implementation
** of the memory allocation subsystem uses the malloc(), realloc()
-** and free() provided by the standard C library. However, if
+** and free() provided by the standard C library. {F17382} However, if
** SQLite is compiled with the following C preprocessor macro
**
** SQLITE_MEMORY_SIZE=NNN
**
** where NNN is an integer, then SQLite create a static
** array of at least NNN bytes in size and use that array
-** for all of its dynamic memory allocation needs.
+** for all of its dynamic memory allocation needs. {END} Additional
+** memory allocator options may be added in future releases.
**
** In SQLite version 3.5.0 and 3.5.1, it was possible to define
** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
@@ -1149,43 +1494,107 @@ char *sqlite3_snprintf(int,char*,const c
** is no longer provided. Only built-in memory allocators can be
** used.
**
-** Exception: The windows OS interface layer calls
+** The windows OS interface layer calls
** the system malloc() and free() directly when converting
** filenames between the UTF-8 encoding used by SQLite
** and whatever filename encoding is used by the particular windows
** installation. Memory allocation errors are detected, but
** they are reported back as [SQLITE_CANTOPEN] or
** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
+**
+** INVARIANTS:
+**
+** {F17303} The [sqlite3_malloc(N)] interface returns either a pointer to
+** newly checked-out block of at least N bytes of memory
+** that is 8-byte aligned,
+** or it returns NULL if it is unable to fulfill the request.
+**
+** {F17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if
+** N is less than or equal to zero.
+**
+** {F17305} The [sqlite3_free(P)] interface releases memory previously
+** returned from [sqlite3_malloc()] or [sqlite3_realloc()],
+** making it available for reuse.
+**
+** {F17306} A call to [sqlite3_free(NULL)] is a harmless no-op.
+**
+** {F17310} A call to [sqlite3_realloc(0,N)] is equivalent to a call
+** to [sqlite3_malloc(N)].
+**
+** {F17312} A call to [sqlite3_realloc(P,0)] is equivalent to a call
+** to [sqlite3_free(P)].
+**
+** {F17315} The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()],
+** and [sqlite3_free()] for all of its memory allocation and
+** deallocation needs.
+**
+** {F17318} The [sqlite3_realloc(P,N)] interface returns either a pointer
+** to a block of checked-out memory of at least N bytes in size
+** that is 8-byte aligned, or a NULL pointer.
+**
+** {F17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
+** copies the first K bytes of content from P into the newly allocated
+** where K is the lessor of N and the size of the buffer P.
+**
+** {F17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
+** releases the buffer P.
+**
+** {F17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is
+** not modified or released.
+**
+** LIMITATIONS:
+**
+** {U17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
+** must be either NULL or else a pointer obtained from a prior
+** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that has
+** not been released.
+**
+** {U17351} The application must not read or write any part of
+** a block of memory after it has been released using
+** [sqlite3_free()] or [sqlite3_realloc()].
+**
*/
void *sqlite3_malloc(int);
void *sqlite3_realloc(void*, int);
void sqlite3_free(void*);
/*
-** CAPI3REF: Memory Allocator Statistics
+** CAPI3REF: Memory Allocator Statistics {F17370}
**
-** In addition to the basic three allocation routines
-** [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()],
-** the memory allocation subsystem included with the SQLite
-** sources provides the interfaces shown below.
-**
-** The first of these two routines returns the amount of memory
-** currently outstanding (malloced but not freed). The second
-** returns the largest instantaneous amount of outstanding
-** memory. The highwater mark is reset if the argument is
-** true.
-**
-** The value returned may or may not include allocation
-** overhead, depending on which built-in memory allocator
-** implementation is used.
+** SQLite provides these two interfaces for reporting on the status
+** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
+** the memory allocation subsystem included within the SQLite.
+**
+** INVARIANTS:
+**
+** {F17371} The [sqlite3_memory_used()] routine returns the
+** number of bytes of memory currently outstanding
+** (malloced but not freed).
+**
+** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum
+** value of [sqlite3_memory_used()]
+** since the highwater mark was last reset.
+**
+** {F17374} The values returned by [sqlite3_memory_used()] and
+** [sqlite3_memory_highwater()] include any overhead
+** added by SQLite in its implementation of [sqlite3_malloc()],
+** but not overhead added by the any underlying system library
+** routines that [sqlite3_malloc()] may call.
+**
+** {F17375} The memory highwater mark is reset to the current value of
+** [sqlite3_memory_used()] if and only if the parameter to
+** [sqlite3_memory_highwater()] is true. The value returned
+** by [sqlite3_memory_highwater(1)] is the highwater mark
+** prior to the reset.
*/
sqlite3_int64 sqlite3_memory_used(void);
sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
/*
-** CAPI3REF: Compile-Time Authorization Callbacks
-***
-** This routine registers a authorizer callback with the SQLite library.
+** CAPI3REF: Compile-Time Authorization Callbacks {F12500}
+**
+** This routine registers a authorizer callback with a particular
+** database connection, supplied in the first argument.
** The authorizer callback is invoked as SQL statements are being compiled
** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various
@@ -1195,25 +1604,30 @@ sqlite3_int64 sqlite3_memory_highwater(i
** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the
** specific action but allow the SQL statement to continue to be
** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
-** rejected with an error.
-**
-** Depending on the action, the [SQLITE_IGNORE] and [SQLITE_DENY] return
-** codes might mean something different or they might mean the same
-** thing. If the action is, for example, to perform a delete opertion,
-** then [SQLITE_IGNORE] and [SQLITE_DENY] both cause the statement compilation
-** to fail with an error. But if the action is to read a specific column
-** from a specific table, then [SQLITE_DENY] will cause the entire
-** statement to fail but [SQLITE_IGNORE] will cause a NULL value to be
-** read instead of the actual column value.
+** rejected with an error. If the authorizer callback returns
+** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
+** then [sqlite3_prepare_v2()] or equivalent call that triggered
+** the authorizer will fail with an error message.
+**
+** When the callback returns [SQLITE_OK], that means the operation
+** requested is ok. When the callback returns [SQLITE_DENY], the
+** [sqlite3_prepare_v2()] or equivalent call that triggered the
+** authorizer will fail with an error message explaining that
+** access is denied. If the authorizer code is [SQLITE_READ]
+** and the callback returns [SQLITE_IGNORE] then the prepared
+** statement is constructed to insert a NULL value in place of
+** the table column that would have
+** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
+** return can be used to deny an untrusted user access to individual
+** columns of a table.
**
** The first parameter to the authorizer callback is a copy of
** the third parameter to the sqlite3_set_authorizer() interface.
** The second parameter to the callback is an integer
** [SQLITE_COPY | action code] that specifies the particular action
-** to be authorized. The available action codes are
-** [SQLITE_COPY | documented separately]. The third through sixth
-** parameters to the callback are strings that contain additional
-** details about the action to be authorized.
+** to be authorized. The third through sixth
+** parameters to the callback are zero-terminated strings that contain
+** additional details about the action to be authorized.
**
** An authorizer is used when preparing SQL statements from an untrusted
** source, to ensure that the SQL statements do not try to access data
@@ -1228,12 +1642,64 @@ sqlite3_int64 sqlite3_memory_highwater(i
**
** Only a single authorizer can be in place on a database connection
** at a time. Each call to sqlite3_set_authorizer overrides the
-** previous call. A NULL authorizer means that no authorization
-** callback is invoked. The default authorizer is NULL.
+** previous call. Disable the authorizer by installing a NULL callback.
+** The authorizer is disabled by default.
**
** Note that the authorizer callback is invoked only during
** [sqlite3_prepare()] or its variants. Authorization is not
** performed during statement evaluation in [sqlite3_step()].
+**
+** INVARIANTS:
+**
+** {F12501} The [sqlite3_set_authorizer(D,...)] interface registers a
+** authorizer callback with database connection D.
+**
+** {F12502} The authorizer callback is invoked as SQL statements are
+** being compiled
+**
+** {F12503} If the authorizer callback returns any value other than
+** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] then
+** the [sqlite3_prepare_v2()] or equivalent call that caused
+** the authorizer callback to run shall fail with an
+** [SQLITE_ERROR] error code and an appropriate error message.
+**
+** {F12504} When the authorizer callback returns [SQLITE_OK], the operation
+** described is coded normally.
+**
+** {F12505} When the authorizer callback returns [SQLITE_DENY], the
+** [sqlite3_prepare_v2()] or equivalent call that caused the
+** authorizer callback to run shall fail
+** with an [SQLITE_ERROR] error code and an error message
+** explaining that access is denied.
+**
+** {F12506} If the authorizer code (the 2nd parameter to the authorizer
+** callback) is [SQLITE_READ] and the authorizer callback returns
+** [SQLITE_IGNORE] then the prepared statement is constructed to
+** insert a NULL value in place of the table column that would have
+** been read if [SQLITE_OK] had been returned.
+**
+** {F12507} If the authorizer code (the 2nd parameter to the authorizer
+** callback) is anything other than [SQLITE_READ], then
+** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY].
+**
+** {F12510} The first parameter to the authorizer callback is a copy of
+** the third parameter to the [sqlite3_set_authorizer()] interface.
+**
+** {F12511} The second parameter to the callback is an integer
+** [SQLITE_COPY | action code] that specifies the particular action
+** to be authorized.
+**
+** {F12512} The third through sixth parameters to the callback are
+** zero-terminated strings that contain
+** additional details about the action to be authorized.
+**
+** {F12520} Each call to [sqlite3_set_authorizer()] overrides the
+** any previously installed authorizer.
+**
+** {F12521} A NULL authorizer means that no authorization
+** callback is invoked.
+**
+** {F12522} The default authorizer is NULL.
*/
int sqlite3_set_authorizer(
sqlite3*,
@@ -1242,7 +1708,7 @@ int sqlite3_set_authorizer(
);
/*
-** CAPI3REF: Authorizer Return Codes
+** CAPI3REF: Authorizer Return Codes {F12590}
**
** The [sqlite3_set_authorizer | authorizer callback function] must
** return either [SQLITE_OK] or one of these two constants in order
@@ -1254,7 +1720,7 @@ int sqlite3_set_authorizer(
#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
/*
-** CAPI3REF: Authorizer Action Codes
+** CAPI3REF: Authorizer Action Codes {F12550}
**
** The [sqlite3_set_authorizer()] interface registers a callback function
** that is invoked to authorizer certain SQL statement actions. The
@@ -1263,14 +1729,36 @@ int sqlite3_set_authorizer(
** the authorizer callback may be passed.
**
** These action code values signify what kind of operation is to be
-** authorized. The 3rd and 4th parameters to the authorization callback
-** function will be parameters or NULL depending on which of these
+** authorized. The 3rd and 4th parameters to the authorization
+** callback function will be parameters or NULL depending on which of these
** codes is used as the second parameter. The 5th parameter to the
** authorizer callback is the name of the database ("main", "temp",
** etc.) if applicable. The 6th parameter to the authorizer callback
** is the name of the inner-most trigger or view that is responsible for
** the access attempt or NULL if this access attempt is directly from
** top-level SQL code.
+**
+** INVARIANTS:
+**
+** {F12551} The second parameter to an
+** [sqlite3_set_authorizer | authorizer callback is always an integer
+** [SQLITE_COPY | authorizer code] that specifies what action
+** is being authorized.
+**
+** {F12552} The 3rd and 4th parameters to the
+** [sqlite3_set_authorizer | authorization callback function]
+** will be parameters or NULL depending on which
+** [SQLITE_COPY | authorizer code] is used as the second parameter.
+**
+** {F12553} The 5th parameter to the
+** [sqlite3_set_authorizer | authorizer callback] is the name
+** of the database (example: "main", "temp", etc.) if applicable.
+**
+** {F12554} The 6th parameter to the
+** [sqlite3_set_authorizer | authorizer callback] is the name
+** of the inner-most trigger or view that is responsible for
+** the access attempt or NULL if this access attempt is directly from
+** top-level SQL code.
*/
/******************************************* 3rd ************ 4th ***********/
#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
@@ -1307,79 +1795,146 @@ int sqlite3_set_authorizer(
#define SQLITE_COPY 0 /* No longer used */
/*
-** CAPI3REF: Tracing And Profiling Functions
+** CAPI3REF: Tracing And Profiling Functions {F12280}
**
** These routines register callback functions that can be used for
** tracing and profiling the execution of SQL statements.
-** The callback function registered by sqlite3_trace() is invoked
-** at the first [sqlite3_step()] for the evaluation of an SQL statement.
+**
+** The callback function registered by sqlite3_trace() is invoked at
+** various times when an SQL statement is being run by [sqlite3_step()].
+** The callback returns a UTF-8 rendering of the SQL statement text
+** as the statement first begins executing. Additional callbacks occur
+** as each triggersubprogram is entered. The callbacks for triggers
+** contain a UTF-8 SQL comment that identifies the trigger.
+**
** The callback function registered by sqlite3_profile() is invoked
-** as each SQL statement finishes and includes
-** information on how long that statement ran.
+** as each SQL statement finishes. The profile callback contains
+** the original statement text and an estimate of wall-clock time
+** of how long that statement took to run.
**
** The sqlite3_profile() API is currently considered experimental and
-** is subject to change.
+** is subject to change or removal in a future release.
+**
+** The trigger reporting feature of the trace callback is considered
+** experimental and is subject to change or removal in future releases.
+** Future versions of SQLite might also add new trace callback
+** invocations.
+**
+** INVARIANTS:
+**
+** {F12281} The callback function registered by [sqlite3_trace()] is
+** whenever an SQL statement first begins to execute and
+** whenever a trigger subprogram first begins to run.
+**
+** {F12282} Each call to [sqlite3_trace()] overrides the previously
+** registered trace callback.
+**
+** {F12283} A NULL trace callback disables tracing.
+**
+** {F12284} The first argument to the trace callback is a copy of
+** the pointer which was the 3rd argument to [sqlite3_trace()].
+**
+** {F12285} The second argument to the trace callback is a
+** zero-terminated UTF8 string containing the original text
+** of the SQL statement as it was passed into [sqlite3_prepare_v2()]
+** or the equivalent, or an SQL comment indicating the beginning
+** of a trigger subprogram.
+**
+** {F12287} The callback function registered by [sqlite3_profile()] is invoked
+** as each SQL statement finishes.
+**
+** {F12288} The first parameter to the profile callback is a copy of
+** the 3rd parameter to [sqlite3_profile()].
+**
+** {F12289} The second parameter to the profile callback is a
+** zero-terminated UTF-8 string that contains the complete text of
+** the SQL statement as it was processed by [sqlite3_prepare_v2()]
+** or the equivalent.
+**
+** {F12290} The third parameter to the profile callback is an estimate
+** of the number of nanoseconds of wall-clock time required to
+** run the SQL statement from start to finish.
*/
void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
void *sqlite3_profile(sqlite3*,
void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
/*
-** CAPI3REF: Query Progress Callbacks
+** CAPI3REF: Query Progress Callbacks {F12910}
**
-** This routine configures a callback function - the progress callback - that
-** is invoked periodically during long running calls to [sqlite3_exec()],
-** [sqlite3_step()] and [sqlite3_get_table()]. An example use for this
+** This routine configures a callback function - the
+** progress callback - that is invoked periodically during long
+** running calls to [sqlite3_exec()], [sqlite3_step()] and
+** [sqlite3_get_table()]. An example use for this
** interface is to keep a GUI updated during a large query.
**
-** The progress callback is invoked once for every N virtual machine opcodes,
-** where N is the second argument to this function. The progress callback
-** itself is identified by the third argument to this function. The fourth
-** argument to this function is a void pointer passed to the progress callback
-** function each time it is invoked.
-**
-** If a call to [sqlite3_exec()], [sqlite3_step()], or [sqlite3_get_table()]
-** results in fewer than N opcodes being executed, then the progress
-** callback is never invoked.
-**
-** Only a single progress callback function may be registered for each
-** open database connection. Every call to sqlite3_progress_handler()
-** overwrites the results of the previous call.
-** To remove the progress callback altogether, pass NULL as the third
-** argument to this function.
-**
-** If the progress callback returns a result other than 0, then the current
-** query is immediately terminated and any database changes rolled back.
-** The containing [sqlite3_exec()], [sqlite3_step()], or
-** [sqlite3_get_table()] call returns SQLITE_INTERRUPT. This feature
-** can be used, for example, to implement the "Cancel" button on a
-** progress dialog box in a GUI.
+** If the progress callback returns non-zero, the opertion is
+** interrupted. This feature can be used to implement a
+** "Cancel" button on a GUI dialog box.
+**
+** INVARIANTS:
+**
+** {F12911} The callback function registered by [sqlite3_progress_handler()]
+** is invoked periodically during long running calls to
+** [sqlite3_step()].
+**
+** {F12912} The progress callback is invoked once for every N virtual
+** machine opcodes, where N is the second argument to
+** the [sqlite3_progress_handler()] call that registered
+** the callback. What if N is less than 1?
+**
+** {F12913} The progress callback itself is identified by the third
+** argument to [sqlite3_progress_handler()].
+**
+** {F12914} The fourth argument [sqlite3_progress_handler()] is a
+*** void pointer passed to the progress callback
+** function each time it is invoked.
+**
+** {F12915} If a call to [sqlite3_step()] results in fewer than
+** N opcodes being executed,
+** then the progress callback is never invoked. {END}
+**
+** {F12916} Every call to [sqlite3_progress_handler()]
+** overwrites any previously registere progress handler.
+**
+** {F12917} If the progress handler callback is NULL then no progress
+** handler is invoked.
+**
+** {F12918} If the progress callback returns a result other than 0, then
+** the behavior is a if [sqlite3_interrupt()] had been called.
*/
void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
/*
-** CAPI3REF: Opening A New Database Connection
+** CAPI3REF: Opening A New Database Connection {F12700}
**
-** Open the sqlite database file "filename". The "filename" is UTF-8
-** encoded for [sqlite3_open()] and [sqlite3_open_v2()] and UTF-16 encoded
+** These routines open an SQLite database file whose name
+** is given by the filename argument.
+** The filename argument is interpreted as UTF-8
+** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16
** in the native byte order for [sqlite3_open16()].
-** An [sqlite3*] handle is returned in *ppDb, even
-** if an error occurs. If the database is opened (or created) successfully,
-** then [SQLITE_OK] is returned. Otherwise an error code is returned. The
+** An [sqlite3*] handle is usually returned in *ppDb, even
+** if an error occurs. The only exception is if SQLite is unable
+** to allocate memory to hold the [sqlite3] object, a NULL will
+** be written into *ppDb instead of a pointer to the [sqlite3] object.
+** If the database is opened (and/or created)
+** successfully, then [SQLITE_OK] is returned. Otherwise an
+** error code is returned. The
** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
** an English language description of the error.
**
** The default encoding for the database will be UTF-8 if
** [sqlite3_open()] or [sqlite3_open_v2()] is called and
-** UTF-16 if [sqlite3_open16()] is used.
+** UTF-16 in the native byte order if [sqlite3_open16()] is used.
**
-** Whether or not an error occurs when it is opened, resources associated
-** with the [sqlite3*] handle should be released by passing it to
-** [sqlite3_close()] when it is no longer required.
-**
-** The [sqlite3_open_v2()] interface works like [sqlite3_open()] except that
-** provides two additional parameters for additional control over the
-** new database connection. The flags parameter can be one of:
+** Whether or not an error occurs when it is opened, resources
+** associated with the [sqlite3*] handle should be released by passing it
+** to [sqlite3_close()] when it is no longer required.
+**
+** The [sqlite3_open_v2()] interface works like [sqlite3_open()]
+** except that it acccepts two additional parameters for additional control
+** over the new database connection. The flags parameter can be
+** one of:
**
**
** - [SQLITE_OPEN_READONLY]
@@ -1387,12 +1942,14 @@ void sqlite3_progress_handler(sqlite3*,
**
- [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]
**
**
-** The first value opens the database read-only. If the database does
-** not previously exist, an error is returned. The second option opens
+** The first value opens the database read-only.
+** If the database does not previously exist, an error is returned.
+** The second option opens
** the database for reading and writing if possible, or reading only if
-** if the file is write protected. In either case the database must already
-** exist or an error is returned. The third option opens the database
-** for reading and writing and creates it if it does not already exist.
+** if the file is write protected. In either case the database
+** must already exist or an error is returned. The third option
+** opens the database for reading and writing and creates it if it does
+** not already exist.
** The third options is behavior that is always used for [sqlite3_open()]
** and [sqlite3_open16()].
**
@@ -1420,6 +1977,69 @@ void sqlite3_progress_handler(sqlite3*,
** codepage is currently defined. Filenames containing international
** characters must be converted to UTF-8 prior to passing them into
** [sqlite3_open()] or [sqlite3_open_v2()].
+**
+** INVARIANTS:
+**
+** {F12701} The [sqlite3_open()], [sqlite3_open16()], and
+** [sqlite3_open_v2()] interfaces create a new
+** [database connection] associated with
+** the database file given in their first parameter.
+**
+** {F12702} The filename argument is interpreted as UTF-8
+** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16
+** in the native byte order for [sqlite3_open16()].
+**
+** {F12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()],
+** or [sqlite3_open_v2()] writes a pointer to a new
+** [database connection] into *ppDb.
+**
+** {F12704} The [sqlite3_open()], [sqlite3_open16()], and
+** [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success,
+** or an appropriate [error code] on failure.
+**
+** {F12706} The default text encoding for a new database created using
+** [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8.
+**
+** {F12707} The default text encoding for a new database created using
+** [sqlite3_open16()] will be UTF-16.
+**
+** {F12709} The [sqlite3_open(F,D)] interface is equivalent to
+** [sqlite3_open_v2(F,D,G,0)] where the G parameter is
+** [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE].
+**
+** {F12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
+** bit value [SQLITE_OPEN_READONLY] then the database is opened
+** for reading only.
+**
+** {F12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
+** bit value [SQLITE_OPEN_READWRITE] then the database is opened
+** reading and writing if possible, or for reading only if the
+** file is write protected by the operating system.
+**
+** {F12713} If the G parameter to [sqlite3_open(v2(F,D,G,V)] omits the
+** bit value [SQLITE_OPEN_CREATE] and the database does not
+** previously exist, an error is returned.
+**
+** {F12714} If the G parameter to [sqlite3_open(v2(F,D,G,V)] contains the
+** bit value [SQLITE_OPEN_CREATE] and the database does not
+** previously exist, then an attempt is made to create and
+** initialize the database.
+**
+** {F12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()],
+** or [sqlite3_open_v2()] is ":memory:", then an private,
+** ephemeral, in-memory database is created for the connection.
+** Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
+** in sqlite3_open_v2()?
+**
+** {F12719} If the filename is NULL or an empty string, then a private,
+** ephermeral on-disk database will be created.
+** Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
+** in sqlite3_open_v2()?
+**
+** {F12721} The [database connection] created by
+** [sqlite3_open_v2(F,D,G,V)] will use the
+** [sqlite3_vfs] object identified by the V parameter, or
+** the default [sqlite3_vfs] object is V is a NULL pointer.
*/
int sqlite3_open(
const char *filename, /* Database filename (UTF-8) */
@@ -1437,45 +2057,59 @@ int sqlite3_open_v2(
);
/*
-** CAPI3REF: Error Codes And Messages
+** CAPI3REF: Error Codes And Messages {F12800}
**
** The sqlite3_errcode() interface returns the numeric
** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code]
** for the most recent failed sqlite3_* API call associated
-** with [sqlite3] handle 'db'. If a prior API call failed but the
+** with [sqlite3] handle 'db'. If a prior API call failed but the
** most recent API call succeeded, the return value from sqlite3_errcode()
-** is undefined.
+** is undefined.
**
** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
** text that describes the error, as either UTF8 or UTF16 respectively.
-** Memory to hold the error message string is managed internally. The
-** string may be overwritten or deallocated by subsequent calls to SQLite
-** interface functions.
-**
-** Calls to many sqlite3_* functions set the error code and string returned
-** by [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()]
-** (overwriting the previous values). Note that calls to [sqlite3_errcode()],
-** [sqlite3_errmsg()], and [sqlite3_errmsg16()] themselves do not affect the
-** results of future invocations. Calls to API routines that do not return
-** an error code (example: [sqlite3_data_count()]) do not
-** change the error code returned by this routine. Interfaces that are
-** not associated with a specific database connection (examples:
-** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()] do not change
-** the return code.
-**
-** Assuming no other intervening sqlite3_* API calls are made, the error
-** code returned by this function is associated with the same error as
-** the strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()].
+** Memory to hold the error message string is managed internally.
+** The application does not need to worry with freeing the result.
+** However, the error string might be overwritten or deallocated by
+** subsequent calls to other SQLite interface functions.
+**
+** INVARIANTS:
+**
+** {F12801} The [sqlite3_errcode(D)] interface returns the numeric
+** [SQLITE_OK | result code] or
+** [SQLITE_IOERR_READ | extended result code]
+** for the most recently failed interface call associated
+** with [database connection] D.
+**
+** {F12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)]
+** interfaces return English-language text that describes
+** the error in the mostly recently failed interface call,
+** encoded as either UTF8 or UTF16 respectively.
+**
+** {F12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]
+** are valid until the next SQLite interface call.
+**
+** {F12808} Calls to API routines that do not return an error code
+** (example: [sqlite3_data_count()]) do not
+** change the error code or message returned by
+** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
+**
+** {F12809} Interfaces that are not associated with a specific
+** [database connection] (examples:
+** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()]
+** do not change the values returned by
+** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
*/
int sqlite3_errcode(sqlite3 *db);
const char *sqlite3_errmsg(sqlite3*);
const void *sqlite3_errmsg16(sqlite3*);
/*
-** CAPI3REF: SQL Statement Object
+** CAPI3REF: SQL Statement Object {F13000}
+** KEYWORDS: {prepared statement} {prepared statements}
**
-** Instance of this object represent single SQL statements. This
-** is variously known as a "prepared statement" or a
+** An instance of this object represent single SQL statements. This
+** object is variously known as a "prepared statement" or a
** "compiled SQL statement" or simply as a "statement".
**
** The life of a statement object goes something like this:
@@ -1497,66 +2131,67 @@ const void *sqlite3_errmsg16(sqlite3*);
typedef struct sqlite3_stmt sqlite3_stmt;
/*
-** CAPI3REF: Compiling An SQL Statement
+** CAPI3REF: Compiling An SQL Statement {F13010}
**
** To execute an SQL query, it must first be compiled into a byte-code
** program using one of these routines.
**
-** The first argument "db" is an [sqlite3 | SQLite database handle]
+** The first argument "db" is an [database connection]
** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()]
-** or [sqlite3_open16()].
+** or [sqlite3_open16()].
** The second argument "zSql" is the statement to be compiled, encoded
** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()
** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2()
-** use UTF-16.
+** use UTF-16. {END}
**
** If the nByte argument is less
-** than zero, then zSql is read up to the first zero terminator. If
-** nByte is non-negative, then it is the maximum number of
+** than zero, then zSql is read up to the first zero terminator.
+** If nByte is non-negative, then it is the maximum number of
** bytes read from zSql. When nByte is non-negative, the
-** zSql string ends at either the first '\000' character or
-** until the nByte-th byte, whichever comes first.
+** zSql string ends at either the first '\000' or '\u0000' character or
+** until the nByte-th byte, whichever comes first. {END}
**
-** *pzTail is made to point to the first byte past the end of the first
-** SQL statement in zSql. This routine only compiles the first statement
-** in zSql, so *pzTail is left pointing to what remains uncompiled.
-**
-** *ppStmt is left pointing to a compiled
-** [sqlite3_stmt | SQL statement structure] that can be
-** executed using [sqlite3_step()]. Or if there is an error, *ppStmt may be
-** set to NULL. If the input text contained no SQL (if the input is and
-** empty string or a comment) then *ppStmt is set to NULL. The calling
-** procedure is responsible for deleting the compiled SQL statement
+** *pzTail is made to point to the first byte past the end of the
+** first SQL statement in zSql. These routines only compiles the first
+** statement in zSql, so *pzTail is left pointing to what remains
+** uncompiled.
+**
+** *ppStmt is left pointing to a compiled [prepared statement] that can be
+** executed using [sqlite3_step()]. Or if there is an error, *ppStmt is
+** set to NULL. If the input text contains no SQL (if the input
+** is and empty string or a comment) then *ppStmt is set to NULL.
+** {U13018} The calling procedure is responsible for deleting the
+** compiled SQL statement
** using [sqlite3_finalize()] after it has finished with it.
**
** On success, [SQLITE_OK] is returned. Otherwise an
-** [SQLITE_ERROR | error code] is returned.
+** [error code] is returned.
**
** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
** recommended for all new programs. The two older interfaces are retained
** for backwards compatibility, but their use is discouraged.
** In the "v2" interfaces, the prepared statement
** that is returned (the [sqlite3_stmt] object) contains a copy of the
-** original SQL text. This causes the [sqlite3_step()] interface to
+** original SQL text. {END} This causes the [sqlite3_step()] interface to
** behave a differently in two ways:
**
**
** -
** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
** always used to do, [sqlite3_step()] will automatically recompile the SQL
-** statement and try to run it again. If the schema has changed in a way
-** that makes the statement no longer valid, [sqlite3_step()] will still
-** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is
-** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the
-** error go away. Note: use [sqlite3_errmsg()] to find the text of the parsing
-** error that results in an [SQLITE_SCHEMA] return.
+** statement and try to run it again. If the schema has changed in
+** a way that makes the statement no longer valid, [sqlite3_step()] will still
+** return [SQLITE_SCHEMA]. But unlike the legacy behavior,
+** [SQLITE_SCHEMA] is now a fatal error. Calling
+** [sqlite3_prepare_v2()] again will not make the
+** error go away. Note: use [sqlite3_errmsg()] to find the text
+** of the parsing error that results in an [SQLITE_SCHEMA] return. {END}
**
**
** -
** When an error occurs,
** [sqlite3_step()] will return one of the detailed
-** [SQLITE_ERROR | result codes] or
-** [SQLITE_IOERR_READ | extended result codes] such as directly.
+** [error codes] or [extended error codes].
** The legacy behavior was that [sqlite3_step()] would only return a generic
** [SQLITE_ERROR] result code and you would have to make a second call to
** [sqlite3_reset()] in order to find the underlying cause of the problem.
@@ -1564,6 +2199,42 @@ typedef struct sqlite3_stmt sqlite3_stmt
** returned immediately.
**
**
+**
+** INVARIANTS:
+**
+** {F13011} The [sqlite3_prepare(db,zSql,...)] and
+** [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the
+** text in their zSql parameter as UTF-8.
+**
+** {F13012} The [sqlite3_prepare16(db,zSql,...)] and
+** [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the
+** text in their zSql parameter as UTF-16 in the native byte order.
+**
+** {F13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
+** and its variants is less than zero, then SQL text is
+** read from zSql is read up to the first zero terminator.
+**
+** {F13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
+** and its variants is non-negative, then nBytes bytes
+** SQL text is read from zSql.
+**
+** {F13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants
+** if the zSql input text contains more than one SQL statement
+** and pzTail is not NULL, then *pzTail is made to point to the
+** first byte past the end of the first SQL statement in zSql.
+** What does *pzTail point to if there is one statement?
+**
+** {F13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)]
+** or one of its variants writes into *ppStmt a pointer to a new
+** [prepared statement] or a pointer to NULL
+** if zSql contains nothing other than whitespace or comments.
+**
+** {F13019} The [sqlite3_prepare_v2()] interface and its variants return
+** [SQLITE_OK] or an appropriate [error code] upon failure.
+**
+** {F13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its
+** variants returns an error (any value other than [SQLITE_OK])
+** it first sets *ppStmt to NULL.
*/
int sqlite3_prepare(
sqlite3 *db, /* Database handle */
@@ -1595,84 +2266,111 @@ int sqlite3_prepare16_v2(
);
/*
-** CAPI3REF: Dynamically Typed Value Object
+** CAPIREF: Retrieving Statement SQL {F13100}
+**
+** This intereface can be used to retrieve a saved copy of the original
+** SQL text used to create a [prepared statement].
+**
+** INVARIANTS:
+**
+** {F13101} If the [prepared statement] passed as
+** the an argument to [sqlite3_sql()] was compiled
+** compiled using either [sqlite3_prepare_v2()] or
+** [sqlite3_prepare16_v2()],
+** then [sqlite3_sql()] function returns a pointer to a
+** zero-terminated string containing a UTF-8 rendering
+** of the original SQL statement.
+**
+** {F13102} If the [prepared statement] passed as
+** the an argument to [sqlite3_sql()] was compiled
+** compiled using either [sqlite3_prepare()] or
+** [sqlite3_prepare16()],
+** then [sqlite3_sql()] function returns a NULL pointer.
+**
+** {F13103} The string returned by [sqlite3_sql(S)] is valid until the
+** [prepared statement] S is deleted using [sqlite3_finalize(S)].
+*/
+const char *sqlite3_sql(sqlite3_stmt *pStmt);
+
+/*
+** CAPI3REF: Dynamically Typed Value Object {F15000}
**
-** SQLite uses dynamic typing for the values it stores. Values can
-** be integers, floating point values, strings, BLOBs, or NULL. When
-** passing around values internally, each value is represented as
-** an instance of the sqlite3_value object.
+** SQLite uses the sqlite3_value object to represent all values
+** that are or can be stored in a database table.
+** SQLite uses dynamic typing for the values it stores.
+** Values stored in sqlite3_value objects can be
+** be integers, floating point values, strings, BLOBs, or NULL.
*/
typedef struct Mem sqlite3_value;
/*
-** CAPI3REF: SQL Function Context Object
+** CAPI3REF: SQL Function Context Object {F16001}
**
** The context in which an SQL function executes is stored in an
-** sqlite3_context object. A pointer to such an object is the
-** first parameter to user-defined SQL functions.
+** sqlite3_context object. A pointer to an sqlite3_context
+** object is always first parameter to application-defined SQL functions.
*/
typedef struct sqlite3_context sqlite3_context;
/*
-** CAPI3REF: Binding Values To Prepared Statements
+** CAPI3REF: Binding Values To Prepared Statements {F13500}
**
-** In the SQL strings input to [sqlite3_prepare_v2()] and its variants,
-** one or more literals can be replace by a parameter in one of these
-** forms:
+** In the SQL strings input to [sqlite3_prepare_v2()] and its
+** variants, literals may be replace by a parameter in one
+** of these forms:
**
**
** - ?
**
- ?NNN
-**
- :AAA
-**
- @AAA
+**
- :VVV
+**
- @VVV
**
- $VVV
**
**
** In the parameter forms shown above NNN is an integer literal,
-** AAA is an alphanumeric identifier and VVV is a variable name according
-** to the syntax rules of the TCL programming language.
-** The values of these parameters (also called "host parameter names")
+** VVV alpha-numeric parameter name.
+** The values of these parameters (also called "host parameter names"
+** or "SQL parameters")
** can be set using the sqlite3_bind_*() routines defined here.
**
-** The first argument to the sqlite3_bind_*() routines always is a pointer
-** to the [sqlite3_stmt] object returned from [sqlite3_prepare_v2()] or
-** its variants. The second
-** argument is the index of the parameter to be set. The first parameter has
-** an index of 1. When the same named parameter is used more than once, second
-** and subsequent
-** occurrences have the same index as the first occurrence. The index for
-** named parameters can be looked up using the
-** [sqlite3_bind_parameter_name()] API if desired. The index for "?NNN"
-** parametes is the value of NNN.
+** The first argument to the sqlite3_bind_*() routines always
+** is a pointer to the [sqlite3_stmt] object returned from
+** [sqlite3_prepare_v2()] or its variants. The second
+** argument is the index of the parameter to be set. The
+** first parameter has an index of 1. When the same named
+** parameter is used more than once, second and subsequent
+** occurrences have the same index as the first occurrence.
+** The index for named parameters can be looked up using the
+** [sqlite3_bind_parameter_name()] API if desired. The index
+** for "?NNN" parameters is the value of NNN.
** The NNN value must be between 1 and the compile-time
** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999).
-** See limits.html for additional information.
**
** The third argument is the value to bind to the parameter.
**
** In those
** routines that have a fourth argument, its value is the number of bytes
-** in the parameter. To be clear: the value is the number of bytes in the
-** string, not the number of characters. The number
+** in the parameter. To be clear: the value is the number of bytes
+** in the value, not the number of characters. The number
** of bytes does not include the zero-terminator at the end of strings.
** If the fourth parameter is negative, the length of the string is
** number of bytes up to the first zero terminator.
**
** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
-** text after SQLite has finished with it. If the fifth argument is the
-** special value [SQLITE_STATIC], then the library assumes that the information
-** is in static, unmanaged space and does not need to be freed. If the
-** fifth argument has the value [SQLITE_TRANSIENT], then SQLite makes its
-** own private copy of the data immediately, before the sqlite3_bind_*()
-** routine returns.
+** string after SQLite has finished with it. If the fifth argument is
+** the special value [SQLITE_STATIC], then SQLite assumes that the
+** information is in static, unmanaged space and does not need to be freed.
+** If the fifth argument has the value [SQLITE_TRANSIENT], then
+** SQLite makes its own private copy of the data immediately, before
+** the sqlite3_bind_*() routine returns.
**
-** The sqlite3_bind_zeroblob() routine binds a BLOB of length n that
+** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
** is filled with zeros. A zeroblob uses a fixed amount of memory
** (just an integer to hold it size) while it is being processed.
** Zeroblobs are intended to serve as place-holders for BLOBs whose
** content is later written using
-** [sqlite3_blob_open | increment BLOB I/O] routines. A negative
+** [sqlite3_blob_open | increment BLOB I/O] routines. A negative
** value for the zeroblob results in a zero-length BLOB.
**
** The sqlite3_bind_*() routines must be called after
@@ -1684,8 +2382,85 @@ typedef struct sqlite3_context sqlite3_c
** These routines return [SQLITE_OK] on success or an error code if
** anything goes wrong. [SQLITE_RANGE] is returned if the parameter
** index is out of range. [SQLITE_NOMEM] is returned if malloc fails.
-** [SQLITE_MISUSE] is returned if these routines are called on a virtual
-** machine that is the wrong state or which has already been finalized.
+** [SQLITE_MISUSE] might be returned if these routines are called on a
+** virtual machine that is the wrong state or which has already been finalized.
+** Detection of misuse is unreliable. Applications should not depend
+** on SQLITE_MISUSE returns. SQLITE_MISUSE is intended to indicate a
+** a logic error in the application. Future versions of SQLite might
+** panic rather than return SQLITE_MISUSE.
+**
+** See also: [sqlite3_bind_parameter_count()],
+** [sqlite3_bind_parameter_name()], and
+** [sqlite3_bind_parameter_index()].
+**
+** INVARIANTS:
+**
+** {F13506} The [sqlite3_prepare | SQL statement compiler] recognizes
+** tokens of the forms "?", "?NNN", "$VVV", ":VVV", and "@VVV"
+** as SQL parameters, where NNN is any sequence of one or more
+** digits and where VVV is any sequence of one or more
+** alphanumeric characters or "::" optionally followed by
+** a string containing no spaces and contained within parentheses.
+**
+** {F13509} The initial value of an SQL parameter is NULL.
+**
+** {F13512} The index of an "?" SQL parameter is one larger than the
+** largest index of SQL parameter to the left, or 1 if
+** the "?" is the leftmost SQL parameter.
+**
+** {F13515} The index of an "?NNN" SQL parameter is the integer NNN.
+**
+** {F13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is
+** the same as the index of leftmost occurances of the same
+** parameter, or one more than the largest index over all
+** parameters to the left if this is the first occurrance
+** of this parameter, or 1 if this is the leftmost parameter.
+**
+** {F13521} The [sqlite3_prepare | SQL statement compiler] fail with
+** an [SQLITE_RANGE] error if the index of an SQL parameter
+** is less than 1 or greater than SQLITE_MAX_VARIABLE_NUMBER.
+**
+** {F13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)]
+** associate the value V with all SQL parameters having an
+** index of N in the [prepared statement] S.
+**
+** {F13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)]
+** override prior calls with the same values of S and N.
+**
+** {F13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)]
+** persist across calls to [sqlite3_reset(S)].
+**
+** {F13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
+** [sqlite3_bind_text(S,N,V,L,D)], or
+** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L
+** bytes of the blob or string pointed to by V, when L
+** is non-negative.
+**
+** {F13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or
+** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters
+** from V through the first zero character when L is negative.
+**
+** {F13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
+** [sqlite3_bind_text(S,N,V,L,D)], or
+** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
+** constant [SQLITE_STATIC], SQLite assumes that the value V
+** is held in static unmanaged space that will not change
+** during the lifetime of the binding.
+**
+** {F13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
+** [sqlite3_bind_text(S,N,V,L,D)], or
+** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
+** constant [SQLITE_TRANSIENT], the routine makes a
+** private copy of V value before it returns.
+**
+** {F13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
+** [sqlite3_bind_text(S,N,V,L,D)], or
+** [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to
+** a function, SQLite invokes that function to destroy the
+** V value after it has finished using the V value.
+**
+** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound
+** is a blob of L bytes, or a zero-length blob if L is negative.
*/
int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
int sqlite3_bind_double(sqlite3_stmt*, int, double);
@@ -1698,99 +2473,184 @@ int sqlite3_bind_value(sqlite3_stmt*, in
int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
/*
-** CAPI3REF: Number Of Host Parameters
+** CAPI3REF: Number Of SQL Parameters {F13600}
**
-** Return the largest host parameter index in the precompiled statement given
-** as the argument. When the host parameters are of the forms like ":AAA"
-** or "?", then they are assigned sequential increasing numbers beginning
-** with one, so the value returned is the number of parameters. However
-** if the same host parameter name is used multiple times, each occurrance
-** is given the same number, so the value returned in that case is the number
-** of unique host parameter names. If host parameters of the form "?NNN"
-** are used (where NNN is an integer) then there might be gaps in the
-** numbering and the value returned by this interface is the index of the
-** host parameter with the largest index value.
-**
-** The prepared statement must not be [sqlite3_finalize | finalized]
-** prior to this routine returnning. Otherwise the results are undefined
-** and probably undesirable.
+** This routine can be used to find the number of SQL parameters
+** in a prepared statement. SQL parameters are tokens of the
+** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
+** place-holders for values that are [sqlite3_bind_blob | bound]
+** to the parameters at a later time.
+**
+** This routine actually returns the index of the largest parameter.
+** For all forms except ?NNN, this will correspond to the number of
+** unique parameters. If parameters of the ?NNN are used, there may
+** be gaps in the list.
+**
+** See also: [sqlite3_bind_blob|sqlite3_bind()],
+** [sqlite3_bind_parameter_name()], and
+** [sqlite3_bind_parameter_index()].
+**
+** INVARIANTS:
+**
+** {F13601} The [sqlite3_bind_parameter_count(S)] interface returns
+** the largest index of all SQL parameters in the
+** [prepared statement] S, or 0 if S
+** contains no SQL parameters.
*/
int sqlite3_bind_parameter_count(sqlite3_stmt*);
/*
-** CAPI3REF: Name Of A Host Parameter
+** CAPI3REF: Name Of A Host Parameter {F13620}
**
-** This routine returns a pointer to the name of the n-th parameter in a
-** [sqlite3_stmt | prepared statement].
-** Host parameters of the form ":AAA" or "@AAA" or "$VVV" have a name
-** which is the string ":AAA" or "@AAA" or "$VVV".
+** This routine returns a pointer to the name of the n-th
+** SQL parameter in a [prepared statement].
+** SQL parameters of the form ":AAA" or "@AAA" or "$AAA" have a name
+** which is the string ":AAA" or "@AAA" or "$VVV".
** In other words, the initial ":" or "$" or "@"
** is included as part of the name.
** Parameters of the form "?" or "?NNN" have no name.
**
-** The first bound parameter has an index of 1, not 0.
+** The first host parameter has an index of 1, not 0.
**
-** If the value n is out of range or if the n-th parameter is nameless,
-** then NULL is returned. The returned string is always in the
-** UTF-8 encoding even if the named parameter was originally specified
-** as UTF-16 in [sqlite3_prepare16()] or [sqlite3_prepare16_v2()].
+** If the value n is out of range or if the n-th parameter is
+** nameless, then NULL is returned. The returned string is
+** always in the UTF-8 encoding even if the named parameter was
+** originally specified as UTF-16 in [sqlite3_prepare16()] or
+** [sqlite3_prepare16_v2()].
+**
+** See also: [sqlite3_bind_blob|sqlite3_bind()],
+** [sqlite3_bind_parameter_count()], and
+** [sqlite3_bind_parameter_index()].
+**
+** INVARIANTS:
+**
+** {F13621} The [sqlite3_bind_parameter_name(S,N)] interface returns
+** a UTF-8 rendering of the name of the SQL parameter in
+** [prepared statement] S having index N, or
+** NULL if there is no SQL parameter with index N or if the
+** parameter with index N is an anonymous parameter "?" or
+** a numbered parameter "?NNN".
*/
const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
/*
-** CAPI3REF: Index Of A Parameter With A Given Name
+** CAPI3REF: Index Of A Parameter With A Given Name {F13640}
**
-** This routine returns the index of a host parameter with the given name.
-** The name must match exactly. If no parameter with the given name is
-** found, return 0. Parameter names must be UTF8.
+** Return the index of an SQL parameter given its name. The
+** index value returned is suitable for use as the second
+** parameter to [sqlite3_bind_blob|sqlite3_bind()]. A zero
+** is returned if no matching parameter is found. The parameter
+** name must be given in UTF-8 even if the original statement
+** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
+**
+** See also: [sqlite3_bind_blob|sqlite3_bind()],
+** [sqlite3_bind_parameter_count()], and
+** [sqlite3_bind_parameter_index()].
+**
+** INVARIANTS:
+**
+** {F13641} The [sqlite3_bind_parameter_index(S,N)] interface returns
+** the index of SQL parameter in [prepared statement]
+** S whose name matches the UTF-8 string N, or 0 if there is
+** no match.
*/
int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
/*
-** CAPI3REF: Reset All Bindings On A Prepared Statement
+** CAPI3REF: Reset All Bindings On A Prepared Statement {F13660}
**
** Contrary to the intuition of many, [sqlite3_reset()] does not
** reset the [sqlite3_bind_blob | bindings] on a
-** [sqlite3_stmt | prepared statement]. Use this routine to
+** [prepared statement]. Use this routine to
** reset all host parameters to NULL.
+**
+** INVARIANTS:
+**
+** {F13661} The [sqlite3_clear_bindings(S)] interface resets all
+** SQL parameter bindings in [prepared statement] S
+** back to NULL.
*/
int sqlite3_clear_bindings(sqlite3_stmt*);
/*
-** CAPI3REF: Number Of Columns In A Result Set
+** CAPI3REF: Number Of Columns In A Result Set {F13710}
**
** Return the number of columns in the result set returned by the
-** [sqlite3_stmt | compiled SQL statement]. This routine returns 0
+** [prepared statement]. This routine returns 0
** if pStmt is an SQL statement that does not return data (for
** example an UPDATE).
+**
+** INVARIANTS:
+**
+** {F13711} The [sqlite3_column_count(S)] interface returns the number of
+** columns in the result set generated by the
+** [prepared statement] S, or 0 if S does not generate
+** a result set.
*/
int sqlite3_column_count(sqlite3_stmt *pStmt);
/*
-** CAPI3REF: Column Names In A Result Set
+** CAPI3REF: Column Names In A Result Set {F13720}
**
** These routines return the name assigned to a particular column
** in the result set of a SELECT statement. The sqlite3_column_name()
-** interface returns a pointer to a UTF8 string and sqlite3_column_name16()
-** returns a pointer to a UTF16 string. The first parameter is the
-** [sqlite3_stmt | prepared statement] that implements the SELECT statement.
+** interface returns a pointer to a zero-terminated UTF8 string
+** and sqlite3_column_name16() returns a pointer to a zero-terminated
+** UTF16 string. The first parameter is the
+** [prepared statement] that implements the SELECT statement.
** The second parameter is the column number. The left-most column is
** number 0.
**
** The returned string pointer is valid until either the
-** [sqlite3_stmt | prepared statement] is destroyed by [sqlite3_finalize()]
+** [prepared statement] is destroyed by [sqlite3_finalize()]
** or until the next call sqlite3_column_name() or sqlite3_column_name16()
** on the same column.
**
** If sqlite3_malloc() fails during the processing of either routine
** (for example during a conversion from UTF-8 to UTF-16) then a
** NULL pointer is returned.
+**
+** The name of a result column is the value of the "AS" clause for
+** that column, if there is an AS clause. If there is no AS clause
+** then the name of the column is unspecified and may change from
+** one release of SQLite to the next.
+**
+** INVARIANTS:
+**
+** {F13721} A successful invocation of the [sqlite3_column_name(S,N)]
+** interface returns the name
+** of the Nth column (where 0 is the left-most column) for the
+** result set of [prepared statement] S as a
+** zero-terminated UTF-8 string.
+**
+** {F13723} A successful invocation of the [sqlite3_column_name16(S,N)]
+** interface returns the name
+** of the Nth column (where 0 is the left-most column) for the
+** result set of [prepared statement] S as a
+** zero-terminated UTF-16 string in the native byte order.
+**
+** {F13724} The [sqlite3_column_name()] and [sqlite3_column_name16()]
+** interfaces return a NULL pointer if they are unable to
+** allocate memory memory to hold there normal return strings.
+**
+** {F13725} If the N parameter to [sqlite3_column_name(S,N)] or
+** [sqlite3_column_name16(S,N)] is out of range, then the
+** interfaces returns a NULL pointer.
+**
+** {F13726} The strings returned by [sqlite3_column_name(S,N)] and
+** [sqlite3_column_name16(S,N)] are valid until the next
+** call to either routine with the same S and N parameters
+** or until [sqlite3_finalize(S)] is called.
+**
+** {F13727} When a result column of a [SELECT] statement contains
+** an AS clause, the name of that column is the indentifier
+** to the right of the AS keyword.
*/
const char *sqlite3_column_name(sqlite3_stmt*, int N);
const void *sqlite3_column_name16(sqlite3_stmt*, int N);
/*
-** CAPI3REF: Source Of Data In A Query Result
+** CAPI3REF: Source Of Data In A Query Result {F13740}
**
** These routines provide a means to determine what column of what
** table in which database a result of a SELECT statement comes from.
@@ -1799,33 +2659,95 @@ const void *sqlite3_column_name16(sqlite
** the database name, the _table_ routines return the table name, and
** the origin_ routines return the column name.
** The returned string is valid until
-** the [sqlite3_stmt | prepared statement] is destroyed using
+** the [prepared statement] is destroyed using
** [sqlite3_finalize()] or until the same information is requested
** again in a different encoding.
**
** The names returned are the original un-aliased names of the
** database, table, and column.
**
-** The first argument to the following calls is a
-** [sqlite3_stmt | compiled SQL statement].
+** The first argument to the following calls is a [prepared statement].
** These functions return information about the Nth column returned by
** the statement, where N is the second function argument.
**
** If the Nth column returned by the statement is an expression
** or subquery and is not a column value, then all of these functions
-** return NULL. Otherwise, they return the
+** return NULL. These routine might also return NULL if a memory
+** allocation error occurs. Otherwise, they return the
** name of the attached database, table and column that query result
** column was extracted from.
**
-** As with all other SQLite APIs, those postfixed with "16" return UTF-16
-** encoded strings, the other functions return UTF-8.
+** As with all other SQLite APIs, those postfixed with "16" return
+** UTF-16 encoded strings, the other functions return UTF-8. {END}
**
** These APIs are only available if the library was compiled with the
** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
**
+** {U13751}
** If two or more threads call one or more of these routines against the same
** prepared statement and column at the same time then the results are
** undefined.
+**
+** INVARIANTS:
+**
+** {F13741} The [sqlite3_column_database_name(S,N)] interface returns either
+** the UTF-8 zero-terminated name of the database from which the
+** Nth result column of [prepared statement] S
+** is extracted, or NULL if the the Nth column of S is a
+** general expression or if unable to allocate memory
+** to store the name.
+**
+** {F13742} The [sqlite3_column_database_name16(S,N)] interface returns either
+** the UTF-16 native byte order
+** zero-terminated name of the database from which the
+** Nth result column of [prepared statement] S
+** is extracted, or NULL if the the Nth column of S is a
+** general expression or if unable to allocate memory
+** to store the name.
+**
+** {F13743} The [sqlite3_column_table_name(S,N)] interface returns either
+** the UTF-8 zero-terminated name of the table from which the
+** Nth result column of [prepared statement] S
+** is extracted, or NULL if the the Nth column of S is a
+** general expression or if unable to allocate memory
+** to store the name.
+**
+** {F13744} The [sqlite3_column_table_name16(S,N)] interface returns either
+** the UTF-16 native byte order
+** zero-terminated name of the table from which the
+** Nth result column of [prepared statement] S
+** is extracted, or NULL if the the Nth column of S is a
+** general expression or if unable to allocate memory
+** to store the name.
+**
+** {F13745} The [sqlite3_column_origin_name(S,N)] interface returns either
+** the UTF-8 zero-terminated name of the table column from which the
+** Nth result column of [prepared statement] S
+** is extracted, or NULL if the the Nth column of S is a
+** general expression or if unable to allocate memory
+** to store the name.
+**
+** {F13746} The [sqlite3_column_origin_name16(S,N)] interface returns either
+** the UTF-16 native byte order
+** zero-terminated name of the table column from which the
+** Nth result column of [prepared statement] S
+** is extracted, or NULL if the the Nth column of S is a
+** general expression or if unable to allocate memory
+** to store the name.
+**
+** {F13748} The return values from
+** [sqlite3_column_database_name|column metadata interfaces]
+** are valid
+** for the lifetime of the [prepared statement]
+** or until the encoding is changed by another metadata
+** interface call for the same prepared statement and column.
+**
+** LIMITATIONS:
+**
+** {U13751} If two or more threads call one or more
+** [sqlite3_column_database_name|column metadata interfaces]
+** the same [prepared statement] and result column
+** at the same time then the results are undefined.
*/
const char *sqlite3_column_database_name(sqlite3_stmt*,int);
const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
@@ -1835,16 +2757,16 @@ const char *sqlite3_column_origin_name(s
const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
/*
-** CAPI3REF: Declared Datatype Of A Query Result
+** CAPI3REF: Declared Datatype Of A Query Result {F13760}
**
-** The first parameter is a [sqlite3_stmt | compiled SQL statement].
+** The first parameter is a [prepared statement].
** If this statement is a SELECT statement and the Nth column of the
-** returned result set of that SELECT is a table column (not an
+** returned result set of that SELECT is a table column (not an
** expression or subquery) then the declared type of the table
-** column is returned. If the Nth column of the result set is an
+** column is returned. If the Nth column of the result set is an
** expression or subquery, then a NULL pointer is returned.
-** The returned string is always UTF-8 encoded. For example, in
-** the database schema:
+** The returned string is always UTF-8 encoded. {END}
+** For example, in the database schema:
**
** CREATE TABLE t1(c1 VARIANT);
**
@@ -1862,14 +2784,36 @@ const void *sqlite3_column_origin_name16
** strongly typed, but the typing is dynamic not static. Type
** is associated with individual values, not with the containers
** used to hold those values.
+**
+** INVARIANTS:
+**
+** {F13761} A successful call to [sqlite3_column_decltype(S,N)]
+** returns a zero-terminated UTF-8 string containing the
+** the declared datatype of the table column that appears
+** as the Nth column (numbered from 0) of the result set to the
+** [prepared statement] S.
+**
+** {F13762} A successful call to [sqlite3_column_decltype16(S,N)]
+** returns a zero-terminated UTF-16 native byte order string
+** containing the declared datatype of the table column that appears
+** as the Nth column (numbered from 0) of the result set to the
+** [prepared statement] S.
+**
+** {F13763} If N is less than 0 or N is greater than or equal to
+** the number of columns in [prepared statement] S
+** or if the Nth column of S is an expression or subquery rather
+** than a table column or if a memory allocation failure
+** occurs during encoding conversions, then
+** calls to [sqlite3_column_decltype(S,N)] or
+** [sqlite3_column_decltype16(S,N)] return NULL.
*/
-const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
+const char *sqlite3_column_decltype(sqlite3_stmt*,int);
const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
/*
-** CAPI3REF: Evaluate An SQL Statement
+** CAPI3REF: Evaluate An SQL Statement {F13200}
**
-** After an [sqlite3_stmt | SQL statement] has been prepared with a call
+** After an [prepared statement] has been prepared with a call
** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of
** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()],
** then this function must be called one or more times to evaluate the
@@ -1912,11 +2856,11 @@ const void *sqlite3_column_decltype16(sq
** With the legacy interface, a more specific error code (example:
** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
** can be obtained by calling [sqlite3_reset()] on the
-** [sqlite3_stmt | prepared statement]. In the "v2" interface,
+** [prepared statement]. In the "v2" interface,
** the more specific error code is returned directly by sqlite3_step().
**
** [SQLITE_MISUSE] means that the this routine was called inappropriately.
-** Perhaps it was called on a [sqlite3_stmt | prepared statement] that has
+** Perhaps it was called on a [prepared statement] that has
** already been [sqlite3_finalize | finalized] or on one that had
** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
** be the case that the same database connection is being used by two or
@@ -1928,34 +2872,69 @@ const void *sqlite3_column_decltype16(sq
** [SQLITE_ERROR], following any error other than [SQLITE_BUSY]
** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or
** [sqlite3_finalize()] in order to find one of the specific
-** [SQLITE_ERROR | result codes] that better describes the error.
+** [error codes] that better describes the error.
** We admit that this is a goofy design. The problem has been fixed
** with the "v2" interface. If you prepare all of your SQL statements
** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the
-** more specific [SQLITE_ERROR | result codes] are returned directly
+** more specific [error codes] are returned directly
** by sqlite3_step(). The use of the "v2" interface is recommended.
+**
+** INVARIANTS:
+**
+** {F13202} If [prepared statement] S is ready to be
+** run, then [sqlite3_step(S)] advances that prepared statement
+** until to completion or until it is ready to return another
+** row of the result set or an interrupt or run-time error occurs.
+**
+** {F15304} When a call to [sqlite3_step(S)] causes the
+** [prepared statement] S to run to completion,
+** the function returns [SQLITE_DONE].
+**
+** {F15306} When a call to [sqlite3_step(S)] stops because it is ready
+** to return another row of the result set, it returns
+** [SQLITE_ROW].
+**
+** {F15308} If a call to [sqlite3_step(S)] encounters an
+** [sqlite3_interrupt|interrupt] or a run-time error,
+** it returns an appropraite error code that is not one of
+** [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE].
+**
+** {F15310} If an [sqlite3_interrupt|interrupt] or run-time error
+** occurs during a call to [sqlite3_step(S)]
+** for a [prepared statement] S created using
+** legacy interfaces [sqlite3_prepare()] or
+** [sqlite3_prepare16()] then the function returns either
+** [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE].
*/
int sqlite3_step(sqlite3_stmt*);
/*
-** CAPI3REF:
+** CAPI3REF: Number of columns in a result set {F13770}
**
** Return the number of values in the current row of the result set.
**
-** After a call to [sqlite3_step()] that returns [SQLITE_ROW], this routine
-** will return the same value as the [sqlite3_column_count()] function.
-** After [sqlite3_step()] has returned an [SQLITE_DONE], [SQLITE_BUSY], or
-** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been
-** called on the [sqlite3_stmt | prepared statement] for the first time,
-** this routine returns zero.
+** INVARIANTS:
+**
+** {F13771} After a call to [sqlite3_step(S)] that returns
+** [SQLITE_ROW], the [sqlite3_data_count(S)] routine
+** will return the same value as the
+** [sqlite3_column_count(S)] function.
+**
+** {F13772} After [sqlite3_step(S)] has returned any value other than
+** [SQLITE_ROW] or before [sqlite3_step(S)] has been
+** called on the [prepared statement] for
+** the first time since it was [sqlite3_prepare|prepared]
+** or [sqlite3_reset|reset], the [sqlite3_data_count(S)]
+** routine returns zero.
*/
int sqlite3_data_count(sqlite3_stmt *pStmt);
/*
-** CAPI3REF: Fundamental Datatypes
+** CAPI3REF: Fundamental Datatypes {F10265}
+** KEYWORDS: SQLITE_TEXT
**
-** Every value in SQLite has one of five fundamental datatypes:
+** {F10266}Every value in SQLite has one of five fundamental datatypes:
**
**
** - 64-bit signed integer
@@ -1963,7 +2942,7 @@ int sqlite3_data_count(sqlite3_stmt *pSt
**
- string
**
- BLOB
**
- NULL
-**
+** {END}
**
** These constants are codes for each of those types.
**
@@ -1984,12 +2963,14 @@ int sqlite3_data_count(sqlite3_stmt *pSt
#define SQLITE3_TEXT 3
/*
-** CAPI3REF: Results Values From A Query
+** CAPI3REF: Results Values From A Query {F13800}
+**
+** These routines form the "result set query" interface.
**
** These routines return information about
** a single column of the current result row of a query. In every
** case the first argument is a pointer to the
-** [sqlite3_stmt | SQL statement] that is being
+** [prepared statement] that is being
** evaluated (the [sqlite3_stmt*] that was returned from
** [sqlite3_prepare_v2()] or one of its variants) and
** the second argument is the index of the column for which information
@@ -2030,12 +3011,12 @@ int sqlite3_data_count(sqlite3_stmt *pSt
** bytes in the string, not the number of characters.
**
** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
-** even zero-length strings, are always zero terminated. The return
+** even empty strings, are always zero terminated. The return
** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
** pointer, possibly even a NULL pointer.
**
** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
-** but leaves the result in UTF-16 instead of UTF-8.
+** but leaves the result in UTF-16 in native byte order instead of UTF-8.
** The zero terminator is not included in this count.
**
** These routines attempt to convert the value where appropriate. For
@@ -2127,6 +3108,61 @@ int sqlite3_data_count(sqlite3_stmt *pSt
** is either the integer 0, the floating point number 0.0, or a NULL
** pointer. Subsequent calls to [sqlite3_errcode()] will return
** [SQLITE_NOMEM].
+**
+** INVARIANTS:
+**
+** {F13803} The [sqlite3_column_blob(S,N)] interface converts the
+** Nth column in the current row of the result set for
+** [prepared statement] S into a blob and then returns a
+** pointer to the converted value.
+**
+** {F13806} The [sqlite3_column_bytes(S,N)] interface returns the
+** number of bytes in the blob or string (exclusive of the
+** zero terminator on the string) that was returned by the
+** most recent call to [sqlite3_column_blob(S,N)] or
+** [sqlite3_column_text(S,N)].
+**
+** {F13809} The [sqlite3_column_bytes16(S,N)] interface returns the
+** number of bytes in the string (exclusive of the
+** zero terminator on the string) that was returned by the
+** most recent call to [sqlite3_column_text16(S,N)].
+**
+** {F13812} The [sqlite3_column_double(S,N)] interface converts the
+** Nth column in the current row of the result set for
+** [prepared statement] S into a floating point value and
+** returns a copy of that value.
+**
+** {F13815} The [sqlite3_column_int(S,N)] interface converts the
+** Nth column in the current row of the result set for
+** [prepared statement] S into a 64-bit signed integer and
+** returns the lower 32 bits of that integer.
+**
+** {F13818} The [sqlite3_column_int64(S,N)] interface converts the
+** Nth column in the current row of the result set for
+** [prepared statement] S into a 64-bit signed integer and
+** returns a copy of that integer.
+**
+** {F13821} The [sqlite3_column_text(S,N)] interface converts the
+** Nth column in the current row of the result set for
+** [prepared statement] S into a zero-terminated UTF-8
+** string and returns a pointer to that string.
+**
+** {F13824} The [sqlite3_column_text16(S,N)] interface converts the
+** Nth column in the current row of the result set for
+** [prepared statement] S into a zero-terminated 2-byte
+** aligned UTF-16 native byte order
+** string and returns a pointer to that string.
+**
+** {F13827} The [sqlite3_column_type(S,N)] interface returns
+** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
+** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
+** the Nth column in the current row of the result set for
+** [prepared statement] S.
+**
+** {F13830} The [sqlite3_column_value(S,N)] interface returns a
+** pointer to the [sqlite3_value] object that for the
+** Nth column in the current row of the result set for
+** [prepared statement] S.
*/
const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
@@ -2140,51 +3176,77 @@ int sqlite3_column_type(sqlite3_stmt*, i
sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
/*
-** CAPI3REF: Destroy A Prepared Statement Object
+** CAPI3REF: Destroy A Prepared Statement Object {F13300}
**
** The sqlite3_finalize() function is called to delete a
-** [sqlite3_stmt | compiled SQL statement]. If the statement was
+** [prepared statement]. If the statement was
** executed successfully, or not executed at all, then SQLITE_OK is returned.
** If execution of the statement failed then an
-** [SQLITE_ERROR | error code] or [SQLITE_IOERR_READ | extended error code]
+** [error code] or [extended error code]
** is returned.
**
** This routine can be called at any point during the execution of the
-** [sqlite3_stmt | virtual machine]. If the virtual machine has not
+** [prepared statement]. If the virtual machine has not
** completed execution when this routine is called, that is like
** encountering an error or an interrupt. (See [sqlite3_interrupt()].)
** Incomplete updates may be rolled back and transactions cancelled,
** depending on the circumstances, and the
-** [SQLITE_ERROR | result code] returned will be [SQLITE_ABORT].
+** [error code] returned will be [SQLITE_ABORT].
+**
+** INVARIANTS:
+**
+** {F11302} The [sqlite3_finalize(S)] interface destroys the
+** [prepared statement] S and releases all
+** memory and file resources held by that object.
+**
+** {F11304} If the most recent call to [sqlite3_step(S)] for the
+** [prepared statement] S returned an error,
+** then [sqlite3_finalize(S)] returns that same error.
*/
int sqlite3_finalize(sqlite3_stmt *pStmt);
/*
-** CAPI3REF: Reset A Prepared Statement Object
+** CAPI3REF: Reset A Prepared Statement Object {F13330}
**
** The sqlite3_reset() function is called to reset a
-** [sqlite3_stmt | compiled SQL statement] object.
-** back to it's initial state, ready to be re-executed.
+** [prepared statement] object.
+** back to its initial state, ready to be re-executed.
** Any SQL statement variables that had values bound to them using
** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
** Use [sqlite3_clear_bindings()] to reset the bindings.
+**
+** {F11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S
+** back to the beginning of its program.
+**
+** {F11334} If the most recent call to [sqlite3_step(S)] for
+** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
+** or if [sqlite3_step(S)] has never before been called on S,
+** then [sqlite3_reset(S)] returns [SQLITE_OK].
+**
+** {F11336} If the most recent call to [sqlite3_step(S)] for
+** [prepared statement] S indicated an error, then
+** [sqlite3_reset(S)] returns an appropriate [error code].
+**
+** {F11338} The [sqlite3_reset(S)] interface does not change the values
+** of any [sqlite3_bind_blob|bindings] on [prepared statement] S.
*/
int sqlite3_reset(sqlite3_stmt *pStmt);
/*
-** CAPI3REF: Create Or Redefine SQL Functions
+** CAPI3REF: Create Or Redefine SQL Functions {F16100}
+** KEYWORDS: {function creation routines}
**
-** The following two functions are used to add SQL functions or aggregates
+** These two functions (collectively known as
+** "function creation routines") are used to add SQL functions or aggregates
** or to redefine the behavior of existing SQL functions or aggregates. The
** difference only between the two is that the second parameter, the
** name of the (scalar) function or aggregate, is encoded in UTF-8 for
** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
**
-** The first argument is the [sqlite3 | database handle] that holds the
-** SQL function or aggregate is to be added or redefined. If a single
-** program uses more than one database handle internally, then SQL
-** functions or aggregates must be added individually to each database
-** handle with which they will be used.
+** The first parameter is the [database connection] to which the SQL
+** function is to be added. If a single
+** program uses more than one [database connection] internally, then SQL
+** functions must be added individually to each [database connection].
**
** The second parameter is the name of the SQL function to be created
** or redefined.
@@ -2228,30 +3290,90 @@ int sqlite3_reset(sqlite3_stmt *pStmt);
** arguments or differing perferred text encodings. SQLite will use
** the implementation most closely matches the way in which the
** SQL function is used.
+**
+** INVARIANTS:
+**
+** {F16103} The [sqlite3_create_function16()] interface behaves exactly
+** like [sqlite3_create_function()] in every way except that it
+** interprets the zFunctionName argument as
+** zero-terminated UTF-16 native byte order instead of as a
+** zero-terminated UTF-8.
+**
+** {F16106} A successful invocation of
+** the [sqlite3_create_function(D,X,N,E,...)] interface registers
+** or replaces callback functions in [database connection] D
+** used to implement the SQL function named X with N parameters
+** and having a perferred text encoding of E.
+**
+** {F16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)]
+** replaces the P, F, S, and L values from any prior calls with
+** the same D, X, N, and E values.
+**
+** {F16112} The [sqlite3_create_function(D,X,...)] interface fails with
+** a return code of [SQLITE_ERROR] if the SQL function name X is
+** longer than 255 bytes exclusive of the zero terminator.
+**
+** {F16118} Either F must be NULL and S and L are non-NULL or else F
+** is non-NULL and S and L are NULL, otherwise
+** [sqlite3_create_function(D,X,N,E,P,F,S,L)] returns [SQLITE_ERROR].
+**
+** {F16121} The [sqlite3_create_function(D,...)] interface fails with an
+** error code of [SQLITE_BUSY] if there exist [prepared statements]
+** associated with the [database connection] D.
+**
+** {F16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an
+** error code of [SQLITE_ERROR] if parameter N (specifying the number
+** of arguments to the SQL function being registered) is less
+** than -1 or greater than 127.
+**
+** {F16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)]
+** interface causes callbacks to be invoked for the SQL function
+** named X when the number of arguments to the SQL function is
+** exactly N.
+**
+** {F16130} When N is -1, the [sqlite3_create_function(D,X,N,...)]
+** interface causes callbacks to be invoked for the SQL function
+** named X with any number of arguments.
+**
+** {F16133} When calls to [sqlite3_create_function(D,X,N,...)]
+** specify multiple implementations of the same function X
+** and when one implementation has N>=0 and the other has N=(-1)
+** the implementation with a non-zero N is preferred.
+**
+** {F16136} When calls to [sqlite3_create_function(D,X,N,E,...)]
+** specify multiple implementations of the same function X with
+** the same number of arguments N but with different
+** encodings E, then the implementation where E matches the
+** database encoding is preferred.
+**
+** {F16139} For an aggregate SQL function created using
+** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finializer
+** function L will always be invoked exactly once if the
+** step function S is called one or more times.
*/
int sqlite3_create_function(
- sqlite3 *,
+ sqlite3 *db,
const char *zFunctionName,
int nArg,
int eTextRep,
- void*,
+ void *pApp,
void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
void (*xStep)(sqlite3_context*,int,sqlite3_value**),
void (*xFinal)(sqlite3_context*)
);
int sqlite3_create_function16(
- sqlite3*,
+ sqlite3 *db,
const void *zFunctionName,
int nArg,
int eTextRep,
- void*,
+ void *pApp,
void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
void (*xStep)(sqlite3_context*,int,sqlite3_value**),
void (*xFinal)(sqlite3_context*)
);
/*
-** CAPI3REF: Text Encodings
+** CAPI3REF: Text Encodings {F10267}
**
** These constant define integer codes that represent the various
** text encodings supported by SQLite.
@@ -2280,7 +3402,7 @@ void sqlite3_thread_cleanup(void);
int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
/*
-** CAPI3REF: Obtaining SQL Function Parameter Values
+** CAPI3REF: Obtaining SQL Function Parameter Values {F15100}
**
** The C-language implementation of SQL functions and aggregates uses
** this set of interface routines to access the parameter values on
@@ -2307,9 +3429,9 @@ int sqlite3_memory_alarm(void(*)(void*,s
** The sqlite3_value_numeric_type() interface attempts to apply
** numeric affinity to the value. This means that an attempt is
** made to convert the value to an integer or floating point. If
-** such a conversion is possible without loss of information (in order
-** words if the value is original a string that looks like a number)
-** then it is done. Otherwise no conversion occurs. The
+** such a conversion is possible without loss of information (in other
+** words if the value is a string that looks like a number)
+** then the conversion is done. Otherwise no conversion occurs. The
** [SQLITE_INTEGER | datatype] after conversion is returned.
**
** Please pay particular attention to the fact that the pointer that
@@ -2323,6 +3445,69 @@ int sqlite3_memory_alarm(void(*)(void*,s
** Or, if the sqlite3_value* argument comes from the [sqlite3_column_value()]
** interface, then these routines should be called from the same thread
** that ran [sqlite3_column_value()].
+**
+**
+** INVARIANTS:
+**
+** {F15103} The [sqlite3_value_blob(V)] interface converts the
+** [sqlite3_value] object V into a blob and then returns a
+** pointer to the converted value.
+**
+** {F15106} The [sqlite3_value_bytes(V)] interface returns the
+** number of bytes in the blob or string (exclusive of the
+** zero terminator on the string) that was returned by the
+** most recent call to [sqlite3_value_blob(V)] or
+** [sqlite3_value_text(V)].
+**
+** {F15109} The [sqlite3_value_bytes16(V)] interface returns the
+** number of bytes in the string (exclusive of the
+** zero terminator on the string) that was returned by the
+** most recent call to [sqlite3_value_text16(V)],
+** [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)].
+**
+** {F15112} The [sqlite3_value_double(V)] interface converts the
+** [sqlite3_value] object V into a floating point value and
+** returns a copy of that value.
+**
+** {F15115} The [sqlite3_value_int(V)] interface converts the
+** [sqlite3_value] object V into a 64-bit signed integer and
+** returns the lower 32 bits of that integer.
+**
+** {F15118} The [sqlite3_value_int64(V)] interface converts the
+** [sqlite3_value] object V into a 64-bit signed integer and
+** returns a copy of that integer.
+**
+** {F15121} The [sqlite3_value_text(V)] interface converts the
+** [sqlite3_value] object V into a zero-terminated UTF-8
+** string and returns a pointer to that string.
+**
+** {F15124} The [sqlite3_value_text16(V)] interface converts the
+** [sqlite3_value] object V into a zero-terminated 2-byte
+** aligned UTF-16 native byte order
+** string and returns a pointer to that string.
+**
+** {F15127} The [sqlite3_value_text16be(V)] interface converts the
+** [sqlite3_value] object V into a zero-terminated 2-byte
+** aligned UTF-16 big-endian
+** string and returns a pointer to that string.
+**
+** {F15130} The [sqlite3_value_text16le(V)] interface converts the
+** [sqlite3_value] object V into a zero-terminated 2-byte
+** aligned UTF-16 little-endian
+** string and returns a pointer to that string.
+**
+** {F15133} The [sqlite3_value_type(V)] interface returns
+** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
+** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
+** the [sqlite3_value] object V.
+**
+** {F15136} The [sqlite3_value_numeric_type(V)] interface converts
+** the [sqlite3_value] object V into either an integer or
+** a floating point value if it can do so without loss of
+** information, and returns one of [SQLITE_NULL],
+** [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or
+** [SQLITE_BLOB] as appropriate for
+** the [sqlite3_value] object V after the conversion attempt.
*/
const void *sqlite3_value_blob(sqlite3_value*);
int sqlite3_value_bytes(sqlite3_value*);
@@ -2338,16 +3523,19 @@ int sqlite3_value_type(sqlite3_value*);
int sqlite3_value_numeric_type(sqlite3_value*);
/*
-** CAPI3REF: Obtain Aggregate Function Context
+** CAPI3REF: Obtain Aggregate Function Context {F16210}
**
** The implementation of aggregate SQL functions use this routine to allocate
-** a structure for storing their state. The first time this routine
-** is called for a particular aggregate, a new structure of size nBytes
-** is allocated, zeroed, and returned. On subsequent calls (for the
-** same aggregate instance) the same buffer is returned. The implementation
+** a structure for storing their state.
+** The first time the sqlite3_aggregate_context() routine is
+** is called for a particular aggregate, SQLite allocates nBytes of memory
+** zeros that memory, and returns a pointer to it.
+** On second and subsequent calls to sqlite3_aggregate_context()
+** for the same aggregate function index, the same buffer is returned.
+** The implementation
** of the aggregate can use the returned buffer to accumulate data.
**
-** The buffer allocated is freed automatically by SQLite whan the aggregate
+** SQLite automatically frees the allocated buffer when the aggregate
** query concludes.
**
** The first parameter should be a copy of the
@@ -2357,24 +3545,54 @@ int sqlite3_value_numeric_type(sqlite3_v
**
** This routine must be called from the same thread in which
** the aggregate SQL function is running.
+**
+** INVARIANTS:
+**
+** {F16211} The first invocation of [sqlite3_aggregate_context(C,N)] for
+** a particular instance of an aggregate function (for a particular
+** context C) causes SQLite to allocation N bytes of memory,
+** zero that memory, and return a pointer to the allocationed
+** memory.
+**
+** {F16213} If a memory allocation error occurs during
+** [sqlite3_aggregate_context(C,N)] then the function returns 0.
+**
+** {F16215} Second and subsequent invocations of
+** [sqlite3_aggregate_context(C,N)] for the same context pointer C
+** ignore the N parameter and return a pointer to the same
+** block of memory returned by the first invocation.
+**
+** {F16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is
+** automatically freed on the next call to [sqlite3_reset()]
+** or [sqlite3_finalize()] for the [prepared statement] containing
+** the aggregate function associated with context C.
*/
void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
/*
-** CAPI3REF: User Data For Functions
+** CAPI3REF: User Data For Functions {F16240}
**
-** The pUserData parameter to the [sqlite3_create_function()]
-** and [sqlite3_create_function16()] routines
-** used to register user functions is available to
-** the implementation of the function using this call.
+** The sqlite3_user_data() interface returns a copy of
+** the pointer that was the pUserData parameter (the 5th parameter)
+** of the the [sqlite3_create_function()]
+** and [sqlite3_create_function16()] routines that originally
+** registered the application defined function. {END}
**
** This routine must be called from the same thread in which
-** the SQL function is running.
+** the application-defined function is running.
+**
+** INVARIANTS:
+**
+** {F16243} The [sqlite3_user_data(C)] interface returns a copy of the
+** P pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]
+** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that
+** registered the SQL function associated with
+** [sqlite3_context] C.
*/
void *sqlite3_user_data(sqlite3_context*);
/*
-** CAPI3REF: Function Auxiliary Data
+** CAPI3REF: Function Auxiliary Data {F16270}
**
** The following two functions may be used by scalar SQL functions to
** associate meta-data with argument values. If the same value is passed to
@@ -2388,16 +3606,27 @@ void *sqlite3_user_data(sqlite3_context*
** does not need to be recompiled on each invocation.
**
** The sqlite3_get_auxdata() interface returns a pointer to the meta-data
-** associated with the Nth argument value to the current SQL function
-** call, where N is the second parameter. If no meta-data has been set for
-** that value, then a NULL pointer is returned.
-**
-** The sqlite3_set_auxdata() is used to associate meta-data with an SQL
-** function argument. The third parameter is a pointer to the meta-data
-** to be associated with the Nth user function argument value. The fourth
-** parameter specifies a destructor that will be called on the meta-
-** data pointer to release it when it is no longer required. If the
-** destructor is NULL, it is not invoked.
+** associated by the sqlite3_set_auxdata() function with the Nth argument
+** value to the application-defined function.
+** If no meta-data has been ever been set for the Nth
+** argument of the function, or if the cooresponding function parameter
+** has changed since the meta-data was set, then sqlite3_get_auxdata()
+** returns a NULL pointer.
+**
+** The sqlite3_set_auxdata() interface saves the meta-data
+** pointed to by its 3rd parameter as the meta-data for the N-th
+** argument of the application-defined function. Subsequent
+** calls to sqlite3_get_auxdata() might return this data, if it has
+** not been destroyed.
+** If it is not NULL, SQLite will invoke the destructor
+** function given by the 4th parameter to sqlite3_set_auxdata() on
+** the meta-data when the corresponding function parameter changes
+** or when the SQL statement completes, whichever comes first.
+**
+** SQLite is free to call the destructor and drop meta-data on
+** any parameter of any function at any time. The only guarantee
+** is that the destructor will be called before the metadata is
+** dropped.
**
** In practice, meta-data is preserved between function calls for
** expressions that are constant at compile time. This includes literal
@@ -2405,13 +3634,40 @@ void *sqlite3_user_data(sqlite3_context*
**
** These routines must be called from the same thread in which
** the SQL function is running.
+**
+** INVARIANTS:
+**
+** {F16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer
+** to metadata associated with the Nth parameter of the SQL function
+** whose context is C, or NULL if there is no metadata associated
+** with that parameter.
+**
+** {F16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata
+** pointer P to the Nth parameter of the SQL function with context
+** C.
+**
+** {F16276} SQLite will invoke the destructor D with a single argument
+** which is the metadata pointer P following a call to
+** [sqlite3_set_auxdata(C,N,P,D)] when SQLite ceases to hold
+** the metadata.
+**
+** {F16277} SQLite ceases to hold metadata for an SQL function parameter
+** when the value of that parameter changes.
+**
+** {F16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor
+** is called for any prior metadata associated with the same function
+** context C and parameter N.
+**
+** {F16279} SQLite will call destructors for any metadata it is holding
+** in a particular [prepared statement] S when either
+** [sqlite3_reset(S)] or [sqlite3_finalize(S)] is called.
*/
-void *sqlite3_get_auxdata(sqlite3_context*, int);
-void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
+void *sqlite3_get_auxdata(sqlite3_context*, int N);
+void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
/*
-** CAPI3REF: Constants Defining Special Destructor Behavior
+** CAPI3REF: Constants Defining Special Destructor Behavior {F10280}
**
** These are special value for the destructor that is passed in as the
** final argument to routines like [sqlite3_result_blob()]. If the destructor
@@ -2429,7 +3685,7 @@ typedef void (*sqlite3_destructor_type)(
#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
/*
-** CAPI3REF: Setting The Result Of An SQL Function
+** CAPI3REF: Setting The Result Of An SQL Function {F16400}
**
** These routines are used by the xFunc or xFinal callbacks that
** implement SQL functions and aggregates. See
@@ -2443,17 +3699,188 @@ typedef void (*sqlite3_destructor_type)(
** [sqlite3_bind_blob | sqlite3_bind_* documentation] for
** additional information.
**
-** The sqlite3_result_error() and sqlite3_result_error16() functions
-** cause the implemented SQL function to throw an exception. The
-** parameter to sqlite3_result_error() or sqlite3_result_error16()
-** is the text of an error message.
-**
-** The sqlite3_result_toobig() cause the function implementation
-** to throw and error indicating that a string or BLOB is to long
-** to represent.
+** The sqlite3_result_blob() interface sets the result from
+** an application defined function to be the BLOB whose content is pointed
+** to by the second parameter and which is N bytes long where N is the
+** third parameter.
+** The sqlite3_result_zeroblob() inerfaces set the result of
+** the application defined function to be a BLOB containing all zero
+** bytes and N bytes in size, where N is the value of the 2nd parameter.
+**
+** The sqlite3_result_double() interface sets the result from
+** an application defined function to be a floating point value specified
+** by its 2nd argument.
**
-** These routines must be called from within the same thread as
-** the SQL function associated with the [sqlite3_context] pointer.
+** The sqlite3_result_error() and sqlite3_result_error16() functions
+** cause the implemented SQL function to throw an exception.
+** SQLite uses the string pointed to by the
+** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
+** as the text of an error message. SQLite interprets the error
+** message string from sqlite3_result_error() as UTF8. SQLite
+** interprets the string from sqlite3_result_error16() as UTF16 in native
+** byte order. If the third parameter to sqlite3_result_error()
+** or sqlite3_result_error16() is negative then SQLite takes as the error
+** message all text up through the first zero character.
+** If the third parameter to sqlite3_result_error() or
+** sqlite3_result_error16() is non-negative then SQLite takes that many
+** bytes (not characters) from the 2nd parameter as the error message.
+** The sqlite3_result_error() and sqlite3_result_error16()
+** routines make a copy private copy of the error message text before
+** they return. Hence, the calling function can deallocate or
+** modify the text after they return without harm.
+** The sqlite3_result_error_code() function changes the error code
+** returned by SQLite as a result of an error in a function. By default,
+** the error code is SQLITE_ERROR.
+**
+** The sqlite3_result_toobig() interface causes SQLite
+** to throw an error indicating that a string or BLOB is to long
+** to represent. The sqlite3_result_nomem() interface
+** causes SQLite to throw an exception indicating that the a
+** memory allocation failed.
+**
+** The sqlite3_result_int() interface sets the return value
+** of the application-defined function to be the 32-bit signed integer
+** value given in the 2nd argument.
+** The sqlite3_result_int64() interface sets the return value
+** of the application-defined function to be the 64-bit signed integer
+** value given in the 2nd argument.
+**
+** The sqlite3_result_null() interface sets the return value
+** of the application-defined function to be NULL.
+**
+** The sqlite3_result_text(), sqlite3_result_text16(),
+** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
+** set the return value of the application-defined function to be
+** a text string which is represented as UTF-8, UTF-16 native byte order,
+** UTF-16 little endian, or UTF-16 big endian, respectively.
+** SQLite takes the text result from the application from
+** the 2nd parameter of the sqlite3_result_text* interfaces.
+** If the 3rd parameter to the sqlite3_result_text* interfaces
+** is negative, then SQLite takes result text from the 2nd parameter
+** through the first zero character.
+** If the 3rd parameter to the sqlite3_result_text* interfaces
+** is non-negative, then as many bytes (not characters) of the text
+** pointed to by the 2nd parameter are taken as the application-defined
+** function result.
+** If the 4th parameter to the sqlite3_result_text* interfaces
+** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
+** function as the destructor on the text or blob result when it has
+** finished using that result.
+** If the 4th parameter to the sqlite3_result_text* interfaces
+** or sqlite3_result_blob is the special constant SQLITE_STATIC, then
+** SQLite assumes that the text or blob result is constant space and
+** does not copy the space or call a destructor when it has
+** finished using that result.
+** If the 4th parameter to the sqlite3_result_text* interfaces
+** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
+** then SQLite makes a copy of the result into space obtained from
+** from [sqlite3_malloc()] before it returns.
+**
+** The sqlite3_result_value() interface sets the result of
+** the application-defined function to be a copy the [sqlite3_value]
+** object specified by the 2nd parameter. The
+** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
+** so that [sqlite3_value] specified in the parameter may change or
+** be deallocated after sqlite3_result_value() returns without harm.
+**
+** If these routines are called from within the different thread
+** than the one containing the application-defined function that recieved
+** the [sqlite3_context] pointer, the results are undefined.
+**
+** INVARIANTS:
+**
+** {F16403} The default return value from any SQL function is NULL.
+**
+** {F16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the
+** return value of function C to be a blob that is N bytes
+** in length and with content pointed to by V.
+**
+** {F16409} The [sqlite3_result_double(C,V)] interface changes the
+** return value of function C to be the floating point value V.
+**
+** {F16412} The [sqlite3_result_error(C,V,N)] interface changes the return
+** value of function C to be an exception with error code
+** [SQLITE_ERROR] and a UTF8 error message copied from V up to the
+** first zero byte or until N bytes are read if N is positive.
+**
+** {F16415} The [sqlite3_result_error16(C,V,N)] interface changes the return
+** value of function C to be an exception with error code
+** [SQLITE_ERROR] and a UTF16 native byte order error message
+** copied from V up to the first zero terminator or until N bytes
+** are read if N is positive.
+**
+** {F16418} The [sqlite3_result_error_toobig(C)] interface changes the return
+** value of the function C to be an exception with error code
+** [SQLITE_TOOBIG] and an appropriate error message.
+**
+** {F16421} The [sqlite3_result_error_nomem(C)] interface changes the return
+** value of the function C to be an exception with error code
+** [SQLITE_NOMEM] and an appropriate error message.
+**
+** {F16424} The [sqlite3_result_error_code(C,E)] interface changes the return
+** value of the function C to be an exception with error code E.
+** The error message text is unchanged.
+**
+** {F16427} The [sqlite3_result_int(C,V)] interface changes the
+** return value of function C to be the 32-bit integer value V.
+**
+** {F16430} The [sqlite3_result_int64(C,V)] interface changes the
+** return value of function C to be the 64-bit integer value V.
+**
+** {F16433} The [sqlite3_result_null(C)] interface changes the
+** return value of function C to be NULL.
+**
+** {F16436} The [sqlite3_result_text(C,V,N,D)] interface changes the
+** return value of function C to be the UTF8 string
+** V up through the first zero or until N bytes are read if N
+** is positive.
+**
+** {F16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the
+** return value of function C to be the UTF16 native byte order
+** string V up through the first zero or until N bytes are read if N
+** is positive.
+**
+** {F16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the
+** return value of function C to be the UTF16 big-endian
+** string V up through the first zero or until N bytes are read if N
+** is positive.
+**
+** {F16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the
+** return value of function C to be the UTF16 little-endian
+** string V up through the first zero or until N bytes are read if N
+** is positive.
+**
+** {F16448} The [sqlite3_result_value(C,V)] interface changes the
+** return value of function C to be [sqlite3_value] object V.
+**
+** {F16451} The [sqlite3_result_zeroblob(C,N)] interface changes the
+** return value of function C to be an N-byte blob of all zeros.
+**
+** {F16454} The [sqlite3_result_error()] and [sqlite3_result_error16()]
+** interfaces make a copy of their error message strings before
+** returning.
+**
+** {F16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
+** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
+** [sqlite3_result_text16be(C,V,N,D)], or
+** [sqlite3_result_text16le(C,V,N,D)] is the constant [SQLITE_STATIC]
+** then no destructor is ever called on the pointer V and SQLite
+** assumes that V is immutable.
+**
+** {F16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
+** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
+** [sqlite3_result_text16be(C,V,N,D)], or
+** [sqlite3_result_text16le(C,V,N,D)] is the constant
+** [SQLITE_TRANSIENT] then the interfaces makes a copy of the
+** content of V and retains the copy.
+**
+** {F16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
+** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
+** [sqlite3_result_text16be(C,V,N,D)], or
+** [sqlite3_result_text16le(C,V,N,D)] is some value other than
+** the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then
+** SQLite will invoke the destructor D with V as its only argument
+** when it has finished with the V value.
*/
void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_double(sqlite3_context*, double);
@@ -2461,6 +3888,7 @@ void sqlite3_result_error(sqlite3_contex
void sqlite3_result_error16(sqlite3_context*, const void*, int);
void sqlite3_result_error_toobig(sqlite3_context*);
void sqlite3_result_error_nomem(sqlite3_context*);
+void sqlite3_result_error_code(sqlite3_context*, int);
void sqlite3_result_int(sqlite3_context*, int);
void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
void sqlite3_result_null(sqlite3_context*);
@@ -2472,35 +3900,37 @@ void sqlite3_result_value(sqlite3_contex
void sqlite3_result_zeroblob(sqlite3_context*, int n);
/*
-** CAPI3REF: Define New Collating Sequences
+** CAPI3REF: Define New Collating Sequences {F16600}
**
** These functions are used to add new collation sequences to the
** [sqlite3*] handle specified as the first argument.
**
** The name of the new collation sequence is specified as a UTF-8 string
** for sqlite3_create_collation() and sqlite3_create_collation_v2()
-** and a UTF-16 string for sqlite3_create_collation16(). In all cases
+** and a UTF-16 string for sqlite3_create_collation16(). In all cases
** the name is passed as the second function argument.
**
** The third argument may be one of the constants [SQLITE_UTF8],
** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied
** routine expects to be passed pointers to strings encoded using UTF-8,
-** UTF-16 little-endian or UTF-16 big-endian respectively. The
+** UTF-16 little-endian or UTF-16 big-endian respectively. The
** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that
** the routine expects pointers to 16-bit word aligned strings
** of UTF16 in the native byte order of the host computer.
**
** A pointer to the user supplied routine must be passed as the fifth
-** argument. If it is NULL, this is the same as deleting the collation
-** sequence (so that SQLite cannot call it anymore). Each time the user
+** argument. If it is NULL, this is the same as deleting the collation
+** sequence (so that SQLite cannot call it anymore).
+** Each time the application
** supplied function is invoked, it is passed a copy of the void* passed as
** the fourth argument to sqlite3_create_collation() or
** sqlite3_create_collation16() as its first parameter.
**
-** The remaining arguments to the user-supplied routine are two strings,
-** each represented by a [length, data] pair and encoded in the encoding
+** The remaining arguments to the application-supplied routine are two strings,
+** each represented by a (length, data) pair and encoded in the encoding
** that was passed as the third argument when the collation sequence was
-** registered. The user routine should return negative, zero or positive if
+** registered. {END} The application defined collation routine should
+** return negative, zero or positive if
** the first string is less than, equal to, or greater than the second
** string. i.e. (STRING1 - STRING2).
**
@@ -2508,13 +3938,59 @@ void sqlite3_result_zeroblob(sqlite3_con
** excapt that it takes an extra argument which is a destructor for
** the collation. The destructor is called when the collation is
** destroyed and is passed a copy of the fourth parameter void* pointer
-** of the sqlite3_create_collation_v2(). Collations are destroyed when
+** of the sqlite3_create_collation_v2().
+** Collations are destroyed when
** they are overridden by later calls to the collation creation functions
** or when the [sqlite3*] database handle is closed using [sqlite3_close()].
**
-** The sqlite3_create_collation_v2() interface is experimental and
-** subject to change in future releases. The other collation creation
-** functions are stable.
+** INVARIANTS:
+**
+** {F16603} A successful call to the
+** [sqlite3_create_collation_v2(B,X,E,P,F,D)] interface
+** registers function F as the comparison function used to
+** implement collation X on [database connection] B for
+** databases having encoding E.
+**
+** {F16604} SQLite understands the X parameter to
+** [sqlite3_create_collation_v2(B,X,E,P,F,D)] as a zero-terminated
+** UTF-8 string in which case is ignored for ASCII characters and
+** is significant for non-ASCII characters.
+**
+** {F16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)]
+** with the same values for B, X, and E, override prior values
+** of P, F, and D.
+**
+** {F16609} The destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
+** is not NULL then it is called with argument P when the
+** collating function is dropped by SQLite.
+**
+** {F16612} A collating function is dropped when it is overloaded.
+**
+** {F16615} A collating function is dropped when the database connection
+** is closed using [sqlite3_close()].
+**
+** {F16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
+** is passed through as the first parameter to the comparison
+** function F for all subsequent invocations of F.
+**
+** {F16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly
+** the same as a call to [sqlite3_create_collation_v2()] with
+** the same parameters and a NULL destructor.
+**
+** {F16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)],
+** SQLite uses the comparison function F for all text comparison
+** operations on [database connection] B on text values that
+** use the collating sequence name X.
+**
+** {F16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same
+** as [sqlite3_create_collation(B,X,E,P,F)] except that the
+** collation name X is understood as UTF-16 in native byte order
+** instead of UTF-8.
+**
+** {F16630} When multiple comparison functions are available for the same
+** collating sequence, SQLite chooses the one whose text encoding
+** requires the least amount of conversion from the default
+** text encoding of the database.
*/
int sqlite3_create_collation(
sqlite3*,
@@ -2540,7 +4016,7 @@ int sqlite3_create_collation16(
);
/*
-** CAPI3REF: Collation Needed Callbacks
+** CAPI3REF: Collation Needed Callbacks {F16700}
**
** To avoid having to register all collation sequences before a database
** can be used, a single callback function may be registered with the
@@ -2549,21 +4025,43 @@ int sqlite3_create_collation16(
**
** If the function is registered using the sqlite3_collation_needed() API,
** then it is passed the names of undefined collation sequences as strings
-** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names
+** encoded in UTF-8. {F16703} If sqlite3_collation_needed16() is used, the names
** are passed as UTF-16 in machine native byte order. A call to either
** function replaces any existing callback.
**
** When the callback is invoked, the first argument passed is a copy
** of the second argument to sqlite3_collation_needed() or
-** sqlite3_collation_needed16(). The second argument is the database
-** handle. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], or
-** [SQLITE_UTF16LE], indicating the most desirable form of the collation
-** sequence function required. The fourth parameter is the name of the
+** sqlite3_collation_needed16(). The second argument is the database
+** handle. The third argument is one of [SQLITE_UTF8],
+** [SQLITE_UTF16BE], or [SQLITE_UTF16LE], indicating the most
+** desirable form of the collation sequence function required.
+** The fourth parameter is the name of the
** required collation sequence.
**
** The callback function should register the desired collation using
** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
** [sqlite3_create_collation_v2()].
+**
+** INVARIANTS:
+**
+** {F16702} A successful call to [sqlite3_collation_needed(D,P,F)]
+** or [sqlite3_collation_needed16(D,P,F)] causes
+** the [database connection] D to invoke callback F with first
+** parameter P whenever it needs a comparison function for a
+** collating sequence that it does not know about.
+**
+** {F16704} Each successful call to [sqlite3_collation_needed()] or
+** [sqlite3_collation_needed16()] overrides the callback registered
+** on the same [database connection] by prior calls to either
+** interface.
+**
+** {F16706} The name of the requested collating function passed in the
+** 4th parameter to the callback is in UTF-8 if the callback
+** was registered using [sqlite3_collation_needed()] and
+** is in UTF-16 native byte order if the callback was
+** registered using [sqlite3_collation_needed16()].
+**
+**
*/
int sqlite3_collation_needed(
sqlite3*,
@@ -2602,10 +4100,11 @@ int sqlite3_rekey(
);
/*
-** CAPI3REF: Suspend Execution For A Short Time
+** CAPI3REF: Suspend Execution For A Short Time {F10530}
**
-** This function causes the current thread to suspend execution
-** a number of milliseconds specified in its parameter.
+** The sqlite3_sleep() function
+** causes the current thread to suspend execution
+** for at least a number of milliseconds specified in its parameter.
**
** If the operating system does not support sleep requests with
** millisecond time resolution, then the time will be rounded up to
@@ -2614,11 +4113,22 @@ int sqlite3_rekey(
**
** SQLite implements this interface by calling the xSleep()
** method of the default [sqlite3_vfs] object.
+**
+** INVARIANTS:
+**
+** {F10533} The [sqlite3_sleep(M)] interface invokes the xSleep
+** method of the default [sqlite3_vfs|VFS] in order to
+** suspend execution of the current thread for at least
+** M milliseconds.
+**
+** {F10536} The [sqlite3_sleep(M)] interface returns the number of
+** milliseconds of sleep actually requested of the operating
+** system, which might be larger than the parameter M.
*/
int sqlite3_sleep(int);
/*
-** CAPI3REF: Name Of The Folder Holding Temporary Files
+** CAPI3REF: Name Of The Folder Holding Temporary Files {F10310}
**
** If this global variable is made to point to a string which is
** the name of a folder (a.ka. directory), then all temporary files
@@ -2634,12 +4144,13 @@ int sqlite3_sleep(int);
SQLITE_EXTERN char *sqlite3_temp_directory;
/*
-** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode
+** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode {F12930}
**
-** Test to see whether or not the database connection is in autocommit
-** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on
-** by default. Autocommit is disabled by a BEGIN statement and reenabled
-** by the next COMMIT or ROLLBACK.
+** The sqlite3_get_autocommit() interfaces returns non-zero or
+** zero if the given database connection is or is not in autocommit mode,
+** respectively. Autocommit mode is on
+** by default. Autocommit mode is disabled by a [BEGIN] statement.
+** Autocommit mode is reenabled by a [COMMIT] or [ROLLBACK].
**
** If certain kinds of errors occur on a statement within a multi-statement
** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR],
@@ -2648,72 +4159,179 @@ SQLITE_EXTERN char *sqlite3_temp_directo
** find out if SQLite automatically rolled back the transaction after
** an error is to use this function.
**
-** If another thread changes the autocommit status of the database
-** connection while this routine is running, then the return value
-** is undefined.
+** INVARIANTS:
+**
+** {F12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or
+** zero if the [database connection] D is or is not in autocommit
+** mode, respectively.
+**
+** {F12932} Autocommit mode is on by default.
+**
+** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement.
+**
+** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK]
+** statement.
+**
+**
+** LIMITATIONS:
+***
+** {U12936} If another thread changes the autocommit status of the database
+** connection while this routine is running, then the return value
+** is undefined.
*/
int sqlite3_get_autocommit(sqlite3*);
/*
-** CAPI3REF: Find The Database Handle Associated With A Prepared Statement
+** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120}
**
-** Return the [sqlite3*] database handle to which a
-** [sqlite3_stmt | prepared statement] belongs.
-** This is the same database handle that was
+** The sqlite3_db_handle interface
+** returns the [sqlite3*] database handle to which a
+** [prepared statement] belongs.
+** The database handle returned by sqlite3_db_handle
+** is the same database handle that was
** the first argument to the [sqlite3_prepare_v2()] or its variants
** that was used to create the statement in the first place.
+**
+** INVARIANTS:
+**
+** {F13123} The [sqlite3_db_handle(S)] interface returns a pointer
+** to the [database connection] associated with
+** [prepared statement] S.
*/
sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
/*
-** CAPI3REF: Commit And Rollback Notification Callbacks
+** CAPI3REF: Commit And Rollback Notification Callbacks {F12950}
**
-** These routines
-** register callback functions to be invoked whenever a transaction
-** is committed or rolled back. The pArg argument is passed through
+** The sqlite3_commit_hook() interface registers a callback
+** function to be invoked whenever a transaction is committed.
+** Any callback set by a previous call to sqlite3_commit_hook()
+** for the same database connection is overridden.
+** The sqlite3_rollback_hook() interface registers a callback
+** function to be invoked whenever a transaction is committed.
+** Any callback set by a previous call to sqlite3_commit_hook()
+** for the same database connection is overridden.
+** The pArg argument is passed through
** to the callback. If the callback on a commit hook function
** returns non-zero, then the commit is converted into a rollback.
**
-** If another function was previously registered, its pArg value is returned.
-** Otherwise NULL is returned.
+** If another function was previously registered, its
+** pArg value is returned. Otherwise NULL is returned.
**
** Registering a NULL function disables the callback.
**
** For the purposes of this API, a transaction is said to have been
** rolled back if an explicit "ROLLBACK" statement is executed, or
-** an error or constraint causes an implicit rollback to occur. The
-** callback is not invoked if a transaction is automatically rolled
-** back because the database connection is closed.
+** an error or constraint causes an implicit rollback to occur.
+** The rollback callback is not invoked if a transaction is
+** automatically rolled back because the database connection is closed.
+** The rollback callback is not invoked if a transaction is
+** rolled back because a commit callback returned non-zero.
+** Check on this
**
** These are experimental interfaces and are subject to change.
+**
+** INVARIANTS:
+**
+** {F12951} The [sqlite3_commit_hook(D,F,P)] interface registers the
+** callback function F to be invoked with argument P whenever
+** a transaction commits on [database connection] D.
+**
+** {F12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P
+** argument from the previous call with the same
+** [database connection ] D , or NULL on the first call
+** for a particular [database connection] D.
+**
+** {F12953} Each call to [sqlite3_commit_hook()] overwrites the callback
+** registered by prior calls.
+**
+** {F12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL
+** then the commit hook callback is cancelled and no callback
+** is invoked when a transaction commits.
+**
+** {F12955} If the commit callback returns non-zero then the commit is
+** converted into a rollback.
+**
+** {F12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the
+** callback function F to be invoked with argument P whenever
+** a transaction rolls back on [database connection] D.
+**
+** {F12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P
+** argument from the previous call with the same
+** [database connection ] D , or NULL on the first call
+** for a particular [database connection] D.
+**
+** {F12963} Each call to [sqlite3_rollback_hook()] overwrites the callback
+** registered by prior calls.
+**
+** {F12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL
+** then the rollback hook callback is cancelled and no callback
+** is invoked when a transaction rolls back.
*/
void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
/*
-** CAPI3REF: Data Change Notification Callbacks
+** CAPI3REF: Data Change Notification Callbacks {F12970}
**
-** Register a callback function with the database connection identified by the
+** The sqlite3_update_hook() interface
+** registers a callback function with the database connection identified by the
** first argument to be invoked whenever a row is updated, inserted or deleted.
** Any callback set by a previous call to this function for the same
** database connection is overridden.
**
** The second argument is a pointer to the function to invoke when a
-** row is updated, inserted or deleted. The first argument to the callback is
-** a copy of the third argument to sqlite3_update_hook(). The second callback
-** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending
-** on the operation that caused the callback to be invoked. The third and
+** row is updated, inserted or deleted.
+** The first argument to the callback is
+** a copy of the third argument to sqlite3_update_hook().
+** The second callback
+** argument is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
+** depending on the operation that caused the callback to be invoked.
+** The third and
** fourth arguments to the callback contain pointers to the database and
-** table name containing the affected row. The final callback parameter is
-** the rowid of the row. In the case of an update, this is the rowid after
+** table name containing the affected row.
+** The final callback parameter is
+** the rowid of the row.
+** In the case of an update, this is the rowid after
** the update takes place.
**
** The update hook is not invoked when internal system tables are
** modified (i.e. sqlite_master and sqlite_sequence).
**
-** If another function was previously registered, its pArg value is returned.
-** Otherwise NULL is returned.
+** If another function was previously registered, its pArg value
+** is returned. Otherwise NULL is returned.
+**
+** INVARIANTS:
+**
+** {F12971} The [sqlite3_update_hook(D,F,P)] interface causes callback
+** function F to be invoked with first parameter P whenever
+** a table row is modified, inserted, or deleted on
+** [database connection] D.
+**
+** {F12973} The [sqlite3_update_hook(D,F,P)] interface returns the value
+** of P for the previous call on the same [database connection] D,
+** or NULL for the first call.
+**
+** {F12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)]
+** is NULL then the no update callbacks are made.
+**
+** {F12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls
+** to the same interface on the same [database connection] D.
+**
+** {F12979} The update hook callback is not invoked when internal system
+** tables such as sqlite_master and sqlite_sequence are modified.
+**
+** {F12981} The second parameter to the update callback
+** is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
+** depending on the operation that caused the callback to be invoked.
+**
+** {F12983} The third and fourth arguments to the callback contain pointers
+** to zero-terminated UTF-8 strings which are the names of the
+** database and table that is being updated.
+
+** {F12985} The final callback parameter is the rowid of the row after
+** the change occurs.
*/
void *sqlite3_update_hook(
sqlite3*,
@@ -2722,55 +4340,86 @@ void *sqlite3_update_hook(
);
/*
-** CAPI3REF: Enable Or Disable Shared Pager Cache
+** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330}
**
** This routine enables or disables the sharing of the database cache
** and schema data structures between connections to the same database.
** Sharing is enabled if the argument is true and disabled if the argument
** is false.
**
-** Beginning in SQLite version 3.5.0, cache sharing is enabled and disabled
-** for an entire process. In prior versions of SQLite, sharing was
+** Cache sharing is enabled and disabled
+** for an entire process. {END} This is a change as of SQLite version 3.5.0.
+** In prior versions of SQLite, sharing was
** enabled or disabled for each thread separately.
**
** The cache sharing mode set by this interface effects all subsequent
** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
-** Existing database connections continue use the sharing mode that was
-** in effect at the time they were opened.
+** Existing database connections continue use the sharing mode
+** that was in effect at the time they were opened.
**
-** Virtual tables cannot be used with a shared cache. When shared
+** Virtual tables cannot be used with a shared cache. When shared
** cache is enabled, the [sqlite3_create_module()] API used to register
** virtual tables will always return an error.
**
** This routine returns [SQLITE_OK] if shared cache was
-** enabled or disabled successfully. An [SQLITE_ERROR | error code]
+** enabled or disabled successfully. An [error code]
** is returned otherwise.
**
-** Shared cache is disabled by default. But this might change in
+** Shared cache is disabled by default. But this might change in
** future releases of SQLite. Applications that care about shared
** cache setting should set it explicitly.
+**
+** INVARIANTS:
+**
+** {F10331} A successful invocation of [sqlite3_enable_shared_cache(B)]
+** will enable or disable shared cache mode for any subsequently
+** created [database connection] in the same process.
+**
+** {F10336} When shared cache is enabled, the [sqlite3_create_module()]
+** interface will always return an error.
+**
+** {F10337} The [sqlite3_enable_shared_cache(B)] interface returns
+** [SQLITE_OK] if shared cache was enabled or disabled successfully.
+**
+** {F10339} Shared cache is disabled by default.
*/
int sqlite3_enable_shared_cache(int);
/*
-** CAPI3REF: Attempt To Free Heap Memory
+** CAPI3REF: Attempt To Free Heap Memory {F17340}
**
-** Attempt to free N bytes of heap memory by deallocating non-essential
-** memory allocations held by the database library (example: memory
-** used to cache database pages to improve performance).
+** The sqlite3_release_memory() interface attempts to
+** free N bytes of heap memory by deallocating non-essential memory
+** allocations held by the database labrary. {END} Memory used
+** to cache database pages to improve performance is an example of
+** non-essential memory. Sqlite3_release_memory() returns
+** the number of bytes actually freed, which might be more or less
+** than the amount requested.
+**
+** INVARIANTS:
+**
+** {F17341} The [sqlite3_release_memory(N)] interface attempts to
+** free N bytes of heap memory by deallocating non-essential
+** memory allocations held by the database labrary.
+**
+** {F16342} The [sqlite3_release_memory(N)] returns the number
+** of bytes actually freed, which might be more or less
+** than the amount requested.
*/
int sqlite3_release_memory(int);
/*
-** CAPI3REF: Impose A Limit On Heap Size
+** CAPI3REF: Impose A Limit On Heap Size {F17350}
**
-** Place a "soft" limit on the amount of heap memory that may be allocated
-** by SQLite. If an internal allocation is requested
-** that would exceed the specified limit, [sqlite3_release_memory()] is
+** The sqlite3_soft_heap_limit() interface
+** places a "soft" limit on the amount of heap memory that may be allocated
+** by SQLite. If an internal allocation is requested
+** that would exceed the soft heap limit, [sqlite3_release_memory()] is
** invoked one or more times to free up some space before the allocation
** is made.
**
-** The limit is called "soft", because if [sqlite3_release_memory()] cannot
+** The limit is called "soft", because if
+** [sqlite3_release_memory()] cannot
** free sufficient memory to prevent the limit from being exceeded,
** the memory is allocated anyway and the current operation proceeds.
**
@@ -2778,23 +4427,51 @@ int sqlite3_release_memory(int);
** [sqlite3_release_memory()] will only be called when memory is exhausted.
** The default value for the soft heap limit is zero.
**
-** SQLite makes a best effort to honor the soft heap limit. But if it
-** is unable to reduce memory usage below the soft limit, execution will
+** SQLite makes a best effort to honor the soft heap limit.
+** But if the soft heap limit cannot honored, execution will
** continue without error or notification. This is why the limit is
** called a "soft" limit. It is advisory only.
**
** Prior to SQLite version 3.5.0, this routine only constrained the memory
** allocated by a single thread - the same thread in which this routine
** runs. Beginning with SQLite version 3.5.0, the soft heap limit is
-** applied to all threads. The value specified for the soft heap limit
-** is an upper bound on the total memory allocation for all threads. In
+** applied to all threads. The value specified for the soft heap limit
+** is an upper bound on the total memory allocation for all threads. In
** version 3.5.0 there is no mechanism for limiting the heap usage for
** individual threads.
+**
+** INVARIANTS:
+**
+** {F16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit
+** of N bytes on the amount of heap memory that may be allocated
+** using [sqlite3_malloc()] or [sqlite3_realloc()] at any point
+** in time.
+**
+** {F16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would
+** cause the total amount of allocated memory to exceed the
+** soft heap limit, then [sqlite3_release_memory()] is invoked
+** in an attempt to reduce the memory usage prior to proceeding
+** with the memory allocation attempt.
+**
+** {F16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger
+** attempts to reduce memory usage through the soft heap limit
+** mechanism continue even if the attempt to reduce memory
+** usage is unsuccessful.
+**
+** {F16354} A negative or zero value for N in a call to
+** [sqlite3_soft_heap_limit(N)] means that there is no soft
+** heap limit and [sqlite3_release_memory()] will only be
+** called when memory is completely exhausted.
+**
+** {F16355} The default value for the soft heap limit is zero.
+**
+** {F16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the
+** values set by all prior calls.
*/
void sqlite3_soft_heap_limit(int);
/*
-** CAPI3REF: Extract Metadata About A Column Of A Table
+** CAPI3REF: Extract Metadata About A Column Of A Table {F12850}
**
** This routine
** returns meta-data about a specific column of a specific database
@@ -2870,18 +4547,25 @@ int sqlite3_table_column_metadata(
);
/*
-** CAPI3REF: Load An Extension
-**
-** Attempt to load an SQLite extension library contained in the file
-** zFile. The entry point is zProc. zProc may be 0 in which case the
-** name of the entry point defaults to "sqlite3_extension_init".
+** CAPI3REF: Load An Extension {F12600}
**
-** Return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
-**
-** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with
-** error message text. The calling function should free this memory
+** {F12601} The sqlite3_load_extension() interface
+** attempts to load an SQLite extension library contained in the file
+** zFile. {F12602} The entry point is zProc. {F12603} zProc may be 0
+** in which case the name of the entry point defaults
+** to "sqlite3_extension_init".
+**
+** {F12604} The sqlite3_load_extension() interface shall
+** return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
+**
+** {F12605}
+** If an error occurs and pzErrMsg is not 0, then the
+** sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with
+** error message text stored in memory obtained from [sqlite3_malloc()].
+** {END} The calling function should free this memory
** by calling [sqlite3_free()].
**
+** {F12606}
** Extension loading must be enabled using [sqlite3_enable_load_extension()]
** prior to calling this API or an error will be returned.
*/
@@ -2893,40 +4577,42 @@ int sqlite3_load_extension(
);
/*
-** CAPI3REF: Enable Or Disable Extension Loading
+** CAPI3REF: Enable Or Disable Extension Loading {F12620}
**
** So as not to open security holes in older applications that are
** unprepared to deal with extension loading, and as a means of disabling
** extension loading while evaluating user-entered SQL, the following
** API is provided to turn the [sqlite3_load_extension()] mechanism on and
-** off. It is off by default. See ticket #1863.
+** off. {F12622} It is off by default. {END} See ticket #1863.
**
-** Call this routine with onoff==1 to turn extension loading on
-** and call it with onoff==0 to turn it back off again.
+** {F12621} Call the sqlite3_enable_load_extension() routine
+** with onoff==1 to turn extension loading on
+** and call it with onoff==0 to turn it back off again. {END}
*/
int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
/*
-** CAPI3REF: Make Arrangements To Automatically Load An Extension
+** CAPI3REF: Make Arrangements To Automatically Load An Extension {F12640}
**
-** Register an extension entry point that is automatically invoked
+** {F12641} This function
+** registers an extension entry point that is automatically invoked
** whenever a new database connection is opened using
-** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()].
+** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()]. {END}
**
** This API can be invoked at program startup in order to register
** one or more statically linked extensions that will be available
** to all new database connections.
**
-** Duplicate extensions are detected so calling this routine multiple
+** {F12642} Duplicate extensions are detected so calling this routine multiple
** times with the same extension is harmless.
**
-** This routine stores a pointer to the extension in an array
-** that is obtained from malloc(). If you run a memory leak
+** {F12643} This routine stores a pointer to the extension in an array
+** that is obtained from sqlite_malloc(). {END} If you run a memory leak
** checker on your program and it reports a leak because of this
-** array, then invoke [sqlite3_automatic_extension_reset()] prior
+** array, then invoke [sqlite3_reset_auto_extension()] prior
** to shutdown to free the memory.
**
-** Automatic extensions apply across all threads.
+** {F12644} Automatic extensions apply across all threads. {END}
**
** This interface is experimental and is subject to change or
** removal in future releases of SQLite.
@@ -2935,13 +4621,14 @@ int sqlite3_auto_extension(void *xEntryP
/*
-** CAPI3REF: Reset Automatic Extension Loading
+** CAPI3REF: Reset Automatic Extension Loading {F12660}
**
-** Disable all previously registered automatic extensions. This
-** routine undoes the effect of all prior [sqlite3_automatic_extension()]
+** {F12661} This function disables all previously registered
+** automatic extensions. {END} This
+** routine undoes the effect of all prior [sqlite3_auto_extension()]
** calls.
**
-** This call disabled automatic extensions in all threads.
+** {F12662} This call disabled automatic extensions in all threads. {END}
**
** This interface is experimental and is subject to change or
** removal in future releases of SQLite.
@@ -2969,6 +4656,9 @@ typedef struct sqlite3_vtab_cursor sqlit
typedef struct sqlite3_module sqlite3_module;
/*
+** CAPI3REF: Virtual Table Object {F18000}
+** KEYWORDS: sqlite3_module
+**
** A module is a class of virtual tables. Each module is defined
** by an instance of the following structure. This structure consists
** mostly of methods for the module.
@@ -3005,6 +4695,9 @@ struct sqlite3_module {
};
/*
+** CAPI3REF: Virtual Table Indexing Information {F18100}
+** KEYWORDS: sqlite3_index_info
+**
** The sqlite3_index_info structure and its substructures is used to
** pass information into and receive the reply from the xBestIndex
** method of an sqlite3_module. The fields under **Inputs** are the
@@ -3016,7 +4709,8 @@ struct sqlite3_module {
**
** column OP expr
**
-** Where OP is =, <, <=, >, or >=. The particular operator is stored
+** Where OP is =, <, <=, >, or >=.
+** The particular operator is stored
** in aConstraint[].op. The index of the column is stored in
** aConstraint[].iColumn. aConstraint[].usable is TRUE if the
** expr on the right-hand side can be evaluated (and thus the constraint
@@ -3084,6 +4778,8 @@ struct sqlite3_index_info {
#define SQLITE_INDEX_CONSTRAINT_MATCH 64
/*
+** CAPI3REF: Register A Virtual Table Implementation {F18200}
+**
** This routine is used to register a new module name with an SQLite
** connection. Module names must be registered before creating new
** virtual tables on the module, or before using preexisting virtual
@@ -3097,6 +4793,8 @@ int sqlite3_create_module(
);
/*
+** CAPI3REF: Register A Virtual Table Implementation {F18210}
+**
** This routine is identical to the sqlite3_create_module() method above,
** except that it allows a destructor function to be specified. It is
** even more experimental than the rest of the virtual tables API.
@@ -3110,6 +4808,9 @@ int sqlite3_create_module_v2(
);
/*
+** CAPI3REF: Virtual Table Instance Object {F18010}
+** KEYWORDS: sqlite3_vtab
+**
** Every module implementation uses a subclass of the following structure
** to describe a particular instance of the module. Each subclass will
** be tailored to the specific needs of the module implementation. The
@@ -3133,7 +4834,11 @@ struct sqlite3_vtab {
/* Virtual table implementations will typically add additional fields */
};
-/* Every module implementation uses a subclass of the following structure
+/*
+** CAPI3REF: Virtual Table Cursor Object {F18020}
+** KEYWORDS: sqlite3_vtab_cursor
+**
+** Every module implementation uses a subclass of the following structure
** to describe cursors that point into the virtual table and are used
** to loop through the virtual table. Cursors are created using the
** xOpen method of the module. Each module implementation will define
@@ -3148,6 +4853,8 @@ struct sqlite3_vtab_cursor {
};
/*
+** CAPI3REF: Declare The Schema Of A Virtual Table {F18280}
+**
** The xCreate and xConnect methods of a module use the following API
** to declare the format (the names and datatypes of the columns) of
** the virtual tables they implement.
@@ -3155,6 +4862,8 @@ struct sqlite3_vtab_cursor {
int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable);
/*
+** CAPI3REF: Overload A Function For A Virtual Table {F18300}
+**
** Virtual tables can provide alternative implementations of functions
** using the xFindFunction method. But global versions of those functions
** must exist in order to be overloaded.
@@ -3185,10 +4894,11 @@ int sqlite3_overload_function(sqlite3*,
*/
/*
-** CAPI3REF: A Handle To An Open BLOB
+** CAPI3REF: A Handle To An Open BLOB {F17800}
**
-** An instance of the following opaque structure is used to
-** represent an blob-handle. A blob-handle is created by
+** An instance of this object represents an open BLOB on which
+** incremental I/O can be preformed.
+** Objects of this type are created by
** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()].
** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
** can be used to read or write small subsections of the blob.
@@ -3198,26 +4908,48 @@ int sqlite3_overload_function(sqlite3*,
typedef struct sqlite3_blob sqlite3_blob;
/*
-** CAPI3REF: Open A BLOB For Incremental I/O
+** CAPI3REF: Open A BLOB For Incremental I/O {F17810}
**
-** Open a handle to the blob located in row iRow,, column zColumn,
-** table zTable in database zDb. i.e. the same blob that would
-** be selected by:
+** This interfaces opens a handle to the blob located
+** in row iRow,, column zColumn, table zTable in database zDb;
+** in other words, the same blob that would be selected by:
**
**
** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
-**
+** {END}
**
** If the flags parameter is non-zero, the blob is opened for
** read and write access. If it is zero, the blob is opened for read
** access.
**
** On success, [SQLITE_OK] is returned and the new
-** [sqlite3_blob | blob handle] is written to *ppBlob.
+** [sqlite3_blob | blob handle] is written to *ppBlob.
** Otherwise an error code is returned and
** any value written to *ppBlob should not be used by the caller.
** This function sets the database-handle error code and message
** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
+**
+** INVARIANTS:
+**
+** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)]
+** interface opens an [sqlite3_blob] object P on the blob
+** in column C of table T in database B on [database connection] D.
+**
+** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] starts
+** a new transaction on [database connection] D if that connection
+** is not already in a transaction.
+**
+** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface opens the blob
+** for read and write access if and only if the F parameter
+** is non-zero.
+**
+** {F17819} The [sqlite3_blob_open()] interface returns [SQLITE_OK] on
+** success and an appropriate [error code] on failure.
+**
+** {F17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)]
+** then subsequent calls to [sqlite3_errcode(D)],
+** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
+** information approprate for that error.
*/
int sqlite3_blob_open(
sqlite3*,
@@ -3230,36 +4962,103 @@ int sqlite3_blob_open(
);
/*
-** CAPI3REF: Close A BLOB Handle
+** CAPI3REF: Close A BLOB Handle {F17830}
**
** Close an open [sqlite3_blob | blob handle].
+**
+** Closing a BLOB shall cause the current transaction to commit
+** if there are no other BLOBs, no pending prepared statements, and the
+** database connection is in autocommit mode.
+** If any writes were made to the BLOB, they might be held in cache
+** until the close operation if they will fit. {END}
+** Closing the BLOB often forces the changes
+** out to disk and so if any I/O errors occur, they will likely occur
+** at the time when the BLOB is closed. {F17833} Any errors that occur during
+** closing are reported as a non-zero return value.
+**
+** The BLOB is closed unconditionally. Even if this routine returns
+** an error code, the BLOB is still closed.
+**
+** INVARIANTS:
+**
+** {F17833} The [sqlite3_blob_close(P)] interface closes an
+** [sqlite3_blob] object P previously opened using
+** [sqlite3_blob_open()].
+**
+** {F17836} Closing an [sqlite3_blob] object using
+** [sqlite3_blob_close()] shall cause the current transaction to
+** commit if there are no other open [sqlite3_blob] objects
+** or [prepared statements] on the same [database connection] and
+** the [database connection] is in
+** [sqlite3_get_autocommit | autocommit mode].
+**
+** {F17839} The [sqlite3_blob_close(P)] interfaces closes the
+** [sqlite3_blob] object P unconditionally, even if
+** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK].
+**
*/
int sqlite3_blob_close(sqlite3_blob *);
/*
-** CAPI3REF: Return The Size Of An Open BLOB
+** CAPI3REF: Return The Size Of An Open BLOB {F17840}
**
** Return the size in bytes of the blob accessible via the open
-** [sqlite3_blob | blob-handle] passed as an argument.
+** [sqlite3_blob] object in its only argument.
+**
+** INVARIANTS:
+**
+** {F17843} The [sqlite3_blob_bytes(P)] interface returns the size
+** in bytes of the BLOB that the [sqlite3_blob] object P
+** refers to.
*/
int sqlite3_blob_bytes(sqlite3_blob *);
/*
-** CAPI3REF: Read Data From A BLOB Incrementally
+** CAPI3REF: Read Data From A BLOB Incrementally {F17850}
**
** This function is used to read data from an open
** [sqlite3_blob | blob-handle] into a caller supplied buffer.
-** n bytes of data are copied into buffer
-** z from the open blob, starting at offset iOffset.
+** N bytes of data are copied into buffer
+** Z from the open blob, starting at offset iOffset.
+**
+** If offset iOffset is less than N bytes from the end of the blob,
+** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is
+** less than zero [SQLITE_ERROR] is returned and no data is read.
**
** On success, SQLITE_OK is returned. Otherwise, an
-** [SQLITE_ERROR | SQLite error code] or an
-** [SQLITE_IOERR_READ | extended error code] is returned.
+** [error code] or an [extended error code] is returned.
+**
+** INVARIANTS:
+**
+** {F17853} The [sqlite3_blob_read(P,Z,N,X)] interface reads N bytes
+** beginning at offset X from
+** the blob that [sqlite3_blob] object P refers to
+** and writes those N bytes into buffer Z.
+**
+** {F17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the blob
+** is less than N+X bytes, then the function returns [SQLITE_ERROR]
+** and nothing is read from the blob.
+**
+** {F17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero
+** then the function returns [SQLITE_ERROR]
+** and nothing is read from the blob.
+**
+** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface returns [SQLITE_OK]
+** if N bytes where successfully read into buffer Z.
+**
+** {F17865} If the requested read could not be completed,
+** the [sqlite3_blob_read(P,Z,N,X)] interface returns an
+** appropriate [error code] or [extended error code].
+**
+** {F17868} If an error occurs during evaluation of [sqlite3_blob_read(D,...)]
+** then subsequent calls to [sqlite3_errcode(D)],
+** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
+** information approprate for that error.
*/
-int sqlite3_blob_read(sqlite3_blob *, void *z, int n, int iOffset);
+int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
/*
-** CAPI3REF: Write Data Into A BLOB Incrementally
+** CAPI3REF: Write Data Into A BLOB Incrementally {F17870}
**
** This function is used to write data into an open
** [sqlite3_blob | blob-handle] from a user supplied buffer.
@@ -3270,34 +5069,67 @@ int sqlite3_blob_read(sqlite3_blob *, vo
** was not opened for writing (the flags parameter to [sqlite3_blob_open()]
*** was zero), this function returns [SQLITE_READONLY].
**
-** This function may only modify the contents of the blob, it is
-** not possible to increase the size of a blob using this API. If
-** offset iOffset is less than n bytes from the end of the blob,
-** [SQLITE_ERROR] is returned and no data is written.
+** This function may only modify the contents of the blob; it is
+** not possible to increase the size of a blob using this API.
+** If offset iOffset is less than n bytes from the end of the blob,
+** [SQLITE_ERROR] is returned and no data is written. If n is
+** less than zero [SQLITE_ERROR] is returned and no data is written.
**
** On success, SQLITE_OK is returned. Otherwise, an
-** [SQLITE_ERROR | SQLite error code] or an
-** [SQLITE_IOERR_READ | extended error code] is returned.
+** [error code] or an [extended error code] is returned.
+**
+** INVARIANTS:
+**
+** {F17873} The [sqlite3_blob_write(P,Z,N,X)] interface writes N bytes
+** from buffer Z into
+** the blob that [sqlite3_blob] object P refers to
+** beginning at an offset of X into the blob.
+**
+** {F17875} The [sqlite3_blob_write(P,Z,N,X)] interface returns
+** [SQLITE_READONLY] if the [sqlite3_blob] object P was
+** [sqlite3_blob_open | opened] for reading only.
+**
+** {F17876} In [sqlite3_blob_write(P,Z,N,X)] if the size of the blob
+** is less than N+X bytes, then the function returns [SQLITE_ERROR]
+** and nothing is written into the blob.
+**
+** {F17879} In [sqlite3_blob_write(P,Z,N,X)] if X or N is less than zero
+** then the function returns [SQLITE_ERROR]
+** and nothing is written into the blob.
+**
+** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface returns [SQLITE_OK]
+** if N bytes where successfully written into blob.
+**
+** {F17885} If the requested write could not be completed,
+** the [sqlite3_blob_write(P,Z,N,X)] interface returns an
+** appropriate [error code] or [extended error code].
+**
+** {F17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)]
+** then subsequent calls to [sqlite3_errcode(D)],
+** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
+** information approprate for that error.
*/
int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
/*
-** CAPI3REF: Virtual File System Objects
+** CAPI3REF: Virtual File System Objects {F11200}
**
** A virtual filesystem (VFS) is an [sqlite3_vfs] object
** that SQLite uses to interact
-** with the underlying operating system. Most builds come with a
+** with the underlying operating system. Most SQLite builds come with a
** single default VFS that is appropriate for the host computer.
** New VFSes can be registered and existing VFSes can be unregistered.
** The following interfaces are provided.
**
-** The sqlite3_vfs_find() interface returns a pointer to a VFS given its
-** name. Names are case sensitive. If there is no match, a NULL
+** The sqlite3_vfs_find() interface returns a pointer to
+** a VFS given its name. Names are case sensitive.
+** Names are zero-terminated UTF-8 strings.
+** If there is no match, a NULL
** pointer is returned. If zVfsName is NULL then the default
-** VFS is returned.
+** VFS is returned.
**
-** New VFSes are registered with sqlite3_vfs_register(). Each
-** new VFS becomes the default VFS if the makeDflt flag is set.
+** New VFSes are registered with sqlite3_vfs_register().
+** Each new VFS becomes the default VFS if the makeDflt flag is set.
** The same VFS can be registered multiple times without injury.
** To make an existing VFS into the default VFS, register it again
** with the makeDflt flag set. If two different VFSes with the
@@ -3308,13 +5140,40 @@ int sqlite3_blob_write(sqlite3_blob *, c
** Unregister a VFS with the sqlite3_vfs_unregister() interface.
** If the default VFS is unregistered, another VFS is chosen as
** the default. The choice for the new VFS is arbitrary.
+**
+** INVARIANTS:
+**
+** {F11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the
+** registered [sqlite3_vfs] object whose name exactly matches
+** the zero-terminated UTF-8 string N, or it returns NULL if
+** there is no match.
+**
+** {F11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then
+** the function returns a pointer to the default [sqlite3_vfs]
+** object if there is one, or NULL if there is no default
+** [sqlite3_vfs] object.
+**
+** {F11209} The [sqlite3_vfs_register(P,F)] interface registers the
+** well-formed [sqlite3_vfs] object P using the name given
+** by the zName field of the object.
+**
+** {F11212} Using the [sqlite3_vfs_register(P,F)] interface to register
+** the same [sqlite3_vfs] object multiple times is a harmless no-op.
+**
+** {F11215} The [sqlite3_vfs_register(P,F)] interface makes the
+** the [sqlite3_vfs] object P the default [sqlite3_vfs] object
+** if F is non-zero.
+**
+** {F11218} The [sqlite3_vfs_unregister(P)] interface unregisters the
+** [sqlite3_vfs] object P so that it is no longer returned by
+** subsequent calls to [sqlite3_vfs_find()].
*/
sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
int sqlite3_vfs_unregister(sqlite3_vfs*);
/*
-** CAPI3REF: Mutexes
+** CAPI3REF: Mutexes {F17000}
**
** The SQLite core uses these routines for thread
** synchronization. Though they are intended for internal
@@ -3348,10 +5207,10 @@ int sqlite3_vfs_unregister(sqlite3_vfs*)
** application that links against SQLite to provide its own mutex
** implementation without having to modify the SQLite core.
**
-** The sqlite3_mutex_alloc() routine allocates a new
-** mutex and returns a pointer to it. If it returns NULL
-** that means that a mutex could not be allocated. SQLite
-** will unwind its stack and return an error. The argument
+** {F17011} The sqlite3_mutex_alloc() routine allocates a new
+** mutex and returns a pointer to it. {F17012} If it returns NULL
+** that means that a mutex could not be allocated. {F17013} SQLite
+** will unwind its stack and return an error. {F17014} The argument
** to sqlite3_mutex_alloc() is one of these integer constants:
**
**
@@ -3362,60 +5221,62 @@ int sqlite3_vfs_unregister(sqlite3_vfs*)
** - SQLITE_MUTEX_STATIC_MEM2
**
- SQLITE_MUTEX_STATIC_PRNG
**
- SQLITE_MUTEX_STATIC_LRU
-**
+** {END}
**
-** The first two constants cause sqlite3_mutex_alloc() to create
+** {F17015} The first two constants cause sqlite3_mutex_alloc() to create
** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
-** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
+** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END}
** The mutex implementation does not need to make a distinction
** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
-** not want to. But SQLite will only request a recursive mutex in
-** cases where it really needs one. If a faster non-recursive mutex
+** not want to. {F17016} But SQLite will only request a recursive mutex in
+** cases where it really needs one. {END} If a faster non-recursive mutex
** implementation is available on the host platform, the mutex subsystem
** might return such a mutex in response to SQLITE_MUTEX_FAST.
**
-** The other allowed parameters to sqlite3_mutex_alloc() each return
-** a pointer to a static preexisting mutex. Four static mutexes are
+** {F17017} The other allowed parameters to sqlite3_mutex_alloc() each return
+** a pointer to a static preexisting mutex. {END} Four static mutexes are
** used by the current version of SQLite. Future versions of SQLite
** may add additional static mutexes. Static mutexes are for internal
** use by SQLite only. Applications that use SQLite mutexes should
** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
** SQLITE_MUTEX_RECURSIVE.
**
-** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
+** {F17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
-** returns a different mutex on every call. But for the static
+** returns a different mutex on every call. {F17034} But for the static
** mutex types, the same mutex is returned on every call that has
-** the same type number.
+** the same type number. {END}
**
-** The sqlite3_mutex_free() routine deallocates a previously
-** allocated dynamic mutex. SQLite is careful to deallocate every
-** dynamic mutex that it allocates. The dynamic mutexes must not be in
-** use when they are deallocated. Attempting to deallocate a static
-** mutex results in undefined behavior. SQLite never deallocates
-** a static mutex.
+** {F17019} The sqlite3_mutex_free() routine deallocates a previously
+** allocated dynamic mutex. {F17020} SQLite is careful to deallocate every
+** dynamic mutex that it allocates. {U17021} The dynamic mutexes must not be in
+** use when they are deallocated. {U17022} Attempting to deallocate a static
+** mutex results in undefined behavior. {F17023} SQLite never deallocates
+** a static mutex. {END}
**
** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
-** to enter a mutex. If another thread is already within the mutex,
+** to enter a mutex. {F17024} If another thread is already within the mutex,
** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
-** SQLITE_BUSY. The sqlite3_mutex_try() interface returns SQLITE_OK
-** upon successful entry. Mutexes created using SQLITE_MUTEX_RECURSIVE can
-** be entered multiple times by the same thread. In such cases the,
+** SQLITE_BUSY. {F17025} The sqlite3_mutex_try() interface returns SQLITE_OK
+** upon successful entry. {F17026} Mutexes created using
+** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
+** {F17027} In such cases the,
** mutex must be exited an equal number of times before another thread
-** can enter. If the same thread tries to enter any other kind of mutex
-** more than once, the behavior is undefined. SQLite will never exhibit
-** such behavior in its own use of mutexes.
+** can enter. {U17028} If the same thread tries to enter any other
+** kind of mutex more than once, the behavior is undefined.
+** {F17029} SQLite will never exhibit
+** such behavior in its own use of mutexes. {END}
**
** Some systems (ex: windows95) do not the operation implemented by
** sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() will
-** always return SQLITE_BUSY. The SQLite core only ever uses
-** sqlite3_mutex_try() as an optimization so this is acceptable behavior.
+** always return SQLITE_BUSY. {F17030} The SQLite core only ever uses
+** sqlite3_mutex_try() as an optimization so this is acceptable behavior. {END}
**
-** The sqlite3_mutex_leave() routine exits a mutex that was
-** previously entered by the same thread. The behavior
+** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was
+** previously entered by the same thread. {U17032} The behavior
** is undefined if the mutex is not currently entered by the
-** calling thread or is not currently allocated. SQLite will
-** never do either.
+** calling thread or is not currently allocated. {F17033} SQLite will
+** never do either. {END}
**
** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
*/
@@ -3426,44 +5287,44 @@ int sqlite3_mutex_try(sqlite3_mutex*);
void sqlite3_mutex_leave(sqlite3_mutex*);
/*
-** CAPI3REF: Mutex Verifcation Routines
+** CAPI3REF: Mutex Verifcation Routines {F17080}
**
** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
-** are intended for use inside assert() statements. The SQLite core
+** are intended for use inside assert() statements. {F17081} The SQLite core
** never uses these routines except inside an assert() and applications
-** are advised to follow the lead of the core. The core only
+** are advised to follow the lead of the core. {F17082} The core only
** provides implementations for these routines when it is compiled
-** with the SQLITE_DEBUG flag. External mutex implementations
+** with the SQLITE_DEBUG flag. {U17087} External mutex implementations
** are only required to provide these routines if SQLITE_DEBUG is
** defined and if NDEBUG is not defined.
**
-** These routines should return true if the mutex in their argument
-** is held or not held, respectively, by the calling thread.
+** {F17083} These routines should return true if the mutex in their argument
+** is held or not held, respectively, by the calling thread. {END}
**
-** The implementation is not required to provided versions of these
+** {X17084} The implementation is not required to provided versions of these
** routines that actually work.
** If the implementation does not provide working
** versions of these routines, it should at least provide stubs
** that always return true so that one does not get spurious
-** assertion failures.
+** assertion failures. {END}
**
-** If the argument to sqlite3_mutex_held() is a NULL pointer then
-** the routine should return 1. This seems counter-intuitive since
+** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then
+** the routine should return 1. {END} This seems counter-intuitive since
** clearly the mutex cannot be held if it does not exist. But the
** the reason the mutex does not exist is because the build is not
** using mutexes. And we do not want the assert() containing the
** call to sqlite3_mutex_held() to fail, so a non-zero return is
-** the appropriate thing to do. The sqlite3_mutex_notheld()
+** the appropriate thing to do. {F17086} The sqlite3_mutex_notheld()
** interface should also return 1 when given a NULL pointer.
*/
int sqlite3_mutex_held(sqlite3_mutex*);
int sqlite3_mutex_notheld(sqlite3_mutex*);
/*
-** CAPI3REF: Mutex Types
+** CAPI3REF: Mutex Types {F17001}
**
-** The [sqlite3_mutex_alloc()] interface takes a single argument
-** which is one of these integer constants.
+** {F17002} The [sqlite3_mutex_alloc()] interface takes a single argument
+** which is one of these integer constants. {END}
*/
#define SQLITE_MUTEX_FAST 0
#define SQLITE_MUTEX_RECURSIVE 1
@@ -3474,32 +5335,71 @@ int sqlite3_mutex_notheld(sqlite3_mutex*
#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
/*
-** CAPI3REF: Low-Level Control Of Database Files
+** CAPI3REF: Low-Level Control Of Database Files {F11300}
**
-** The [sqlite3_file_control()] interface makes a direct call to the
+** {F11301} The [sqlite3_file_control()] interface makes a direct call to the
** xFileControl method for the [sqlite3_io_methods] object associated
-** with a particular database identified by the second argument. The
+** with a particular database identified by the second argument. {F11302} The
** name of the database is the name assigned to the database by the
** ATTACH SQL command that opened the
-** database. To control the main database file, use the name "main"
-** or a NULL pointer. The third and fourth parameters to this routine
+** database. {F11303} To control the main database file, use the name "main"
+** or a NULL pointer. {F11304} The third and fourth parameters to this routine
** are passed directly through to the second and third parameters of
-** the xFileControl method. The return value of the xFileControl
+** the xFileControl method. {F11305} The return value of the xFileControl
** method becomes the return value of this routine.
**
-** If the second parameter (zDbName) does not match the name of any
-** open database file, then SQLITE_ERROR is returned. This error
+** {F11306} If the second parameter (zDbName) does not match the name of any
+** open database file, then SQLITE_ERROR is returned. {F11307} This error
** code is not remembered and will not be recalled by [sqlite3_errcode()]
-** or [sqlite3_errmsg()]. The underlying xFileControl method might
-** also return SQLITE_ERROR. There is no way to distinguish between
+** or [sqlite3_errmsg()]. {U11308} The underlying xFileControl method might
+** also return SQLITE_ERROR. {U11309} There is no way to distinguish between
** an incorrect zDbName and an SQLITE_ERROR return from the underlying
-** xFileControl method.
+** xFileControl method. {END}
**
** See also: [SQLITE_FCNTL_LOCKSTATE]
*/
int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
/*
+** CAPI3REF: Testing Interface {F11400}
+**
+** The sqlite3_test_control() interface is used to read out internal
+** state of SQLite and to inject faults into SQLite for testing
+** purposes. The first parameter a operation code that determines
+** the number, meaning, and operation of all subsequent parameters.
+**
+** This interface is not for use by applications. It exists solely
+** for verifying the correct operation of the SQLite library. Depending
+** on how the SQLite library is compiled, this interface might not exist.
+**
+** The details of the operation codes, their meanings, the parameters
+** they take, and what they do are all subject to change without notice.
+** Unlike most of the SQLite API, this function is not guaranteed to
+** operate consistently from one release to the next.
+*/
+int sqlite3_test_control(int op, ...);
+
+/*
+** CAPI3REF: Testing Interface Operation Codes {F11410}
+**
+** These constants are the valid operation code parameters used
+** as the first argument to [sqlite3_test_control()].
+**
+** These parameters and their meansing are subject to change
+** without notice. These values are for testing purposes only.
+** Applications should not use any of these parameters or the
+** [sqlite3_test_control()] interface.
+*/
+#define SQLITE_TESTCTRL_FAULT_CONFIG 1
+#define SQLITE_TESTCTRL_FAULT_FAILURES 2
+#define SQLITE_TESTCTRL_FAULT_BENIGN_FAILURES 3
+#define SQLITE_TESTCTRL_FAULT_PENDING 4
+
+
+
+
+
+/*
** Undo the hack that converts floating point types to integer for
** builds on processors without floating point support.
*/