Lines Matching refs:is
5 ** a legal notice, here is a blessing:
14 ** or constant definition does not appear in this file, then it is
15 ** not a published API of SQLite, is subject to change without
24 ** The official C-language API documentation for SQLite is derived
25 ** from comments in this file. This file is the authoritative source
28 ** The name of this file under configuration management is "sqlite.h.in".
87 ** evaluates to a string literal that is the SQLite version in the
88 ** format "X.Y.Z" where X is the major version number (always 3 for
89 ** SQLite3) and Y is the minor version number and Z is the release number.)^
94 ** be larger than the release from which it is derived. Either Y will
123 ** the header, and thus insure that the application is
135 ** function is provided for use in DLLs since DLL users usually do not have
139 ** to a string constant whose value is the same as the [SQLITE_SOURCE_ID]
157 ** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
158 ** are enabled and SQLite is threadsafe. When the
159 ** [SQLITE_THREADSAFE] macro is 0,
160 ** the mutexes are omitted. Without the mutexes, it is not safe
164 ** So if speed is of utmost importance, it makes sense to disable
166 ** ^The default behavior is for mutexes to be enabled.
169 ** version of SQLite that it is linking against was compiled with
173 ** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
181 ** is unchanged by calls to sqlite3_config().)^
191 ** Each open SQLite database is represented by a pointer to an instance of
192 ** the opaque structure named "sqlite3". It is useful to think of an sqlite3
195 ** is its destructor. There are many other interfaces (such as
206 ** Because there is no cross-platform way to specify 64-bit integer types
242 ** ^The sqlite3_close() routine is the destructor for the [sqlite3] object.
243 ** ^Calls to sqlite3_close() return SQLITE_OK if the [sqlite3] object is
249 ** sqlite3_close() is called on a [database connection] that still has
253 ** ^If [sqlite3_close()] is invoked while a transaction is open,
254 ** the transaction is automatically rolled back.
260 ** ^Calling sqlite3_close() with a NULL pointer argument is a
267 ** This is legacy and deprecated. It is included for historical
268 ** compatibility and is not documented.
275 ** The sqlite3_exec() interface is a convenience wrapper around
284 ** sqlite3_exec() is not NULL, then it is invoked for each result row
286 ** to sqlite3_exec() is relayed through to the 1st argument of each
288 ** is NULL, then no callback is ever invoked and result rows are
294 ** is not NULL then any error message is written into memory obtained
298 ** of sqlite3_exec() after the error message string is no longer needed.
299 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
307 ** ^The 2nd argument to the sqlite3_exec() callback function is the
309 ** callback is an array of pointers to strings obtained as if from
311 ** result row is NULL then the corresponding string pointer for the
312 ** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
313 ** sqlite3_exec() callback is an array of pointers to strings where each
317 ** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
320 ** is not changed.
326 ** is a valid and open [database connection].
328 ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
330 ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
359 #define SQLITE_BUSY 5 /* The database file is locked */
360 #define SQLITE_LOCKED 6 /* A table in the database is locked */
365 #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
367 #define SQLITE_FULL 13 /* Insertion failed because database is full */
370 #define SQLITE_EMPTY 16 /* Database is empty */
380 #define SQLITE_NOTADB 26 /* File opened that is not a database file */
456 ** object returns an integer which is a vector of the these
464 ** are aligned to an address which is an integer multiple of
466 ** that when data is appended to a file, the data is appended
467 ** first then the size of the file is extended, never the other
469 ** information is written to disk in the same order as calls
504 ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
522 ** for their own use. The pMethods entry is a pointer to an
544 ** is for the xOpen to set the sqlite3_file.pMethods element to NULL.
547 ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
548 ** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
562 ** either in this process or in some other process, is holding a RESERVED,
566 ** The xFileControl() method is a generic interface that allows custom
568 ** [sqlite3_file_control()] interface. The second "op" argument is an
569 ** integer opcode. The third argument is a generic pointer intended to
576 ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
581 ** device that underlies the file. The sector size is the
604 ** are aligned to an address which is an integer multiple of
606 ** that when data is appended to a file, the data is appended
607 ** first then the size of the file is extended, never the other
609 ** information is written to disk in the same order as calls
643 ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
648 ** is used during testing and only needs to be supported when SQLITE_TEST
649 ** is defined.
675 ** The value of the iVersion field is initially 1 but may be larger in
677 ** object when the iVersion value is increased. Note that the structure
682 ** The szOsFile field is the size of the subclassed [sqlite3_file]
683 ** structure used by this VFS. mxPathname is the maximum length of
693 ** The pNext field is the only field in the sqlite3_vfs
703 ** is either a NULL pointer or string obtained
705 ** the string will be valid and unchanged until xClose() is
709 ** If the zFilename parameter is xOpen is a NULL pointer then xOpen
711 ** xFilename parameter is NULL it will also be the case that the
716 ** or [sqlite3_open16()] is used, then flags includes at least
751 ** deleted when it is closed. The [SQLITE_OPEN_DELETEONCLOSE]
754 ** The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
758 ** SQLITE_OPEN_CREATE, is used to indicate that file should always
759 ** be created, and that it is an error if it already exists.
760 ** It is <i>not</i> used to indicate the file should be opened
775 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
776 ** to test whether a file is at least readable. The file can be a
781 ** is also passed as a parameter to both methods. If the output buffer
782 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
790 ** of good-quality randomness into zOut. The return value is
827 ** what kind of permissions the xAccess method is looking for.
831 ** checks whether the file is both readable and writable.
833 ** checks whether the file is readable.
849 ** A call to sqlite3_initialize() is an "effective" call if it is
850 ** the first time sqlite3_initialize() is invoked during the lifetime of
851 ** the process, or if it is the first time sqlite3_initialize() is invoked
856 ** A call to sqlite3_shutdown() is an "effective" call if it is the first
861 ** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
862 ** is not. The sqlite3_shutdown() interface must only be called from a
872 ** ^If for some reason, sqlite3_initialize() is unable to initialize
873 ** the library (perhaps it is unable to allocate a needed resource such
876 ** ^The sqlite3_initialize() routine is called internally by many other
880 ** initialized when [sqlite3_open()] is called if it has not be initialized
881 ** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
885 ** it is recommended that applications always invoke sqlite3_initialize()
888 ** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
902 ** interface is called automatically by sqlite3_initialize() and
903 ** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
905 ** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
922 ** The sqlite3_config() interface is used to make global configuration
924 ** the application. The default configuration is recommended for most
925 ** applications and so this routine is usually not necessary. It is
928 ** The sqlite3_config() interface is not threadsafe. The application
930 ** threads while sqlite3_config() is running. Furthermore, sqlite3_config()
933 ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
938 ** The first argument to sqlite3_config() is an integer
940 ** what property of SQLite is to be configured. Subsequent arguments
944 ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
945 ** ^If the option is unknown or SQLite is unable to set the option
954 ** The sqlite3_db_config() interface is used to make configuration
955 ** changes to a [database connection]. The interface is similar to
959 ** the database connection is created using [sqlite3_open()],
962 ** The second argument to sqlite3_db_config(D,V,...) is the
964 ** aspect of the [database connection] is being configured.
965 ** The only choice for this value is [SQLITE_DBCONFIG_LOOKASIDE].
970 ** the call is considered successful.
981 ** This object is used in only one place in the SQLite interface.
982 ** A pointer to an instance of this object is the argument to
983 ** [sqlite3_config()] when the configuration option is
993 ** and that this object is only useful to a tiny minority of applications
994 ** with specialized memory allocation requirements. This object is
1003 ** with the exception that if the second argument to xRealloc is zero,
1006 ** xRealloc is always a value returned by a prior call to xRoundup.
1013 ** is always at least as big as the requested size but may be larger.
1025 ** structures. The xShutdown method is invoked (indirectly) by
1027 ** by xInit. The pAppData pointer is used as the only parameter to
1032 ** xShutdown method is only called from [sqlite3_shutdown()] so it does
1035 ** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
1036 ** it is by default) and so the methods are automatically serialized.
1037 ** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
1068 ** is invoked.
1075 ** by a single thread. ^If SQLite is compiled with
1077 ** it is not possible to change the [threading mode] from its default
1086 ** The application is responsible for serializing access to
1090 ** [database connection] at the same time. ^If SQLite is compiled with
1092 ** it is not possible to set the Multi-thread [threading mode] and
1101 ** In this mode (which is the default when SQLite is compiled with
1104 ** application is free to use the same [database connection] or the
1106 ** ^If SQLite is compiled with
1108 ** it is not possible to set the Serialized [threading mode] and
1113 ** <dd> ^(This option takes a single argument which is a pointer to an
1121 ** <dd> ^(This option takes a single argument which is a pointer to an
1123 ** structure is filled with the currently defined memory allocation routines.)^
1139 ** ^Memory allocation statistics are enabled by default unless SQLite is
1156 ** never require a scratch buffer that is more than 6 times the database
1158 ** what is provided by this configuration option, then
1165 ** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option.
1170 ** page header. ^The page header size is 20 to 40 bytes depending on
1171 ** the host architecture. ^It is harmless, apart from the wasted memory,
1176 ** page cache memory is needed beyond what is provided by this option, then
1189 ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
1192 ** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
1194 ** allocator is engaged to handle all of SQLites memory allocation needs.
1199 ** <dd> ^(This option takes a single argument which is a pointer to an
1204 ** [sqlite3_config()] returns. ^If SQLite is compiled with
1206 ** the entire mutexing subsystem is omitted from the build and hence calls to
1211 ** <dd> ^(This option takes a single argument which is a pointer to an
1214 ** structure is filled with the currently defined mutex routines.)^
1217 ** profiling or testing, for example. ^If SQLite is compiled with
1219 ** the entire mutexing subsystem is omitted from the build and hence calls to
1226 ** [database connection]. The first argument is the
1227 ** size of each lookaside buffer slot and the second is the number of
1234 ** <dd> ^(This option takes a single argument which is a pointer to
1240 ** <dd> ^(This option takes a single argument which is a pointer to an
1257 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
1275 ** is invoked.
1281 ** ^The first argument (the third parameter to [sqlite3_db_config()] is a
1285 ** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
1286 ** size of each lookaside buffer slot. ^The third argument is the number of
1290 ** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
1312 ** integer key called the [ROWID | "rowid"]. ^The rowid is always available
1316 ** is another alias for the rowid.
1321 ** have ever occurred on that database connection, zero is returned.
1324 ** row is returned by this routine as long as the trigger is running.
1328 ** ^An [INSERT] that fails due to a constraint violation is not a
1338 ** ^For the purposes of this routine, an [INSERT] is considered to
1339 ** be successful even if it is subsequently rolled back.
1341 ** This function is accessible to SQL statements via the
1346 ** function is running and thus changes the last insert [rowid],
1347 ** then the value returned by [sqlite3_last_insert_rowid()] is
1368 ** ^(A "row change" is a change to a single row of a single table
1374 ** A "trigger context" is a scope of execution that begins and
1377 ** evaluated outside of any trigger. This is the "top level"
1379 ** new trigger context is entered for the duration of that one
1402 ** while [sqlite3_changes()] is running then the value returned
1403 ** is unpredictable and not meaningful.
1421 ** the statement that makes them is completed (when the statement handle
1422 ** is passed to [sqlite3_reset()] or [sqlite3_finalize()]).
1428 ** while [sqlite3_total_changes()] is running then the value
1429 ** returned is unpredictable and not meaningful.
1437 ** return at its earliest opportunity. This routine is typically
1442 ** ^It is safe to call this routine from a thread different from the
1443 ** thread that is currently running the database operation. But it
1444 ** is not safe to call this routine with a [database connection] that
1445 ** is closed or might close before sqlite3_interrupt() returns.
1447 ** ^If an SQL operation is very nearly finished at the time when
1448 ** sqlite3_interrupt() is called, then it might not have an opportunity
1451 ** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
1452 ** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
1453 ** that is inside an explicit transaction, then the entire transaction
1456 ** ^The sqlite3_interrupt(D) call is in effect until all currently running
1464 ** SQL statements is a no-op and has no effect on SQL statements
1468 ** is running then bad things will likely happen.
1477 ** if additional input is needed before sending the text into
1479 ** appears to be a complete SQL statement. ^A statement is judged to be
1480 ** complete if it ends with a semicolon token and is not a prefix of a
1487 ** ^These routines return 0 if the statement is incomplete. ^If a
1488 ** memory allocation fails, then SQLITE_NOMEM is returned.
1494 ** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
1497 ** regardless of whether or not the input SQL is complete.)^
1512 ** an attempt is made to open a database table that another thread
1515 ** ^If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]
1516 ** is returned immediately upon encountering the lock. ^If the busy callback
1517 ** is not NULL, then the callback might be invoked with two arguments.
1519 ** ^The first argument to the busy handler is a copy of the void* pointer which
1520 ** is the third argument to sqlite3_busy_handler(). ^The second argument to
1521 ** the busy handler callback is the number of times that the busy handler has
1524 ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
1526 ** is made to open the database for reading and the cycle repeats.
1529 ** when there is lock contention. ^If SQLite determines that invoking the busy
1532 ** Consider a scenario where one process is holding a read lock that
1533 ** it is trying to promote to a reserved lock and
1534 ** a second process is holding a reserved lock that it is trying
1536 ** because it is blocked by the second and the second process cannot
1537 ** proceed because it is blocked by the first. If both processes
1543 ** ^The default busy callback is NULL.
1545 ** ^The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
1546 ** when SQLite is in the middle of a large transaction where all the
1551 ** readers. ^If it is unable to promote the lock, then the in-memory
1553 ** code is promoted from the relatively benign [SQLITE_BUSY] to
1558 ** this is important.
1578 ** for a specified amount of time when a table is locked. ^The handler
1590 ** this routine, that other busy handler is cleared.)^
1597 ** Definition: A <b>result table</b> is memory data structure created by the
1606 ** A result table is an array of pointers to zero-terminated UTF-8 strings.
1614 ** It is not safe to pass a result table directly to [sqlite3_free()].
1618 ** is as follows:
1629 ** result table has 8 entries. Suppose the result table is stored
1653 ** [sqlite3_free_table()] is able to release the memory properly and safely.
1655 ** ^(The sqlite3_get_table() interface is implemented as a wrapper around
1683 ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
1686 ** ^(In sqlite3_snprintf() routine is similar to "snprintf()" from
1687 ** the standard C library. The result is written into the
1688 ** buffer supplied as the second parameter whose size is given by
1690 ** first two parameters is reversed from snprintf().)^ This is an
1699 ** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
1700 ** guarantees that the buffer is always zero-terminated. ^The first
1701 ** parameter "n" is the total size of the buffer, including space for
1708 ** is are "%q", "%Q", and "%z" options.
1712 ** %q is designed for use inside a string literal.)^ By doubling each '\''
1730 ** Because the %q format string is used, the '\'' character in zText
1731 ** is escaped and the SQL generated is as follows:
1737 ** This is correct. Had we used %s instead of %q, the generated SQL
1744 ** This second example is an SQL syntax error. As a general rule you should
1749 ** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
1759 ** variable even if the zText variable is a NULL pointer.
1763 ** the result, [sqlite3_free()] is called on the input string.)^
1778 ** of memory at least N bytes in length, where N is the parameter.
1779 ** ^If sqlite3_malloc() is unable to obtain sufficient free
1781 ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
1786 ** that it might be reused. ^The sqlite3_free() routine is
1787 ** a no-op if is called with a NULL pointer. Passing a NULL pointer
1788 ** to sqlite3_free() is harmless. After being freed, memory
1792 ** might result if sqlite3_free() is called with a non-NULL pointer that
1796 ** prior memory allocation to be at least N bytes, where N is the
1797 ** second parameter. The memory allocation to be resized is the first
1799 ** is a NULL pointer then its behavior is identical to calling
1800 ** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
1801 ** ^If the second parameter to sqlite3_realloc() is zero or
1802 ** negative then the behavior is exactly the same as calling
1803 ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
1805 ** of at least N bytes in size or NULL if sufficient memory is unavailable.
1806 ** ^If M is the size of the prior allocation, then min(N,M) bytes
1808 ** by sqlite3_realloc() and the prior allocation is freed.
1810 ** is not freed.
1813 ** is always aligned to at least an 8 byte boundary.
1818 ** is no longer provided. Only built-in memory allocators can be used.
1823 ** and whatever filename encoding is used by the particular Windows
1858 ** ^The memory high-water mark is reset to the current value of
1860 ** [sqlite3_memory_highwater()] is true. ^The value returned
1861 ** by [sqlite3_memory_highwater(1)] is the high-water mark
1872 ** already uses the largest possible [ROWID]. The PRNG is also used for
1878 ** ^The first time this routine is invoked (either internally or by
1879 ** the application) the PRNG is seeded using randomness obtained
1881 ** ^On all subsequent invocations, the pseudo-randomness is generated
1892 ** ^The authorizer callback is invoked as SQL statements are being compiled
1895 ** points during the compilation process, as logic is being created
1896 ** to perform various actions, the authorizer callback is invoked to
1907 ** requested is ok. ^When the callback returns [SQLITE_DENY], the
1910 ** access is denied.
1912 ** ^The first parameter to the authorizer callback is a copy of the third
1914 ** to the callback is an integer [SQLITE_COPY | action code] that specifies
1919 ** ^If the action code is [SQLITE_READ]
1921 ** [prepared statement] statement is constructed to substitute
1926 ** ^If the action code is [SQLITE_DELETE] and the callback returns
1928 ** [truncate optimization] is disabled and all rows are deleted individually.
1930 ** An authorizer is used when [sqlite3_prepare | preparing]
1938 ** user-entered SQL is being [sqlite3_prepare | prepared] that
1949 ** The authorizer is disabled by default.
1956 ** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
1961 ** ^Note that the authorizer callback is invoked only during
1962 ** [sqlite3_prepare()] or its variants. Authorization is not
1978 ** to signal SQLite whether or not the action is permitted. See the
1989 ** that is invoked to authorize certain SQL statement actions. The
1990 ** second parameter to the callback is an integer code that specifies
1991 ** what action is being authorized. These are the integer action codes that
1994 ** These action code values signify what kind of operation is to be
1997 ** codes is used as the second parameter. ^(The 5th parameter to the
1998 ** authorizer callback is the name of the database ("main", "temp",
2000 ** is the name of the inner-most trigger or view that is responsible for
2001 ** the access attempt or NULL if this access attempt is directly from
2046 ** ^The callback function registered by sqlite3_trace() is invoked at
2047 ** various times when an SQL statement is being run by [sqlite3_step()].
2048 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
2051 ** as each triggered subprogram is entered. The callbacks for triggers
2054 ** ^The callback function registered by sqlite3_profile() is invoked
2067 ** progress callback - that is invoked periodically during long
2070 ** interface is to keep a GUI updated during a large query.
2072 ** ^If the progress callback returns non-zero, the operation is
2087 ** ^These routines open an SQLite database file whose name is given by the
2088 ** filename argument. ^The filename argument is interpreted as UTF-8 for
2090 ** order for sqlite3_open16(). ^(A [database connection] handle is usually
2091 ** returned in *ppDb, even if an error occurs. The only exception is that
2092 ** if SQLite is unable to allocate memory to hold the [sqlite3] object,
2094 ** object.)^ ^(If the database is opened (and/or created) successfully, then
2095 ** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The
2101 ** sqlite3_open() or sqlite3_open_v2() is called and
2102 ** UTF-16 in the native byte order if sqlite3_open16() is used.
2104 ** Whether or not an error occurs when it is opened, resources
2106 ** passing it to [sqlite3_close()] when it is no longer required.
2118 ** <dd>The database is opened in read-only mode. If the database does not
2119 ** already exist, an error is returned.</dd>)^
2122 ** <dd>The database is opened for reading and writing if possible, or reading
2123 ** only if the file is write protected by the operating system. In either
2124 ** case the database must already exist, otherwise an error is returned.</dd>)^
2127 ** <dd>The database is opened for reading and writing, and is creates it if
2128 ** it does not already exist. This is the behavior that is always used for
2132 ** If the 3rd parameter to sqlite3_open_v2() is not one of the
2136 ** then the behavior is undefined.
2138 ** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
2141 ** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
2146 ** cache is enabled using [sqlite3_enable_shared_cache()]. ^The
2148 ** participate in [shared cache mode] even if it is enabled.
2150 ** ^If the filename is ":memory:", then a private, temporary in-memory database
2151 ** is created for the connection. ^This in-memory database will vanish when
2152 ** the database connection is closed. Future versions of SQLite might
2154 ** It is recommended that when a database filename actually does begin with
2158 ** ^If the filename is an empty string, then a private, temporary
2160 ** automatically deleted as soon as the database connection is closed.
2162 ** ^The fourth parameter to sqlite3_open_v2() is the name of the
2164 ** the new database connection should use. ^If the fourth parameter is
2165 ** a NULL pointer then the default [sqlite3_vfs] object is used.
2169 ** codepage is currently defined. Filenames containing international
2195 ** sqlite3_errcode() is undefined. ^The sqlite3_extended_errcode()
2196 ** interface is the same except that it always returns the
2202 ** ^(Memory to hold the error message string is managed internally.
2207 ** When the serialized [threading mode] is in use, it might be the
2231 ** This object is variously known as a "prepared statement" or a
2256 ** on a connection by connection basis. The first parameter is the
2257 ** [database connection] whose limit is to be set or queried. The
2258 ** second parameter is one of the [limit categories] that define a
2259 ** class of constructs to be size limited. The third parameter is the
2262 ** ^If the new limit is a negative number, the limit is unchanged.
2263 ** ^(For the limit category of SQLITE_LIMIT_XYZ there is a
2267 ** (The "_LIMIT_" in the name is changed to "_MAX_".))^
2294 ** The synopsis of the meanings of the various limits is shown below.
2295 ** Additional information is available at [limits | Limits in SQLite].
2356 ** The first argument, "db", is a [database connection] obtained from a
2360 ** The second argument, "zSql", is the statement to be compiled, encoded
2365 ** ^If the nByte argument is less than zero, then zSql is read up to the
2366 ** first zero terminator. ^If nByte is non-negative, then it is the maximum
2367 ** number of bytes read from zSql. ^When nByte is non-negative, the
2370 ** that the supplied string is nul-terminated, then there is a small
2372 ** is equal to the number of bytes in the input string <i>including</i>
2375 ** ^If pzTail is not NULL then *pzTail is made to point to the first byte
2377 ** compile the first statement in zSql, so *pzTail is left pointing to
2380 ** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
2381 ** executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set
2382 ** to NULL. ^If the input text contains no SQL (if the input is an empty
2383 ** string or a comment) then *ppStmt is set to NULL.
2384 ** The calling procedure is responsible for deleting the compiled
2389 ** otherwise an [error code] is returned.
2393 ** for backwards compatibility, but their use is discouraged.
2395 ** that is returned (the [sqlite3_stmt] object) contains a copy of the
2405 ** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is
2417 ** interfaces, the underlying reason for the error is returned immediately.
2483 ** a mutex is held. A internal mutex is held for a protected
2484 ** sqlite3_value object but no mutex is held for an unprotected
2485 ** sqlite3_value object. If SQLite is compiled to be single-threaded
2487 ** or if SQLite is run in one of reduced mutex modes
2489 ** then there is no distinction between protected and unprotected
2491 ** for maximum code portability it is recommended that applications
2498 ** [sqlite3_column_value()] is unprotected.
2509 ** The context in which an SQL function executes is stored in an
2511 ** is always first parameter to [application-defined SQL functions].
2542 ** ^The first argument to the sqlite3_bind_*() routines is always
2546 ** ^The second argument is the index of the SQL parameter to be set.
2548 ** SQL parameter is used more than once, second and subsequent
2552 ** for "?NNN" parameters is the value of NNN.
2556 ** ^The third argument is the value to bind to the parameter.
2558 ** ^(In those routines that have a fourth argument, its value is the
2559 ** number of bytes in the parameter. To be clear: the value is the
2561 ** ^If the fourth parameter is negative, the length of the string is
2565 ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
2566 ** string after SQLite has finished with it. ^If the fifth argument is
2568 ** information is in static, unmanaged space and does not need to be freed.
2574 ** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
2575 ** (just an integer to hold its size) while it is being processed.
2577 ** content is later written using
2585 ** routine is passed a [prepared statement] that has been finalized, the
2586 ** result is undefined and probably harmful.
2593 ** ^[SQLITE_RANGE] is returned if the parameter
2594 ** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
2635 ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
2638 ** is included as part of the name.)^
2644 ** ^If the value N is out of range or if the N-th parameter is
2645 ** nameless, then NULL is returned. ^The returned string is
2660 ** index value returned is suitable for use as the second
2662 ** is returned if no matching parameter is found. ^The parameter
2685 ** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
2697 ** UTF-16 string. ^The first parameter is the [prepared statement]
2698 ** that implements the [SELECT] statement. ^The second parameter is the
2699 ** column number. ^The leftmost column is number 0.
2701 ** ^The returned string pointer is valid until either the [prepared statement]
2702 ** is destroyed by [sqlite3_finalize()] or until the next call to
2707 ** NULL pointer is returned.
2709 ** ^The name of a result column is the value of the "AS" clause for
2710 ** that column, if there is an AS clause. If there is no AS clause
2711 ** then the name of the column is unspecified and may change from
2721 ** table column that is the origin of a particular result column in
2727 ** ^The returned string is valid until the [prepared statement] is destroyed
2728 ** using [sqlite3_finalize()] or until the same information is requested
2734 ** ^The first argument to these interfaces is a [prepared statement].
2736 ** the statement, where N is the second function argument.
2737 ** ^The left-most column is column 0 for these routines.
2739 ** ^If the Nth column returned by the statement is an expression or
2740 ** subquery and is not a column value, then all of these functions return
2770 ** ^(The first parameter is a [prepared statement].
2771 ** If this statement is a [SELECT] statement and the Nth column of the
2772 ** returned result set of that [SELECT] is a table column (not an
2774 ** column is returned.)^ ^If the Nth column of the result set is an
2775 ** expression or subquery, then a NULL pointer is returned.
2776 ** ^The returned string is always UTF-8 encoded.
2790 ** is declared to contain a particular type does not mean that the
2791 ** data stored in that column is of the declared type. SQLite is
2792 ** strongly typed, but the typing is dynamic not static. ^Type
2793 ** is associated with individual values, not with the containers
2811 ** new "v2" interface is recommended for new applications but the legacy
2820 ** database locks it needs to do its job. ^If the statement is a [COMMIT]
2822 ** statement. If the statement is not a [COMMIT] and occurs within a
2832 ** is returned each time a new row of data is ready for processing by the
2834 ** sqlite3_step() is called again to retrieve the next row of data.
2843 ** the more specific error code is returned directly by sqlite3_step().
2849 ** be the case that the same database connection is being used by two or
2857 ** We admit that this is a goofy design. The problem has been fixed
2862 ** by sqlite3_step(). The use of the "v2" interface is recommended.
2913 ** result row of a query. ^In every case the first argument is a pointer
2914 ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
2916 ** and the second argument is the index of the column for which information
2922 ** column index is out of range, the result is undefined.
2935 ** of the result column. ^The returned value is one of [SQLITE_INTEGER],
2937 ** returned by sqlite3_column_type() is only meaningful if no type
2939 ** the value returned by sqlite3_column_type() is undefined. Future
2943 ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
2945 ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
2947 ** ^If the result is a numeric value then sqlite3_column_bytes() uses
2951 ** of the string. ^For clarity: the value returned is the number of
2956 ** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary
2959 ** ^The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
2961 ** ^The zero terminator is not included in this count.
2963 ** ^The object returned by [sqlite3_column_value()] is an
2967 ** [sqlite3_column_value()] is used in any other way, including calls
2969 ** or [sqlite3_value_bytes()], then the behavior is undefined.
2972 ** example, if the internal representation is FLOAT and a text result
2973 ** is requested, [sqlite3_snprintf()] is used internally to perform the
2981 ** <tr><td> NULL <td> INTEGER <td> Result is 0
2982 ** <tr><td> NULL <td> FLOAT <td> Result is 0.0
2983 ** <tr><td> NULL <td> TEXT <td> Result is NULL pointer
2984 ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer
3013 ** <li> The initial content is a BLOB and sqlite3_column_text() or
3014 ** sqlite3_column_text16() is called. A zero-terminator might
3016 ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
3017 ** sqlite3_column_text16() is called. The content must be converted
3019 ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
3020 ** sqlite3_column_text() is called. The content must be converted
3027 ** of conversion are done in place when it is possible, but sometimes they
3030 ** ^(The safest and easiest to remember policy is to invoke these routines
3049 ** [sqlite3_finalize()] is called. ^The memory space used to hold strings
3050 ** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned
3055 ** of these routines, a default value is returned. The default value
3056 ** is either the integer 0, the floating point number 0.0, or a NULL
3074 ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
3076 ** SQLITE_OK is returned. ^If execution of the statement failed then an
3077 ** [error code] or [extended error code] is returned.
3081 ** completed execution when this routine is called, that is like
3092 ** The sqlite3_reset() function is called to reset a [prepared statement]
3124 ** two is that the second parameter, the name of the (scalar) function or
3125 ** aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16
3128 ** ^The first parameter is the [database connection] to which the SQL
3129 ** function is to be added. ^If an application uses more than one database
3133 ** The second parameter is the name of the SQL function to be created or
3134 ** redefined. ^The length of the name is limited to 255 bytes, exclusive of
3135 ** the zero-terminator. Note that the name length limit is in bytes, not
3140 ** is the number of arguments that the SQL function or
3141 ** aggregate takes. ^If this parameter is -1, then the SQL function or
3144 ** parameter is less than -1 or greater than 127 then the behavior is
3156 ** If there is only a single implementation which does not care what text
3157 ** encoding is used, then the fourth argument should be [SQLITE_ANY].
3159 ** ^(The fifth parameter is an arbitrary pointer. The implementation of the
3170 ** ^It is permitted to register multiple implementations of the same
3174 ** SQL function is used. ^A function implementation with a non-negative
3175 ** nArg parameter is a better match than a function implementation with
3177 ** matches the database encoding is a better
3178 ** match than a function where the encoding is different.
3179 ** ^A function where the encoding difference is between UTF16le and UTF16be
3180 ** is a closer match than a function where the encoding difference is
3190 ** ^An application-defined function is permitted to call other
3193 ** statement in which the function is running.
3258 ** The 4th parameter to these callbacks is an array of pointers to
3259 ** [protected sqlite3_value] objects. There is one [sqlite3_value] object for
3277 ** numeric affinity to the value. This means that an attempt is
3279 ** such a conversion is possible without loss of information (in other
3280 ** words, if the value is a string that looks like a number)
3281 ** then the conversion is performed. Otherwise no conversion occurs.
3282 ** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
3312 ** ^The first time the sqlite3_aggregate_context(C,N) routine is called
3317 ** the same buffer is returned. Sqlite3_aggregate_context() is normally
3319 ** last time when the xFinal callback is invoked. ^(When no rows match
3321 ** implementation is never called and xFinal() is called exactly once.
3325 ** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer if N is
3328 ** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
3338 ** [sqlite3_context | SQL function context] that is the first parameter
3343 ** the aggregate SQL function is running.
3357 ** the application-defined function is running.
3376 ** associate metadata with argument values. If the same value is passed to
3380 ** function. The compiled version of the regular expression is stored as
3398 ** ^If it is not NULL, SQLite will invoke the destructor
3403 ** SQLite is free to call the destructor and drop metadata on any
3404 ** parameter of any function at any time. ^The only guarantee is that
3405 ** the destructor will be called before the metadata is dropped.
3407 ** ^(In practice, metadata is preserved between function calls for
3412 ** the SQL function is running.
3421 ** These are special values for the destructor that is passed in as the
3423 ** argument is SQLITE_STATIC, it means that the content pointer is constant
3429 ** The typedef is necessary to work around problems in certain
3449 ** an application-defined function to be the BLOB whose content is pointed
3450 ** to by the second parameter and which is N bytes long where N is the
3455 ** bytes and N bytes in size, where N is the value of the 2nd parameter.
3469 ** or sqlite3_result_error16() is negative then SQLite takes as the error
3472 ** sqlite3_result_error16() is non-negative then SQLite takes that many
3480 ** the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error()
3484 ** indicating that a string or BLOB is too long to represent.
3502 ** a text string which is represented as UTF-8, UTF-16 native byte order,
3507 ** is negative, then SQLite takes result text from the 2nd parameter
3510 ** is non-negative, then as many bytes (not characters) of the text
3514 ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
3518 ** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
3519 ** assumes that the text or BLOB result is in constant space and does not
3523 ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
3534 ** [unprotected sqlite3_value] object is required, so either
3564 ** ^The name of the new collation sequence is specified as a UTF-8 string
3567 ** the name is passed as the second function argument.
3580 ** argument. ^If it is NULL, this is the same as deleting the collation
3582 ** ^Each time the application supplied function is invoked, it is passed
3590 ** return negative, zero or positive if the first string is less than,
3594 ** except that it takes an extra argument which is a destructor for
3595 ** the collation. ^The destructor is called when the collation is
3596 ** destroyed and is passed a copy of the fourth parameter void* pointer
3599 ** collation creation functions or when the [database connection] is closed
3633 ** sequence is required.
3635 ** ^If the function is registered using the sqlite3_collation_needed() API,
3636 ** then it is passed the names of undefined collation sequences as strings
3637 ** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
3641 ** ^(When the callback is invoked, the first argument passed is a copy
3643 ** sqlite3_collation_needed16(). The second argument is the database
3644 ** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
3646 ** sequence function required. The fourth parameter is the name of the
3668 ** The code to implement this API is not available in the public release
3677 ** Change the key on an open database. If the current database is not
3679 ** database is decrypted.
3681 ** The code to implement this API is not available in the public release
3698 ** requested from the operating system is returned.
3708 ** ^(If this global variable is made to point to a string which is
3712 ** is a NULL pointer, then SQLite performs a search for an appropriate
3715 ** It is not safe to read or modify this variable in more than one
3716 ** thread at a time. It is not safe to read or modify this variable
3717 ** if a [database connection] is being used at the same time in a separate
3719 ** It is intended that this variable be set once
3727 ** that this variable points to is held in memory obtained from
3730 ** Hence, if this variable is modified directly, either it should be
3741 ** zero if the given database connection is or is not in autocommit mode,
3742 ** respectively. ^Autocommit mode is on by default.
3743 ** ^Autocommit mode is disabled by a [BEGIN] statement.
3744 ** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
3751 ** an error is to use this function.
3754 ** connection while this routine is running, then the return value
3755 ** is undefined.
3764 ** returned by sqlite3_db_handle is the same [database connection]
3775 ** pStmt associated with the [database connection] pDb. ^If pStmt is NULL
3790 ** function to be invoked whenever a transaction is [COMMIT | committed].
3792 ** for the same database connection is overridden.
3794 ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
3796 ** for the same database connection is overridden.
3797 ** ^The pArg argument is passed through to the callback.
3799 ** then the commit is converted into a rollback.
3817 ** operation is allowed to continue normally. ^If the commit hook
3818 ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
3819 ** ^The rollback hook is invoked on a rollback that results from a commit
3822 ** ^For the purposes of this API, a transaction is said to have been
3823 ** rolled back if an explicit "ROLLBACK" statement is executed, or
3825 ** ^The rollback callback is not invoked if a transaction is
3826 ** automatically rolled back because the database connection is closed.
3827 ** ^The rollback callback is not invoked if a transaction is
3840 ** to be invoked whenever a row is updated, inserted or deleted.
3842 ** for the same database connection is overridden.
3844 ** ^The second argument is a pointer to the function to invoke when a
3845 ** row is updated, inserted or deleted.
3846 ** ^The first argument to the callback is a copy of the third argument
3848 ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
3853 ** ^The final callback parameter is the [rowid] of the row.
3854 ** ^In the case of an update, this is the [rowid] after the update takes place.
3856 ** ^(The update hook is not invoked when internal system tables are
3860 ** is not invoked when duplication rows are deleted because of an
3861 ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook
3893 ** to the same database. Sharing is enabled if the argument is true
3894 ** and disabled if the argument is false.)^
3896 ** ^Cache sharing is enabled and disabled for an entire process.
3897 ** This is a change as of SQLite version 3.5.0. In prior versions of SQLite,
3906 ** successfully. An [error code] is returned otherwise.)^
3908 ** ^Shared cache is disabled by default. But this might change in
3922 ** pages to improve performance is an example of non-essential memory.
3933 ** ^If an internal allocation is requested that would exceed the
3934 ** soft heap limit, [sqlite3_release_memory()] is invoked one or
3935 ** more times to free up some space before the allocation is performed.
3937 ** ^The limit is called "soft" because if [sqlite3_release_memory()]
3939 ** the memory is allocated anyway and the current operation proceeds.
3941 ** ^A negative or zero value for N means that there is no soft heap limit and
3942 ** [sqlite3_release_memory()] will only be called when memory is exhausted.
3943 ** ^The default value for the soft heap limit is zero.
3947 ** continue without error or notification.)^ This is why the limit is
3948 ** called a "soft" limit. It is advisory only.
3952 ** runs. Beginning with SQLite version 3.5.0, the soft heap limit is
3954 ** is an upper bound on the total memory allocation for all threads. In
3955 ** version 3.5.0 there is no mechanism for limiting the heap usage for
3967 ** ^The column is identified by the second, third and fourth parameters to
3968 ** this function. ^The second parameter is either the name of the database
3970 ** table or NULL. ^If it is NULL, then all attached databases are searched
3978 ** ^Metadata is returned by writing to the memory locations passed as the 5th
3980 ** NULL, in which case the corresponding element of metadata is omitted.
3989 ** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY
3990 ** <tr><td> 9th <td> int <td> True if column is [AUTOINCREMENT]
3995 ** declaration type and collation sequence is valid only until the next
3998 ** ^If the specified table is actually a view, an [error code] is returned.
4000 ** ^If the specified column is "rowid", "oid" or "_rowid_" and an
4002 ** parameters are set for the explicitly declared column. ^(If there is no
4016 ** cannot be found, an [error code] is returned and an error message left
4019 ** ^This API is only available if the library was compiled with the
4031 int *pAutoinc /* OUTPUT: True if column is auto-increment */
4042 ** ^The entry point is zProc.
4047 ** ^If an error occurs and pzErrMsg is not 0, then the
4072 ** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
4074 ** ^Extension loading is off by default. See ticket #1863.
4089 ** in an array that is obtained from [sqlite3_malloc()]. That memory
4090 ** is deallocated by [sqlite3_reset_auto_extension()].)^
4092 ** ^This function registers an extension entry point that is
4094 ** is opened using [sqlite3_open()], [sqlite3_open16()],
4097 ** multiple times with the same extension is harmless.
4116 ** The interface to the virtual-table mechanism is currently considered
4118 ** If this is a problem for you, do not use the interface at this time.
4141 ** ^A virtual table module is created by filling in a persistent
4144 ** ^The registration remains valid until it is replaced by a different
4146 ** of this structure must not change while it is registered with
4184 ** The sqlite3_index_info structure and its substructures is used to
4194 ** where OP is =, <, <=, >, or >=.)^ ^(The particular operator is
4195 ** stored in aConstraint[].op.)^ ^(The index of the column is stored in
4196 ** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the
4198 ** is usable) and false if it cannot.)^
4206 ** ^Information about the ORDER BY clause is stored in aOrderBy[].
4211 ** the right-hand side of the corresponding aConstraint[] is evaluated
4213 ** is true, then the constraint is assumed to be fully handled by the
4214 ** virtual table and is not checked again by SQLite.)^
4218 ** ^[sqlite3_free()] is used to free idxPtr if and only if
4219 ** needToFreeIdxPtr is true.
4223 ** sorting step is required.
4225 ** ^The estimatedCost value is an estimate of the cost of doing the
4236 unsigned char usable; /* True if this constraint is usable */
4246 int argvIndex; /* if >0, constraint is part of argv to xFilter */
4252 int orderByConsumed; /* True if output is already ordered */
4271 ** ^The module name is registered on the [database connection] specified
4272 ** by the first parameter. ^The name of the module is given by the
4273 ** second parameter. ^The third parameter is a pointer to
4275 ** parameter is an arbitrary client data pointer that is passed through
4277 ** when a new virtual table is be being created or reinitialized.
4280 ** is a pointer to a destructor for the pClientData. ^SQLite will
4281 ** invoke the destructor function (if it is not NULL) when SQLite
4283 ** interface is equivalent to sqlite3_create_module_v2() with a NULL
4309 ** The purpose of this superclass is to define certain fields that are
4314 ** take care that any prior string is freed by a call to [sqlite3_free()]
4316 ** is delivered up to the client application, the string will be automatically
4371 ** before this API is called, a new function is created.)^ ^The implementation
4373 ** the new function is not good for anything by itself. Its only
4374 ** purpose is to be a placeholder function that can be overloaded
4381 ** to a comment remarkably similar to this one) is currently considered
4383 ** If this is a problem for you, do not use the interface at this time.
4416 ** ^If the flags parameter is non-zero, then the BLOB is opened for read
4417 ** and write access. ^If it is zero, the BLOB is opened for read access.
4418 ** ^It is not possible to open a column that is part of an index or primary
4419 ** key for writing. ^If [foreign key constraints] are enabled, it is
4420 ** not possible to open a column that is part of a [child key] for writing.
4422 ** ^Note that the database name is not the filename that contains
4424 ** appears after the AS keyword when the database is connected using [ATTACH].
4425 ** ^For the main database file, the database name is "main".
4426 ** ^For TEMP tables, the database name is "temp".
4428 ** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is written
4429 ** to *ppBlob. Otherwise an [error code] is returned and *ppBlob is set
4433 ** functions. ^Note that the *ppBlob variable is always initialized in a
4437 ** ^(If the row that a BLOB handle points to is modified by an
4439 ** then the BLOB handle is marked as "expired".
4440 ** This is true if any column of the row is changed, even a column
4441 ** other than the one the BLOB handle is open on.)^
4478 ** database connection is in [autocommit mode].
4484 ** at the time when the BLOB is closed. Any errors that occur during
4487 ** ^(The BLOB is closed unconditionally. Even if this routine returns
4488 ** an error code, the BLOB is still closed.)^
4491 ** by a failed call to [sqlite3_blob_open()]) is a harmless no-op.
4513 ** ^(This function is used to read data from an open [BLOB handle] into a
4517 ** ^If offset iOffset is less than N bytes from the end of the BLOB,
4518 ** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is
4519 ** less than zero, [SQLITE_ERROR] is returned and no data is read.
4527 ** Otherwise, an [error code] or an [extended error code] is returned.)^
4541 ** ^This function is used to write data into an open [BLOB handle] from a
4549 ** ^This function may only modify the contents of the BLOB; it is
4551 ** ^If offset iOffset is less than N bytes from the end of the BLOB,
4552 ** [SQLITE_ERROR] is returned and no data is written. ^If N is
4553 ** less than zero [SQLITE_ERROR] is returned and no data is written.
4565 ** Otherwise, an [error code] or an [extended error code] is returned.)^
4579 ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
4582 ** single default VFS that is appropriate for the host computer.
4589 ** ^If there is no match, a NULL pointer is returned.
4590 ** ^If zVfsName is NULL then the default VFS is returned.
4593 ** ^Each new VFS becomes the default VFS if the makeDflt flag is set.
4597 ** same name are registered, the behavior is undefined. If a
4598 ** VFS is registered with a name that is NULL or an empty string,
4599 ** then the behavior is undefined.
4602 ** ^(If the default VFS is unregistered, another VFS is chosen as
4603 ** the default. The choice for the new VFS is arbitrary.)^
4614 ** use by SQLite, code that links against SQLite is
4619 ** is selected automatically at compile-time. ^(The following
4629 ** ^The SQLITE_MUTEX_NOOP implementation is a set of routines
4630 ** that does no real locking and is appropriate for use in
4635 ** ^(If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
4637 ** implementation is included with the library. In this case the
4647 ** to sqlite3_mutex_alloc() is one of these integer constants:
4662 ** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
4663 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
4668 ** implementation is available on the host platform, the mutex subsystem
4681 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
4683 ** mutex types, the same mutex is returned on every call that has
4687 ** allocated dynamic mutex. ^SQLite is careful to deallocate every
4694 ** to enter a mutex. ^If another thread is already within the mutex,
4702 ** kind of mutex more than once, the behavior is undefined.
4709 ** sqlite3_mutex_try() as an optimization so this is acceptable behavior.)^
4713 ** is undefined if the mutex is not currently entered by the
4714 ** calling thread or is not currently allocated. SQLite will
4718 ** sqlite3_mutex_leave() is a NULL pointer, then all three routines
4746 ** ^The xMutexInit method defined by this structure is invoked as
4748 ** ^The xMutexInit routine is calle by SQLite exactly once for each
4751 ** ^The xMutexEnd method defined by this structure is invoked as
4753 ** implementation of this method is expected to release all outstanding
4756 ** interface is invoked exactly once for each call to [sqlite3_shutdown()].
4772 ** The only difference is that the public sqlite3_XXX functions enumerated
4777 ** (i.e. it is acceptable to provide an implementation that segfaults if
4778 ** it is passed a NULL pointer).
4790 ** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
4792 ** If xMutexInit fails in any way, it is expected to clean up after itself
4815 ** provides implementations for these routines when it is compiled
4817 ** are only required to provide these routines if SQLITE_DEBUG is
4818 ** defined and if NDEBUG is not defined.
4821 ** is held or not held, respectively, by the calling thread.
4823 ** ^The implementation is not required to provided versions of these
4828 ** ^If the argument to sqlite3_mutex_held() is a NULL pointer then
4831 ** the reason the mutex does not exist is because the build is not
4833 ** call to sqlite3_mutex_held() to fail, so a non-zero return is
4846 ** which is one of these integer constants.
4867 ** when the [threading mode] is Serialized.
4868 ** ^If the [threading mode] is Single-thread or Multi-thread then this
4890 ** open database file, then SQLITE_ERROR is returned. ^This error
4891 ** code is not remembered and will not be recalled by [sqlite3_errcode()]
4893 ** also return SQLITE_ERROR. There is no way to distinguish between
4904 ** ^The sqlite3_test_control() interface is used to read out internal
4906 ** purposes. ^The first parameter is an operation code that determines
4909 ** This interface is not for use by applications. It exists solely
4911 ** on how the SQLite library is compiled, this interface might not exist.
4915 ** Unlike most of the SQLite API, this function is not guaranteed to
4950 ** ^This interface is used to retrieve runtime status information
4952 ** highwater marks. ^The first argument is an integer code for
4955 ** ^The current value of the parameter is returned into *pCurrent.
4956 ** ^The highest recorded value is returned in *pHighwater. ^If the
4957 ** resetFlag is true, then the highest record value is reset after
4958 ** *pHighwater is written. ^(Some parameters do not record the highest
4960 ** nothing is written into *pHighwater and the resetFlag is ignored.)^
4962 ** value. For these latter parameters nothing is written into *pCurrent.)^
4967 ** This routine is threadsafe but is not atomic. This routine can be
4971 ** and it is possible that another thread might change the parameter
4988 ** <dd>This parameter is the current amount of memory checked out
4993 ** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
4994 ** this parameter. The amount returned is the sum of the allocation
5001 ** *pHighwater parameter to [sqlite3_status()] is of interest.
5002 ** The value written into the *pCurrent parameter is undefined.</dd>)^
5008 ** value returned is in pages, not in bytes.</dd>)^
5022 ** *pHighwater parameter to [sqlite3_status()] is of interest.
5023 ** The value written into the *pCurrent parameter is undefined.</dd>)^
5028 ** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not
5038 ** larger (that is, because the requested allocation was larger than the
5046 ** *pHighwater parameter to [sqlite3_status()] is of interest.
5047 ** The value written into the *pCurrent parameter is undefined.</dd>)^
5050 ** <dd>This parameter records the deepest parser stack. It is only
5051 ** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
5070 ** ^This interface is used to retrieve runtime status information
5071 ** about a single [database connection]. ^The first argument is the
5073 ** is the parameter to interrogate. ^Currently, the only allowed value
5074 ** for the second parameter is [SQLITE_DBSTATUS_LOOKASIDE_USED].
5077 ** ^The current value of the requested parameter is written into *pCur
5078 ** and the highest instantaneous value is written into *pHiwtr. ^If
5079 ** the resetFlg is true, then the highest instantaneous value is
5097 ** if a discontinued or unsupported verb is invoked.
5118 ** that the prepared statement is using a full table scan rather than
5121 ** ^(This interface is used to retrieve and reset counter values from
5122 ** a [prepared statement]. The first argument is the prepared statement
5124 ** is an integer code for a specific [SQLITE_STMTSTATUS_SORT | counter]
5126 ** ^The current value of the requested counter is returned.
5127 ** ^If the resetFlg is true, then the counter is reset to zero after this
5144 ** <dd>^This is the number of times that SQLite has stepped forward in
5150 ** <dd>^This is the number of sort operations that have occurred.
5163 ** The sqlite3_pcache type is opaque. It is implemented by
5181 ** heap memory used by SQLite is used by the page cache to cache data read
5185 ** that memory is allocated and released, and the policies used to
5194 ** ^The xInit() method is called once for each call to [sqlite3_initialize()]
5196 ** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^
5200 ** ^The xShutdown() method is called from within [sqlite3_shutdown()],
5206 ** xShutdown method is only called from [sqlite3_shutdown()] so it does
5213 ** ^The xCreate() method is used to construct a new cache instance. SQLite
5215 ** though this is not guaranteed. ^The
5216 ** first parameter, szPage, is the size in bytes of the pages that must
5218 ** will the page size of the database file that is to be cached plus an
5223 ** ^R is constant for a particular build of SQLite. ^The second argument to
5224 ** xCreate(), bPurgeable, is true if the cache being created will
5226 ** false if it is used for an in-memory database. ^The cache implementation
5228 ** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
5235 ** instance passed as the first argument. This is the value configured using
5237 ** parameter, the implementation is not required to do anything with this
5238 ** value; it is advisory only.
5243 ** ^The xFetch() method is used to fetch a page and return a pointer to it.
5244 ** ^A 'page', in this context, is a buffer of szPage bytes aligned at an
5245 ** 8-byte boundary. ^The page to be fetched is determined by the key. ^The
5246 ** mimimum key value is 1. After it has been retrieved using xFetch, the page
5247 ** is considered to be "pinned".
5249 ** ^If the requested page is already in the page cache, then the page cache
5251 ** intact. ^(If the requested page is not already in the cache, then the
5252 ** behavior of the cache implementation is determined by the value of the
5256 ** <tr><th> createFlag <th> Behaviour when page is not already in cache
5261 ** NULL if allocating a new page is effectively impossible.
5271 ** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
5272 ** as its second argument. ^(If the third parameter, discard, is non-zero,
5274 ** assumes that the next time the page is retrieved from the cache using
5275 ** the xFetch() method, it will be zeroed.)^ ^If the discard parameter is
5276 ** zero, then the page is considered to be unpinned. ^The cache implementation
5279 ** ^(The cache is not required to perform any reference counting. A single
5283 ** ^The xRekey() method is used to change the key value associated with the
5286 ** discarded. ^Any prior cache entry associated with newKey is guaranteed not
5295 ** ^The xDestroy() method is used to delete a cache allocated by xCreate().
5321 ** online backup operation. ^The sqlite3_backup object is created by
5322 ** a call to [sqlite3_backup_init()] and is destroyed by a call to
5334 ** It is useful either for creating backups of databases or
5339 ** ^Exclusive access is required to the destination database for the
5340 ** duration of the operation. ^However the source database is only
5341 ** read-locked while it is actually being read; it is not locked
5344 ** reading or writing to the source database while the backup is underway.
5348 ** <li><b>sqlite3_backup_init()</b> is called once to initialize the
5350 ** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
5352 ** <li><b>sqlite3_backup_finish()</b> is called to release all resources
5363 ** ^The database name is "main" for the main database, "temp" for the
5373 ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
5389 ** ^If N is negative, all remaining source pages are copied.
5395 ** then an [error code] is returned. ^As well as [SQLITE_OK] and
5402 ** the destination is an in-memory database with a different page size
5407 ** is invoked (if one is specified). ^If the
5408 ** busy-handler returns non-zero before the lock is available, then
5409 ** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
5412 ** is being used to write to the source database when sqlite3_backup_step()
5413 ** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
5416 ** [SQLITE_READONLY] is returned, then
5417 ** there is no point in retrying the call to sqlite3_backup_step(). These
5423 ** on the destination file. ^The exclusive lock is not released until either
5424 ** sqlite3_backup_finish() is called or the backup operation is complete
5428 ** ^Because the source database is not locked between calls to
5430 ** through the backup process. ^If the source database is modified by an
5434 ** database is modified by the using the same database connection as is used
5435 ** by the backup operation, then the backup database is automatically
5446 ** active write-transaction on the destination database is rolled back.
5447 ** The [sqlite3_backup] object is invalid
5450 ** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
5458 ** is not a permanent error and does not affect the return value of
5470 ** sqlite3_backup_step(). ^If the source database is modified during a backup
5478 ** purposes while a backup operation is underway or being initialized.
5479 ** ^If SQLite is compiled and configured to support threadsafe database
5484 ** [database connection] is not passed to any other API (by any thread) after
5485 ** sqlite3_backup_init() is called and before the corresponding call to
5488 ** and so no error code is reported, but the operations may malfunction
5490 ** backup is in progress might also also cause a mutex deadlock.
5494 ** is not accessed while the backup is running. In practice this means
5496 ** backed up to is not accessed by any connection within the process,
5499 ** The [sqlite3_backup] object itself is partially threadsafe. Multiple
5503 ** same time as another thread is invoking sqlite3_backup_step() it is
5527 ** ^This API is only available if the library was compiled with the
5536 ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
5538 ** has locked the required resource is stored internally. ^After an
5542 ** when the blocking connections current transaction is concluded. ^The
5543 ** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
5546 ** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
5547 ** there is a chance that the blocking connection will have already
5548 ** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
5549 ** If this happens, then the specified callback is invoked immediately,
5552 ** ^If the blocked connection is attempting to obtain a write-lock on a
5558 ** blocked connection. If sqlite3_unlock_notify() is called when the
5560 ** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
5562 ** unlock-notify callback is cancelled. ^The blocked connections
5566 ** The unlock-notify callback is not reentrant. If an application invokes
5570 ** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
5575 ** When an unlock-notify callback is registered, the application provides a
5576 ** single void* pointer that is passed to the callback when it is invoked.
5579 ** an unlock-notify callback is a pointer to an array of void* pointers,
5580 ** and the second is the number of entries in the array.
5582 ** When a blocking connections transaction is concluded, there may be
5586 ** multiple times, it is invoked once with the set of void* context pointers
5596 ** application to deadlock. For example, if connection X is waiting for
5598 ** Y is waiting on connection X's transaction, then neither connection
5603 ** system in a deadlocked state, then SQLITE_LOCKED is returned and no
5604 ** unlock-notify callback is registered. The system is said to be in
5608 ** A's transaction is concluded. ^Indirect deadlock is also detected, so
5609 ** the system is also considered to be deadlocked if connection B has
5611 ** C's transaction, where connection C is waiting on connection A. ^Any
5616 ** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
5617 ** always appropriate to call sqlite3_unlock_notify(). There is however,
5620 ** that belong to the same connection. If there are, SQLITE_LOCKED is
5621 ** returned. In this case there is no "blocking connection", so invoking
5626 ** One way around this problem is to check the extended error code returned
5627 ** by an sqlite3_step() call. ^(If there is a blocking connection, then the
5628 ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
5629 ** the special "DROP TABLE/INDEX" case, the extended error code is just
5657 ** The sqlite3_log() interface is intended for use by extensions such as
5658 ** virtual tables, collating functions, and SQL functions. While there is
5660 ** is considered bad form.
5663 ** will not use dynamically allocated memory. The log message is stored in
5664 ** a fixed-length buffer on the stack. If the log message is longer than