** azResult[0] = "Name";
@@ -1048,28 +1263,55 @@ int sqlite3_busy_timeout(sqlite3*, int ms);
** azResult[7] = "21";
**
**
-** Notice that there is an extra row of data containing the column
-** headers. But the *nrow return value is still 3. *ncolumn is
-** set to 2. In general, the number of values inserted into azResult
-** will be ((*nrow) + 1)*(*ncolumn).
+** The sqlite3_get_table() function evaluates one or more
+** semicolon-separated SQL statements in the zero-terminated UTF-8
+** string of its 2nd parameter. It returns a result table to the
+** pointer given in its 3rd parameter.
**
-** {U12374} After the calling function has finished using the result, it should
-** pass the result data pointer to sqlite3_free_table() in order to
+** After the calling function has finished using the result, it should
+** pass the pointer to the result table to sqlite3_free_table() in order to
** release the memory that was malloc-ed. Because of the way the
-** [sqlite3_malloc()] happens, the calling function must not try to call
-** [sqlite3_free()] directly. Only [sqlite3_free_table()] is able to release
-** the memory properly and safely. {END}
-**
-** {F12373} The return value of this routine is the same as
-** from [sqlite3_exec()].
+** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
+** function must not try to call [sqlite3_free()] directly. Only
+** [sqlite3_free_table()] is able to release the memory properly and safely.
+**
+** The sqlite3_get_table() interface is implemented as a wrapper around
+** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
+** to any internal data structures of SQLite. It uses only the public
+** interface defined here. As a consequence, errors that occur in the
+** wrapper layer outside of the internal [sqlite3_exec()] call are not
+** reflected in subsequent calls to [sqlite3_errcode()] or
+** [sqlite3_errmsg()].
+**
+** INVARIANTS:
+**
+** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then
+** it frees the result table under construction, aborts the
+** query in process, skips any subsequent queries, sets the
+** *resultp output pointer to NULL and returns [SQLITE_NOMEM].
+**
+** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL
+** then [sqlite3_get_table()] write the number of columns in the
+** result set of the query into *ncolumn if the query is
+** successful (if the function returns SQLITE_OK).
+**
+** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL
+** then [sqlite3_get_table()] write the number of rows in the
+** result set of the query into *nrow if the query is
+** successful (if the function returns SQLITE_OK).
+**
+** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value
+** to the number of columns in the result set of the query in the
+** sql parameter, or to zero if the query in sql has an empty
+** result set.
*/
int sqlite3_get_table(
- sqlite3*, /* An open database */
- const char *sql, /* SQL to be executed */
- char ***resultp, /* Result written to a char *[] that this points to */
- int *nrow, /* Number of result rows written here */
- int *ncolumn, /* Number of result columns written here */
- char **errmsg /* Error msg written here */
+ sqlite3*, /* An open database */
+ const char *sql, /* SQL to be evaluated */
+ char ***pResult, /* Results of the query */
+ int *nrow, /* Number of result rows written here */
+ int *ncolumn, /* Number of result columns written here */
+ char **errmsg /* Error msg written here */
);
void sqlite3_free_table(char **result);
@@ -1079,30 +1321,30 @@ void sqlite3_free_table(char **result);
** These routines are workalikes of the "printf()" family of functions
** from the standard C library.
**
-** {F17401} The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
+** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
** results into memory obtained from [sqlite3_malloc()].
-** {U17402} The strings returned by these two routines should be
-** released by [sqlite3_free()]. {F17403} Both routines return a
+** The strings returned by these two routines should be
+** released by [sqlite3_free()]. Both routines return a
** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
** memory to hold the resulting string.
**
-** {F17404} In sqlite3_snprintf() routine is similar to "snprintf()" from
+** In sqlite3_snprintf() routine is similar to "snprintf()" from
** the standard C library. The result is written into the
** buffer supplied as the second parameter whose size is given by
-** the first parameter. {END} Note that the order of the
+** the first parameter. Note that the order of the
** first two parameters is reversed from snprintf(). This is an
** historical accident that cannot be fixed without breaking
-** backwards compatibility. {F17405} Note also that sqlite3_snprintf()
+** backwards compatibility. Note also that sqlite3_snprintf()
** returns a pointer to its buffer instead of the number of
-** characters actually written into the buffer. {END} We admit that
+** characters actually written into the buffer. We admit that
** the number of characters written would be a more useful return
** value but we cannot change the implementation of sqlite3_snprintf()
** now without breaking compatibility.
**
-** {F17406} As long as the buffer size is greater than zero, sqlite3_snprintf()
-** guarantees that the buffer is always zero-terminated. {F17407} The first
+** As long as the buffer size is greater than zero, sqlite3_snprintf()
+** guarantees that the buffer is always zero-terminated. The first
** parameter "n" is the total size of the buffer, including space for
-** the zero terminator. {END} So the longest string that can be completely
+** the zero terminator. So the longest string that can be completely
** written will be n-1 characters.
**
** These routines all implement some additional formatting
@@ -1110,9 +1352,9 @@ void sqlite3_free_table(char **result);
** All of the usual printf formatting options apply. In addition, there
** is are "%q", "%Q", and "%z" options.
**
-** {F17410} The %q option works like %s in that it substitutes a null-terminated
+** The %q option works like %s in that it substitutes a null-terminated
** string from the argument list. But %q also doubles every '\'' character.
-** %q is designed for use inside a string literal. {END} By doubling each '\''
+** %q is designed for use inside a string literal. By doubling each '\''
** character it escapes that character and allows it to be inserted into
** the string.
**
@@ -1148,7 +1390,7 @@ void sqlite3_free_table(char **result);
** should always use %q instead of %s when inserting text into a string
** literal.
**
-** {F17411} The %Q option works like %q except it also adds single quotes around
+** The %Q option works like %q except it also adds single quotes around
** the outside of the total string. Or if the parameter in the argument
** list is a NULL pointer, %Q substitutes the text "NULL" (without single
** quotes) in place of the %Q option. {END} So, for example, one could say:
@@ -1162,9 +1404,27 @@ void sqlite3_free_table(char **result);
** The code above will render a correct SQL statement in the zSQL
** variable even if the zText variable is a NULL pointer.
**
-** {F17412} The "%z" formatting option works exactly like "%s" with the
+** 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. {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);
@@ -1173,50 +1433,50 @@ char *sqlite3_snprintf(int,char*,const char*, ...);
/*
** CAPI3REF: Memory Allocation Subsystem {F17300}
**
-** {F17301} The SQLite core uses these three routines for all of its own
-** internal memory allocation needs. {END} "Core" in the previous sentence
+** 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.
**
-** {F17302} The sqlite3_malloc() routine returns a pointer to a block
+** The sqlite3_malloc() routine returns a pointer to a block
** of memory at least N bytes in length, where N is the parameter.
-** {F17303} If sqlite3_malloc() is unable to obtain sufficient free
-** memory, it returns a NULL pointer. {F17304} If the parameter N to
+** 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.
**
-** {F17305} Calling sqlite3_free() with a pointer previously returned
+** Calling sqlite3_free() with a pointer previously returned
** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
-** that it might be reused. {F17306} The sqlite3_free() routine is
+** 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. {U17307} After being freed, memory
+** 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.
-** {U17309} Memory corruption, 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().
**
-** {F17310} The sqlite3_realloc() interface attempts to resize a
+** 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. {F17311} If the first parameter to sqlite3_realloc()
+** 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().
-** {F17312} If the second parameter to sqlite3_realloc() is zero or
+** 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().
-** {F17313} Sqlite3_realloc() returns a pointer to a memory allocation
+** Sqlite3_realloc() returns a pointer to a memory allocation
** of at least N bytes in size or NULL if sufficient memory is unavailable.
-** {F17314} If M is the size of the prior allocation, then min(N,M) bytes
+** 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.
-** {F17315} If sqlite3_realloc() returns NULL, then the prior allocation
+** If sqlite3_realloc() returns NULL, then the prior allocation
** is not freed.
**
-** {F17316} The memory returned by sqlite3_malloc() and sqlite3_realloc()
+** The memory returned by sqlite3_malloc() and sqlite3_realloc()
** is always aligned to at least an 8 byte boundary. {END}
**
-** {F17381} The default implementation
+** The default implementation
** of the memory allocation subsystem uses the malloc(), realloc()
** and free() provided by the standard C library. {F17382} However, if
** SQLite is compiled with the following C preprocessor macro
@@ -1241,6 +1501,58 @@ char *sqlite3_snprintf(int,char*,const char*, ...);
** 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);
@@ -1249,29 +1561,31 @@ void sqlite3_free(void*);
/*
** 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 here.
-**
-** {F17371} The sqlite3_memory_used() routine returns the
-** number of bytes of memory currently outstanding (malloced but not freed).
-** {F17372} The value returned by sqlite3_memory_used() includes
-** any overhead added by SQLite, but not overhead added by the
-** library malloc() that backs the sqlite3_malloc() implementation.
-** {F17373} The sqlite3_memory_highwater() routines returns the
-** maximum number of bytes that have been outstanding at any time
-** since the highwater mark was last reset.
-** {F17374} The byte count returned by sqlite3_memory_highwater()
-** uses the same byte counting rules as sqlite3_memory_used(). {END}
-** In other words, overhead added internally by SQLite is counted,
-** but overhead from the underlying system malloc is not.
-** {F17375} If the parameter to sqlite3_memory_highwater() is true,
-** then the highwater mark is reset to the current value of
-** sqlite3_memory_used() and the prior highwater mark (before the
-** reset) is returned. {F17376} If the parameter to
-** sqlite3_memory_highwater() is zero, then the highwater mark is
-** unchanged.
+** 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);
@@ -1279,44 +1593,41 @@ sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
/*
** CAPI3REF: Compile-Time Authorization Callbacks {F12500}
**
-** {F12501} This routine registers a authorizer callback with a particular
-** database connection, supplied in the first argument. {F12502}
+** 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()]. {F12503} At various
+** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various
** points during the compilation process, as logic is being created
** to perform various actions, the authorizer callback is invoked to
** see if those actions are allowed. The authorizer callback should
** 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. {F12504} If the authorizer callback returns
+** 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 shall
-** fail with an SQLITE_ERROR error code and an appropriate error message. {END}
+** the authorizer will fail with an error message.
**
** When the callback returns [SQLITE_OK], that means the operation
-** requested is ok. {F12505} When the callback returns [SQLITE_DENY], the
+** requested is ok. When the callback returns [SQLITE_DENY], the
** [sqlite3_prepare_v2()] or equivalent call that triggered the
-** authorizer 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 anything other than [SQLITE_READ], then
-** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY].
-** 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. {END}
-**
-** {F12510} The first parameter to the authorizer callback is a copy of
+** 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.
-** {F12511} The second parameter to the callback is an integer
+** The second parameter to the callback is an integer
** [SQLITE_COPY | action code] that specifies the particular action
-** to be authorized. {END} The available action codes are
-** [SQLITE_COPY | documented separately]. {F12512} The third through sixth
+** 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. {END}
+** 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
@@ -1329,14 +1640,66 @@ sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
** user-entered SQL is being prepared that disallows everything
** except SELECT statements.
**
-** {F12520} Only a single authorizer can be in place on a database connection
+** 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. {F12521} A NULL authorizer means that no authorization
-** callback is invoked. {F12522} The default authorizer is NULL. {END}
+** 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. {F12523} Authorization is not
-** performed during statement evaluation in [sqlite3_step()]. {END}
+** [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*,
@@ -1360,20 +1723,42 @@ int sqlite3_set_authorizer(
** CAPI3REF: Authorizer Action Codes {F12550}
**
** The [sqlite3_set_authorizer()] interface registers a callback function
-** that is invoked to authorizer certain SQL statement actions. {F12551} The
+** that is invoked to authorizer certain SQL statement actions. The
** second parameter to the callback is an integer code that specifies
** what action is being authorized. These are the integer action codes that
-** the authorizer callback may be passed. {END}
+** the authorizer callback may be passed.
**
** These action code values signify what kind of operation is to be
-** authorized. {F12552} The 3rd and 4th parameters to the authorization
+** 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. {F12553} The 5th parameter to the
+** 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. {F12554} The 6th parameter to the authorizer callback
+** 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 */
@@ -1415,31 +1800,60 @@ int sqlite3_set_authorizer(
** These routines register callback functions that can be used for
** tracing and profiling the execution of SQL statements.
**
-** {F12281} The callback function registered by sqlite3_trace() is invoked
-** at the first [sqlite3_step()] for the evaluation of an SQL statement.
-** {F12282} Only a single trace callback can be registered at a time.
-** Each call to sqlite3_trace() overrides the previous. {F12283} A
-** NULL callback for sqlite3_trace() 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. {END} Note that the
-** host parameter are not expanded in the SQL statement text.
-**
-** {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. {END}
+** 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. 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*,
@@ -1448,68 +1862,78 @@ void *sqlite3_profile(sqlite3*,
/*
** CAPI3REF: Query Progress Callbacks {F12910}
**
-** {F12911} This routine configures a callback function - the
+** 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()]. {END} An example use for this
+** [sqlite3_get_table()]. An example use for this
** interface is to keep a GUI updated during a large query.
**
+** 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 this function.
+** machine opcodes, where N is the second argument to
+** the [sqlite3_progress_handler()] call that registered
+** the callback.