** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
-** @(#) $Id: sqlite.h.in,v 1.275 2007/12/05 18:05:16 drh Exp $
+** @(#) $Id: sqlite.h.in,v 1.276 2007/12/06 02:42:08 drh Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
/*
** CAPI3REF: Compile-Time Library Version Numbers {F10010}
**
-** {F10011} The version of the SQLite library is contained in the sqlite3.h
-** header file in a #define named SQLITE_VERSION. {F10012} The SQLITE_VERSION
-** macro resolves to a string constant.
-**
-** {F10013} The format of the version string is "X.Y.Z", where
+** {F10011} The #define in the sqlite3.h header file named
+** SQLITE_VERSION resolves to a string literal that identifies
+** the version of the SQLite library in the format "X.Y.Z", where
** X is the major version number, Y is the minor version number and Z
** is the release number. The X.Y.Z might be followed by "alpha" or "beta".
-** For example "3.1.1beta". {END}
+** {END} For example "3.1.1beta".
**
** The X value is always 3 in SQLite. The X value only changes when
** backwards compatibility is broken and we intend to never break
** but not backwards compatible. The Z value is incremented with
** each release but resets back to 0 when Y is incremented.
**
-** {F10014} The SQLITE_VERSION_NUMBER is an integer with the value
-** (X*1000000 + Y*1000 + Z). For example, for version "3.1.1beta",
+** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer
+** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are as
+** with SQLITE_VERSION. {END} For example, for version "3.1.1beta",
** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using
** version 3.1.1 or greater at compile time, programs may use the test
-** (SQLITE_VERSION_NUMBER>=3001001). {END}
+** (SQLITE_VERSION_NUMBER>=3001001).
**
** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
*/
/*
** CAPI3REF: Run-Time Library Version Numbers {F10020}
**
-** {F10021} These routines return values equivalent to the header constants
-** [SQLITE_VERSION] and [SQLITE_VERSION_NUMBER]. {END} The values returned
-** by this routines should only be different from the header values
+** {F10021} The sqlite3_libversion_number() interface returns an integer
+** equal to [SQLITE_VERSION_NUMBER]. {END} The value returned
+** by this routine should only be different from the header values
** if the application is compiled using an sqlite3.h header from a
** different version of SQLite than library. Cautious programmers might
** include a check in their application to verify that
**
** {F10022} The sqlite3_version[] string constant contains the text of the
** [SQLITE_VERSION] string. {F10023} The sqlite3_libversion() function returns
-** a poiner to the sqlite3_version[] string constant. {END} The function
+** a pointer to the sqlite3_version[] string constant. {END} The
+** sqlite3_libversion() function
** is provided for DLL users who can only access functions and not
** constants within the DLL.
*/
/*
** CAPI3REF: Test To See If The Library Is Threadsafe {F10100}
**
-** {F10101} This routine returns TRUE (nonzero) if SQLite was compiled with
-** all of its mutexes enabled and is thus threadsafe. {F10102} It returns
-** zero if the particular build is for single-threaded operation
-** only. {END}
+** {F10101} The sqlite3_threadsafe() routine returns nonzero
+** if SQLite was compiled with its mutexes enabled or zero if
+** SQLite was compiled with mutexes disabled. {END} If this
+** routine returns false, then it is not safe for simultaneously
+** running threads to both invoke SQLite interfaces.
**
-** {F10103} Really all this routine does is return true if SQLite was
+** Really all this routine does is return true if SQLite was
** compiled with the -DSQLITE_THREADSAFE=1 option and false if
-** compiled with -DSQLITE_THREADSAFE=0. {U10104} If SQLite uses an
+** compiled with -DSQLITE_THREADSAFE=0. If SQLite uses an
** application-defined mutex subsystem, malloc subsystem, collating
** sequence, VFS, SQL function, progress callback, commit hook,
** extension, or other accessories and these add-ons are not
** threadsafe, then clearly the combination will not be threadsafe
-** either. {END} Hence, this routine never reports that the library
+** either. Hence, this routine never reports that the library
** is guaranteed to be threadsafe, only when it is guaranteed not
** to be.
*/
/*
** CAPI3REF: Closing A Database Connection {F12010}
**
-** {F12010} Call this function with a pointer to a structure that was
-** previously returned from [sqlite3_open()], [sqlite3_open16()], or
-** [sqlite3_open_v2()] and the corresponding database will by
-** closed. {END}
+** {F12011} The sqlite3_close() interfaces destroys an [sqlite3] object
+** allocated by a prior call to [sqlite3_open()], [sqlite3_open16()], or
+** [sqlite3_open_v2()]. {F12012} Sqlite3_close() releases all
+** memory used by the connection and closes all open files. {END}.
**
-** {F12011} All SQL statements prepared using [sqlite3_prepare_v2()] or
-** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()]
-** before this routine is called. Otherwise, SQLITE_BUSY is returned and the
-** database connection remains open. {END}
+** {F12013} If the database connection contains
+** [sqlite3_stmt | prepared statements] that have not been finalized
+** by [sqlite3_finalize()], then sqlite3_close() returns SQLITE_BUSY
+** and leaves the connection open. {F12014} Giving sqlite3_close()
+** a NULL pointer is a harmless no-op. {END}
**
-** {U12012} Passing this routine a database connection that has already been
-** closed results in undefined behavior. {U12013} If other interfaces that
+** {U12015} Passing this routine a database connection that has already been
+** closed results in undefined behavior. {U12016} If other interfaces that
** reference the same database connection are pending (either in the
** same thread or in different threads) when this routine is called,
** then the behavior is undefined and is almost certainly undesirable.
** CAPI3REF: One-Step Query Execution Interface {F12100}
**
** {F12101} The sqlite3_exec() interface evaluates zero or more
-** UTF-8 encoded, semicolon-separated SQL
-** statements provided as its second argument. {F12102} The SQL
+** UTF-8 encoded, semicolon-separated SQL statements in the zero-terminated
+** string of its second argument. {F12102} The SQL
** statements are evaluated in the context of the database connection
-** provided in the first argument.
+** specified by in the first argument.
** {F12103} SQL statements are prepared one by one using
** [sqlite3_prepare()] or the equivalent, evaluated
** using one or more calls to [sqlite3_step()], then destroyed
** is an array of pointers to strings holding the values for each column
** as extracted using [sqlite3_column_text()]. NULL values in the result
** set result in a NULL pointer. All other value are in their UTF-8
-** string representation. {F12110}
+** string representation. {F12117}
** The 4th parameter to the callback is an array of strings
** obtained using [sqlite3_column_name()] and holding
** the names of each column, also in UTF-8.
** {F12112} If an error occurs while parsing or evaluating the SQL
** then an appropriate error message is written into memory obtained
** from [sqlite3_malloc()] and *errmsg is made to point to that message
-** assuming errmsg is not NULL. {U12113} The calling function
-** is responsible for freeing the memory using [sqlite3_free()].
-** {F12114} If errmsg==NULL, then no error message is ever written.
+** assuming errmsg is not NULL.
+** {U12113} The calling function is responsible for freeing the memory
+** using [sqlite3_free()].
+** {F12116} If [sqlite3_malloc()] fails while attempting to generate
+** the error message, *errmsg is set to NULL.
+** {F12114} If errmsg is NULL then no attempt is made to generate an
+** error message. <todo>Is the return code SQLITE_NOMEM or the original
+** error code?</todo> <todo>What happens if there are multiple errors?
+** Do we get code for the first error, or is the choice of reported
+** error arbitrary?</todo>
**
** {F12115} The return value is is SQLITE_OK if there are no errors and
** some other [SQLITE_OK | return code] if there is an error.
** Many SQLite functions return an integer result code from the set shown
** above in order to indicates success or failure.
**
-** {F10211} The result codes above are the only ones returned by SQLite in its
-** default configuration. {F10212} However, the
+** {F10211} The result codes shown here are the only ones returned
+** by SQLite in its default configuration. {F10212} However, the
** [sqlite3_extended_result_codes()] API can be used to set a database
** connectoin to return more detailed result codes. {END}
**
** CAPI3REF: Extended Result Codes {F10220}
**
** In its default configuration, SQLite API routines return one of 26 integer
-** [result codes]. However, experience has shown that
+** [SQLITE_OK | result codes]. However, experience has shown that
** many of these result codes are too course-grained. They do not provide as
-** much information about problems as users might like. In an effort to
+** much information about problems as programmers might like. In an effort to
** address this, newer versions of SQLite (version 3.3.8 and later) include
** support for additional result codes that provide more detailed information
** about errors. {F10221} The extended result codes are enabled or disabled
** CAPI3REF: Mutex Handle {F17110}
**
** The mutex module within SQLite defines [sqlite3_mutex] to be an
-** abstract type for a mutex object. The SQLite core never looks
-** at the internal representation of an [sqlite3_mutex]. It only
+** abstract type for a mutex object. {F17111} The SQLite core never looks
+** at the internal representation of an [sqlite3_mutex]. {END} It only
** deals with pointers to the [sqlite3_mutex] object.
**
** Mutexes are created using [sqlite3_mutex_alloc()].
** The zName field holds the name of the VFS module. The name must
** be unique across all VFS modules.
**
-** SQLite will guarantee that the zFilename string passed to
+** {F11141} SQLite will guarantee that the zFilename string passed to
** xOpen() is a full pathname as generated by xFullPathname() and
** that the string will be valid and unchanged until xClose() is
-** called. So the [sqlite3_file] can store a pointer to the
+** called. {END} So the [sqlite3_file] can store a pointer to the
** filename if it needs to remember the filename for some reason.
**
-** The flags argument to xOpen() is a copy of the flags argument
-** to [sqlite3_open_v2()]. If [sqlite3_open()] or [sqlite3_open16()]
-** is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
+** {F11142} The flags argument to xOpen() includes all bits set in
+** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
+** or [sqlite3_open16()] is used, then flags includes at least
+** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END}
** If xOpen() opens a file read-only then it sets *pOutFlags to
** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be
** set.
**
-** SQLite will also add one of the following flags to the xOpen()
+** {F11143} SQLite will also add one of the following flags to the xOpen()
** call, depending on the object being opened:
**
** <ul>
** <li> [SQLITE_OPEN_TRANSIENT_DB]
** <li> [SQLITE_OPEN_SUBJOURNAL]
** <li> [SQLITE_OPEN_MASTER_JOURNAL]
-** </ul>
+** </ul> {END}
**
** The file I/O implementation can use the object type flags to
** changes the way it deals with files. For example, an application
** be doing page-aligned sector reads and writes in a random order
** and set up its I/O subsystem accordingly.
**
-** SQLite might also add one of the following flags to the xOpen
+** {F11144} SQLite might also add one of the following flags to the xOpen
** method:
**
** <ul>
** <li> [SQLITE_OPEN_EXCLUSIVE]
** </ul>
**
-** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
-** deleted when it is closed. This will always be set for TEMP
-** databases and journals and for subjournals. The
-** [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
+** {F11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
+** deleted when it is closed. {F11146} The [SQLITE_OPEN_DELETEONCLOSE]
+** will be set for TEMP databases, journals and for subjournals.
+** {F11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
** for exclusive access. This flag is set for all files except
-** for the main database file.
+** for the main database file. {END}
**
-** Space to hold the [sqlite3_file] structure passed as the third
-** argument to xOpen is allocated by caller (the SQLite core).
-** szOsFile bytes are allocated for this object. The xOpen method
-** fills in the allocated space.
+** {F11148} At least szOsFile bytes of memory is allocated by SQLite
+** to hold the [sqlite3_file] structure passed as the third
+** argument to xOpen. {END} The xOpen method does not have to
+** allocate the structure; it should just fill it in.
**
-** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
+** {F11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
** to test for the existance of a file,
** or [SQLITE_ACCESS_READWRITE] to test to see
** if a file is readable and writable, or [SQLITE_ACCESS_READ]
-** to test to see if a file is at least readable. The file can be a
+** to test to see if a file is at least readable. {END} The file can be a
** directory.
**
-** SQLite will always allocate at least mxPathname+1 byte for
-** the output buffers for xGetTempname and xFullPathname. The exact
+** {F11150} SQLite will always allocate at least mxPathname+1 byte for
+** the output buffers for xGetTempname and xFullPathname. {F11151} The exact
** size of the output buffer is also passed as a parameter to both
-** methods. If the output buffer is not large enough, SQLITE_CANTOPEN
+** methods. {END} If the output buffer is not large enough, SQLITE_CANTOPEN
** should be returned. As this is handled as a fatal error by SQLite,
-** vfs implementations should endevour to prevent this by setting
+** vfs implementations should endeavor to prevent this by setting
** mxPathname to a sufficiently large value.
**
** The xRandomness(), xSleep(), and xCurrentTime() interfaces
};
/*
-** CAPI3REF: Flags for the xAccess VFS method {F11150}
+** CAPI3REF: Flags for the xAccess VFS method {F11190}
**
-** {F11151} These integer constants can be used as the third parameter to
+** {F11191} These integer constants can be used as the third parameter to
** the xAccess method of an [sqlite3_vfs] object. {END} They determine
** the kind of what kind of permissions the xAccess method is
-** looking for. {F11152} With SQLITE_ACCESS_EXISTS, the xAccess method
-** simply checks to see if the file exists. {F11153} With
+** looking for. {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method
+** simply checks to see if the file exists. {F11193} With
** SQLITE_ACCESS_READWRITE, the xAccess method checks to see
-** if the file is both readable and writable. {F11154} With
+** if the file is both readable and writable. {F11194} With
** SQLITE_ACCESS_READ the xAccess method
** checks to see if the file is readable.
*/
/*
** CAPI3REF: Enable Or Disable Extended Result Codes {F12200}
**
-** {F12201} This routine enables or disables the
-** [SQLITE_IOERR_READ | extended result codes] feature. {F12202}
+** {F12201} The sqlite3_extended_result_codes() routine enables or disables the
+** [SQLITE_IOERR_READ | extended result codes] feature on a database
+** connection if its 2nd parameter is
+** non-zero or zero, respectively. {F12202}
** By default, SQLite API routines return one of only 26 integer
** [SQLITE_OK | result codes]. {F12203} When extended result codes
** are enabled by this routine, the repetoire of result codes can be
** triggers are not counted. {F12243} Use the [sqlite3_total_changes()] function
** to find the total number of changes including changes caused by triggers.
**
-** {F12244} Within the body of a trigger, the sqlite3_changes() interface can be
-** called to find the number of
+** {F12244} Within the body of a trigger, the sqlite3_changes() interface
+** can be called to find the number of
** changes in the most recently completed INSERT, UPDATE, or DELETE
-** statement within the body of the trigger.
+** statement within the body of the same trigger.
**
-** {F12245} All changes are counted, even if they were later undone by a
+** {F12245} All changes are counted, even if they are later undone by a
** ROLLBACK or ABORT. {F12246} Except, changes associated with creating and
** dropping tables are not counted.
**
**
** See also the [sqlite3_change()] interface.
**
-** SQLite implements the command "DELETE FROM table" without a WHERE clause
-** by dropping and recreating the table. (This is much faster than going
+** {F12265} SQLite implements the command "DELETE FROM table" without
+** a WHERE clause by dropping and recreating the table. (This is much
+** faster than going
** through and deleting individual elements form the table.) Because of
** this optimization, the change count for "DELETE FROM table" will be
** zero regardless of the number of elements that were originally in the
** is not safe to call this routine with a database connection that
** is closed or might close before sqlite3_interrupt() returns.
**
+** If an SQL is very nearly finished at the time when sqlite3_interrupt()
+** is called, then it might not have an opportunity to be interrupted.
+** It might continue to completion.
** {F12274} The SQL operation that is interrupted will return
-** [SQLITE_INTERRUPT]. {F12275} If an interrupted operation was an
-** update that is inside an explicit transaction, then the entire
-** transaction will be rolled back automatically.
+** [SQLITE_INTERRUPT]. {F12275} If the interrupted SQL operation is an
+** INSERT, UPDATE, or DELETE that is inside an explicit transaction,
+** then the entire transaction will be rolled back automatically.
+** {F12276} A call to sqlite3_interrupt() has no effect on SQL statements
+** that are started after sqlite3_interrupt() returns.
*/
void sqlite3_interrupt(sqlite3*);
** CAPI3REF: Determine If An SQL Statement Is Complete {F10510}
**
** These routines are useful for command-line input to determine if the
-** currently entered text forms one or more complete SQL statements or
-** if additional input is needed before sending the statements into
+** currently entered text seems to form complete a SQL statement or
+** if additional input is needed before sending the text into
** SQLite for parsing. These routines return true if the input string
** appears to be a complete SQL statement. A statement is judged to be
** complete if it ends with a semicolon and is not a fragment of a
** CREATE TRIGGER statement. These routines do not parse the SQL and
-** will not detect syntactically incorrect SQL.
+** so will not detect syntactically incorrect SQL.
**
** {F10511} These functions return true if the given input string
** ends with a semicolon optionally followed by whitespace or
** invoked whenever an attempt is made to open a database table
** that another thread or process has locked.
** {F12312} If the busy callback is NULL, then [SQLITE_BUSY]
-** (or sometimes [SQLITE_IOERR_BLOCKED])
+** or [SQLITE_IOERR_BLOCKED]
** is returned immediately upon encountering the lock.
** {F12313} If the busy callback is not NULL, then the
** callback will be invoked with two arguments. {F12314} The
** {F12317} If the callback returns non-zero, then another attempt
** is made to open the database for reading and the cycle repeats.
**
-** {U12318} The presence of a busy handler does not guarantee that
-** it will be invoked when there is lock contention.
+** The presence of a busy handler does not guarantee that
+** it will be invoked when there is lock contention. {F12319}
** If SQLite determines that invoking the busy handler could result in
-** a deadlock, it will return [SQLITE_BUSY] instead. {END}
+** a deadlock, it will go ahead and return [SQLITE_BUSY] or
+** [SQLITE_IOERR_BLOCKED] instead of invoking the
+** busy handler. {END}
** Consider a scenario where one process is holding a read lock that
** it is trying to promote to a reserved lock and
** a second process is holding a reserved lock that it is trying
** to promote to an exclusive lock. The first process cannot proceed
** because it is blocked by the second and the second process cannot
** proceed because it is blocked by the first. If both processes
-** invoke the busy handlers, neither will make any progress.
-** {F12319} Therefore,
+** invoke the busy handlers, neither will make any progress. Therefore,
** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
** will induce the first process to release its read lock and allow
** the second process to proceed.
**
-** {F12321} The default busy callback is NULL.
+** {F12321} The default busy callback is NULL. {END}
**
** {F12322} The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
** when SQLite is in the middle of a large transaction where all the
** So if two database connections share a single cache, then changing
** the busy handler on one connection will also change the busy
** handler in the other connection. {F12332} The busy handler is invoked
-** in the thread that was running when the SQLITE_BUSY was hit.
+** in the thread that was running when the lock contention occurs.
*/
int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
/*
** CAPI3REF: Set A Busy Timeout {F12340}
**
-** {F12341} This routine sets a busy handler that sleeps for a while when a
+** {F12341} This routine sets a [sqlite3_busy_handler | busy handler]
+** that sleeps for a while when a
** table is locked. {F12342} The handler will sleep multiple times until
** at least "ms" milliseconds of sleeping have been done. {F12343} After
** "ms" milliseconds of sleeping, the handler returns 0 which
/*
** CAPI3REF: Memory Allocation Subsystem {F17300}
**
-** {F17301} The SQLite core (not counting operating-system specific VFS
-** implementations) uses these three routines for all of its own
-** internal memory allocation needs. {END}
+** {F17301} The SQLite core uses these three routines for all of its own
+** internal memory allocation needs. {END} "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
** of memory at least N bytes in length, where N is the parameter.
** {F17315} If sqlite3_realloc() returns NULL, then the prior allocation
** is not freed.
**
+** {F17316} The memory returned by sqlite3_malloc() and sqlite3_realloc()
+** is always aligned to at least an 8 byte boundary. {END}
+**
** {F17381} The default implementation
** of the memory allocation subsystem uses the malloc(), realloc()
** and free() provided by the standard C library. {F17382} However, if
** is no longer provided. Only built-in memory allocators can be
** used.
**
-** <b>Exception:</b> 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
** 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 since the
-** highwater mark was last reset.
+** 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().
+** 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
** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. {F12503} 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. {X12504} The authorizer callback should
+** 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. {END}
-**
-** 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. {F12504} 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}
+**
+** When the callback returns [SQLITE_OK], that means the operation
+** requested is ok. {F12505} 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
** the third parameter to the sqlite3_set_authorizer() interface.
);
/*
-** CAPI3REF: Authorizer Return Codes {F12505}
+** 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
#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
+** that is invoked to authorizer certain SQL statement actions. {F12551} 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.
+** the authorizer callback may be passed. {END}
**
** 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
-** codes is used as the second parameter. The 5th parameter to the
+** authorized. {F12552} 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
** authorizer callback is the name of the database ("main", "temp",
-** etc.) if applicable. The 6th parameter to the authorizer callback
+** etc.) if applicable. {F12554} 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.
#define SQLITE_COPY 0 /* No longer used */
/*
-** CAPI3REF: Tracing And Profiling Functions {F12290}
+** CAPI3REF: Tracing And Profiling Functions {F12280}
**
** These routines register callback functions that can be used for
** tracing and profiling the execution of SQL statements.
**
-** {F12291} The callback function registered by sqlite3_trace() is invoked
+** {F12281} The callback function registered by sqlite3_trace() is invoked
** at the first [sqlite3_step()] for the evaluation of an SQL statement.
-** {F12292} Only a single trace callback can be registered at a time.
-** Each call to sqlite3_trace() overrides the previous. {F12293} A
-** NULL callback for sqlite3_trace() disables tracing.
-**
-** {F12295} The callback function registered by sqlite3_profile() is invoked
-** as each SQL statement finishes and includes
-** information on how long that statement ran.{END}
-**
+** {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 sqlite3_profile() API is currently considered experimental and
** is subject to change.
** to [sqlite3_close()] when it is no longer required.
**
** {F12709} The [sqlite3_open_v2()] interface works like [sqlite3_open()]
-** except that provides two additional parameters for additional control
+** except that it acccepts two additional parameters for additional control
** over the new database connection. {F12710} The flags parameter can be
** one of:
**
/*
** CAPI3REF: SQL Statement Object {F13000}
**
-** 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:
** than zero, then zSql is read up to the first zero terminator.
** {F13014} 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
+** zSql string ends at either the first '\000' or '\u0000' character or
** until the nByte-th byte, whichever comes first. {END}
**
** {F13015} *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. {END}
+** first SQL statement in zSql. These routines only compiles the first
+** statement in zSql, so *pzTail is left pointing to what remains
+** uncompiled. {END}
**
** {F13016} *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. {F13017} If the input text contained no SQL (if the input
+** set to NULL. {F13017} 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
** pointer is valid until the statement
** is deleted using sqlite3_finalize().
** {F13103} The string returned by sqlite3_sql() is always UTF8 even
-** if a UTF16 string was originally entered using [sqlite3_prepare16_v2()].
+** if a UTF16 string was originally entered using [sqlite3_prepare16_v2()]
+** or the equivalent.
**
** {F13104} If the statement was compiled using either of the legacy
** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this
/*
** 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.
+** {F15001} SQLite uses the sqlite3_value object to represent all values
+** that are or can be stored in a database table. {END}
+** SQLite uses dynamic typing for the values it stores.
+** {F15002} 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 {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. {F16002} 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 {F13500}
**
** {F13501} In the SQL strings input to [sqlite3_prepare_v2()] and its
-** variants, one or more literals can be replace by a parameter in one
+** variants, literals may be replace by a parameter in one
** of these forms:
**
** <ul>
** occurrences have the same index as the first occurrence.
** {F13506} The index for named parameters can be looked up using the
** [sqlite3_bind_parameter_name()] API if desired. {F13507} The index
-** for "?NNN" parametes is the value of NNN.
+** for "?NNN" parameters is the value of NNN.
** {F13508} The NNN value must be between 1 and the compile-time
** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). {END}
** See <a href="limits.html">limits.html</a> for additional information.
**
** {F13601} Return the largest host parameter index in the precompiled
** statement given as the argument. {F13602} When the host parameters
-** are of the forms like ":AAA" or "?",
+** are of the forms like ":AAA", "$VVV", "@AAA", or "?",
** then they are assigned sequential increasing numbers beginning
** with one, so the value returned is the number of parameters.
** {F13603} However
** Host parameters of the form ":AAA" or "@AAA" or "$VVV" 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. {F13623}
+** is included as part of the name. {F13626}
** Parameters of the form "?" or "?NNN" have no name.
**
-** {F13623} The first bound parameter has an index of 1, not 0.
+** {F13623} The first host parameter has an index of 1, not 0.
**
** {F13624} If the value n is out of range or if the n-th parameter is
** nameless, then NULL is returned. {F13625} The returned string is
**
** {F13721} These routines return the name assigned to a particular column
** in the result set of a SELECT statement. {F13722} The sqlite3_column_name()
-** interface returns a pointer to a UTF8 string and sqlite3_column_name16()
-** returns a pointer to a UTF16 string. {F13723} The first parameter is the
+** interface returns a pointer to a zero-terminated UTF8 string
+** and sqlite3_column_name16() returns a pointer to a zero-terminated
+** UTF16 string. {F13723} The first parameter is the
** [sqlite3_stmt | prepared statement] that implements the SELECT statement.
** The second parameter is the column number. The left-most column is
** number 0.
**
** The first parameter is a [sqlite3_stmt | compiled SQL statement].
** {F13761} 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. {F13762} If the Nth column of the result set is an
** expression or subquery, then a NULL pointer is returned.
int sqlite3_data_count(sqlite3_stmt *pStmt);
/*
-** CAPI3REF: Fundamental Datatypes {F10260}
+** CAPI3REF: Fundamental Datatypes {F10265}
**
-** {F10261}Every value in SQLite has one of five fundamental datatypes:
+** {F10266}Every value in SQLite has one of five fundamental datatypes:
**
** <ul>
** <li> 64-bit signed integer
);
/*
-** CAPI3REF: Text Encodings {F10260}
+** CAPI3REF: Text Encodings {F10267}
**
** These constant define integer codes that represent the various
** text encodings supported by SQLite.
** 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
** 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()].
+**
*/
const void *sqlite3_value_blob(sqlite3_value*);
int sqlite3_value_bytes(sqlite3_value*);
** 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.
+** {F16211} 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.
+** {F16212} On second and subsequent calls to sqlite3_aggregate_context()
+** for the same aggregate function index, the same buffer is returned. {END}
+** The implementation
** of the aggregate can use the returned buffer to accumulate data.
**
-** The buffer allocated is freed automatically by SQLite whan the aggregate
-** query concludes.
+** {F16213} SQLite automatically frees the allocated buffer when the aggregate
+** query concludes. {END}
**
** The first parameter should be a copy of the
** [sqlite3_context | SQL function context] that is the first
/*
** 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.
+** {F16241} 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.
+** {U16243} This routine must be called from the same thread in which
+** the application-defined function is running.
*/
void *sqlite3_user_data(sqlite3_context*);
** invocations of the same function so that the original pattern string
** does not need to be recompiled on each invocation.
**
+** {F16271}
** 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.
+** {F16272} 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.
+**
+** {F16275} 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. {END} Subsequent
+** calls to sqlite3_get_auxdata() might return this data, if it has
+** not been destroyed.
+** {F16277} 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. {END}
**
** In practice, meta-data is preserved between function calls for
** expressions that are constant at compile time. This includes literal
** These routines must be called from the same thread in which
** the SQL function is running.
*/
-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*));
/*
** [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.
-**
-** These routines must be called from within the same thread as
-** the SQL function associated with the [sqlite3_context] pointer.
+** {F16402} 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.
+** {F16403} 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.
+**
+** {F16407} The sqlite3_result_double() interface sets the result from
+** an application defined function to be a floating point value specified
+** by its 2nd argument.
+**
+** {F16409} The sqlite3_result_error() and sqlite3_result_error16() functions
+** cause the implemented SQL function to throw an exception.
+** {F16411} 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. {F16412} SQLite interprets the error
+** message string from sqlite3_result_error() as UTF8. {F16413} SQLite
+** interprets the string from sqlite3_result_error16() as UTF16 in native
+** byte order. {F16414} 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.
+** {F16415} 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.
+** {F16417} The sqlite3_result_error() and sqlite3_result_error16()
+** routines make a copy private copy of the error message text before
+** they return. {END} Hence, the calling function can deallocate or
+** modify the text after they return without harm.
+**
+** {F16421} The sqlite3_result_toobig() interface causes SQLite
+** to throw an error indicating that a string or BLOB is to long
+** to represent. {F16422} The sqlite3_result_nomem() interface
+** causes SQLite to throw an exception indicating that the a
+** memory allocation failed.
+**
+** {F16431} 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.
+** {F16432} 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.
+**
+** {F16437} The sqlite3_result_null() interface sets the return value
+** of the application-defined function to be NULL.
+**
+** {F16441} 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.
+** {F16442} SQLite takes the text result from the application from
+** the 2nd parameter of the sqlite3_result_text* interfaces.
+** {F16444} 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.
+** {F16447} 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.
+** {F16451} 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.
+** {F16453} 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.
+** {F16454} 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.
+**
+** {F16461} 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. {F16463} 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.
+**
+** {U16491} 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.
*/
void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_double(sqlite3_context*, double);
/*
** CAPI3REF: Define New Collating Sequences {F16600}
**
+** {F16601}
** These functions are used to add new collation sequences to the
** [sqlite3*] handle specified as the first argument.
**
+** {F16602}
** 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(). {F16603} In all cases
** the name is passed as the second function argument.
**
+** {F16604}
** 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. {F16605} 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.
**
+** {F16607}
** 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. {F16609} If it is NULL, this is the same as deleting the collation
+** sequence (so that SQLite cannot call it anymore).
+** {F16611} 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,
+** {F16612}
+** 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).
**
+** {F16615}
** The sqlite3_create_collation_v2() works like sqlite3_create_collation()
** excapt that it takes an extra argument which is a destructor for
-** the collation. The destructor is called when the collation is
+** the collation. {F16617} 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().
+** {F16618} 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.
*/
int sqlite3_create_collation(
sqlite3*,
/*
** CAPI3REF: Collation Needed Callbacks {F16700}
**
+** {F16701}
** To avoid having to register all collation sequences before a database
** can be used, a single callback function may be registered with the
** database handle to be called whenever an undefined collation sequence is
** required.
**
+** {F16702}
** 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
-** are passed as UTF-16 in machine native byte order. A call to either
+** encoded in UTF-8. {F16703} If sqlite3_collation_needed16() is used, the names
+** are passed as UTF-16 in machine native byte order. {F16704} A call to either
** function replaces any existing callback.
**
-** When the callback is invoked, the first argument passed is a copy
+** {F16705} 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
-** required collation sequence.
+** sqlite3_collation_needed16(). {F16706} The second argument is the database
+** handle. {F16707} The third argument is one of [SQLITE_UTF8],
+** [SQLITE_UTF16BE], or [SQLITE_UTF16LE], indicating the most
+** desirable form of the collation sequence function required.
+** {F16708} The fourth parameter is the name of the
+** required collation sequence. {END}
**
** The callback function should register the desired collation using
** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
/*
** CAPI3REF: Suspend Execution For A Short Time {F10530}
**
-** This function causes the current thread to suspend execution
+** {F10531} 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
+** {F10532} If the operating system does not support sleep requests with
** millisecond time resolution, then the time will be rounded up to
-** the nearest second. The number of milliseconds of sleep actually
+** the nearest second. {F10533} The number of milliseconds of sleep actually
** requested from the operating system is returned.
**
-** SQLite implements this interface by calling the xSleep()
-** method of the default [sqlite3_vfs] object.
+** {F10534} SQLite implements this interface by calling the xSleep()
+** method of the default [sqlite3_vfs] object. {END}
*/
int sqlite3_sleep(int);
/*
** 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.
+** {F12931} The sqlite3_get_autocommit() interfaces returns non-zero or
+** zero if the given database connection is or is not in autocommit mode,
+** respectively. {F12932} Autocommit mode is on
+** by default. {F12933} Autocommit mode is disabled by a BEGIN statement.
+** {F12934} Autocommit mode is reenabled by a COMMIT or ROLLBACK. {END}
**
** If certain kinds of errors occur on a statement within a multi-statement
** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR],
** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
-** transaction might be rolled back automatically. The only way to
+** transaction might be rolled back automatically. {F12935} The only way to
** find out if SQLite automatically rolled back the transaction after
-** an error is to use this function.
+** an error is to use this function. {END}
**
-** If another thread changes the autocommit status of the database
+** {U12936} If another thread changes the autocommit status of the database
** connection while this routine is running, then the return value
-** is undefined.
+** is undefined. {END}
*/
int sqlite3_get_autocommit(sqlite3*);
/*
** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120}
**
-** Return the [sqlite3*] database handle to which a
+** {F13121} The sqlite3_db_handle interface
+** returns the [sqlite3*] database handle to which a
** [sqlite3_stmt | prepared statement] belongs.
-** This is the same database handle that was
+** {F13122} 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.
*/
/*
** 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
-** to the callback. If the callback on a commit hook function
+** {F12951} The sqlite3_commit_hook() interface registers a callback
+** function to be invoked whenever a transaction is committed.
+** {F12952} Any callback set by a previous call to sqlite3_commit_hook()
+** for the same database connection is overridden.
+** {F12953} The sqlite3_rollback_hook() interface registers a callback
+** function to be invoked whenever a transaction is committed.
+** {F12954} Any callback set by a previous call to sqlite3_commit_hook()
+** for the same database connection is overridden.
+** {F12956} The pArg argument is passed through
+** to the callback. {F12957} 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.
+** {F12958} If another function was previously registered, its
+** pArg value is returned. Otherwise NULL is returned.
**
-** Registering a NULL function disables the callback.
+** {F12959} Registering a NULL function disables the callback.
**
-** For the purposes of this API, a transaction is said to have been
+** {F12961} 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.
+** {F12962} The rollback callback is not invoked if a transaction is
+** automatically rolled back because the database connection is closed.
+** {F12964} The rollback callback is not invoked if a transaction is
+** rolled back because a commit callback returned non-zero.
+** <todo> Check on this </todo> {END}
**
** These are experimental interfaces and are subject to change.
*/
/*
** CAPI3REF: Data Change Notification Callbacks {F12970}
**
-** Register a callback function with the database connection identified by the
+** {F12971} 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
+** {F12972} 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
+** {F12974} The second argument is a pointer to the function to invoke when a
+** row is updated, inserted or deleted.
+** {F12976} The first argument to the callback is
+** a copy of the third argument to sqlite3_update_hook().
+** {F12977} 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.
+** {F12978} 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.
+** {F12979} The final callback parameter is
+** the rowid of the row.
+** {F12981} 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
+** {F12983} 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.
+** {F12984} If another function was previously registered, its pArg value
+** is returned. {F12985} Otherwise NULL is returned.
*/
void *sqlite3_update_hook(
sqlite3*,
/*
** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330}
**
+** {F10331}
** This routine enables or disables the sharing of the database cache
** and schema data structures between connections to the same database.
+** {F10332}
** 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
+** {F10333} 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.
**
+** {F10334}
** 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.
+** {F10335} Existing database connections continue use the sharing mode
+** that was in effect at the time they were opened. {END}
**
-** Virtual tables cannot be used with a shared cache. When shared
+** Virtual tables cannot be used with a shared cache. {F10336} When shared
** cache is enabled, the [sqlite3_create_module()] API used to register
-** virtual tables will always return an error.
+** virtual tables will always return an error. {END}
**
-** This routine returns [SQLITE_OK] if shared cache was
-** enabled or disabled successfully. An [SQLITE_ERROR | error code]
-** is returned otherwise.
+** {F10337} This routine returns [SQLITE_OK] if shared cache was
+** enabled or disabled successfully. {F10338} An [SQLITE_ERROR | error code]
+** is returned otherwise. {END}
**
-** Shared cache is disabled by default. But this might change in
+** {F10339} Shared cache is disabled by default. {END} But this might change in
** future releases of SQLite. Applications that care about shared
** cache setting should set it explicitly.
*/
/*
** 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).
+** {F17341} 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. {F16342} sqlite3_release_memory() 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 {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
+** {F16351} The sqlite3_soft_heap_limit() interface
+** places a "soft" limit on the amount of heap memory that may be allocated
+** by SQLite. {F16352} 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.
+** is made. {END}
**
-** The limit is called "soft", because if [sqlite3_release_memory()] cannot
+** {F16353} 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.
**
+** {F16354}
** A negative or zero value for N means that there is no soft heap limit and
** [sqlite3_release_memory()] will only be called when memory is exhausted.
-** The default value for the soft heap limit is zero.
+** {F16355} 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
-** continue without error or notification. This is why the limit is
+** SQLite makes a best effort to honor the soft heap limit.
+** {F16356} But if the soft heap limit cannot honored, execution will
+** continue without error or notification. {END} 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. {F16357} The value specified for the soft heap limit
+** is an upper bound on the total memory allocation for all threads. {END} In
** version 3.5.0 there is no mechanism for limiting the heap usage for
** individual threads.
*/
/*
** CAPI3REF: Load An Extension {F12600}
**
-** 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".
+** {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".
**
-** Return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
+** {F12604} The sqlite3_load_extension() interface shall
+** 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
+** {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.
*/
** 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 {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_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.
/*
** CAPI3REF: Reset Automatic Extension Loading {F12660}
**
-** Disable all previously registered automatic extensions. This
+** {F12661} This function disables all previously registered
+** automatic extensions. {END} This
** routine undoes the effect of all prior [sqlite3_automatic_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.
/*
** 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:
+** {F17811} 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:
**
** <pre>
** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
-** </pre>
+** </pre> {END}
**
-** If the flags parameter is non-zero, the blob is opened for
+** {F17812} 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.
+** access. {END}
**
-** On success, [SQLITE_OK] is returned and the new
-** [sqlite3_blob | blob handle] is written to *ppBlob.
-** Otherwise an error code is returned and
+** {F17813} On success, [SQLITE_OK] is returned and the new
+** [sqlite3_blob | blob handle] is written to *ppBlob.
+** {F17814} 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
+** {F17815} This function sets the database-handle error code and message
** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
+** <todo>We should go through and mark all interfaces that behave this
+** way with a similar statement</todo>
*/
int sqlite3_blob_open(
sqlite3*,
**
** Close an open [sqlite3_blob | blob handle].
**
-** Closing a BLOB might cause the current transaction to commit.
-** If any writes were made to the BLOB, they might be held in cache
-** until the close operation. Closing the BLOB forces the changes
+** {F17831} 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.
+** {F17832} 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. Any errors that occur during
+** 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
+** {F17839} The BLOB is closed unconditionally. Even if this routine returns
** an error code, the BLOB is still closed.
*/
int sqlite3_blob_close(sqlite3_blob *);
**
** 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
+** {F17851} n bytes of data are copied into buffer
** z from the open blob, starting at offset iOffset.
**
-** On success, SQLITE_OK is returned. Otherwise, an
+** {F17852} If offset iOffset is less than n bytes from the end of the blob,
+** [SQLITE_ERROR] is returned and no data is read. {F17853} If n is
+** less than zero [SQLITE_ERROR] is returned and no data is read.
+**
+** {F17854} On success, SQLITE_OK is returned. Otherwise, an
** [SQLITE_ERROR | SQLite error code] or an
** [SQLITE_IOERR_READ | extended error code] is returned.
*/
**
** This function is used to write data into an open
** [sqlite3_blob | blob-handle] from a user supplied buffer.
-** n bytes of data are copied from the buffer
+** {F17871} n bytes of data are copied from the buffer
** pointed to by z into the open blob, starting at offset iOffset.
**
-** If the [sqlite3_blob | blob-handle] passed as the first argument
+** {F17872} If the [sqlite3_blob | blob-handle] passed as the first argument
** 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.
+** {F17873} This function may only modify the contents of the blob; it is
+** not possible to increase the size of a blob using this API.
+** {F17874} If offset iOffset is less than n bytes from the end of the blob,
+** [SQLITE_ERROR] is returned and no data is written. {F17875} If n is
+** less than zero [SQLITE_ERROR] is returned and no data is written.
**
-** On success, SQLITE_OK is returned. Otherwise, an
+** {F17876} On success, SQLITE_OK is returned. Otherwise, an
** [SQLITE_ERROR | SQLite error code] or an
** [SQLITE_IOERR_READ | extended error code] is returned.
*/
** 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
-** pointer is returned. If zVfsName is NULL then the default
-** VFS is returned.
-**
-** 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
-** same name are registered, the behavior is undefined. If a
+** {F11201} The sqlite3_vfs_find() interface returns a pointer to
+** a VFS given its name. {F11202} Names are case sensitive.
+** {F11203} Names are zero-terminated UTF-8 strings.
+** {F11204} If there is no match, a NULL
+** pointer is returned. {F11205} If zVfsName is NULL then the default
+** VFS is returned. {END}
+**
+** {F11210} New VFSes are registered with sqlite3_vfs_register().
+** {F11211} Each new VFS becomes the default VFS if the makeDflt flag is set.
+** {F11212} The same VFS can be registered multiple times without injury.
+** {F11213} To make an existing VFS into the default VFS, register it again
+** with the makeDflt flag set. {U11214} If two different VFSes with the
+** same name are registered, the behavior is undefined. {U11215} If a
** VFS is registered with a name that is NULL or an empty string,
** then the behavior is undefined.
**
-** Unregister a VFS with the sqlite3_vfs_unregister() interface.
-** If the default VFS is unregistered, another VFS is chosen as
+** {F11220} Unregister a VFS with the sqlite3_vfs_unregister() interface.
+** {F11221} If the default VFS is unregistered, another VFS is chosen as
** the default. The choice for the new VFS is arbitrary.
*/
sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
** 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:
**
** <ul>
** <li> SQLITE_MUTEX_STATIC_MEM2
** <li> SQLITE_MUTEX_STATIC_PRNG
** <li> SQLITE_MUTEX_STATIC_LRU
-** </ul>
+** </ul> {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()].
*/
** never uses these routines except inside an assert() and applications
** 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. {U17083} 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.
**
** {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()]. {U11307} The underlying xFileControl method might
-** also return SQLITE_ERROR. {U11308} 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. {END}
**
projects / thirdparty / sqlite.git / commitdiff
