Lines Matching +full:reset +full:- +full:pin +full:- +full:assert +full:- +full:time +full:- +full:ms
2 ** 2001-09-15
13 ** presents to client programs. If a C-function, structure, datatype,
24 ** The official C-language API documentation for SQLite is derived
69 ** that require non-default calling conventions.
94 ** These no-op macros are used in front of interfaces to mark those
96 ** should not use deprecated interfaces - they are supported for backwards
120 ** CAPI3REF: Compile-Time Library Version Numbers
132 ** and Z will be reset to zero.
136 ** <a href="http://fossil-scm.org/">Fossil configuration management
138 ** a string which identifies a particular check-in of SQLite
140 ** string contains the date and time of the check-in (UTC) and a SHA1
141 ** or SHA3-256 hash of the entire source tree. If the source code has
151 #define SQLITE_SOURCE_ID "2025-06-28 14:00:48 2af157d77fb1304a74176eaee7fbc7c7e932d946bf25325e…
154 ** CAPI3REF: Run-Time Library Version Numbers
160 ** programmers might include assert() statements in their application to
166 ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
167 ** assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );
168 ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
191 ** CAPI3REF: Run-Time Library Compilation Options Diagnostics
195 ** compile time. ^The SQLITE_ prefix may be omitted from the
199 ** over the list of options that were defined at compile time by
200 ** returning the N-th compile time option string. ^If N is out of range,
207 ** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
225 ** [SQLITE_THREADSAFE] compile-time option being set to 0.
243 ** This interface only reports on the compile-time mutex setting
249 ** sqlite3_threadsafe() function shows only the compile-time setting of
250 ** thread safety, not any run-time changes to that setting made by
275 ** CAPI3REF: 64-Bit Integer Types
278 ** Because there is no cross-platform way to specify 64-bit integer types
279 ** SQLite includes typedefs for 64-bit signed and unsigned integers.
286 ** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
309 ** substitute integer for floating-point.
351 ** argument is a harmless no-op.
364 ** CAPI3REF: One-Step Query Execution Interface
372 ** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
373 ** semicolon-separate SQL statements passed into its 2nd argument,
395 ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
447 /* beginning-of-error-codes */
478 /* end-of-error-codes */
486 ** these result codes are too coarse-grained. They do not provide as
592 ** [sqlite3_open_v2()] has historically be a no-op and might become an
648 ** read-only media and cannot be changed even by processes with
659 ** property, SQLite is careful to only do full-page reads and write
660 ** on aligned pages, with the one exception that it will do a sub-page
718 ** (Third-party VFS implementations might also make the distinction
753 ** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
777 ** requested lock, then the call to xLock() is a no-op.
780 ** to xUnlock() is a no-op.
793 ** locking strategy (for example to use dot-file locks), to inquire
841 ** fails to zero-fill short reads might seem to work. However,
842 ** failure to zero-fill short reads will eventually lead to
898 ** The [SQLITE_FCNTL_SIZE_LIMIT] opcode is used by in-memory VFS that
900 ** of the in-memory database. The argument is a pointer to a [sqlite3_int64].
910 ** point to an integer (type int) containing the new chunk-size to use
912 ** chunks (say 1MB at a time), may reduce file-system fragmentation and
923 ** the [rollback journal] or the [write-ahead log]) for a particular database
936 ** this file-control is NULL. However, if the database file is being synced
937 ** as part of a multi-database commit, the argument points to a nul-terminated
938 ** string containing the transactions super-journal file name. VFSes that
955 ** anti-virus programs. By default, the windows VFS will retry file read,
981 ** WAL mode. If the integer is -1, then it is overwritten with the current
986 ** persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
990 ** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
991 ** mode. If the integer is -1, then it is overwritten with the current
992 ** zero-damage mode setting.
1003 ** final bottom-level VFS are written into memory obtained from
1007 ** all file-control actions, there is no guarantee that this will actually
1009 ** pointer in case this file-control is not implemented. This file-control
1013 ** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
1017 ** to a pointer to the top-level VFS.)^
1019 ** upper-most shim only.
1036 ** VFS has handled the PRAGMA itself and the parser generates a no-op
1038 ** of the result string if the string is non-NULL.
1044 ** it is able to override built-in [PRAGMA] statements.
1048 ** file-control may be invoked by SQLite on the database file handle
1050 ** to the connection's busy-handler callback. The argument is of type (void**)
1051 ** - an array of two (void *) values. The first (void *) actually points
1053 ** busy-handler, this function should be invoked with the second (void *) in
1054 ** the array as the only argument. If it returns non-zero, then the operation
1059 ** ^Applications can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
1069 ** maximum number of bytes that will be used for memory-mapped I/O.
1075 ** file-control is used internally to implement [PRAGMA mmap_size].
1081 ** The argument is a zero-terminated string. Higher layers in the
1083 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
1104 ** The [SQLITE_FCNTL_NULL_IO] opcode sets the low-level file descriptor
1113 ** Applications should <em>not</em> use this file-control.
1162 ** The parameter is a pointer to a 32-bit signed integer that contains
1163 ** the value that M is to be set to. Before returning, the 32-bit signed
1174 ** a database file. The argument is a pointer to a 32-bit unsigned integer.
1200 ** file to the database file, but before the *-shm file is updated to
1205 ** whether or not there is a database client in another process with a wal-mode
1207 ** (void*) argument passed with this file-control should be a pointer to a
1211 ** the database is not a wal-mode db, or if there is no such connection in any
1221 ** database is not a temp db, then the [SQLITE_FCNTL_RESET_CACHE] file-control
1222 ** purges the contents of the in-memory page cache. If there is an open
1223 ** transaction, or if the db is a temp-db, this opcode is a no-op, not an error.
1303 ** as a normal, nul-terminated, UTF-8 buffer containing the filename, but
1327 ** the end. Each time such an extension occurs, the iVersion field
1346 ** in a thread-safe way. The [sqlite3_vfs_find()] interface
1364 ** consist of a single "-" character followed by no more than
1365 ** 11 alphanumeric and/or "-" characters.
1380 ** If xOpen() opens a file read-only then it sets *pOutFlags to
1400 ** the open of a journal file a no-op. Writes to this journal would
1401 ** also be no-ops, and any attempt to read the journal would return
1403 ** file will be doing page-aligned sector reads and writes in a random
1442 ** flag is never actually used and is not implemented in the built-in
1445 ** non-zero error code if there is an I/O error or if the name of
1447 ** is returned, then non-zero or zero is written into *pResOut to indicate
1461 ** of good-quality randomness into zOut. The return value is
1465 ** method returns a Julian Day Number for the current date and time as
1469 ** a 24-hour day).
1471 ** date and time if that method is available (if iVersion is 2 or
1495 void *pAppData; /* Pointer to application-specific data */
1601 ** the first time sqlite3_initialize() is invoked during the lifetime of
1602 ** the process, or if it is the first time sqlite3_initialize() is invoked
1605 ** are harmless no-ops.)^
1610 ** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
1633 ** compile-time option, then the automatic calls to sqlite3_initialize()
1642 ** The sqlite3_os_init() routine does operating-system specific
1658 ** (using the [SQLITE_OS_OTHER=1] compile-time
1660 ** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
1692 ** The exceptional configuration options that may be invoked at any time
1698 ** implementation of an application-defined [sqlite3_os_init()].
1702 ** then this routine returns a non-zero [error code].
1716 ** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code
1729 ** and low-level memory allocation routines.
1741 ** Note that SQLite comes with several [built-in memory allocators]
1746 ** memory allocator that simulates memory out-of-memory conditions in
1813 ** [sqlite3_shutdown()] is a no-op that returns SQLITE_MISUSE.
1828 ** non-zero [error code] if a discontinued or unsupported configuration option
1834 ** [threading mode] to Single-thread. In other words, it disables
1837 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1839 ** value of Single-thread and so [sqlite3_config()] will return
1845 ** [threading mode] to Multi-thread. In other words, it disables
1849 ** are enabled so that SQLite will be safe to use in a multi-threaded
1851 ** [database connection] at the same time. ^If SQLite is compiled with
1852 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1853 ** it is not possible to set the Multi-thread [threading mode] and
1866 ** same [prepared statement] in different threads at the same time.
1868 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1877 ** alternative low-level memory allocation routines to be used in place of
1905 ** disabled, the following SQLite interfaces become non-operational:
1926 ** This configuration option is a no-op if an application-defined page
1929 ** 8-byte aligned memory (pMem), the size of each page cache line (sz),
1937 ** argument must be either a NULL pointer or a pointer to an 8-byte
1944 ** ^If pMem is NULL and N is non-zero, then each database connection
1947 ** of -1024*N bytes if N is negative, . ^If additional
1960 ** An 8-byte aligned pointer to the memory,
1967 ** The first pointer (the memory pointer) must be aligned to an 8-byte
1975 ** The argument specifies alternative low-level mutex routines to be used
1979 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1992 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
2006 ** The [-DSQLITE_DEFAULT_LOOKASIDE] option can be used to change the
2007 ** default lookaside configuration at compile-time.
2028 ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
2030 ** passed through as the first parameter to the application-defined logger
2038 ** In a multi-threaded application, the application-defined logger
2043 ** If non-zero, then URI handling is globally enabled. If the parameter is zero,
2060 ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
2061 ** if that compile-time option is omitted.
2071 ** They are retained for backwards compatibility but are now no-ops.
2077 ** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
2093 ** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
2100 ** compile-time maximum mmap size set by the
2101 ** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
2103 ** changed to its compile-time default.
2108 ** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
2109 ** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
2125 ** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched
2134 ** becomes the [statement journal] spill-to-disk threshold.
2137 ** Or if the threshold is -1, statement journals are always held
2143 ** [SQLITE_STMTJRNL_SPILL] compile-time option.
2148 ** of type (int) - the new value of the sorter-reference size threshold.
2152 ** of a table column that its values are likely to be very large - larger
2153 ** than the configured sorter-reference size threshold - then a reference
2159 ** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option.
2164 ** [sqlite3_int64] parameter which is the default maximum size for an in-memory
2167 ** [SQLITE_FCNTL_SIZE_LIMIT] [sqlite3_file_control|file-control]. If this
2169 ** by the [SQLITE_MEMDB_DEFAULT_MAXSIZE] compile-time option. If that
2170 ** compile-time option is not set, then the default maximum is 1073741824.
2176 ** compiled with -DSQLITE_ALLOW_ROWID_IN_VIEW, in which case the capability
2184 ** is compiled without -DSQLITE_ALLOW_ROWID_IN_VIEW (which is the usual and
2202 #define SQLITE_CONFIG_PCACHE 14 /* no-op */
2203 #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
2226 ** The [sqlite3_db_config()] interface is a var-args functions. It takes a
2231 ** page says "the N-th argument" it means "the N-th parameter past the
2232 ** configuration option" or "the (N+2)-th parameter to sqlite3_db_config()".
2238 ** non-zero [error code] if a discontinued or unsupported configuration option
2271 ** The buffer must be aligned to an 8-byte boundary.
2285 ** [-DSQLITE_DEFAULT_LOOKASIDE] option can be used to set the default lookaside
2286 ** configuration at compile-time. Typical values for lookaside are 1200 for
2316 ** triggers in the main database schema or in the schemas of [ATTACH]-ed
2333 ** views in the main database schema or in the schemas of ATTACH-ed
2340 ** [FTS3] full-text search engine extension.
2355 ** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].
2357 ** When the first argument to this interface is 1, then only the C-API is
2359 ** this interface is 0, then both the C-API and the SQL function are disabled.
2360 ** If the first argument is -1, then no changes are made to state of either the
2361 ** C-API or the SQL function.
2391 ** which is positive to disable checkpoints-on-close, or zero (the default)
2394 ** into which is written 0 or 1 to indicate whether checkpoints-on-close
2395 ** have been disabled - 0 if they are not disabled, 1 if they are.
2418 ** behavior. The first parameter passed to this operation is an integer -
2422 ** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if
2428 ** [VACUUM] in order to reset a database back to an empty database
2436 ** the database in WAL mode after the reset if it was in WAL mode before
2437 ** the reset.
2480 ** behaves as it did prior to [version 3.24.0] (2018-06-04). See the
2489 ** the legacy [double-quoted string literal] misfeature for DML statements
2491 ** default value of this setting is determined by the [-DSQLITE_DQS]
2492 ** compile-time option.
2498 ** the legacy [double-quoted string literal] misfeature for DDL statements,
2500 ** default value of this setting is determined by the [-DSQLITE_DQS]
2501 ** compile-time option.
2528 ** created database file to have a schema format version number (the 4-byte
2555 ** an integer.. The first argument is 1, 0, or -1 to enable, disable, or
2570 ** argument is 1, 0, or -1 to enable, disable, or leave unchanged the
2586 ** to an integer. The first argument is 1, 0, or -1 to enable, disable, or
2587 ** leave unchanged the attach-create flag, respectively. If the second
2589 ** second argument points to depending on if the attach-create flag is set
2600 ** but the database will be opened read-only. If this option is disabled,
2605 ** to an integer. The first argument is 1, 0, or -1 to enable, disable, or
2620 ** to an integer. The first argument is 1, 0, or -1 to enable, disable, or
2636 ** option is disabled. If the first argument is -1, then the option setting
2688 ** has a unique 64-bit signed
2773 ** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
2795 ** any changes performed by sub-triggers, as the sqlite3_changes()
2796 ** value will be saved and restored after each sub-trigger has run.)^
2864 ** CAPI3REF: Interrupt A Long-Running Query
2870 ** or Ctrl-C where the user wants a long query operation to halt
2878 ** ^If an SQL operation is very nearly finished at the time when
2895 ** SQL statements is a no-op and has no effect on SQL statements
2908 ** These routines are useful during command-line input to determine if the
2914 ** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within
2929 ** then the return value from sqlite3_complete16() will be non-zero
2932 ** The input to [sqlite3_complete()] must be a zero-terminated
2933 ** UTF-8 string.
2935 ** The input to [sqlite3_complete16()] must be a zero-terminated
2936 ** UTF-16 string in native byte order.
2943 ** KEYWORDS: {busy-handler callback} {busy handler}
2965 ** ^If the callback returns non-zero, then another attempt
3007 ** for a specified amount of time when a table is locked. ^The handler
3008 ** will sleep multiple times until at least "ms" milliseconds of sleeping
3009 ** have accumulated. ^After at least "ms" milliseconds of sleeping,
3023 SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
3030 ** the VFS supports blocking locks, it sets the timeout in ms used by
3032 ** handle. In non-SQLITE_ENABLE_SETLK_TIMEOUT builds, or if the VFS does
3033 ** not support blocking locks, this function is a no-op.
3036 ** -1 to this function requests that the VFS blocks for a long time -
3040 ** Internally, each SQLite database handle store two timeout values - the
3041 ** busy-timeout (used for rollback mode databases, or if the VFS does not
3042 ** support blocking locks) and the setlk-timeout (used for blocking locks
3043 ** on wal-mode databases). The sqlite3_busy_timeout() method sets both
3044 ** values, this function sets only the setlk-timeout value. Therefore,
3045 ** to configure separate busy-timeout and setlk-timeout values for a single
3056 SQLITE_API int sqlite3_setlk_timeout(sqlite3*, int ms, int flags);
3079 ** A result table is an array of pointers to zero-terminated UTF-8 strings.
3081 ** to zero-terminated strings that contain the names of the columns.
3083 ** in NULL pointers. All other values are in their UTF-8 zero-terminated
3095 ** -----------------------
3117 ** semicolon-separated SQL statements in the zero-terminated UTF-8
3149 ** These routines are work-alikes of the "printf()" family of functions
3153 ** plus some additional non-standard formats ([%q], [%Q], [%w], and [%z]).
3154 ** See the [built-in printf()] documentation for details.
3177 ** guarantees that the buffer is always zero-terminated. ^The first
3180 ** written will be n-1 characters.
3184 ** See also: [built-in printf()], [printf() SQL function]
3196 ** does not include operating-system specific [VFS] implementation. The
3207 ** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
3208 ** of a signed 32-bit integer.
3213 ** a no-op if is called with a NULL pointer. Passing a NULL pointer
3218 ** might result if sqlite3_free() is called with a non-NULL pointer that
3238 ** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
3239 ** of a 32-bit signed integer.
3254 ** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
3278 ** routines, which form the built-in memory allocation subsystem.
3283 ** value of [sqlite3_memory_used()] since the high-water mark
3284 ** was last reset. ^The values returned by [sqlite3_memory_used()] and
3290 ** ^The memory high-water mark is reset to the current value of
3293 ** by [sqlite3_memory_highwater(1)] is the high-water mark
3294 ** prior to the reset.
3300 ** CAPI3REF: Pseudo-Random Number Generator
3302 ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
3305 ** the built-in random() and randomblob() SQL functions. This interface allows
3316 ** non-NULL P then the pseudo-randomness is generated
3323 ** CAPI3REF: Compile-Time Authorization Callbacks
3354 ** to the callback are either NULL pointers or zero-terminated strings
3382 ** user-entered SQL is being [sqlite3_prepare | prepared] that
3391 ** at a time. Each call to sqlite3_set_authorizer overrides the
3401 ** statement might be re-prepared during [sqlite3_step()] due to a
3447 ** is the name of the inner-most trigger or view that is responsible for
3449 ** top-level SQL code.
3499 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
3503 ** contain a UTF-8 SQL comment that identifies the trigger.)^
3505 ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
3510 ** the original statement text and an estimate of wall-clock time
3512 ** time is in units of nanoseconds, however the current implementation
3514 ** digits in the time are meaningless. Future versions of SQLite
3530 ** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
3552 ** interface by using the X argument when X begins with "--" and invoking
3559 ** X argument points to a 64-bit integer which is approximately
3589 ** M argument should be the bitwise OR-ed combination of
3635 ** ^Only a single progress handler may be defined at one time per
3641 ** ^If the progress callback returns non-zero, the operation is
3665 ** filename argument. ^The filename argument is interpreted as UTF-8 for
3666 ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
3677 ** ^The default encoding will be UTF-8 for databases created using
3679 ** created using sqlite3_open16() will be UTF-16 in the native byte order.
3693 ** <dd>The database is opened in read-only mode. If the database does
3701 ** read-write mode fails due to OS-level permissions, an attempt is
3702 ** made to open it in read-only mode. [sqlite3_db_readonly()] can be
3704 ** read-write.</dd>)^
3720 ** <dd>The database will be opened as an in-memory database. The database
3721 ** is named by the "filename" argument for the purposes of cache-sharing,
3726 ** <dd>The new database connection will use the "multi-thread"
3728 ** to use SQLite at the same time, as long as each thread is using
3734 ** attempt to use the same database connection at the same time.
3744 ** this option is a no-op.
3770 ** upon it. Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op
3781 ** ^If the filename is ":memory:", then a private, temporary in-memory database
3782 ** is created for the connection. ^This in-memory database will vanish when
3790 ** on-disk database will be created. ^This private database will be
3800 ** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
3823 ** SQLite and its built-in [VFSes] interpret the
3838 ** ^If "ro" is specified, then the database is opened for read-only
3841 ** "rw", then the database is opened for read-write (but not create)
3845 ** set to "memory" then a pure [in-memory database] that never reads
3872 ** read-only media. ^When immutable is set, SQLite assumes that the
3874 ** privilege, and so the database is opened read-only and all locking
3899 ** <tr><td style="white-space:nowrap">
3903 ** necessary - space characters can be used literally
3906 ** Open file "data.db" in the current directory for read-only access.
3907 ** Regardless of whether or not shared-cache mode is enabled by
3909 ** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
3910 ** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
3911 ** that uses dot-files in place of posix advisory locking.
3919 ** percent sign - "%" - followed by exactly two hexadecimal digits
3921 ** URI filename are interpreted, they are encoded using UTF-8 and all
3923 ** corresponding octet. If this process generates an invalid UTF-8 encoding,
3927 ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
3929 ** characters must be converted to UTF-8 prior to passing them into
3939 const char *filename, /* Database filename (UTF-8) */
3943 const void *filename, /* Database filename (UTF-16) */
3947 const char *filename, /* Database filename (UTF-8) */
3984 ** case or if the value begins with a non-zero number. The
3992 ** 64-bit signed integer and returns that integer, or D if P does not
3997 ** the value) of the N-th query parameter for filename F, or a NULL
3999 ** parameters minus 1. The N value is zero-based so N should be 0 to obtain
4058 ** ^If X is the name of a rollback or WAL-mode journal file that is
4064 ** only. It is not a general-purpose interface.
4108 ** sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless no-op.
4144 ** change the value of the error code. The error-code preserving
4155 ** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
4156 ** text that describes the error, as either UTF-8 or UTF-16 respectively,
4164 ** ^The sqlite3_errstr(E) interface returns the English-language text
4165 ** that describes the [result code] E, as UTF-8, or NULL if E is not an
4175 ** SQL, then the sqlite3_error_offset() function returns -1.
4179 ** the time of the first error and the call to these interfaces.
4210 ** The life-cycle of a prepared statement object usually goes like this:
4217 ** <li> Reset the prepared statement using [sqlite3_reset()] then go back
4225 ** CAPI3REF: Run-time Limits
4238 ** set at compile-time by a C preprocessor macro called
4247 ** simply invoke this interface with the third parameter set to -1.
4249 ** Run-time limits are intended for use in applications that manage
4262 ** New run-time limit categories may be added in future releases.
4267 ** CAPI3REF: Run-Time Limit Categories
4271 ** that can be lowered at run-time using [sqlite3_limit()].
4347 ** that the prepared statement will be retained for a long time and
4357 ** <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used
4373 ** compiles to see if some SQL syntax is well-formed, without generating
4391 ** To execute an SQL statement, it must first be compiled into a byte-code
4400 ** The use of the UTF-8 interfaces is preferred, as SQLite currently
4401 ** does all parsing using UTF-8. The UTF-16 interfaces are provided
4402 ** as a convenience. The UTF-16 interfaces work by converting the
4403 ** input text into UTF-8, then invoking the corresponding UTF-8 interface.
4410 ** as either UTF-8 or UTF-16. The sqlite3_prepare(), sqlite3_prepare_v2(),
4412 ** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
4413 ** and sqlite3_prepare16_v3() use UTF-16.
4421 ** If the caller knows that the supplied string is nul-terminated, then
4424 ** the nul-terminator.
4426 ** characters, even for the UTF-16 interfaces.
4476 ** ^The specific value of a WHERE-clause [parameter] might influence the
4477 ** choice of query plan if the parameter is the left-hand side of a [LIKE]
4479 ** and the [SQLITE_ENABLE_STAT4] compile-time option is enabled.
4491 const char *zSql, /* SQL statement, UTF-8 encoded */
4498 const char *zSql, /* SQL statement, UTF-8 encoded */
4505 const char *zSql, /* SQL statement, UTF-8 encoded */
4513 const void *zSql, /* SQL statement, UTF-16 encoded */
4520 const void *zSql, /* SQL statement, UTF-16 encoded */
4527 const void *zSql, /* SQL statement, UTF-16 encoded */
4538 ** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
4542 ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
4545 ** ^The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8
4561 ** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of
4562 ** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time
4573 ** the [SQLITE_ENABLE_NORMALIZE] compile-time option is defined.
4585 ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
4589 ** Note that [application-defined SQL functions] or
4593 ** change the database file through side-effects:
4619 ** makes it a no-op, but the sqlite3_stmt_readonly() result would still
4621 ** read-only no-op if the table already exists, but
4678 ** CAPI3REF: Determine If A Prepared Statement Has Been Reset
4681 ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
4685 ** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S)
4692 ** connection that are in need of being reset. This can be used,
4718 ** sqlite3_value object. If SQLite is compiled to be single-threaded
4729 ** implementation of [application-defined SQL functions] are protected.
4747 ** is always first parameter to [application-defined SQL functions].
4748 ** The application-defined SQL function implementation will pass this
4798 ** it should be a pointer to well-formed UTF8 text.
4800 ** it should be a pointer to well-formed UTF16 text.
4802 ** it should be a pointer to a well-formed unicode string that is
4806 ** [[byte-order determination rules]] ^The byte-order of
4807 ** UTF16 input text is determined by the byte-order mark (BOM, U+FEFF)
4824 ** If a non-negative fourth parameter is provided to sqlite3_bind_text()
4864 ** ^A negative value for the zeroblob results in a zero-length BLOB.
4866 ** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
4920 ** to the parameters at a later time.
4938 ** the name of the N-th [SQL parameter] in the [prepared statement] P.
4949 ** ^If the value N is out of range or if the N-th parameter is
4951 ** always in UTF-8 encoding even if the named parameter was
4952 ** originally specified as UTF-16 in [sqlite3_prepare16()],
4969 ** name must be given in UTF-8 even if the original statement
4970 ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or
4980 ** CAPI3REF: Reset All Bindings On A Prepared Statement
4983 ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
4985 ** ^Use this routine to reset all host parameters to NULL.
5011 ** interface returns a pointer to a zero-terminated UTF-8 string
5012 ** and sqlite3_column_name16() returns a pointer to a zero-terminated
5013 ** UTF-16 string. ^The first parameter is the [prepared statement]
5024 ** (for example during a conversion from UTF-8 to UTF-16) then a
5043 ** either a UTF-8 or UTF-16 string. ^The _database_ routines return
5052 ** ^The names returned are the original un-aliased names of the
5058 ** ^The left-most column is column 0 for these routines.
5067 ** UTF-16 encoded strings and the other functions return UTF-8.
5070 ** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
5075 ** at the same time then the results are undefined.
5094 ** ^The returned string is always UTF-8 encoded.
5107 ** ^SQLite uses dynamic run-time typing. ^So just because a column
5149 ** machine without first calling [sqlite3_reset()] to reset the virtual
5153 ** is returned each time a new row of data is ready for processing by the
5157 ** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
5171 ** more threads at the same moment in time.
5176 ** sqlite3_step(). Failure to reset the prepared statement using
5183 ** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
5213 ** will return non-zero if previous call to [sqlite3_step](P) returned
5215 ** where it always returns zero since each step of that multi-step
5229 ** <li> 64-bit signed integer
5230 ** <li> 64-bit IEEE floating point number
5263 ** <tr><td><b>sqlite3_column_int</b><td>→<td>32-bit INTEGER result
5264 ** <tr><td><b>sqlite3_column_int64</b><td>→<td>64-bit INTEGER result
5265 ** <tr><td><b>sqlite3_column_text</b><td>→<td>UTF-8 TEXT result
5266 ** <tr><td><b>sqlite3_column_text16</b><td>→<td>UTF-16 TEXT result
5271 ** or a UTF-8 TEXT result in bytes
5273 ** <td>→ <td>Size of UTF-16
5325 ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
5327 ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
5328 ** the string to UTF-8 and then returns the number of bytes.
5330 ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
5334 ** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
5336 ** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
5337 ** the string to UTF-16 and then returns the number of bytes.
5339 ** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
5350 ** even empty strings, are always zero-terminated. ^The return
5351 ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
5367 ** [application-defined SQL functions] or [virtual tables], not within
5368 ** top-level application code.
5386 ** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
5407 ** sqlite3_column_text16() is called. A zero-terminator might
5409 ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
5411 ** to UTF-16.</li>
5412 ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
5414 ** to UTF-8.</li>
5417 ** ^Conversions between UTF-16be and UTF-16le are always done in place and do
5448 ** fail if an out-of-memory error occurs during a format conversion.
5449 ** Only the following subset of interfaces are subject to out-of-memory
5460 ** If an out-of-memory error occurs, then the return value from these
5462 ** Valid SQL NULL returns can be distinguished from out-of-memory errors
5496 ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
5507 ** CAPI3REF: Reset A Prepared Statement Object
5510 ** The sqlite3_reset() function is called to reset a [prepared statement]
5511 ** object back to its initial state, ready to be re-executed.
5514 ** Use [sqlite3_clear_bindings()] to reset the bindings.
5532 ** [INSERT] statement with a [RETURNING] clause is only stepped one time,
5563 ** connection then application-defined SQL functions must be added
5567 ** redefined. ^The length of the name is limited to 255 bytes in a UTF-8
5568 ** representation, exclusive of the zero-terminator. ^Note that the name
5569 ** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
5575 ** aggregate takes. ^If this parameter is -1, then the SQL function or
5578 ** parameter is less than -1 or greater than 127 then the behavior is
5597 ** deterministic. The built-in [random()] SQL function is an example of a
5608 ** all application-defined SQL functions that do not need to be
5622 ** pointers to C-language functions that implement the SQL function or
5632 ** C-language callbacks that implement the new function. xStep and xFinal
5633 ** must both be non-NULL. xValue and xInverse may either both be NULL, in
5635 ** non-NULL, in which case the new function may be used as either an aggregate
5638 ** [user-defined window functions|available here].
5653 ** SQL function is used. ^A function implementation with a non-negative
5662 ** ^Built-in functions may be overloaded by new application-defined functions.
5664 ** ^An application-defined function is permitted to call other
5666 ** close the database connection nor finalize or reset the prepared
5719 #define SQLITE_UTF8 1 /* IMP: R-37514-35566 */
5720 #define SQLITE_UTF16LE 2 /* IMP: R-03371-37637 */
5721 #define SQLITE_UTF16BE 3 /* IMP: R-51971-34154 */
5748 ** from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in
5753 ** [application-defined SQL function]
5754 ** that has side-effects or that could potentially leak sensitive information.
5757 ** modified to invoke the application-defined function in ways that are
5761 ** [application-defined SQL functions], regardless of whether or not they
5765 ** that do not have access to the application-defined functions.
5784 ** the function is tagged with SQLITE_INNOCUOUS. Most built-in functions
5786 ** SQLITE_INNOCUOUS flag for application-defined functions unless the
5788 ** security-adverse side-effects and information-leaks.
5793 ** [sqlite3_value_subtype()] to inspect the sub-types of its arguments.
5794 ** This flag instructs SQLite to omit some corner-case optimizations that
5800 ** a non-zero subtype was specified by the function argument expression.
5804 ** [sqlite3_result_subtype()] to cause a sub-type to be associated with its
5808 ** might become a no-op if the function is used as term in an
5817 ** ordered-set aggregate SQL notation with a single ORDER BY term can be
5818 ** used to invoke this function. If the ordered-set aggregate notation is
5820 ** that the ordered-set aggregate syntax is only available if SQLite is
5821 ** built using the -DSQLITE_ENABLE_ORDERED_SET_AGGREGATES compile-time option.
5860 ** <tr><td><b>sqlite3_value_int</b><td>→<td>32-bit INTEGER value
5861 ** <tr><td><b>sqlite3_value_int64</b><td>→<td>64-bit INTEGER value
5863 ** <tr><td><b>sqlite3_value_text</b><td>→<td>UTF-8 TEXT value
5864 ** <tr><td><b>sqlite3_value_text16</b><td>→<td>UTF-16 TEXT value in
5866 ** <tr><td><b>sqlite3_value_text16be</b><td>→<td>UTF-16be TEXT value
5867 ** <tr><td><b>sqlite3_value_text16le</b><td>→<td>UTF-16le TEXT value
5870 ** or a UTF-8 TEXT in bytes
5872 ** <td>→ <td>Size of UTF-16
5890 ** implement [application-defined SQL functions] and [virtual tables].
5900 ** ^The sqlite3_value_text16() interface extracts a UTF-16 string
5901 ** in the native byte-order of the host machine. ^The
5903 ** extract UTF-16 strings as big-endian and little-endian respectively.
5944 ** ^The sqlite3_value_frombind(X) interface returns non-zero if the
5959 ** fail if an out-of-memory error occurs during a format conversion.
5960 ** Only the following subset of interfaces are subject to out-of-memory
5973 ** If an out-of-memory error occurs, then the return value from these
5975 ** Valid SQL NULL returns can be distinguished from out-of-memory errors
6023 ** an [application-defined SQL function] argument V. The subtype
6028 ** Every [application-defined SQL function] that invokes this interface
6049 ** then sqlite3_value_free(V) is a harmless no-op.
6061 ** ^The first time the sqlite3_aggregate_context(C,N) routine is called
6068 ** last time when the xFinal callback is invoked. ^(When no rows match
6072 ** first time from within xFinal().)^
6110 ** the application-defined function is running.
6130 ** These functions may be used by (non-aggregate) SQL functions to
6135 ** regular-expression matching function. The compiled version of the regular
6143 ** value to the application-defined function. ^N is zero for the left-most
6149 ** N-th argument of the application-defined function. ^Subsequent
6156 ** SQLite is free to discard the auxiliary data at any time, including: <ul>
6175 ** to sqlite3_set_auxdata() might still return NULL if an out-of-memory
6181 ** function parameters that are compile-time constants, including literal
6184 ** The value of the N parameter to these interfaces should be non-negative.
6209 ** If P and X are both non-NULL, then the destructor X is invoked with
6212 ** <li> An out-of-memory error occurs during the call to
6223 ** destructors on the client data at the appropriate time. The intended
6268 #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
6284 ** an application-defined function to be the BLOB whose content is pointed
6289 ** interfaces set the result of the application-defined function to be
6293 ** an application-defined function to be a floating point value specified
6301 ** message string from sqlite3_result_error() as UTF-8. ^SQLite
6302 ** interprets the string from sqlite3_result_error16() as UTF-16 using
6303 ** the same [byte-order determination rules] as [sqlite3_bind_text16()].
6308 ** sqlite3_result_error16() is non-negative then SQLite takes that many
6326 ** of the application-defined function to be the 32-bit signed integer
6329 ** of the application-defined function to be the 64-bit signed integer
6333 ** of the application-defined function to be NULL.
6337 ** set the return value of the application-defined function to be
6338 ** a text string which is represented as UTF-8, UTF-16 native byte order,
6339 ** UTF-16 little endian, or UTF-16 big endian, respectively.
6341 ** application-defined function to be a text string in an encoding
6351 ** is non-negative, then as many bytes (not characters) of the text
6352 ** pointed to by the 2nd parameter are taken as the application-defined
6353 ** function result. If the 3rd parameter is non-negative, then it
6360 ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
6376 ** byte-order mark (BOM, U+FEFF) then the BOM is removed from the
6378 ** byte-order specified by the BOM. ^The byte-order specified by
6379 ** the BOM at the beginning of the text overrides the byte-order
6382 ** with bytes 0xfe, 0xff (a big-endian byte-order mark) then the
6393 ** the application-defined function to be a copy of the
6404 ** also associates the host-language pointer P or type T with that
6406 ** [application-defined SQL function] using [sqlite3_value_pointer()].
6414 ** than the one containing the application-defined function that received
6446 ** the result from the [application-defined SQL function] with
6453 ** Every [application-defined SQL function] that invokes this interface
6461 ** If SQLite is compiled with -DSQLITE_STRICT_SUBTYPE=1, then any
6464 ** an error. Future versions of SQLite might enable -DSQLITE_STRICT_SUBTYPE=1
6476 ** ^The name of the collation is a UTF-8 string
6478 ** and a UTF-16 string in native byte order for sqlite3_create_collation16().
6541 ** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
6584 ** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
6585 ** the names are passed as UTF-16 in machine native byte order.
6586 ** ^A call to either function replaces the existing collation-needed callback.
6622 ** CAPI3REF: Suspend Execution For A Short Time
6628 ** millisecond time resolution, then the time will be rounded up to
6652 ** created by SQLite when using a built-in [sqlite3_vfs | VFS]
6665 ** thread at a time. It is not safe to read or modify this variable
6666 ** if a [database connection] is being used at the same time in a separate
6694 ** LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
6695 ** TemporaryFolder->Path->Data();
6698 ** WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
6711 ** SQLite when using a built-in windows [sqlite3_vfs | VFS] will be assumed
6722 ** thread at a time. It is not safe to read or modify this variable
6723 ** if a [database connection] is being used at the same time in a separate
6750 ** a non-NULL value will be copied into memory obtained from [sqlite3_malloc]
6755 ** the current directory on the sub-platforms of Win32 where that concept is
6759 ** UTF-8 or UTF-16, respectively.
6762 unsigned long type, /* Identifier for directory being set or reset */
6763 void *zValue /* New value for directory being set or reset */
6778 ** CAPI3REF: Test For Auto-Commit Mode
6782 ** ^The sqlite3_get_autocommit() interface returns non-zero or
6786 ** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
6788 ** If certain kinds of errors occur on a statement within a multi-statement
6819 ** for the N-th database on database connection D, or a NULL pointer if N is
6821 ** the "temp" schema. Larger values of N correspond to various ATTACH-ed
6829 ** remember the string long-term should make their own copy. Applications that
6831 ** threads should mutex-protect calls to this API and should make their own
6843 ** connection D, or if database N is a temporary or in-memory database, then
6848 ** is [DETACH]-ed or until the database connection closes.
6869 ** CAPI3REF: Determine if a database is read-only
6873 ** of connection D is read-only, 0 if it is read/write, or -1 if N is not
6892 ** a valid schema, then -1 is returned.
6958 ** ^If the callback on a commit hook function returns non-zero,
6980 ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
6982 ** hook returning non-zero, just as it would be with any other rollback.
7002 ** the schema-name of the attached database that is being autovacuumed,
7010 ** <p>^If there are multiple ATTACH-ed database files that are being
7133 ** [-DSQLITE_OMIT_SHARED_CACHE]. The [-DSQLITE_OMIT_SHARED_CACHE]
7134 ** compile-time option is recommended because the
7145 ** that was in effect at the time they were opened.)^
7160 ** shared cache mode should be enabled per-database connection via
7164 ** 32-bit integer is atomic.
7166 ** See Also: [SQLite Shared-Cache Mode]
7174 ** of heap memory by deallocating non-essential memory allocations
7176 ** pages to improve performance is an example of non-essential memory.
7179 ** ^The sqlite3_release_memory() routine is a no-op returning zero
7193 ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
7228 ** sqlite3_soft_heap_limit64(-1) or sqlite3_hard_heap_limit(-1).
7252 ** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and
7253 ** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.
7286 ** interface returns SQLITE_OK and fills in the non-NULL pointers in
7290 ** ^If the column-name parameter to sqlite3_table_column_metadata() is a
7357 int *pAutoinc /* OUTPUT: True if column is auto-increment */
7369 ** with various operating-system specific extensions added.
7378 ** X consists of the lower-case equivalent of all ASCII alphabetic
7417 ** [extension loading] while evaluating user-entered SQL, the following API
7425 ** ^This interface enables or disables both the C-API
7428 ** to enable or disable only the C-API.)^
7468 ** on the list of automatic extensions is a harmless no-op. ^No entry point
7489 ** CAPI3REF: Reset Automatic Extension Loading
7570 ** inputs to xBestIndex and are read-only. xBestIndex inserts its
7582 ** expr on the right-hand side can be evaluated (and thus the constraint
7597 ** passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),
7603 ** non-zero.
7607 ** the right-hand side of the corresponding aConstraint[] is evaluated
7608 ** and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit
7670 int iColumn; /* Column constrained. -1 for ROWID */
7673 int iTermOffset; /* Used internally - xBestIndex should ignore */
7717 ** ^The left-hand operand of the operator is given by the corresponding
7718 ** aConstraint[].iColumn field. ^An iColumn of -1 indicates the left-hand
7721 ** operators have no left-hand operand, and so for those operators the
7730 ** The right-hand operands for each constraint might be accessible using
7731 ** the [sqlite3_vtab_rhs_value()] interface. Usually the right-hand
7733 ** in the input SQL. If the right-hand operand is another column or an
7737 ** SQLITE_INDEX_CONSTRAINT_ISNOTNULL operators have no right-hand operand
7742 ** the [sqlite3_vtab_collation()] interface. For most real-world virtual
7937 ** ^If the flags parameter is non-zero, then the BLOB is opened for read
7939 ** read-only access.
7975 ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
7991 ** and the built-in [zeroblob] SQL function may be used to create a
7992 ** zero-filled blob to read or write using the incremental-blob interface.
8022 ** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -
8044 ** ^If the blob handle being closed was opened for read-write access, and if
8045 ** the database is in auto-commit mode and there are no other open read-write
8053 ** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function
8080 ** caller-supplied buffer. N bytes of data are copied into buffer Z
8109 ** caller-supplied buffer. N bytes of data are copied from the buffer Z
8158 ** ^Names are zero-terminated UTF-8 strings.
8189 ** is selected automatically at compile-time. The following
8200 ** a single-threaded application. The SQLITE_MUTEX_PTHREADS and
8205 ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
8242 ** cases where it really needs one. If a faster non-recursive mutex
8291 ** then any of the four routines behaves as a no-op.
8304 ** An instance of this structure defines the low-level routines
8354 ** xMutexInit() must be no-ops.
8383 ** are intended for use inside assert() statements. The SQLite core
8384 ** never uses these routines except inside an assert() and applications
8400 ** the routine should return 1. This seems counter-intuitive since
8403 ** using mutexes. And we do not want the assert() containing the
8404 ** call to sqlite3_mutex_held() to fail, so a non-zero return is
8420 ** next. Applications that override the built-in mutex logic must be
8436 #define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */
8451 ** ^If the [threading mode] is Single-thread or Multi-thread then this
8457 ** CAPI3REF: Low-Level Control Of Database Files
8573 ** by enclosing in double-quotes) so as not to confuse the parser.
8578 ** The sqlite3_keyword_name(N,Z,L) interface finds the 0-based N-th keyword and
8581 ** zero-terminated. The sqlite3_keyword_name(N,Z,L) routine returns
8587 ** the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero
8599 ** <li> Put all identifier names inside double-quotes. This is the official
8610 ** compile-time options. For example, "VACUUM" is not a keyword if
8611 ** SQLite is compiled with the [-DSQLITE_OMIT_VACUUM] option. Also,
8622 ** An instance of the sqlite3_str object contains a dynamically-sized
8646 ** valid [sqlite3_str] object, though in the event of an out-of-memory
8686 ** [sqlite3_str_vappendf(X,F,V)] interfaces uses the [built-in printf]
8691 ** onto the end of the [sqlite3_str] object X. N must be non-negative.
8692 ** S must contain at least N non-zero bytes of content. To append a
8693 ** zero-terminated string in its entirety, use the [sqlite3_str_appendall()]
8697 ** zero-terminated string S onto the end of [sqlite3_str] object X.
8700 ** single-byte character C onto the end of [sqlite3_str] object X.
8726 ** [SQLITE_NOMEM] following any out-of-memory error, or
8733 ** zero-termination byte.
8754 ** about the performance of SQLite, and optionally to reset various
8760 ** resetFlag is true, then the highest record value is reset after
8768 ** SQLITE_OK on success and a non-zero [error code] on failure.
8771 ** be represented by a 32-bit integer, then the values returned by
8789 ** These integer constants designate various run-time status parameters
8797 ** and internal memory usage by the SQLite library. Auxiliary page-cache
8850 ** New status parameters may be added from time to time.
8879 ** reset back down to the current value.
8882 ** non-zero [error code] on failure.
8898 ** The [sqlite3_db_status()] interface will return a non-zero error code
8908 ** satisfied using lookaside memory. Only the high-water value is meaningful;
8916 ** Only the high-water value is meaningful;
8924 ** Only the high-water value is meaningful;
8948 ** with the connection - main, temp, and any [ATTACH]-ed databases.)^
8989 ** to disk all at once. When pages spill mid-transaction, that introduces
9030 ** ^(This interface is used to retrieve and reset counter values from
9036 ** ^If the resetFlg is true, then the counter is reset to zero after this
9060 ** A non-zero value in this counter may indicate an opportunity to
9066 ** A non-zero value in this counter may indicate an opportunity to
9068 ** need to be reinitialized each time the statement is run.</dd>
9095 ** step was bypassed because a Bloom filter returned not-found. The
9165 ** The built-in page cache is recommended for most uses.
9180 ** built-in default page cache is used instead of the application defined
9212 ** false if it is used for an in-memory database. The cache implementation
9222 ** ^(The xCachesize() method may be called at any time by SQLite to set the
9223 ** suggested maximum cache-size (number of pages stored by) the cache
9269 ** as its second argument. If the third parameter, discard, is non-zero,
9274 ** may choose to evict unpinned pages at any time.
9303 ** is not obligated to free any memory, but well-behaved implementations should
9362 ** for copying in-memory databases to or from persistent files.
9368 ** ^The source database is read-locked only while it is being read;
9402 ** there is already a read or read-write transaction open on the
9434 ** <li> the destination database was opened read-only, or
9435 ** <li> the destination database is using write-ahead-log journaling
9437 ** <li> the destination database is an in-memory database and the
9441 ** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
9442 ** the [sqlite3_busy_handler | busy-handler function]
9444 ** busy-handler returns non-zero before the lock is available, then
9465 ** sqlite3_backup_step(), the source database may be modified mid-way
9472 ** updated at the same time.
9482 ** active write-transaction on the destination database is rolled back.
9489 ** ^If an out-of-memory condition or IO error occurred during any prior
9540 ** same time as another thread is invoking sqlite3_backup_step() it is
9568 ** ^When running in shared-cache mode, a database operation may fail with
9569 ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
9570 ** individual tables within the shared-cache cannot be obtained. See
9571 ** [SQLite Shared-Cache Mode] for a description of shared-cache locking.
9575 ** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
9579 ** ^Shared-cache locks are released when a database connection concludes
9583 ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
9593 ** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
9595 ** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
9599 ** ^If the blocked connection is attempting to obtain a write-lock on a
9600 ** shared-cache table, and more than one other connection currently holds
9601 ** a read-lock on the same table, then SQLite arbitrarily selects one of
9604 ** ^(There may be at most one unlock-notify callback registered by a
9606 ** blocked connection already has a registered unlock-notify callback,
9609 ** unlock-notify callback is canceled. ^The blocked connections
9610 ** unlock-notify callback may also be canceled by closing the blocked
9613 ** The unlock-notify callback is not reentrant. If an application invokes
9614 ** any sqlite3_xxx API functions from within an unlock-notify callback, a
9622 ** When an unlock-notify callback is registered, the application provides a
9626 ** an unlock-notify callback is a pointer to an array of void* pointers,
9630 ** more than one blocked connection that has registered for an unlock-notify
9640 ** Assuming that after registering for an unlock-notify callback a
9651 ** unlock-notify callback is registered. The system is said to be in
9652 ** a deadlocked state if connection A has registered for an unlock-notify
9654 ** B has itself registered for an unlock-notify callback when connection
9657 ** registered for an unlock-notify callback on the conclusion of connection
9669 ** sqlite3_unlock_notify() results in the unlock-notify callback being
9670 ** invoked immediately. If the application then re-attempts the "DROP TABLE"
9690 ** and extensions to compare the contents of two buffers containing UTF-8
9691 ** strings in a case-independent fashion, using the same definition of "case
9707 ** Note that this routine returns zero on a match and non-zero if the strings
9724 ** insensitive - equivalent upper and lower case ASCII characters match
9730 ** Note that this routine returns zero on a match and non-zero if the strings
9754 ** a fixed-length buffer on the stack. If the log message is longer than
9761 ** CAPI3REF: Write-Ahead Log Commit Hook
9765 ** is invoked each time data is committed to a database in wal mode.
9768 ** the associated write-lock on the database released)^, so the implementation
9774 ** ^The third parameter is the name of the database that was written to -
9775 ** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter
9776 ** is the number of pages currently in the write-ahead log file,
9787 ** A single database handle may have at most a single write-ahead log callback
9788 ** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any
9789 ** previously registered write-ahead log callback. ^The return value is
9802 ** CAPI3REF: Configure an auto-checkpoint
9809 ** more frames in the [write-ahead log] file. ^Passing zero or
9824 ** ^Every new [database connection] defaults to having the auto-checkpoint
9840 ** [write-ahead log] for database X on [database connection] D to be
9841 ** transferred into the database file and for the write-ahead log to
9842 ** be reset. See the [checkpointing] documentation for addition
9867 ** in the log were checkpointed. ^The [busy-handler callback]
9874 ** [sqlite3_busy_handler|busy-handler callback]) until there is no
9883 ** [busy-handler callback])
9896 ** the log file or to -1 if the checkpoint could not run because
9900 ** was called) or to -1 if the checkpoint could not run due to an error or
9906 ** any other process is running a checkpoint operation at the same time, the
9908 ** busy-handler configured, it will not be invoked in this case.
9912 ** obtained immediately, and a busy-handler is configured, it is invoked and
9913 ** the writer lock retried until either the busy-handler returns 0 or the lock
9914 ** is successfully obtained. ^The busy-handler is also invoked while waiting for
9915 ** database readers as described above. ^If the busy-handler returns 0 before
9918 ** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
9934 ** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If
10010 ** If X is non-zero, then the virtual table implementation guarantees
10054 ** all schemas ("main", "temp", and any ATTACH-ed databases) whenever the
10085 ** [xUpdate] method understands as a "no-change" value.
10247 ** on the right-hand side of the IN operator.)^ Thus the virtual table
10248 ** only sees a single value from the right-hand side of the IN operator
10249 ** at a time.
10252 ** table to see all values on the right-hand of the IN operator all at
10257 ** ^A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero)
10258 ** if and only if the [sqlite3_index_info|P->aConstraint][N] constraint
10260 ** sqlite3_vtab_in() with -1 in the third argument is a mechanism
10261 ** by which the virtual table can ask SQLite if all-at-once processing
10267 ** the IN operator all-at-once, respectively. ^Thus when the third
10268 ** parameter (F) is non-negative, this interface is the mechanism by
10277 ** (non-zero), that means that the constraint is an IN operator
10278 ** that can be processed all-at-once. ^If the constraint is not an IN
10279 ** operator or cannot be processed all-at-once, then the interface returns
10282 ** ^(All-at-once processing of the IN operator is selected if both of the
10286 ** <li><p> The P->aConstraintUsage[N].argvIndex value is set to a positive
10288 ** use the N-th constraint.
10291 ** non-negative had F>=1.
10295 ** the traditional one-at-a-time processing strategy for the IN constraint.
10296 ** ^If both conditions are true, then the argvIndex-th parameter to the
10299 ** [sqlite3_vtab_in_next()] to find all values on the right-hand side
10305 ** CAPI3REF: Find all elements on the right-hand side of an IN constraint.
10315 ** a parameter that was previously selected for all-at-once IN constraint
10318 ** an xFilter argument that was selected for all-at-once IN constraint
10321 ** ^(Use these routines to access all values on the right-hand side
10363 ** J being a 0-based index into P->aConstraint[], then this routine
10364 ** attempts to set *V to the value of the right-hand operand of
10365 ** that constraint if the right-hand operand is known. ^If the
10366 ** right-hand operand is not known, then *V is set to a NULL pointer.
10369 ** inteface returns SQLITE_NOTFOUND if the right-hand side of the J-th
10375 ** the right-hand operand of a constraint is a literal value in the original
10376 ** SQL statement. If the right-hand operand is an expression or a reference
10381 ** [SQLITE_INDEX_CONSTRAINT_ISNOTNULL], have no right-hand operand. For such
10390 ** "Right-Hand Side".
10425 ** not available, the output variable is set to -1 if the value is numeric,
10431 ** set to the total number of times that the X-th loop has run.</dd>
10435 ** to the total number of rows examined by all iterations of the X-th loop.</dd>
10440 ** iteration of the X-th loop. If the query planner's estimates was accurate,
10447 ** to a zero-terminated UTF-8 string containing the name of the index or table
10448 ** used for the X-th loop.
10452 ** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN]
10453 ** description for the X-th loop.
10457 ** id for the X-th query plan element. The id value is unique within the
10458 ** statement. The select-id is the same value as is output in the first
10469 ** according to the processor time-stamp counter, that elapsed while the
10471 ** all query elements - if it is unavailable the output variable is
10472 ** set to -1.
10495 ** compile-time option.
10503 ** one flag is defined - SQLITE_SCANSTAT_COMPLEX. If SQLITE_SCANSTAT_COMPLEX
10513 ** for. Query elements are numbered starting from zero. A value of -1 may be
10515 ** - less than -1 or greater than or equal to the total number of query
10516 ** elements used to implement the statement - a non-zero value is returned and
10542 ** CAPI3REF: Zero Scan-Status Counters
10547 ** This API is only available if the library is built with pre-processor
10553 ** CAPI3REF: Flush caches to disk mid-transaction
10556 ** ^If a write-transaction is open on [database connection] D when the
10558 ** pages in the pager-cache that are not currently in use are written out
10562 ** interface flushes caches for all schemas - "main", "temp", and
10567 ** immediately and there is a busy-handler callback configured, it is invoked
10575 ** example an IO error or out-of-memory condition), then processing is
10586 ** CAPI3REF: The pre-update hook.
10590 ** [SQLITE_ENABLE_PREUPDATE_HOOK] compile-time option.
10595 ** ^At most one preupdate hook may be registered at a time on a single
10666 ** operation; or 1 for inserts, updates, or deletes invoked by top-level
10667 ** triggers; or 2 for changes resulting from triggers called by top-level
10671 ** the pre-update hook is invoked with SQLITE_DELETE. This is because the
10676 ** pre-update hook is being invoked for some other reason, including a
10677 ** regular DELETE, sqlite3_preupdate_blobwrite() returns -1.
10703 ** CAPI3REF: Low-level system error code
10708 ** The return value is OS-dependent. For example, on unix systems, after
10726 ** as it existed for the point in time when the transaction first started.
10748 ** If there is not already a read-transaction open on schema S when
10751 ** If a read-transaction is opened by this function, then it is guaranteed
10753 ** writer or checkpointer until after the read-transaction is closed. This
10754 ** is not guaranteed if a read-transaction is already open when this
10757 ** even while the read-transaction remains open.
10788 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
10822 ** is returned. If another error code - for example SQLITE_PROTOCOL or an
10823 ** SQLITE_IOERR error code - is returned, then the final state of the
10837 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
10854 ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
10870 ** last time the wal file was deleted. The wal file is deleted when the
10922 ** For an ordinary on-disk database file, the serialization is just a
10923 ** copy of the disk file. For an in-memory database or a "TEMP" database,
10967 ** Zero or more of the following constants can be OR-ed together for
10971 ** a pointer to contiguous in-memory database that it is currently using,
10973 ** a contiguous in-memory database, then this option causes
10975 ** using a contiguous in-memory database if it has been initialized by a
10985 ** reopen S as an in-memory database based on the serialization contained
10989 ** permitted to add content to the in-memory database as long as the total
11051 ** should be treated as read-only.
11055 #define SQLITE_DESERIALIZE_READONLY 4 /* Database is read-only */
11106 /* The double-precision datatype used by RTree depends on the
11107 ** SQLITE_RTREE_INT_ONLY compile-time option.
11117 ** R-Tree geometry query as follows:
11142 ** Register a 2nd-generation geometry callback named zScore that can be
11143 ** used as part of an R-Tree geometry query as follows:
11249 ** is not possible for an application to register a pre-update hook on a
11252 ** which a pre-update hook is already defined. The results of attempting
11333 ** disabled - it does not. A newly created session object is enabled.
11340 ** no-op, and may be used to query the current state of the session.
11417 ** rows a zero-length blob (SQL value X'') is stored in the changeset or
11423 ** zero-length blob back to a NULL value when updating the sqlite_stat1
11427 ** conflict-handler callback) then the X'' value is returned. The application
11475 ** database row along with the updated values for each updated non-primary-key
11484 ** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
11486 ** with non-NULL PRIMARY KEY values is updated so that one or more of its
11499 ** are sorted in the same order in which they were attached (or auto-attached)
11513 ** recorded once - the first time a row with said primary key is inserted,
11520 ** The session object therefore accumulates two types of records - those
11538 ** found and one or more of the non-primary key fields have been
11555 ** This may appear to have some counter-intuitive effects if a single row
11572 ** CAPI3REF: Return An Upper-limit For The Size Of The Changeset
11594 ** does not have a primary key, this function is a no-op (but does not return
11614 ** used to update the table in database zFrom (call this the "from-table")
11616 ** object (call this the "to-table"). Specifically:
11619 ** <li> For each row (primary key) that exists in the to-table but not in
11620 ** the from-table, an INSERT record is added to the session object.
11622 ** <li> For each row (primary key) that exists in the to-table but not in
11623 ** the from-table, a DELETE record is added to the session object.
11626 ** different non-PK values in each, an UPDATE record is added to the
11635 ** Unless the call to this function is a no-op as described above, it is an
11672 ** Because the non-primary key "old.*" fields are omitted, no
11691 ** Return non-zero if no changes to attached tables have been recorded by
11699 ** are restored. However, if this function returns non-zero, then it is
11786 ** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
11810 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
11823 ** *pzTab is set to point to a nul-terminated utf-8 encoded string containing
11826 ** or until the conflict-handler function returns.
11873 unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */
11882 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
11913 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
11947 ** conflict-handler callback by [sqlite3changeset_apply()] with either
11958 ** "conflicting row" associated with the current conflict-handler callback
11996 ** function with an iterator passed to a conflict-handler by
12004 ** returned. This is to allow the following pattern (pseudo-code):
12048 int nIn, const void *pIn, /* Input changeset */
12188 ** <table border=1 style="margin-left:8ex;margin-right:8ex">
12189 ** <tr><th style="white-space:pre">Existing Change </th>
12190 ** <th style="white-space:pre">New Change </th>
12240 ** detected, SQLITE_CORRUPT is returned. Or, if an out-of-memory condition
12322 ** Otherwise, if the return value is non-zero or the xFilter argument to
12354 ** Each time the conflict handler function is invoked, it must return one
12358 ** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
12362 ** returned by each invocation of the conflict-handler function. Refer to
12371 ** stored in all non-primary key columns also match the values stored in
12375 ** the non-primary key fields contains a value different from the original
12376 ** row value stored in the changeset, the conflict-handler function is
12379 ** only the values of those non-primary key fields are compared against
12380 ** the current database contents - any trailing database table columns
12384 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
12389 ** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
12408 ** This includes the case where the INSERT operation is re-attempted because
12416 ** stored in all modified non-primary key columns also match the values
12420 ** the modified non-primary key fields contains a value different from an
12421 ** original row value stored in the changeset, the conflict-handler function
12423 ** UPDATE changes only contain values for non-primary key fields that are
12425 ** avoid the SQLITE_CHANGESET_DATA conflict-handler callback.
12428 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
12432 ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
12450 ** If the output parameters (ppRebase) and (pnRebase) are non-NULL and
12548 ** Values that may be passed as the second argument to a conflict-handler.
12555 ** (non primary-key) fields modified by the update do not contain the
12716 ** combined on a per-field basis, not per-row. This means that in the
12770 ** Argument pIn must point to a buffer containing a changeset nIn bytes
12782 int nIn, const void *pIn,
12800 ** corresponding non-streaming API functions:
12802 ** <table border=1 style="margin-left:8ex;margin-right:8ex">
12803 ** <tr><th>Streaming function<th>Non-streaming equivalent</th>
12813 ** Non-streaming functions that accept changesets (or patchsets) as input
12818 ** low-memory environment is required to handle very large changesets, the
12834 ** int (*xInput)(void *pIn, void *pData, int *pnData),
12835 ** void *pIn,
12838 ** Each time the xInput callback is invoked by the sessions module, the first
12839 ** argument passed is a copy of the supplied pIn context pointer. The second
12888 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
12889 void *pIn, /* First arg for xInput */
12903 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
12904 void *pIn, /* First arg for xInput */
12919 int (*xInputA)(void *pIn, void *pData, int *pnData),
12921 int (*xInputB)(void *pIn, void *pData, int *pnData),
12927 int (*xInput)(void *pIn, void *pData, int *pnData),
12928 void *pIn,
12934 int (*xInput)(void *pIn, void *pData, int *pnData),
12935 void *pIn
12939 int (*xInput)(void *pIn, void *pData, int *pnData),
12940 void *pIn,
12954 int (*xInput)(void *pIn, void *pData, int *pnData),
12955 void *pIn
12963 int (*xInput)(void *pIn, void *pData, int *pnData),
12964 void *pIn,
13082 ** non-negative but less than the number of columns in the table, return
13097 ** non-negative but less than the number of columns in the table, set
13114 ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes
13219 ** If the bClear argument is non-zero, then the auxiliary data is cleared
13241 ** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff);
13243 ** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff)
13249 ** modify this structure directly - it should only be used as shown above
13257 ** through an empty set (all calls to xPhraseFirst() set iCol to -1).
13275 ** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol);
13277 ** pApi->xPhraseNextColumn(pFts, &iter, &iCol)
13286 ** xPhraseFirstColumn() set iCol to -1).
13328 ** to scan the portion of the full-text index that matches the prefix
13335 ** of the initial querying of the full-text index, avoiding the second scan
13338 ** either on a per-table basis using the [FTS5 insttoken | 'insttoken']
13339 ** option, or on a per-query basis using the
13354 ** into the fts5 table, then (*pzLocale) is set to point to a nul-terminated
13355 ** buffer containing the name of the locale in utf-8 encoding. (*pnLocale)
13357 ** nul-terminator.
13442 ** The second and third arguments are an array of nul-terminated strings
13460 ** by argument pText. pText may or may not be nul-terminated. The first
13468 ** <ul><li> <b>FTS5_TOKENIZE_DOCUMENT</b> - A document is being inserted into
13473 ** <li> <b>FTS5_TOKENIZE_QUERY</b> - A MATCH query is being executed
13477 ** <li> <b>(FTS5_TOKENIZE_QUERY | FTS5_TOKENIZE_PREFIX)</b> - Same as
13482 ** <li> <b>FTS5_TOKENIZE_AUX</b> - The tokenizer is being invoked to
13488 ** The sixth and seventh arguments passed to xTokenize() - pLocale and
13489 ** nLocale - are a pointer to a buffer containing the locale to use for
13491 ** pLocale buffer is not nul-terminated. pLocale may be passed NULL (in
13519 ** then the xTokenize() method has two additional arguments - pLocale
13523 ** an nLocale byte buffer containing the name of the locale to use as utf-8
13524 ** text. pLocale is not nul-terminated.
13546 ** built-in tokenizers, the FTS5 query 'first + place' will match instances
13580 ** still appears to contain just two phrases - "(first OR 1st)"
13591 ** when tokenizing query text (it should not - to do so would be
13611 ** It is an error to specify the FTS5_TOKEN_COLOCATED flag the first time
13638 ** provide synonyms for prefixes). However, a non-prefix query like '1st'