Lines Matching +full:- +full:a
2 ** 2001-09-15
5 ** a legal notice, here is a blessing:
13 ** presents to client programs. If a C-function, structure, datatype,
15 ** not a published API of SQLite, is subject to change without
24 ** The official C-language API documentation for SQLite is derived
71 ** These no-op macros are used in front of interfaces to mark those
73 ** should not use deprecated interfaces - they are supported for backwards
79 ** compiler magic ended up generating such a flurry of bug reports
97 ** CAPI3REF: Compile-Time Library Version Numbers
100 ** evaluates to a string literal that is the SQLite version in the
113 ** <a href="http://www.fossil-scm.org/">Fossil configuration management
114 ** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to
115 ** a string which identifies a particular check-in of SQLite
117 ** string contains the date and time of the check-in (UTC) and a SHA1
118 ** or SHA3-256 hash of the entire source tree.
126 #define SQLITE_SOURCE_ID "2017-08-01 13:24:15 9501e22dfeebdcefa783575e47c60b514d7c2e0cad73b2a4…
129 ** CAPI3REF: Run-Time Library Version Numbers
147 ** macro. ^The sqlite3_libversion() function returns a pointer to the
153 ** a pointer to a string constant whose value is the same as the
164 ** CAPI3REF: Run-Time Library Compilation Options Diagnostics
173 ** returning the N-th compile time option string. ^If N is out of range,
174 ** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_
195 ** [SQLITE_THREADSAFE] compile-time option being set to 0.
204 ** Enabling mutexes incurs a measurable performance penalty.
213 ** This interface only reports on the compile-time mutex setting
216 ** can be fully or partially disabled using a call to [sqlite3_config()]
219 ** sqlite3_threadsafe() function shows only the compile-time setting of
220 ** thread safety, not any run-time changes to that setting made by
232 ** Each open SQLite database is represented by a pointer to an instance of
245 ** CAPI3REF: 64-Bit Integer Types
248 ** Because there is no cross-platform way to specify 64-bit integer types
249 ** SQLite includes typedefs for 64-bit signed and unsigned integers.
256 ** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
278 ** If compiling for a processor that lacks floating point support,
279 ** substitute integer for floating-point.
286 ** CAPI3REF: Closing A Database Connection
310 ** sqlite3_close_v2() is called on a [database connection] that still has
316 ** ^If an [sqlite3] object is destroyed while a transaction is open,
320 ** must be either a NULL
324 ** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
325 ** argument is a harmless no-op.
331 ** The type for a callback function.
338 ** CAPI3REF: One-Step Query Execution Interface
341 ** The sqlite3_exec() interface is a convenience wrapper around
344 ** without having to use a lot of C code.
346 ** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
347 ** semicolon-separate SQL statements passed into its 2nd argument,
369 ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
376 ** [sqlite3_column_text()], one for each column. ^If an element of a
378 ** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
383 ** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
384 ** to an empty string, or a pointer that contains only whitespace and/or
392 ** is a valid and open [database connection].
419 /* beginning-of-error-codes */
425 #define SQLITE_LOCKED 6 /* A table in the database is locked */
426 #define SQLITE_NOMEM 7 /* A malloc() failed */
427 #define SQLITE_READONLY 8 /* Attempt to write a readonly database */
445 #define SQLITE_NOTADB 26 /* File opened that is not a database file */
450 /* end-of-error-codes */
458 ** these result codes are too coarse-grained. They do not provide as
464 ** on a per database connection basis using the
560 ** object returns an integer which is a vector of these
570 ** that when data is appended to a file, the data is appended
575 ** after reboot following a crash or power loss, the only bytes in a
579 ** flag indicates that a file cannot be deleted when open. The
581 ** read-only media and cannot be changed even by processes with
616 ** [sqlite3_io_methods] object it uses a combination of
632 ** only make a difference on Mac OSX for the default SQLite code.
633 ** (Third-party VFS implementations might also make the distinction
649 ** for their own use. The pMethods entry is a pointer to an
662 ** [sqlite3_file] object (or, more commonly, a subclass of the
663 ** [sqlite3_file] object) with a pointer to an instance of this object.
668 ** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
670 ** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
676 ** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
690 ** either in this process or in some other process, is holding a RESERVED,
692 ** if such a lock exists and false otherwise.
694 ** The xFileControl() method is a generic interface that allows custom
697 ** integer opcode. The third argument is a generic pointer intended to
698 ** point to a structure that may contain arguments or space in which to
701 ** locking strategy (for example to use dot-file locks), to inquire
702 ** about the status of a lock, or to break stale locks. The SQLite
704 ** A [file control opcodes | list of opcodes] less than 100 is available.
705 ** Applications that define a custom xFileControl method should use opcodes
714 ** method returns a bit vector describing behaviors of the
739 ** that when data is appended to a file, the data is appended
746 ** in the unread portions of the buffer with zeros. A VFS that
747 ** fails to zero-fill short reads might seem to work. However,
748 ** failure to zero-fill short reads will eventually lead to
794 ** compile-time option is used.
798 ** layer a hint of how large the database file will grow to be during the
806 ** extends and truncates the database file in chunks of a size specified
808 ** point to an integer (type int) containing the new chunk-size to use
810 ** chunks (say 1MB at a time), may reduce file-system fragmentation and
814 ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
815 ** to the [sqlite3_file] object associated with a particular database
819 ** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
821 ** the [rollback journal] or the [write-ahead log]) for a particular database
829 ** sent to the VFS immediately before the xSync method is invoked on a
834 ** this file-control is NULL. However, if the database file is being synced
835 ** as part of a multi-database commit, the argument points to a nul-terminated
836 ** string containing the transactions master-journal file name. VFSes that
843 ** and sent to the VFS after a transaction has been committed immediately
853 ** anti-virus programs. By default, the windows VFS will retry file read,
854 ** file write, and file delete operations up to 10 times, with a delay
859 ** within the same process. The argument is a pointer to an array of two
876 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
878 ** WAL mode. If the integer is -1, then it is overwritten with the current
883 ** persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
886 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
887 ** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
888 ** mode. If the integer is -1, then it is overwritten with the current
889 ** zero-damage mode setting.
893 ** a write transaction to indicate that, unless it is rolled back for some
900 ** final bottom-level VFS are written into memory obtained from
904 ** all file-control actions, there is no guarantee that this will actually
905 ** do anything. Callers should initialize the char* variable to a NULL
906 ** pointer in case this file-control is not implemented. This file-control
910 ** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
914 ** to a pointer to the top-level VFS.)^
916 ** upper-most shim only.
919 ** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
927 ** of the char** argument point to a string obtained from [sqlite3_mprintf()]
933 ** VFS has handled the PRAGMA itself and the parser generates a no-op
934 ** prepared statement if result string is NULL, or that returns a copy
935 ** of the result string if the string is non-NULL.
941 ** it is able to override built-in [PRAGMA] statements.
945 ** file-control may be invoked by SQLite on the database file handle
946 ** shortly after it is opened in order to provide a custom VFS with access
947 ** to the connections busy-handler callback. The argument is of type (void **)
948 ** - an array of two (void *) values. The first (void *) actually points
949 ** to a function of type (int (*)(void *)). In order to invoke the connections
950 ** busy-handler, this function should be invoked with the second (void *) in
951 ** the array as the only argument. If it returns non-zero, then the operation
956 ** ^Application can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
957 ** to have SQLite generate a
960 ** argument should be a char** which will be filled with the filename
962 ** invoke [sqlite3_free()] on the result to avoid a memory leak.
966 ** maximum number of bytes that will be used for memory-mapped I/O.
967 ** The argument is a pointer to a value of type sqlite3_int64 that
971 ** can be queried by passing in a pointer to a negative number. This
972 ** file-control is used internally to implement [PRAGMA mmap_size].
978 ** The argument is a zero-terminated string. Higher layers in the
980 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
983 ** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
984 ** pointer to an integer and it writes a boolean into that integer depending
990 ** underlying native file handle associated with a file handle. This file
991 ** control interprets its argument as a pointer to a native file handle and
1001 ** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
1004 ** circumstances in order to fix a problem with priority inversion.
1005 ** Applications should <em>not</em> use this file-control.
1057 ** abstract type for a mutex object. The SQLite core never looks
1068 ** A pointer to the opaque sqlite3_api_routines structure is passed as
1092 ** a pathname in this VFS.
1094 ** Registered sqlite3_vfs objects are kept on a linked list formed by
1097 ** in a thread-safe way. The [sqlite3_vfs_find()] interface
1103 ** or modify this field while holding a particular static mutex.
1112 ** is either a NULL pointer or string obtained
1114 ** ^If a suffix is added to the zFilename parameter, it will
1115 ** consist of a single "-" character followed by no more than
1116 ** 11 alphanumeric and/or "-" characters.
1120 ** the [sqlite3_file] can safely store a pointer to the
1122 ** If the zFilename parameter to xOpen is a NULL pointer then xOpen
1131 ** If xOpen() opens a file read-only then it sets *pOutFlags to
1151 ** the open of a journal file a no-op. Writes to this journal would
1152 ** also be no-ops, and any attempt to read the journal would return
1153 ** SQLITE_IOERR. Or the implementation might recognize that a database
1154 ** file will be doing page-aligned sector reads and writes in a random
1183 ** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
1190 ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
1191 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
1192 ** to test whether a file is at least readable. The file can be a
1197 ** is also passed as a parameter to both methods. If the output buffer
1199 ** handled as a fatal error by SQLite, vfs implementations should endeavor
1200 ** to prevent this by setting mxPathname to a sufficiently large value.
1203 ** interfaces are not strictly a part of the filesystem, but they are
1206 ** of good-quality randomness into zOut. The return value is
1210 ** method returns a Julian Day Number for the current date and time as
1211 ** a floating point value.
1214 ** a 24-hour day).
1223 ** system calls with functions under its control, a test program can
1240 void *pAppData; /* Pointer to application-specific data */
1286 ** [temp_store_directory pragma], though this could change in a future
1290 ** currently unused, though it might be used in a future release of
1329 ** The SQLite core will never attempt to acquire or release a
1345 ** A call to sqlite3_initialize() is an "effective" call if it is
1348 ** following a call to sqlite3_shutdown(). ^(Only an effective call
1350 ** are harmless no-ops.)^
1352 ** A call to sqlite3_shutdown() is an "effective" call if it is the first
1355 ** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
1358 ** is not. The sqlite3_shutdown() interface must only be called from a
1369 ** the library (perhaps it is unable to allocate a needed resource such
1370 ** as a mutex) it returns an [error code] other than [SQLITE_OK].
1378 ** compile-time option, then the automatic calls to sqlite3_initialize()
1387 ** The sqlite3_os_init() routine does operating-system specific
1392 ** setting up a default [sqlite3_vfs] module, or setting up
1393 ** a default configuration using [sqlite3_config()].
1403 ** (using the [SQLITE_OS_OTHER=1] compile-time
1404 ** option) the application must supply a suitable implementation for
1405 ** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
1434 ** implementation of an application-defined [sqlite3_os_init()].
1442 ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
1444 ** then this routine returns a non-zero [error code].
1453 ** changes to a [database connection]. The interface is similar to
1454 ** [sqlite3_config()] except that the changes apply to a single
1458 ** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code
1471 ** and low-level memory allocation routines.
1474 ** A pointer to an instance of this object is the argument to
1483 ** Note that SQLite comes with several [built-in memory allocators]
1485 ** and that this object is only useful to a tiny minority of applications
1488 ** memory allocator that simulates memory out-of-memory conditions in
1495 ** xRealloc is always a value returned by a prior call to xRoundup.
1497 ** xSize should return the allocated size of a memory allocation
1502 ** a memory allocation given a particular requested size. Most memory
1504 ** of 8. Some allocators round up to a larger multiple or to a power of 2.
1533 void (*xFree)(void*); /* Free a prior allocation */
1552 ** the call worked. The [sqlite3_config()] interface will return a
1553 ** non-zero [error code] if a discontinued or unsupported configuration option
1559 ** [threading mode] to Single-thread. In other words, it disables
1560 ** all mutexing and puts SQLite into a mode where it can only be used
1561 ** by a single thread. ^If SQLite is compiled with
1562 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1564 ** value of Single-thread and so [sqlite3_config()] will return
1570 ** [threading mode] to Multi-thread. In other words, it disables
1574 ** are enabled so that SQLite will be safe to use in a multi-threaded
1577 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1578 ** it is not possible to set the Multi-thread [threading mode] and
1593 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1599 ** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is
1600 ** a pointer to an instance of the [sqlite3_mem_methods] structure.
1602 ** alternative low-level memory allocation routines to be used in place of
1608 ** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which
1609 ** is a pointer to an instance of the [sqlite3_mem_methods] structure.
1613 ** routines with a wrapper that simulations memory allocation failure or
1618 ** interpreted as a boolean, which enables or disables the collection of
1620 ** disabled, the following SQLite interfaces become non-operational:
1633 ** <dd> ^The SQLITE_CONFIG_SCRATCH option specifies a static memory buffer
1635 ** to SQLITE_CONFIG_SCRATCH: A pointer an 8-byte
1639 ** The first argument must be a pointer to an 8-byte aligned buffer
1642 ** ^SQLite will never request a scratch buffer that is more than 6
1651 ** fragmentation in low-memory embedded systems.
1655 ** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
1658 ** This configuration option is a no-op if an application-define page
1660 ** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
1661 ** 8-byte aligned memory (pMem), the size of each page cache line (sz),
1664 ** (a power of two between 512 and 65536) plus some extra bytes for each
1669 ** argument must be either a NULL pointer or a pointer to an 8-byte
1674 ** a page cache line is larger than sz bytes or if all of the pMem buffer
1676 ** ^If pMem is NULL and N is non-zero, then each database connection
1679 ** of -1024*N bytes if N is negative, . ^If additional
1685 ** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer
1693 ** An 8-byte aligned pointer to the memory,
1700 ** The first pointer (the memory pointer) must be aligned to an 8-byte
1706 ** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
1708 ** The argument specifies alternative low-level mutex routines to be used
1709 ** in place the mutex routines built into SQLite.)^ ^SQLite makes a copy of
1712 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1718 ** <dd> ^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which
1719 ** is a pointer to an instance of the [sqlite3_mutex_methods] structure. The
1723 ** routines with a wrapper used to track mutex usage for performance
1725 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1741 ** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
1742 ** a pointer to an [sqlite3_pcache_methods2] object. This object specifies
1743 ** the interface to a custom page cache implementation.)^
1744 ** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
1747 ** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
1748 ** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of
1754 ** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
1755 ** function with a call signature of void(*)(void*,int,const char*),
1756 ** and a pointer to void. ^If the function pointer is not NULL, it is
1758 ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
1760 ** passed through as the first parameter to the application-defined logger
1762 ** the logger function is a copy of the first parameter to the corresponding
1763 ** [sqlite3_log()] call and is intended to be a [result code] or an
1768 ** In a multi-threaded application, the application-defined logger
1772 ** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
1773 ** If non-zero, then URI handling is globally enabled. If the parameter is zero,
1786 ** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
1787 ** argument which is interpreted as a boolean in order to enable or disable
1790 ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
1791 ** if that compile-time option is omitted.
1801 ** They are retained for backwards compatibility but are now no-ops.
1807 ** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
1808 ** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
1813 ** points to a buffer containing the name of the main database file. If the
1823 ** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
1830 ** compile-time maximum mmap size set by the
1831 ** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
1833 ** changed to its compile-time default.
1838 ** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
1839 ** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
1844 ** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
1845 ** is a pointer to an integer and writes into that integer the number of extra
1852 ** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which
1855 ** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched
1863 ** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
1864 ** becomes the [statement journal] spill-to-disk threshold.
1867 ** Or if the threshold is -1, statement journals are always held
1870 ** threshold to a value such as 64KiB can greatly reduce the amount of
1873 ** [SQLITE_STMTJRNL_SPILL] compile-time option.
1889 #define SQLITE_CONFIG_PCACHE 14 /* no-op */
1890 #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
1912 ** the call worked. ^The [sqlite3_db_config()] interface will return a
1913 ** non-zero [error code] if a discontinued or unsupported configuration option
1920 ** ^The first argument (the third parameter to [sqlite3_db_config()] is a
1921 ** pointer to a memory buffer to use for lookaside memory.
1928 ** must be aligned to an 8-byte boundary. ^If the second argument to
1929 ** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
1931 ** configuration for a database connection can only be changed when that
1944 ** unchanged. The second parameter is a pointer to an integer into which
1946 ** following this call. The second parameter may be a NULL pointer, in
1954 ** The second parameter is a pointer to an integer into which
1956 ** following this call. The second parameter may be a NULL pointer, in
1960 ** <dd> ^This option is used to enable or disable the two-argument
1962 ** [FTS3] full-text search engine extension.
1967 ** The second parameter is a pointer to an integer into which
1969 ** following this call. The second parameter may be a NULL pointer, in
1976 ** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].
1978 ** When the first argument to this interface is 1, then only the C-API is
1980 ** this interface is 0, then both the C-API and the SQL function are disabled.
1981 ** If the first argument is -1, then no changes are made to state of either the
1982 ** C-API or the SQL function.
1983 ** The second parameter is a pointer to an integer into which
1986 ** be a NULL pointer, in which case the new setting is not reported back.
1991 ** schema. ^The sole argument is a pointer to a constant UTF8 string
1993 ** does not make a copy of the new main schema name string, so the application
1999 ** <dd> Usually, when a database in wal mode is closed or detached from a
2001 ** connections at all to the database. If so, it performs a checkpoint
2004 ** is an integer - non-zero to disable checkpoints-on-close, or zero (the
2005 ** default) to enable them. The second parameter is a pointer to an integer
2006 ** into which is written 0 or 1 to indicate whether checkpoints-on-close
2007 ** have been disabled - 0 if they are not disabled, 1 if they are.
2013 ** a single SQL query statement will always use the same algorithm regardless
2048 ** has a unique 64-bit signed
2052 ** the table has a column of type [INTEGER PRIMARY KEY] then that column
2056 ** the most recent successful [INSERT] into a rowid table or [virtual table]
2067 ** part of committing a transaction (e.g. to flush data accumulated in memory
2075 ** ^(If an [INSERT] occurs within a trigger then this routine will
2080 ** ^An [INSERT] that fails due to a constraint violation is not a
2085 ** encounters a constraint violation, it does not fail. The
2096 ** If a separate thread performs a new [INSERT] on the same
2111 ** without inserting a row into the database.
2126 ** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
2129 ** Changes to a view that are intercepted by
2132 ** DELETE statement run on a view is always zero. Only changes made to real
2136 ** executed while a trigger program is running. This may happen if the
2141 ** <li> ^(Before entering a trigger program the value returned by
2145 ** <li> ^(Within a trigger program each INSERT, UPDATE and DELETE
2148 ** any changes performed by sub-triggers, as the sqlite3_changes()
2149 ** value will be saved and restored after each sub-trigger has run.)^
2153 ** by the first INSERT, UPDATE or DELETE statement within a trigger, it
2155 ** ^If it is used by the second or subsequent such statement within a trigger
2162 ** If a separate thread makes changes on the same database connection
2180 ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers
2186 ** If a separate thread makes changes on the same database connection
2193 ** CAPI3REF: Interrupt A Long-Running Query
2198 ** called in response to a user action such as pressing "Cancel"
2199 ** or Ctrl-C where the user wants a long query operation to halt
2202 ** ^It is safe to call this routine from a thread different from the
2204 ** is not safe to call this routine with a [database connection] that
2223 ** ^A call to sqlite3_interrupt(D) that occurs when there are no running
2224 ** SQL statements is a no-op and has no effect on SQL statements
2232 ** These routines are useful during command-line input to determine if the
2233 ** currently entered text seems to form a complete SQL statement or
2236 ** appears to be a complete SQL statement. ^A statement is judged to be
2237 ** complete if it ends with a semicolon token and is not a prefix of a
2238 ** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within
2241 ** embedded) and thus do not count as a statement terminator. ^Whitespace
2244 ** ^These routines return 0 if the statement is incomplete. ^If a
2253 ** then the return value from sqlite3_complete16() will be non-zero
2256 ** The input to [sqlite3_complete()] must be a zero-terminated
2257 ** UTF-8 string.
2259 ** The input to [sqlite3_complete16()] must be a zero-terminated
2260 ** UTF-16 string in native byte order.
2266 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
2267 ** KEYWORDS: {busy-handler callback} {busy handler}
2270 ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
2272 ** an attempt is made to access a database table associated with
2282 ** ^The first argument to the busy handler is a copy of the void* pointer which
2289 ** ^If the callback returns non-zero, then another attempt
2292 ** The presence of a busy handler does not guarantee that it will be invoked
2294 ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
2297 ** Consider a scenario where one process is holding a read lock that
2298 ** it is trying to promote to a reserved lock and
2299 ** a second process is holding a reserved lock that it is trying
2310 ** ^(There can only be a single busy handler defined for each
2311 ** [database connection]. Setting a new busy handler clears any
2321 ** A busy handler must not close the database connection
2327 ** CAPI3REF: Set A Busy Timeout
2330 ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
2331 ** for a specified amount of time when a table is locked. ^The handler
2340 ** ^(There can only be a single busy handler for a particular
2353 ** This is a legacy interface that is preserved for backwards compatibility.
2356 ** Definition: A <b>result table</b> is memory data structure created by the
2357 ** [sqlite3_get_table()] interface. A result table records the
2360 ** The table conceptually has a number of rows and columns. But
2365 ** A result table is an array of pointers to zero-terminated UTF-8 strings.
2367 ** to zero-terminated strings that contain the names of the columns.
2369 ** in NULL pointers. All other values are in their UTF-8 zero-terminated
2372 ** A result table might consist of one or more memory allocations.
2373 ** It is not safe to pass a result table directly to [sqlite3_free()].
2374 ** A result table should be deallocated using [sqlite3_free_table()].
2376 ** ^(As an example of the result table format, suppose a query result
2381 ** -----------------------
2403 ** semicolon-separated SQL statements in the zero-terminated UTF-8
2404 ** string of its 2nd parameter and returns a result table to the
2414 ** The sqlite3_get_table() interface is implemented as a wrapper around
2417 ** interface defined here. As a consequence, errors that occur in the
2435 ** These routines are work-alikes of the "printf()" family of functions
2438 ** plus some additional non-standard formats, detailed below.
2440 ** C-library standards are omitted from this implementation.
2445 ** released by [sqlite3_free()]. ^Both routines return a
2456 ** returns a pointer to its buffer instead of the number of
2458 ** the number of characters written would be a more useful return
2463 ** guarantees that the buffer is always zero-terminated. ^The first
2466 ** written will be n-1 characters.
2468 ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
2475 ** ^(The %q option works like %s in that it substitutes a nul-terminated
2477 ** %q is designed for use inside a string literal.)^ By doubling each '\''
2484 ** char *zText = "It's a happy day!";
2499 ** INSERT INTO table1 VALUES('It''s a happy day!')
2506 ** INSERT INTO table1 VALUES('It's a happy day!');
2509 ** This second example is an SQL syntax error. As a general rule you should
2510 ** always use %q instead of %s when inserting text into a string literal.
2514 ** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
2523 ** The code above will render a correct SQL statement in the zSQL
2524 ** variable even if the zText variable is a NULL pointer.
2527 ** be contained within double-quotes instead of single quotes, and it
2528 ** escapes the double-quote character instead of the single-quote
2530 ** table and column names into a constructed SQL statement.
2546 ** does not include operating-system specific VFS implementation. The
2549 ** ^The sqlite3_malloc() routine returns a pointer to a block
2552 ** memory, it returns a NULL pointer. ^If the parameter N to
2554 ** a NULL pointer.
2557 ** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
2558 ** of a signed 32-bit integer.
2560 ** ^Calling sqlite3_free() with a pointer previously returned
2563 ** a no-op if is called with a NULL pointer. Passing a NULL pointer
2566 ** memory might result in a segmentation fault or other severe error.
2567 ** Memory corruption, a segmentation fault, or other severe error
2568 ** might result if sqlite3_free() is called with a non-NULL pointer that
2571 ** ^The sqlite3_realloc(X,N) interface attempts to resize a
2574 ** is a NULL pointer then its behavior is identical to calling
2579 ** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
2588 ** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
2589 ** of a 32-bit signed integer.
2591 ** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
2595 ** of bytes requested when X was allocated. ^If X is a NULL pointer then
2597 ** the beginning of memory allocation, or if it points to a formerly
2603 ** is always aligned to at least an 8 byte boundary, or to a
2604 ** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
2608 ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
2610 ** is no longer provided. Only built-in memory allocators can be used.
2614 ** filenames between the UTF-8 encoding used by SQLite
2621 ** must be either NULL or else pointers obtained from a prior
2626 ** a block of memory after it has been released using
2641 ** routines, which form the built-in memory allocation subsystem.
2646 ** value of [sqlite3_memory_used()] since the high-water mark
2653 ** ^The memory high-water mark is reset to the current value of
2656 ** by [sqlite3_memory_highwater(1)] is the high-water mark
2663 ** CAPI3REF: Pseudo-Random Number Generator
2665 ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
2666 ** select random [ROWID | ROWIDs] when inserting new records into a table that
2668 ** the build-in random() and randomblob() SQL functions. This interface allows
2671 ** ^A call to this routine stores N bytes of randomness into buffer P.
2672 ** ^The P parameter can be a NULL pointer.
2675 ** call had N less than one or a NULL pointer for P, then the PRNG is
2678 ** ^If the previous call to this routine had an N of 1 or more and a
2679 ** non-NULL P then the pseudo-randomness is generated
2686 ** CAPI3REF: Compile-Time Authorization Callbacks
2690 ** ^This routine registers an authorizer callback with a particular
2713 ** ^The first parameter to the authorizer callback is a copy of the third
2717 ** to the callback are either NULL pointers or zero-terminated strings
2719 ** Applications must always be prepared to encounter a NULL pointer in any
2725 ** a NULL value in place of the table column that would have
2728 ** columns of a table.
2729 ** ^When a table is referenced by a [SELECT] but no column values are
2730 ** extracted from that table (for example in a query like
2732 ** is invoked once for that table with a column name that is an empty string.
2741 ** example, an application may allow a user to enter arbitrary
2742 ** SQL queries for evaluation by a database. But the application does
2745 ** user-entered SQL is being [sqlite3_prepare | prepared] that
2753 ** ^(Only a single authorizer can be in place on a database connection
2754 ** at a time. Each call to sqlite3_set_authorizer overrides the
2755 ** previous call.)^ ^Disable the authorizer by installing a NULL callback.
2763 ** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
2764 ** statement might be re-prepared during [sqlite3_step()] due to a
2772 ** sqlite3_prepare_v2() to reprepare a statement after a schema change.
2789 ** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
2798 ** The [sqlite3_set_authorizer()] interface registers a callback function
2810 ** is the name of the inner-most trigger or view that is responsible for
2812 ** top-level SQL code.
2862 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
2866 ** contain a UTF-8 SQL comment that identifies the trigger.)^
2868 ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
2873 ** the original statement text and an estimate of wall-clock time
2893 ** to [sqlite3_trace_v2()] is an OR-ed combination of one or more of
2899 ** ^A trace callback has four arguments: xCallback(T,C,P,X).
2901 ** ^The C argument is a copy of the context pointer passed in as the
2907 ** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
2910 ** trigger subprogram. ^The P argument is a pointer to the
2911 ** [prepared statement]. ^The X argument is a pointer to a string which
2913 ** that indicates the invocation of a trigger. ^The callback can compute
2915 ** interface by using the X argument when X begins with "--" and invoking
2921 ** ^The P argument is a pointer to the [prepared statement] and the
2922 ** X argument points to a 64-bit integer which is the estimated of
2927 ** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
2928 ** statement generates a single row of result.
2929 ** ^The P argument is a pointer to the [prepared statement] and the
2933 ** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
2935 ** ^The P argument is a pointer to the [database connection] object
2948 ** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
2952 ** M argument should be the bitwise OR-ed combination of
2963 ** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
2966 ** ^The C argument is a copy of the context pointer.
2988 ** interface is to keep a GUI updated during a large query.
2996 ** ^Only a single progress handler may be defined at one time per
2997 ** [database connection]; setting a new progress handler cancels the
2999 ** ^The progress handler is also disabled by setting N to a value less
3002 ** ^If the progress callback returns non-zero, the operation is
3003 ** interrupted. This feature can be used to implement a
3004 ** "Cancel" button on a GUI progress dialog box.
3015 ** CAPI3REF: Opening A New Database Connection
3019 ** filename argument. ^The filename argument is interpreted as UTF-8 for
3020 ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
3021 ** order for sqlite3_open16(). ^(A [database connection] handle is usually
3024 ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
3028 ** an English language description of the error following a failure of any
3031 ** ^The default encoding will be UTF-8 for databases created using
3033 ** created using sqlite3_open16() will be UTF-16 in the native byte order.
3049 ** <dd>The database is opened in read-only mode. If the database does not
3069 ** opens in the multi-thread [threading mode] as long as the single-thread
3070 ** mode has not been set at compile-time or start-time. ^If the
3072 ** in the serialized [threading mode] unless single-thread was
3073 ** previously selected at compile-time or start-time.
3083 ** a NULL pointer then the default [sqlite3_vfs] object is used.
3085 ** ^If the filename is ":memory:", then a private, temporary in-memory database
3086 ** is created for the connection. ^This in-memory database will vanish when
3089 ** It is recommended that when a database filename actually does begin with
3090 ** a ":" character you should prefix the filename with a pathname such as
3093 ** ^If the filename is an empty string, then a private, temporary
3094 ** on-disk database will be created. ^This private database will be
3100 ** begins with "file:", then the filename is interpreted as a URI. ^URI
3104 ** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
3113 ** error is returned to the caller. ^The fragment component of a URI, if
3117 ** which contains the database. ^If the path begins with a '/' character,
3119 ** with a '/' (meaning that the authority section is omitted from the URI)
3120 ** then the path is interpreted as a relative path.
3122 ** is a drive specification (e.g. "C:").)^
3125 ** The query component of a URI may contain parameters that are interpreted
3126 ** either by SQLite itself, or by a [VFS | custom VFS implementation].
3127 ** SQLite and its built-in [VFSes] interpret the
3132 ** a VFS object that provides the operating system interface that should
3142 ** ^If "ro" is specified, then the database is opened for read-only
3145 ** "rw", then the database is opened for read-write (but not create)
3149 ** set to "memory" then a pure [in-memory database] that never reads
3150 ** or writes from disk is used. ^It is an error to specify a value for
3160 ** a URI filename, its value overrides any behavior requested by setting
3167 ** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
3169 ** is useful for accessing a database on a filesystem that does not
3174 ** <li> <b>immutable</b>: ^The immutable parameter is a boolean query
3176 ** read-only media. ^When immutable is set, SQLite assumes that the
3177 ** database file cannot be changed, even by a process with higher
3178 ** privilege, and so the database is opened read-only and all locking
3180 ** property on a database file that does in fact change can result
3186 ** ^Specifying an unknown parameter in the query component of a URI is not an
3202 ** An error. "darkstar" is not a recognized authority.
3203 ** <tr><td style="white-space:nowrap">
3207 ** necessary - space characters can be used literally
3210 ** Open file "data.db" in the current directory for read-only access.
3211 ** Regardless of whether or not shared-cache mode is enabled by
3212 ** default, use a private cache.
3213 ** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
3214 ** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
3215 ** that uses dot-files in place of posix advisory locking.
3217 ** An error. "readonly" is not a valid option for the "mode" parameter.
3221 ** query components of a URI. A hexadecimal escape sequence consists of a
3222 ** percent sign - "%" - followed by exactly two hexadecimal digits
3223 ** specifying an octet value. ^Before the path or query components of a
3224 ** URI filename are interpreted, they are encoded using UTF-8 and all
3225 ** hexadecimal escape sequences replaced by a single byte containing the
3226 ** corresponding octet. If this process generates an invalid UTF-8 encoding,
3230 ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
3232 ** characters must be converted to UTF-8 prior to passing them into
3242 const char *filename, /* Database filename (UTF-8) */
3246 const void *filename, /* Database filename (UTF-16) */
3250 const char *filename, /* Database filename (UTF-8) */
3260 ** to see if a database file was a URI that contained a specific query
3264 ** a VFS implementation when the flags parameter to xOpen() has one or
3268 ** parameter if it exists or a NULL pointer if P does not appear as a
3269 ** query parameter on F. If P is a query parameter of F
3271 ** a pointer to an empty string.
3273 ** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
3277 ** case or if the value begins with a non-zero number. The
3280 ** if the value begins with a numeric zero. If P is not a query
3284 ** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
3285 ** 64-bit signed integer and returns that integer, or D if P does not
3289 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
3290 ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
3291 ** is not a database file pathname pointer that SQLite passed into the xOpen
3315 ** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
3316 ** text that describes the error, as either UTF-8 or UTF-16 respectively.
3322 ** ^The sqlite3_errstr() interface returns the English-language text
3323 ** that describes the [result code], as UTF-8.
3328 ** case that a second error occurs on a separate thread in between
3351 ** An instance of this object represents a single SQL statement that
3354 ** Think of each SQL statement as a separate computer program. The
3355 ** original SQL text is source code. A prepared statement object
3356 ** is the compiled object code. All SQL must be converted into a
3359 ** The life-cycle of a prepared statement object usually goes like this:
3374 ** CAPI3REF: Run-time Limits
3378 ** on a connection by connection basis. The first parameter is the
3380 ** second parameter is one of the [limit categories] that define a
3384 ** ^If the new limit is a negative number, the limit is unchanged.
3385 ** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
3387 ** set at compile-time by a C preprocessor macro called
3390 ** ^Attempts to increase a limit above its hard upper bound are
3395 ** ^Hence, to find the current value of a limit without changing it,
3396 ** simply invoke this interface with the third parameter set to -1.
3398 ** Run-time limits are intended for use in applications that manage
3400 ** by untrusted external sources. An example application might be a
3405 ** be given much smaller limits designed to prevent a denial of service
3411 ** New run-time limit categories may be added in future releases.
3416 ** CAPI3REF: Run-Time Limit Categories
3420 ** that can be lowered at run-time using [sqlite3_limit()].
3432 ** <dd>The maximum number of columns in a table definition or in the
3433 ** result set of a [SELECT] or the maximum number of columns in an index
3440 ** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
3443 ** <dd>The maximum number of instructions in a virtual machine program
3446 ** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^
3449 ** <dd>The maximum number of arguments on a function.</dd>)^
3467 ** <dd>The maximum number of auxiliary worker threads that a single
3495 ** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
3496 ** that the prepared statement will be retained for a long time and
3499 ** be used just once or at most a few times and then destroyed using
3514 ** To execute an SQL statement, it must first be compiled into a byte-code
3523 ** The use of the UTF-8 interfaces is preferred, as SQLite currently
3524 ** does all parsing using UTF-8. The UTF-16 interfaces are provided
3525 ** as a convenience. The UTF-16 interfaces work by converting the
3526 ** input text into UTF-8, then invoking the corresponding UTF-8 interface.
3528 ** The first argument, "db", is a [database connection] obtained from a
3533 ** as either UTF-8 or UTF-16. The sqlite3_prepare(), sqlite3_prepare_v2(),
3535 ** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
3536 ** and sqlite3_prepare16_v3() use UTF-16.
3542 ** If the caller knows that the supplied string is nul-terminated, then
3543 ** there is a small performance advantage to passing an nByte parameter that
3545 ** the nul-terminator.
3552 ** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
3555 ** string or a comment) then *ppStmt is set to NULL.
3568 ** that is returned (the [sqlite3_stmt] object) contains a copy of the
3583 ** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
3584 ** and the application would have to make a second call to [sqlite3_reset()]
3591 ** WHERE clause might influence the choice of query plan for a statement,
3593 ** a schema change, on the first [sqlite3_step()] call following any change
3595 ** ^The specific value of WHERE-clause [parameter] might influence the
3596 ** choice of query plan if the parameter is the left-hand side of a [LIKE]
3598 ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.
3602 ** the extra prepFlags parameter, which is a bit array consisting of zero or
3605 ** sqlite3_prepare_v3() with a zero prepFlags parameter.
3610 const char *zSql, /* SQL statement, UTF-8 encoded */
3617 const char *zSql, /* SQL statement, UTF-8 encoded */
3624 const char *zSql, /* SQL statement, UTF-8 encoded */
3632 const void *zSql, /* SQL statement, UTF-16 encoded */
3639 const void *zSql, /* SQL statement, UTF-16 encoded */
3646 const void *zSql, /* SQL statement, UTF-16 encoded */
3657 ** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
3661 ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
3665 ** ^(For example, if a prepared statement is created using the SQL
3675 ** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of
3676 ** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time
3692 ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
3696 ** Note that [application-defined SQL functions] or
3697 ** [virtual tables] might change the database indirectly as a side effect.
3698 ** ^(For example, if an application defines a function "eval()" that
3700 ** change the database file through side-effects:
3715 ** change the configuration of a database connection, they do not make
3725 ** CAPI3REF: Determine If A Prepared Statement Has Been Reset
3728 ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
3733 ** interface returns false if S is a NULL pointer. If S is not a
3734 ** NULL pointer and is not a pointer to a valid [prepared statement]
3738 ** to locate all prepared statements associated with a database
3741 ** statements that are holding a transaction open.
3750 ** that can be stored in a database table. SQLite uses dynamic typing
3755 ** Some interfaces require a protected sqlite3_value. Other interfaces
3756 ** will accept either a protected or an unprotected sqlite3_value.
3758 ** whether or not it requires a protected sqlite3_value. The
3759 ** [sqlite3_value_dup()] interface can be used to construct a new
3763 ** a mutex is held. An internal mutex is held for a protected
3765 ** sqlite3_value object. If SQLite is compiled to be single-threaded
3776 ** implementation of [application-defined SQL functions] are protected.
3790 ** sqlite3_context object. ^A pointer to an sqlite3_context object
3791 ** is always first parameter to [application-defined SQL functions].
3792 ** The application-defined SQL function implementation will pass this
3807 ** literals may be replaced by a [parameter] that matches one of following
3824 ** a pointer to the [sqlite3_stmt] object returned from
3839 ** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
3842 ** ^(In those routines that have a fourth argument, its value is the
3850 ** If a non-negative fourth parameter is provided to sqlite3_bind_text()
3860 ** is a destructor used to dispose of the BLOB or
3878 ** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
3879 ** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
3884 ** ^A negative value for the zeroblob results in a zero-length BLOB.
3886 ** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
3888 ** associated with the pointer P of type T. ^D is either a NULL pointer or
3889 ** a pointer to a destructor function for P. ^SQLite will invoke the
3890 ** destructor D with a single argument of P when it is finished using
3891 ** P. The T parameter should be a static string, preferably a string
3895 ** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
3896 ** for the [prepared statement] or with a prepared statement for which
3899 ** routine is passed a [prepared statement] that has been finalized, the
3907 ** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB
3937 ** in a [prepared statement]. SQL parameters are tokens of the
3940 ** to the parameters at a later time.
3954 ** CAPI3REF: Name Of A Host Parameter
3958 ** the name of the N-th [SQL parameter] in the [prepared statement] P.
3960 ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
3964 ** ^Parameters of the form "?" without a following integer have no name
3969 ** ^If the value N is out of range or if the N-th parameter is
3971 ** always in UTF-8 encoding even if the named parameter was
3972 ** originally specified as UTF-16 in [sqlite3_prepare16()],
3982 ** CAPI3REF: Index Of A Parameter With A Given Name
3987 ** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero
3989 ** name must be given in UTF-8 even if the original statement
3990 ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or
4000 ** CAPI3REF: Reset All Bindings On A Prepared Statement
4004 ** the [sqlite3_bind_blob | bindings] on a [prepared statement].
4010 ** CAPI3REF: Number Of Columns In A Result Set
4016 ** ^However, just because this routine returns a positive number does not
4017 ** mean that one or more rows of data will be returned. ^A SELECT statement
4018 ** will always have a positive sqlite3_column_count() but depending on the
4026 ** CAPI3REF: Column Names In A Result Set
4029 ** ^These routines return the name assigned to a particular column
4030 ** in the result set of a [SELECT] statement. ^The sqlite3_column_name()
4031 ** interface returns a pointer to a zero-terminated UTF-8 string
4032 ** and sqlite3_column_name16() returns a pointer to a zero-terminated
4033 ** UTF-16 string. ^The first parameter is the [prepared statement]
4039 ** reprepared by the first call to [sqlite3_step()] for a particular run
4044 ** (for example during a conversion from UTF-8 to UTF-16) then a
4047 ** ^The name of a result column is the value of the "AS" clause for
4056 ** CAPI3REF: Source Of Data In A Query Result
4059 ** ^These routines provide a means to determine the database, table, and
4060 ** table column that is the origin of a particular result column in
4063 ** either a UTF-8 or UTF-16 string. ^The _database_ routines return
4068 ** reprepared by the first call to [sqlite3_step()] for a particular run
4070 ** again in a different encoding.
4072 ** ^The names returned are the original un-aliased names of the
4075 ** ^The first argument to these interfaces is a [prepared statement].
4078 ** ^The left-most column is column 0 for these routines.
4081 ** subquery and is not a column value, then all of these functions return
4082 ** NULL. ^These routine might also return NULL if a memory allocation error
4087 ** UTF-16 encoded strings and the other functions return UTF-8.
4090 ** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
4109 ** CAPI3REF: Declared Datatype Of A Query Result
4112 ** ^(The first parameter is a [prepared statement].
4113 ** If this statement is a [SELECT] statement and the Nth column of the
4114 ** returned result set of that [SELECT] is a table column (not an
4117 ** expression or subquery, then a NULL pointer is returned.
4118 ** ^The returned string is always UTF-8 encoded.
4129 ** column (i==1), and a NULL pointer for the first result column (i==0).)^
4131 ** ^SQLite uses dynamic run-time typing. ^So just because a column
4132 ** is declared to contain a particular type does not mean that the
4145 ** After a [prepared statement] has been prepared using any of
4165 ** database locks it needs to do its job. ^If the statement is a [COMMIT]
4167 ** statement. If the statement is not a [COMMIT] and occurs within an
4177 ** is returned each time a new row of data is ready for processing by the
4181 ** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
4184 ** ^With the legacy interface, a more specific error code (for example,
4191 ** Perhaps it was called on a [prepared statement] that has
4197 ** For all versions of SQLite up to and including 3.6.23.1, a call to
4205 ** than returning [SQLITE_MISUSE]. This is not considered a compatibility
4207 ** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
4211 ** API always returns a generic error code, [SQLITE_ERROR], following any
4215 ** We admit that this is a goofy design. The problem has been fixed
4226 ** CAPI3REF: Number of columns in a result set
4234 ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
4237 ** will return non-zero if previous call to [sqlite3_step](P) returned
4239 ** where it always returns zero since each step of that multi-step
4253 ** <li> 64-bit signed integer
4254 ** <li> 64-bit IEEE floating point number
4263 ** for a completely different meaning. Software that links against both
4279 ** CAPI3REF: Result Values From A Query
4287 ** <tr><td><b>sqlite3_column_int</b><td>→<td>32-bit INTEGER result
4288 ** <tr><td><b>sqlite3_column_int64</b><td>→<td>64-bit INTEGER result
4289 ** <tr><td><b>sqlite3_column_text</b><td>→<td>UTF-8 TEXT result
4290 ** <tr><td><b>sqlite3_column_text16</b><td>→<td>UTF-16 TEXT result
4294 ** <tr><td><b>sqlite3_column_bytes</b><td>→<td>Size of a BLOB
4295 ** or a UTF-8 TEXT result in bytes
4297 ** <td>→ <td>Size of UTF-16
4305 ** ^These routines return information about a single column of the current
4306 ** result row of a query. ^In every case the first argument is a pointer
4314 ** If the SQL statement does not currently point to a valid row, or if the
4323 ** are called from a different thread while any of these routines
4327 ** each return the value of a result column in a specific data format. If
4340 ** After a type conversion, the result of calling sqlite3_column_type()
4343 ** following a type conversion.
4345 ** If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
4349 ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
4351 ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
4352 ** the string to UTF-8 and then returns the number of bytes.
4353 ** ^If the result is a numeric value then sqlite3_column_bytes() uses
4354 ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
4358 ** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
4360 ** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
4361 ** the string to UTF-16 and then returns the number of bytes.
4362 ** ^If the result is a numeric value then sqlite3_column_bytes16() uses
4363 ** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
4374 ** even empty strings, are always zero-terminated. ^The return
4375 ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
4378 ** [unprotected sqlite3_value] object. In a multithreaded environment,
4387 ** [application-defined SQL functions] or [virtual tables], not within
4388 ** top-level application code.
4391 ** ^For example, if the internal representation is FLOAT and a text result
4402 ** <tr><td> NULL <td> TEXT <td> Result is a NULL pointer
4403 ** <tr><td> NULL <td> BLOB <td> Result is a NULL pointer
4406 ** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
4415 ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
4426 ** <li> The initial content is a BLOB and sqlite3_column_text() or
4427 ** sqlite3_column_text16() is called. A zero-terminator might
4429 ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
4431 ** to UTF-16.</li>
4432 ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
4434 ** to UTF-8.</li>
4437 ** ^Conversions between UTF-16be and UTF-16le are always done in place and do
4438 ** not invalidate a prior pointer, though of course the content of the buffer
4460 ** ^The pointers returned are valid until a type conversion occurs as
4467 ** ^(If a memory allocation error occurs during the evaluation of any
4468 ** of these routines, a default value is returned. The default value
4469 ** is either the integer 0, the floating point number 0.0, or a NULL
4485 ** CAPI3REF: Destroy A Prepared Statement Object
4488 ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
4502 ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
4505 ** resource leaks. It is a grievous error for the application to try to use
4506 ** a prepared statement after it has been finalized. Any use of a prepared
4513 ** CAPI3REF: Reset A Prepared Statement Object
4516 ** The sqlite3_reset() function is called to reset a [prepared statement]
4517 ** object back to its initial state, ready to be re-executed.
4542 ** KEYWORDS: {application-defined SQL function}
4543 ** KEYWORDS: {application-defined SQL functions}
4551 ** and the presence or absence of a destructor callback for
4556 ** connection then application-defined SQL functions must be added
4560 ** redefined. ^The length of the name is limited to 255 bytes in a UTF-8
4561 ** representation, exclusive of the zero-terminator. ^Note that the name
4562 ** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
4563 ** ^Any attempt to create a function with a longer name
4568 ** aggregate takes. ^If this parameter is -1, then the SQL function or
4571 ** parameter is less than -1 or greater than 127 then the behavior is
4589 ** the same inputs within a single SQL statement. Most SQL functions are
4590 ** deterministic. The built-in [random()] SQL function is an example of a
4599 ** pointers to C-language functions that implement the SQL function or
4600 ** aggregate. ^A scalar SQL function requires an implementation of the xFunc
4614 ** is passed a single argument which is a copy of the application data
4621 ** SQL function is used. ^A function implementation with a non-negative
4622 ** nArg parameter is a better match than a function implementation with
4623 ** a negative nArg. ^A function where the preferred text encoding
4624 ** matches the database encoding is a better
4625 ** match than a function where the encoding is different.
4626 ** ^A function where the encoding difference is between UTF16le and UTF16be
4627 ** is a closer match than a function where the encoding difference is
4630 ** ^Built-in functions may be overloaded by new application-defined functions.
4632 ** ^An application-defined function is permitted to call other
4675 #define SQLITE_UTF8 1 /* IMP: R-37514-35566 */
4676 #define SQLITE_UTF16LE 2 /* IMP: R-03371-37637 */
4677 #define SQLITE_UTF16BE 3 /* IMP: R-51971-34154 */
4720 ** <tr><td><b>sqlite3_value_int</b><td>→<td>32-bit INTEGER value
4721 ** <tr><td><b>sqlite3_value_int64</b><td>→<td>64-bit INTEGER value
4723 ** <tr><td><b>sqlite3_value_text</b><td>→<td>UTF-8 TEXT value
4724 ** <tr><td><b>sqlite3_value_text16</b><td>→<td>UTF-16 TEXT value in
4726 ** <tr><td><b>sqlite3_value_text16be</b><td>→<td>UTF-16be TEXT value
4727 ** <tr><td><b>sqlite3_value_text16le</b><td>→<td>UTF-16le TEXT value
4729 ** <tr><td><b>sqlite3_value_bytes</b><td>→<td>Size of a BLOB
4730 ** or a UTF-8 TEXT in bytes
4732 ** <td>→ <td>Size of UTF-16
4745 ** [application-defined SQL functions] and [virtual tables].
4752 ** except that these routines take a single [protected sqlite3_value] object
4753 ** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
4755 ** ^The sqlite3_value_text16() interface extracts a UTF-16 string
4756 ** in the native byte-order of the host machine. ^The
4758 ** extract UTF-16 strings as big-endian and little-endian respectively.
4764 ** sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer()
4773 ** sqlite3_value_text(V) is called to extract a text value for that
4775 ** SQLITE_TEXT. Whether or not a persistent internal datatype conversion
4781 ** such a conversion is possible without loss of information (in other
4782 ** words, if the value is a string that looks like a number)
4788 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
4814 ** an [application-defined SQL function] argument V. The subtype
4815 ** information can be used to pass a limited amount of context from
4825 ** ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value]
4826 ** object D and returns a pointer to that copy. ^The [sqlite3_value] returned
4827 ** is a [protected sqlite3_value] object even if the input is not.
4828 ** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
4832 ** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer
4833 ** then sqlite3_value_free(V) is a harmless no-op.
4846 ** for a particular aggregate function, SQLite
4847 ** allocates N of memory, zeroes out that memory, and returns a pointer
4858 ** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer
4859 ** when first called if N is less than or equal to zero or if a memory
4873 ** The first parameter must be a copy of the
4887 ** ^The sqlite3_user_data() interface returns a copy of
4894 ** the application-defined function is running.
4902 ** ^The sqlite3_context_db_handle() interface returns a copy of
4914 ** These functions may be used by (non-aggregate) SQL functions to
4918 ** of where this might be useful is in a regular-expression matching
4925 ** ^The sqlite3_get_auxdata(C,N) interface returns a pointer to the metadata
4927 ** value to the application-defined function. ^N is zero for the left-most
4930 ** returns a NULL pointer.
4932 ** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th
4933 ** argument of the application-defined function. ^Subsequent
4946 ** <li> ^(during the original sqlite3_set_auxdata() call when a memory
4957 ** function parameters that are compile-time constants, including literal
4960 ** The value of the N parameter to these interfaces should be non-negative.
4987 #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
5003 ** an application-defined function to be the BLOB whose content is pointed
5008 ** interfaces set the result of the application-defined function to be
5009 ** a BLOB containing all zero bytes and N bytes in size.
5012 ** an application-defined function to be a floating point value specified
5020 ** message string from sqlite3_result_error() as UTF-8. ^SQLite
5021 ** interprets the string from sqlite3_result_error16() as UTF-16 in native
5026 ** sqlite3_result_error16() is non-negative then SQLite takes that many
5029 ** routines make a private copy of the error message text before
5033 ** returned by SQLite as a result of an error in a function. ^By default,
5034 ** the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error()
5038 ** error indicating that a string or BLOB is too long to represent.
5041 ** error indicating that a memory allocation failed.
5044 ** of the application-defined function to be the 32-bit signed integer
5047 ** of the application-defined function to be the 64-bit signed integer
5051 ** of the application-defined function to be NULL.
5055 ** set the return value of the application-defined function to be
5056 ** a text string which is represented as UTF-8, UTF-16 native byte order,
5057 ** UTF-16 little endian, or UTF-16 big endian, respectively.
5059 ** application-defined function to be a text string in an encoding
5068 ** is non-negative, then as many bytes (not characters) of the text
5069 ** pointed to by the 2nd parameter are taken as the application-defined
5070 ** function result. If the 3rd parameter is non-negative, then it
5073 ** in the string at a byte offset that is less than the value of the 3rd
5077 ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
5083 ** copy the content of the parameter nor call a destructor on the content
5087 ** then SQLite makes a copy of the result into space obtained
5091 ** the application-defined function to be a copy of the
5093 ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
5096 ** ^A [protected sqlite3_value] object may always be used where an
5102 ** also associates the host-language pointer P or type T with that
5104 ** [application-defined SQL function] using [sqlite3_value_pointer()].
5105 ** ^If the D parameter is not NULL, then it is a pointer to a destructor
5107 ** when SQLite is finished with P. The T parameter should be a static
5108 ** string and preferably a string literal. The sqlite3_result_pointer()
5112 ** than the one containing the application-defined function that received
5144 ** the result from the [application-defined SQL function] with
5157 ** ^These functions add, remove, or modify a [collation] associated
5160 ** ^The name of the collation is a UTF-8 string
5162 ** and a UTF-16 string in native byte order for sqlite3_create_collation16().
5184 ** ^The fifth argument, xCallback, is a pointer to the collating function.
5192 ** ^The collating function callback is invoked with a copy of the pArg
5197 ** respectively. A collating function must always return the same answer
5202 ** strings A, B, and C:
5205 ** <li> If A==B then B==A.
5206 ** <li> If A==B and B==C then A==C.
5207 ** <li> If A<B THEN B>A.
5208 ** <li> If A<B and B<C then A<C.
5211 ** If a collating function fails any of the above constraints and that
5224 ** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
5260 ** ^To avoid having to register all collation sequences before a database
5261 ** can be used, a single callback function may be registered with the
5267 ** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
5268 ** the names are passed as UTF-16 in machine native byte order.
5269 ** ^A call to either function replaces the existing collation-needed callback.
5271 ** ^(When the callback is invoked, the first argument passed is a copy
5331 ** Specify the activation key for a SEE database. Unless
5341 ** Specify the activation key for a CEROD database. Unless
5350 ** CAPI3REF: Suspend Execution For A Short Time
5353 ** for at least a number of milliseconds specified in its parameter.
5371 ** ^(If this global variable is made to point to a string which is
5372 ** the name of a folder (a.k.a. directory), then all temporary files
5373 ** created by SQLite when using a built-in [sqlite3_vfs | VFS]
5375 ** is a NULL pointer, then SQLite performs a search for an appropriate
5379 ** It is required to set a temporary folder on Windows Runtime (WinRT).
5381 ** neither read nor write this variable. This global variable is a relic
5386 ** thread at a time. It is not safe to read or modify this variable
5387 ** if a [database connection] is being used at the same time in a separate
5415 ** LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
5416 ** TemporaryFolder->Path->Data();
5419 ** WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
5429 ** ^(If this global variable is made to point to a string which is
5430 ** the name of a folder (a.k.a. directory), then all database files
5431 ** specified with a relative pathname and created or accessed by
5432 ** SQLite when using a built-in windows [sqlite3_vfs | VFS] will be assumed
5433 ** to be relative to that directory.)^ ^If this variable is a NULL
5435 ** with a relative pathname are relative to the current directory
5439 ** Changing the value of this variable while a database connection is
5440 ** open can result in a corrupt database.
5443 ** thread at a time. It is not safe to read or modify this variable
5444 ** if a [database connection] is being used at the same time in a separate
5464 ** CAPI3REF: Test For Auto-Commit Mode
5468 ** ^The sqlite3_get_autocommit() interface returns non-zero or
5471 ** ^Autocommit mode is disabled by a [BEGIN] statement.
5472 ** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
5474 ** If certain kinds of errors occur on a statement within a multi-statement
5488 ** CAPI3REF: Find The Database Handle Of A Prepared Statement
5492 ** to which a [prepared statement] belongs. ^The [database connection]
5501 ** CAPI3REF: Return The Filename For A Database Connection
5504 ** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename
5507 ** connection D, or if database N is a temporary or in-memory database, then
5508 ** a NULL pointer is returned.
5513 ** to open the database originally was a URI or relative pathname.
5518 ** CAPI3REF: Determine if a database is read-only
5522 ** of connection D is read-only, 0 if it is read/write, or -1 if N is not
5523 ** the name of a database on connection D.
5531 ** ^This interface returns a pointer to the next [prepared statement] after
5533 ** then this interface returns a pointer to the first prepared statement
5537 ** The [database connection] pointer D in a call to
5539 ** connection and in particular must not be a NULL pointer.
5547 ** ^The sqlite3_commit_hook() interface registers a callback
5548 ** function to be invoked whenever a transaction is [COMMIT | committed].
5549 ** ^Any callback set by a previous call to sqlite3_commit_hook()
5551 ** ^The sqlite3_rollback_hook() interface registers a callback
5552 ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
5553 ** ^Any callback set by a previous call to sqlite3_rollback_hook()
5556 ** ^If the callback on a commit hook function returns non-zero,
5557 ** then the commit is converted into a rollback.
5574 ** ^Registering a NULL function disables the callback.
5578 ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
5579 ** ^The rollback hook is invoked on a rollback that results from a commit
5580 ** hook returning non-zero, just as it would be with any other rollback.
5582 ** ^For the purposes of this API, a transaction is said to have been
5585 ** ^The rollback callback is not invoked if a transaction is
5597 ** ^The sqlite3_update_hook() interface registers a callback function
5599 ** to be invoked whenever a row is updated, inserted or deleted in
5600 ** a [rowid table].
5601 ** ^Any callback set by a previous call to this function
5604 ** ^The second argument is a pointer to the function to invoke when a
5605 ** row is updated, inserted or deleted in a rowid table.
5606 ** ^The first argument to the callback is a copy of the third argument
5624 ** The exceptions defined in this paragraph might change in a future
5657 ** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).
5675 ** shared cache mode should be enabled per-database connection via
5678 ** This interface is threadsafe on processors where writing a
5679 ** 32-bit integer is atomic.
5681 ** See Also: [SQLite Shared-Cache Mode]
5689 ** of heap memory by deallocating non-essential memory allocations
5691 ** pages to improve performance is an example of non-essential memory.
5694 ** ^The sqlite3_release_memory() routine is a no-op returning zero
5702 ** CAPI3REF: Free Memory Used By A Database Connection
5708 ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
5716 ** CAPI3REF: Impose A Limit On Heap Size
5733 ** sqlite3_soft_heap_limit64() with a negative argument.
5742 ** <li> Memory accounting is disabled using a combination of the
5743 ** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and
5744 ** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.
5755 ** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT],
5772 ** This is a deprecated version of the [sqlite3_soft_heap_limit64()]
5781 ** CAPI3REF: Extract Metadata About A Column Of A Table
5787 ** interface returns SQLITE_OK and fills in the non-NULL pointers in
5791 ** ^If the column-name parameter to sqlite3_table_column_metadata() is a
5794 ** does not. If the table name parameter T in a call to
5818 ** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint
5828 ** ^If the specified table is actually a view, an [error code] is returned.
5831 ** is not a [WITHOUT ROWID] table and an
5858 int *pAutoinc /* OUTPUT: True if column is auto-increment */
5870 ** with various operating-system specific extensions added.
5878 ** If that does not work, it constructs a name "sqlite3_X_init" where the
5879 ** X is consists of the lower-case equivalent of all ASCII alphabetic
5917 ** unprepared to deal with [extension loading], and as a means of disabling
5918 ** [extension loading] while evaluating user-entered SQL, the following API
5926 ** ^This interface enables or disables both the C-API
5929 ** to enable or disable only the C-API.)^
5944 ** xEntryPoint() is the entry point for a statically linked [SQLite extension]
5969 ** on the list of automatic extensions is a harmless no-op. ^No entry point
5981 ** initialization routine X that was registered using a prior call to
5998 ** The interface to the virtual-table mechanism is currently considered
6000 ** If this is a problem for you, do not use the interface at this time.
6002 ** When the virtual-table mechanism stabilizes, we will declare the
6018 ** This structure, sometimes called a "virtual table module",
6019 ** defines the implementation of a [virtual tables].
6022 ** ^A virtual table module is created by filling in a persistent
6023 ** instance of this structure and passing a pointer to that instance
6025 ** ^The registration remains valid until it is replaced by a different
6072 ** method of a [virtual table module]. The fields under **Inputs** are the
6073 ** inputs to xBestIndex and are read-only. xBestIndex inserts its
6085 ** expr on the right-hand side can be evaluated (and thus the constraint
6095 ** ^Each term of aOrderBy records a column of the ORDER BY clause.
6100 ** passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),
6106 ** non-zero.
6110 ** the right-hand side of the corresponding aConstraint[] is evaluated
6111 ** and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit
6124 ** ^The estimatedCost value is an estimate of the cost of a particular
6125 ** strategy. A cost of N indicates that the cost of the strategy is similar
6126 ** to a linear scan of an SQLite table with N rows. A cost of log(N)
6127 ** indicates that the expense of the operation is similar to that of a
6128 ** binary search on a unique indexed field of an SQLite table with N rows.
6133 ** The xBestIndex method may optionally populate the idxFlags field with a
6134 ** mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag -
6139 ** SQLite also assumes that if a call to the xUpdate() method is made as
6140 ** part of the same statement to delete or update a virtual table row and the
6150 ** If a virtual table extension is
6154 ** therefore only be used if [sqlite3_libversion_number()] returns a
6158 ** sqlite3_libversion_number() returns a value greater than or equal to
6165 int iColumn; /* Column constrained. -1 for ROWID */
6168 int iTermOffset; /* Used internally - xBestIndex should ignore */
6178 unsigned char omit; /* Do not code a test for this constraint */
6203 ** an operator that is part of a constraint term in the wHERE clause of
6204 ** a query that uses a [virtual table].
6217 ** CAPI3REF: Register A Virtual Table Implementation
6220 ** ^These routines are used to register a new [virtual table module] name.
6222 ** creating a new [virtual table] using the module and before using a
6227 ** second parameter. ^The third parameter is a pointer to
6231 ** when a new virtual table is be being created or reinitialized.
6233 ** ^The sqlite3_create_module_v2() interface has a fifth parameter which
6234 ** is a pointer to a destructor for the pClientData. ^SQLite will
6239 ** interface is equivalent to sqlite3_create_module_v2() with a NULL
6260 ** Every [virtual table module] implementation uses a subclass
6261 ** of this object to describe a particular instance
6267 ** ^Virtual tables methods can set an error message by assigning a
6269 ** take care that any prior string is freed by a call to [sqlite3_free()]
6270 ** prior to assigning a new string to zErrMsg. ^After the error message
6285 ** Every [virtual table module] implementation uses a subclass of the
6293 ** the content of a cursor structure to suit its own needs.
6304 ** CAPI3REF: Declare The Schema Of A Virtual Table
6306 ** ^The [xCreate] and [xConnect] methods of a
6314 ** CAPI3REF: Overload A Function For A Virtual Table
6322 ** ^(This API makes sure a global version of a function with a particular
6324 ** before this API is called, a new function is created.)^ ^The implementation
6327 ** purpose is to be a placeholder function that can be overloaded
6328 ** by a [virtual table].
6333 ** The interface to the virtual-table mechanism defined above (back up
6334 ** to a comment remarkably similar to this one) is currently considered
6336 ** If this is a problem for you, do not use the interface at this time.
6338 ** When the virtual-table mechanism stabilizes, we will declare the
6343 ** CAPI3REF: A Handle To An Open BLOB
6357 ** CAPI3REF: Open A BLOB For Incremental I/O
6361 ** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located
6375 ** ^If the flags parameter is non-zero, then the BLOB is opened for read
6377 ** read-only access.
6389 ** <li> ^(Table zTable is a WITHOUT ROWID table)^,
6392 ** <li> ^(The specified column of row iRow contains a value that is not
6393 ** a TEXT or BLOB value)^,
6397 ** column zColumn is part of a [child key] definition and the blob is
6405 ** A BLOB referenced by sqlite3_blob_open() may be read using the
6407 ** [sqlite3_blob_write()]. The [BLOB handle] can be moved to a
6409 ** interface. However, the column, table, or database of a [BLOB handle]
6412 ** ^(If the row that a BLOB handle points to is modified by an
6413 ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
6415 ** This is true if any column of the row is changed, even a column
6418 ** an expired BLOB handle fail with a return code of [SQLITE_ABORT].
6419 ** ^(Changes written into a BLOB prior to the BLOB expiring are not
6424 ** the opened blob. ^The size of a blob may not be changed by this
6425 ** interface. Use the [UPDATE] SQL command to change the size of a
6429 ** and the built-in [zeroblob] SQL function may be used to create a
6430 ** zero-filled blob to read or write using the incremental-blob interface.
6432 ** To avoid a resource leak, every open [BLOB handle] should eventually
6433 ** be released by a call to [sqlite3_blob_close()].
6450 ** CAPI3REF: Move a BLOB Handle to a New Row
6454 ** to a different row of the same database table. ^The new row is identified
6457 ** remain the same. Moving an existing [BLOB handle] to a new row is
6458 ** faster than closing the existing handle and opening a new one.
6460 ** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -
6461 ** it must exist and there must be either a blob or text value stored in
6463 ** it does not contain a blob or text value, or if another error occurs, an
6475 ** CAPI3REF: Close A BLOB Handle
6482 ** ^If the blob handle being closed was opened for read-write access, and if
6483 ** the database is in auto-commit mode and there are no other open read-write
6488 ** Calling this function with an argument that is not a NULL pointer or an
6490 ** with a null pointer (such as would be returned by a failed call to
6491 ** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function
6492 ** is passed a valid open blob handle, the values returned by the
6504 ** blob content; they cannot change the size of a blob.
6506 ** This routine only works on a [BLOB handle] which has been created
6507 ** by a prior successful call to [sqlite3_blob_open()] and which has not
6514 ** CAPI3REF: Read Data From A BLOB Incrementally
6517 ** ^(This function is used to read data from an open [BLOB handle] into a
6518 ** caller-supplied buffer. N bytes of data are copied into buffer Z
6533 ** This routine only works on a [BLOB handle] which has been created
6534 ** by a prior successful call to [sqlite3_blob_open()] and which has not
6543 ** CAPI3REF: Write Data Into A BLOB Incrementally
6546 ** ^(This function is used to write data into an open [BLOB handle] from a
6547 ** caller-supplied buffer. N bytes of data are copied from the buffer Z
6561 ** not possible to increase the size of a BLOB using this API.
6575 ** This routine only works on a [BLOB handle] which has been created
6576 ** by a prior successful call to [sqlite3_blob_open()] and which has not
6587 ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
6589 ** with the underlying operating system. Most SQLite builds come with a
6594 ** ^The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.
6596 ** ^Names are zero-terminated UTF-8 strings.
6597 ** ^If there is no match, a NULL pointer is returned.
6605 ** same name are registered, the behavior is undefined. If a
6606 ** VFS is registered with a name that is NULL or an empty string,
6609 ** ^Unregister a VFS with the sqlite3_vfs_unregister() interface.
6627 ** is selected automatically at compile-time. The following
6636 ** The SQLITE_MUTEX_NOOP implementation is a set of routines
6638 ** a single-threaded application. The SQLITE_MUTEX_PTHREADS and
6643 ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
6645 ** application must supply a custom mutex implementation using the
6650 ** ^The sqlite3_mutex_alloc() routine allocates a new
6651 ** mutex and returns a pointer to it. ^The sqlite3_mutex_alloc()
6675 ** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
6677 ** The mutex implementation does not need to make a distinction
6679 ** not want to. SQLite will only request a recursive mutex in
6680 ** cases where it really needs one. If a faster non-recursive mutex
6682 ** might return such a mutex in response to SQLITE_MUTEX_FAST.
6686 ** a pointer to a static preexisting mutex. ^Nine static mutexes are
6695 ** returns a different mutex on every call. ^For the static
6699 ** ^The sqlite3_mutex_free() routine deallocates a previously
6700 ** allocated dynamic mutex. Attempting to deallocate a static
6704 ** to enter a mutex. ^If another thread is already within the mutex,
6720 ** ^The sqlite3_mutex_leave() routine exits a mutex that was
6726 ** sqlite3_mutex_leave() is a NULL pointer, then all three routines
6727 ** behave as no-ops.
6740 ** An instance of this structure defines the low-level routines
6744 ** sufficient, however the application has the option of substituting a custom
6746 ** does not provide a suitable implementation. In this case, the application
6780 ** above silently ignore any invocations that pass a NULL pointer instead
6781 ** of a valid mutex handle. The implementations of the methods defined
6783 ** of passing a NULL pointer instead of a valid mutex handle are undefined
6785 ** it is passed a NULL pointer).
6790 ** xMutexInit() must be no-ops.
6794 ** allocation for a static mutex. ^However xMutexAlloc() may use SQLite
6795 ** memory allocation for a fast or recursive mutex.
6835 ** If the argument to sqlite3_mutex_held() is a NULL pointer then
6836 ** the routine should return 1. This seems counter-intuitive since
6840 ** call to sqlite3_mutex_held() to fail, so a non-zero return is
6842 ** interface should also return 1 when given a NULL pointer.
6852 ** The [sqlite3_mutex_alloc()] interface takes a single argument
6856 ** next. Applications that override the built-in mutex logic must be
6872 #define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */
6877 ** CAPI3REF: Retrieve the mutex for a database connection
6880 ** ^This interface returns a pointer the [sqlite3_mutex] object that
6883 ** ^If the [threading mode] is Single-thread or Multi-thread then this
6884 ** routine returns a NULL pointer.
6889 ** CAPI3REF: Low-Level Control Of Database Files
6892 ** ^The [sqlite3_file_control()] interface makes a direct call to the
6894 ** with a particular database identified by the second argument. ^The
6898 ** ^A NULL pointer can be used in place of "main" to refer to the
6906 ** a pointer to the underlying [sqlite3_file] object to be written into
6908 ** case is a short-circuit path which does not actually invoke the
6996 ** SQLITE_OK on success and a non-zero [error code] on failure.
6999 ** be represented by a 32-bit integer, then the values returned by
7017 ** These integer constants designate various run-time status parameters
7026 ** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache
7068 ** in bytes. Since a single thread may only have one scratch allocation
7112 ** about a single [database connection]. ^The first argument is the
7125 ** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a
7126 ** non-zero [error code] on failure.
7142 ** The [sqlite3_db_status()] interface will return a non-zero error code
7143 ** if a discontinued or unsupported verb is invoked.
7152 ** satisfied using lookaside memory. Only the high-water value is meaningful;
7160 ** Only the high-water value is meaningful;
7168 ** Only the high-water value is meaningful;
7178 ** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a
7191 ** with the connection - main, temp, and any [ATTACH]-ed databases.)^
7222 ** If an IO or other error occurs while writing a page to disk, the effect
7259 ** that the prepared statement is using a full table scan rather than
7263 ** a [prepared statement]. The first argument is the prepared statement
7265 ** is an integer code for a specific [SQLITE_STMTSTATUS counter]
7286 ** a table as part of a full table scan. Large numbers for this counter
7292 ** A non-zero value in this counter may indicate an opportunity to
7298 ** A non-zero value in this counter may indicate an opportunity to
7306 ** used as a proxy for the total work done by the prepared statement.
7317 ** been run. A single "run" for the purposes of this counter is one
7318 ** or more calls to [sqlite3_step()] followed by a call to [sqlite3_reset()].
7325 ** a counter, and so the resetFlg parameter to sqlite3_stmt_status()
7354 ** The sqlite3_pcache_page object represents a single page in the
7376 ** By implementing a
7380 ** determine exactly which parts of a database file are cached and for
7385 ** The built-in page cache is recommended for most uses.
7396 ** method is passed a copy of the sqlite3_pcache_methods2.pArg value.)^
7400 ** built-in default page cache is used instead of the application defined
7419 ** ^SQLite invokes the xCreate() method to construct a new cache instance.
7423 ** be allocated by the cache. ^szPage will always a power of two. ^The
7424 ** second parameter szExtra is a number of bytes of extra storage
7426 ** a number less than 250. SQLite will use the
7431 ** created will be used to cache database pages of a file stored on disk, or
7432 ** false if it is used for an in-memory database. The cache implementation
7434 ** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
7435 ** never invoke xUnpin() except to deliberately delete a page.
7436 ** ^In other words, calls to xUnpin() on a cache with bPurgeable set to
7438 ** ^Hence, a cache created with bPurgeable false will
7443 ** suggested maximum cache-size (number of pages stored by) the cache
7454 ** The xFetch() method locates a page in the cache and returns a pointer to
7455 ** an sqlite3_pcache_page object associated with that page, or a NULL pointer.
7456 ** The pBuf element of the returned sqlite3_pcache_page object will be a
7457 ** pointer to a buffer of szPage bytes used to store the content of a
7459 ** a pointer to the szExtra bytes of extra storage that SQLite has requested
7467 ** implementation must return a pointer to the page buffer with its content
7474 ** <tr><td> 0 <td> Do not allocate a new page. Return NULL.
7475 ** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
7477 ** <tr><td> 2 <td> Make every effort to allocate a new page. Only return
7478 ** NULL if allocating a new page is effectively impossible.
7481 ** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite
7482 ** will only use a createFlag of 2 after a prior call with a createFlag of 1
7488 ** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
7489 ** as its second argument. If the third parameter, discard, is non-zero,
7496 ** The cache must not perform any reference counting. A single
7514 ** ^The xDestroy() method is used to delete a cache allocated by xCreate().
7523 ** is not obligated to free any memory, but well-behaved implementations should
7570 ** a call to [sqlite3_backup_init()] and is destroyed by a call to
7582 ** for copying in-memory databases to or from persistent files.
7586 ** ^SQLite holds a write transaction open on the destination database file
7588 ** ^The source database is read-locked only while it is being read;
7590 ** ^Thus, the backup may be performed on a live source database without
7594 ** ^(To perform a backup operation:
7621 ** ^A call to sqlite3_backup_init() will fail, returning NULL, if
7622 ** there is already a read or read-write transaction open on the
7631 ** ^A successful call to sqlite3_backup_init() returns a pointer to an
7648 ** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
7654 ** <li> the destination database was opened read-only, or
7655 ** <li> the destination database is using write-ahead-log journaling
7657 ** <li> the destination database is an in-memory database and the
7661 ** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
7662 ** the [sqlite3_busy_handler | busy-handler function]
7664 ** busy-handler returns non-zero before the lock is available, then
7682 ** sqlite3_backup_step() obtains a [shared lock] on the source database that
7685 ** sqlite3_backup_step(), the source database may be modified mid-way
7687 ** external process or via a database connection other than the one being
7702 ** active write-transaction on the destination database is rolled back.
7704 ** and may not be used following a call to sqlite3_backup_finish().
7709 ** ^If an out-of-memory condition or IO error occurred during any prior
7713 ** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
7714 ** is not a permanent error and does not affect the return value of
7726 ** sqlite3_backup_step(). If the source database is modified in a way that
7735 ** purposes while a backup operation is underway or being initialized.
7746 ** nevertheless. Use of the destination database connection while a
7747 ** backup is in progress might also also cause a mutex deadlock.
7778 ** ^When running in shared-cache mode, a database operation may fail with
7779 ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
7780 ** individual tables within the shared-cache cannot be obtained. See
7781 ** [SQLite Shared-Cache Mode] for a description of shared-cache locking.
7782 ** ^This API may be used to register a callback that SQLite will invoke
7785 ** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
7789 ** ^Shared-cache locks are released when a database connection concludes
7792 ** ^When a connection (known as the blocked connection) fails to obtain a
7793 ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
7798 ** the first argument to register for a callback that will be invoked
7803 ** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
7804 ** there is a chance that the blocking connection will have already
7809 ** ^If the blocked connection is attempting to obtain a write-lock on a
7810 ** shared-cache table, and more than one other connection currently holds
7811 ** a read-lock on the same table, then SQLite arbitrarily selects one of
7814 ** ^(There may be at most one unlock-notify callback registered by a
7816 ** blocked connection already has a registered unlock-notify callback,
7818 ** called with a NULL pointer as its second argument, then any existing
7819 ** unlock-notify callback is canceled. ^The blocked connections
7820 ** unlock-notify callback may also be canceled by closing the blocked
7823 ** The unlock-notify callback is not reentrant. If an application invokes
7824 ** any sqlite3_xxx API functions from within an unlock-notify callback, a
7832 ** When an unlock-notify callback is registered, the application provides a
7836 ** an unlock-notify callback is a pointer to an array of void* pointers,
7839 ** When a blocking connections transaction is concluded, there may be
7840 ** more than one blocked connection that has registered for an unlock-notify
7850 ** Assuming that after registering for an unlock-notify callback a
7852 ** action (a reasonable assumption), then using this API may cause the
7859 ** detection. ^If a given call to sqlite3_unlock_notify() would put the
7860 ** system in a deadlocked state, then SQLITE_LOCKED is returned and no
7861 ** unlock-notify callback is registered. The system is said to be in
7862 ** a deadlocked state if connection A has registered for an unlock-notify
7864 ** B has itself registered for an unlock-notify callback when connection
7865 ** A's transaction is concluded. ^Indirect deadlock is also detected, so
7867 ** registered for an unlock-notify callback on the conclusion of connection
7868 ** C's transaction, where connection C is waiting on connection A. ^Any
7873 ** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
7875 ** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
7879 ** sqlite3_unlock_notify() results in the unlock-notify callback being
7880 ** invoked immediately. If the application then re-attempts the "DROP TABLE"
7884 ** by an sqlite3_step() call. ^(If there is a blocking connection, then the
7900 ** and extensions to compare the contents of two buffers containing UTF-8
7901 ** strings in a case-independent fashion, using the same definition of "case
7917 ** Note that this routine returns zero on a match and non-zero if the strings
7934 ** insensitive - equivalent upper and lower case ASCII characters match
7940 ** Note that this routine returns zero on a match and non-zero if the strings
7950 ** ^The [sqlite3_log()] interface writes a message into the [error log]
7964 ** a fixed-length buffer on the stack. If the log message is longer than
7965 ** a few hundred characters, it will be truncated to the length of the
7971 ** CAPI3REF: Write-Ahead Log Commit Hook
7974 ** ^The [sqlite3_wal_hook()] function is used to register a callback that
7975 ** is invoked each time data is committed to a database in wal mode.
7978 ** the associated write-lock on the database released)^, so the implementation
7982 ** is a copy of the third parameter passed to sqlite3_wal_hook() when
7983 ** registering the callback. ^The second is a copy of the database handle.
7984 ** ^The third parameter is the name of the database that was written to -
7985 ** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter
7986 ** is the number of pages currently in the write-ahead log file,
7993 ** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value
7997 ** A single database handle may have at most a single write-ahead log callback
7999 ** previously registered write-ahead log callback. ^Note that the
8011 ** CAPI3REF: Configure an auto-checkpoint
8014 ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
8017 ** after committing a transaction if there are N or
8018 ** more frames in the [write-ahead log] file. ^Passing zero or
8019 ** a negative value as the nFrame parameter disables automatic
8023 ** registered using [sqlite3_wal_hook()]. ^Likewise, registering a callback
8033 ** ^Every new [database connection] defaults to having the auto-checkpoint
8034 ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]
8037 ** for a particular application.
8042 ** CAPI3REF: Checkpoint a database
8049 ** [write-ahead log] for database X on [database connection] D to be
8050 ** transferred into the database file and for the write-ahead log to
8054 ** This interface used to be the only way to cause a checkpoint to
8057 ** compatibility and as a convenience for applications that need to manually
8058 ** start a callback but which do not need the full power (and corresponding
8064 ** CAPI3REF: Checkpoint a database
8067 ** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint
8070 ** ^(The M parameter must be a valid [checkpoint mode]:)^
8076 ** in the log were checkpointed. ^The [busy-handler callback]
8083 ** [sqlite3_busy_handler|busy-handler callback]) until there is no
8092 ** [busy-handler callback])
8101 ** to a successful return.
8105 ** the log file or to -1 if the checkpoint could not run because
8109 ** was called) or to -1 if the checkpoint could not run due to an error or
8115 ** any other process is running a checkpoint operation at the same time, the
8116 ** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a
8117 ** busy-handler configured, it will not be invoked in this case.
8121 ** obtained immediately, and a busy-handler is configured, it is invoked and
8122 ** the writer lock retried until either the busy-handler returns 0 or the lock
8123 ** is successfully obtained. ^The busy-handler is also invoked while waiting for
8124 ** database readers as described above. ^If the busy-handler returns 0 before
8127 ** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
8130 ** ^If parameter zDb is NULL or points to a zero length string, then the
8143 ** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If
8144 ** zDb is not NULL (or a zero length string) and is not the name of any
8181 ** of a [virtual table] implementation to configure
8207 ** a call to the [xUpdate] method returns [SQLITE_CONSTRAINT], then the entire
8212 ** If X is non-zero, then the virtual table implementation guarantees
8216 ** is able to roll back a statement or database transaction, and abandon
8223 ** must do so within the [xUpdate] method. If a call to the
8237 ** This function may only be called from within a call to the [xUpdate] method
8238 ** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The
8251 ** inform a [virtual table] implementation what the [ON CONFLICT] mode
8254 ** Note that the [SQLITE_IGNORE] constant is also used as a potential
8256 ** [SQLITE_ABORT] is also a [result code].
8269 ** [sqlite3_stmt_scanstatus(S,X,T,V)] interface. Each constant designates a
8272 ** When the value returned to V is a string, space to hold that string is
8279 ** set to the total number of times that the X-th loop has run.</dd>
8283 ** to the total number of rows examined by all iterations of the X-th loop.</dd>
8288 ** iteration of the X-th loop. If the query planner's estimates was accurate,
8295 ** to a zero-terminated UTF-8 string containing the name of the index or table
8296 ** used for the X-th loop.
8300 ** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN]
8301 ** description for the X-th loop.
8305 ** "select-id" for the X-th loop. The select-id identifies which query or
8306 ** subquery the loop is part of. The main query has a select-id of zero.
8307 ** The select-id is the same value as is output in the first column
8329 ** compile-time option.
8334 ** ^The requested measurement is written into a variable pointed to by
8337 ** Loops are numbered starting from zero. ^If idx is out of range - less than
8339 ** the statement - a non-zero value is returned and the variable that pOut
8344 ** as if the loop did not exist - it returns non-zero and leave the variable
8357 ** CAPI3REF: Zero Scan-Status Counters
8362 ** This API is only available if the library is built with pre-processor
8368 ** CAPI3REF: Flush caches to disk mid-transaction
8370 ** ^If a write-transaction is open on [database connection] D when the
8372 ** pages in the pager-cache that are not currently in use are written out
8373 ** to disk. A dirty page may be in use if a database cursor created by an
8374 ** active SQL statement is reading from it, or if it is page 1 of a database
8376 ** interface flushes caches for all schemas - "main", "temp", and
8381 ** immediately and there is a busy-handler callback configured, it is invoked
8389 ** example an IO error or out-of-memory condition), then processing is
8400 ** CAPI3REF: The pre-update hook.
8403 ** [SQLITE_ENABLE_PREUPDATE_HOOK] compile-time option.
8405 ** ^The [sqlite3_preupdate_hook()] interface registers a callback function
8407 ** on a database table.
8408 ** ^At most one preupdate hook may be registered at a time on a single
8412 ** with a NULL pointer as the second parameter.
8420 ** ^The second parameter to the preupdate callback is a pointer to
8433 ** For an UPDATE or DELETE operation on a [rowid table], the sixth
8435 ** row being modified or deleted. For an INSERT operation on a rowid table,
8436 ** or any operation on a WITHOUT ROWID table, the value of the sixth
8437 ** parameter is undefined. For an INSERT or UPDATE on a rowid table the
8445 ** provide additional information about a preupdate event. These routines
8446 ** may only be called from within a preupdate callback. Invoking any of
8447 ** these routines from outside of a preupdate callback or with a
8455 ** ^The [sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to
8456 ** a [protected sqlite3_value] that contains the value of the Nth column of
8464 ** ^The [sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to
8465 ** a [protected sqlite3_value] that contains the value of the Nth column of
8474 ** callback was invoked as a result of a direct insert, update, or delete
8475 ** operation; or 1 for inserts, updates, or deletes invoked by top-level
8476 ** triggers; or 2 for changes resulting from triggers called by top-level
8491 sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */
8502 ** CAPI3REF: Low-level system error code
8505 ** number that caused the most recent I/O error or failure to open a file.
8506 ** The return value is OS-dependent. For example, on unix systems, after
8518 ** An instance of the snapshot object records the state of a [WAL mode]
8522 ** same database file can each be reading a different historical version
8523 ** of the database file. When a [database connection] begins a read
8527 ** by the reader until a new read transaction is started.
8530 ** version of the database file so that it is possible to later open a new read
8535 ** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer
8544 ** CAPI3REF: Record A Database Snapshot
8547 ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a
8550 ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly
8552 ** If there is not already a read-transaction open on schema S when
8563 ** <li> Schema S of [database connection] D must be a [WAL mode] database.
8565 ** <li> There must not be a write transaction open on schema S of database
8570 ** that a snapshot cannot be taken on a wal mode database with no wal
8577 ** whether or not a read transaction is opened on schema S is undefined.
8579 ** The [sqlite3_snapshot] object returned from a successful call to
8581 ** to avoid a memory leak.
8584 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
8593 ** CAPI3REF: Start a read transaction on an historical snapshot
8596 ** ^The [sqlite3_snapshot_open(D,S,P)] interface starts a
8604 ** ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be
8608 ** a transaction for [sqlite3_snapshot_open(D,S,P)] to work, but the
8610 ** ^A [snapshot] will fail to open if it has been overwritten by a
8612 ** ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the
8614 ** schema S is in [WAL mode]. A database connection might not know
8618 ** (Hint: Run "[PRAGMA application_id]" against a newly opened
8622 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
8631 ** CAPI3REF: Destroy a snapshot
8636 ** using this routine to avoid a memory leak.
8639 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
8661 ** Otherwise, this API returns a negative value if P1 refers to an older
8663 ** snapshot, and a positive value if P1 is a newer snapshot than P2.
8671 ** CAPI3REF: Recover snapshots from a wal file
8674 ** If all connections disconnect from a database file but do not perform
8675 ** a checkpoint, the existing wal file is opened along with the database
8684 ** sqlite3_snapshot_open(). It is an error if there is already a read
8685 ** transaction open on the database, or if the database is not a wal mode
8710 ** a legal notice, here is a blessing:
8730 /* The double-precision datatype used by RTree depends on the
8731 ** SQLITE_RTREE_INT_ONLY compile-time option.
8740 ** Register a geometry callback named zGeom that can be used as part of an
8741 ** R-Tree geometry query as follows:
8754 ** A pointer to a structure of the following type is passed as the first
8766 ** Register a 2nd-generation geometry callback named zScore that can be
8767 ** used as part of an R-Tree geometry query as follows:
8781 ** A pointer to a structure of the following type is passed as the
8786 ** sqlite3_rtree_geometry. This structure is a subclass of
8848 ** CAPI3REF: Create A New Session Object
8850 ** Create a new session object attached to database handle db. If successful,
8851 ** a pointer to the new object is written to *ppSession and SQLITE_OK is
8855 ** It is possible to create multiple session objects attached to a single
8866 ** is not possible for an application to register a pre-update hook on a
8868 ** it possible to create a session object attached to a database handle for
8869 ** which a pre-update hook is already defined. The results of attempting
8884 ** CAPI3REF: Delete A Session Object
8886 ** Delete a session object previously allocated using
8887 ** [sqlite3session_create()]. Once a session object has been deleted, the
8899 ** CAPI3REF: Enable Or Disable A Session Object
8901 ** Enable or disable the recording of changes by a session object. When
8902 ** enabled, a session object records changes made to the database. When
8903 ** disabled - it does not. A newly created session object is enabled.
8905 ** details regarding how enabling and disabling a session object affects
8908 ** Passing zero to this function disables the session. Passing a value
8909 ** greater than zero enables it. Passing a value less than zero is a
8910 ** no-op, and may be used to query the current state of the session.
8920 ** Each change recorded by a session object is marked as either direct or
8921 ** indirect. A change is marked as indirect if either:
8927 ** instead of directly as a result of a users SQL statement.
8930 ** If a single row is affected by more than one operation within a session,
8937 ** is set. Passing a value less than zero does not modify the current value
8947 ** CAPI3REF: Attach A Table To A Session Object
8949 ** If argument zTab is not NULL, then it is the name of a table to attach
8959 ** Changes can only be recorded for tables that have a PRIMARY KEY explicitly
8962 ** KEY may consist of a single column, or may be a composite key.
8965 ** is it an error if the named table does not have a PRIMARY KEY. However,
8980 ** CAPI3REF: Set a table filter on a Session Object.
8985 ** If xFilter returns 0, changes is not tracked. Note that once a table is
8998 ** CAPI3REF: Generate A Changeset From A Session Object
9000 ** Obtain a changeset containing changes to the tables attached to the
9002 ** set *ppChangeset to point to a buffer containing the changeset
9007 ** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
9008 ** each representing a change to a single row of an attached table. An INSERT
9009 ** change contains the values of each field of a new database row. A DELETE
9010 ** contains the original values of each field of a deleted database row. An
9012 ** database row along with the updated values for each updated non-primary-key
9013 ** column. It is not possible for an UPDATE change to represent a change that
9014 ** modifies the values of primary key columns. If such a change is made, it
9015 ** is represented in a changeset as a DELETE followed by an INSERT.
9018 ** more of their PRIMARY KEY columns. If such a row is inserted or deleted,
9021 ** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
9023 ** with non-NULL PRIMARY KEY values is updated so that one or more of its
9024 ** PRIMARY KEY columns are set to NULL, the resulting changeset contains a
9027 ** The contents of a changeset may be traversed using an iterator created
9028 ** using the [sqlite3changeset_start()] API. A changeset may be applied to
9029 ** a database with a compatible schema using the [sqlite3changeset_apply()]
9032 ** Within a changeset generated by this function, all changes related to a
9034 ** a changeset or when applying a changeset to a database, all changes related
9035 ** to a single table are processed before moving on to the next table. Tables
9036 ** are sorted in the same order in which they were attached (or auto-attached)
9038 ** a single table are stored is undefined.
9040 ** Following a successful call to this function, it is the responsibility of
9046 ** Once a table has been attached to a session object, the session object
9050 ** recorded once - the first time a row with said primary key is inserted,
9053 ** There is one exception to the previous paragraph: when a row is inserted,
9054 ** updated or deleted, if one or more of its primary key columns contain a
9057 ** The session object therefore accumulates two types of records - those
9059 ** a new record) and those that consist of the primary key values and the
9061 ** or updates a record).
9069 ** for a row with a matching primary key. If one is found, an INSERT
9074 ** queried for a row with a matching primary key. If such a row is
9075 ** found and one or more of the non-primary key fields have been
9077 ** the changeset. Or, if no such row is found in the table, a DELETE
9078 ** change is added to the changeset. If there is a row with a matching
9083 ** This means, amongst other things, that if a row is inserted and then later
9084 ** deleted while a session object is active, neither the insert nor the delete
9085 ** will be present in the changeset. Or if a row is deleted and then later a
9086 ** row with the same primary key values inserted while a session object is
9088 ** a DELETE and an INSERT.
9090 ** When a session object is disabled (see the [sqlite3session_enable()] API),
9092 ** This may appear to have some counter-intuitive effects if a single row
9093 ** is written to more than once during a session. For example, if a row
9094 ** is inserted while a session object is enabled, then later deleted while
9097 ** Or, if one field of a row is updated while a session is disabled, and
9108 ** CAPI3REF: Load The Difference Between Tables Into A Session
9113 ** does not have a primary key, this function is a no-op (but does not return
9116 ** Argument zFromDb must be the name of a database ("main", "temp" etc.)
9118 ** a table compatible with the table attached to the session by this function.
9119 ** A table is considered compatible if it:
9132 ** This function adds a set of changes to the session object that could be
9133 ** used to update the table in database zFrom (call this the "from-table")
9135 ** object (call this the "to-table"). Specifically:
9138 ** <li> For each row (primary key) that exists in the to-table but not in
9139 ** the from-table, an INSERT record is added to the session object.
9141 ** <li> For each row (primary key) that exists in the to-table but not in
9142 ** the from-table, a DELETE record is added to the session object.
9145 ** different non-PK values in each, an UPDATE record is added to the
9149 ** To clarify, if this function is called and then a changeset constructed
9159 ** may be set to point to a buffer containing an English language error
9172 ** CAPI3REF: Generate A Patchset From A Session Object
9174 ** The differences between a patchset and a changeset are that:
9183 ** A patchset blob may be used with up to date versions of all
9185 ** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,
9186 ** attempting to use a patchset blob with old versions of the
9189 ** Because the non-primary key "old.*" fields are omitted, no
9190 ** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset
9194 ** Changes within a patchset are ordered in the same way as for changesets
9196 ** a single table are grouped together, tables appear in the order in which
9206 ** CAPI3REF: Test if a changeset has recorded any changes.
9208 ** Return non-zero if no changes to attached tables have been recorded by
9213 ** [sqlite3session_changeset()] on the session handle may still return a
9214 ** changeset that contains no changes. This can happen when a row in
9216 ** are restored. However, if this function returns non-zero, then it is
9217 ** guaranteed that a call to sqlite3session_changeset() will return a
9223 ** CAPI3REF: Create An Iterator To Traverse A Changeset
9225 ** Create an iterator used to iterate through the contents of a changeset.
9230 ** The following functions can be used to advance and query a changeset
9248 ** that apply to a single table are grouped together. This means that when
9249 ** an application iterates through a changeset using an iterator created by
9250 ** this function, all changes that relate to a single table are visited
9251 ** consecutively. There is no chance that the iterator will visit a change
9263 ** CAPI3REF: Advance A Changeset Iterator
9267 ** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
9275 ** no error occurs and the iterator points to a valid change after a call
9287 ** CAPI3REF: Obtain The Current Operation From A Changeset Iterator
9290 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
9295 ** If argument pzTab is not NULL, then *pzTab is set to point to a
9296 ** nul-terminated utf-8 encoded string containing the name of the table
9299 ** conflict-handler function returns. If pnCol is not NULL, then *pnCol is
9303 ** [sqlite3session_indirect()] for a description of direct and indirect
9321 ** CAPI3REF: Obtain The Primary Key Definition Of A Table
9323 ** For each modified table, a changeset includes the following:
9340 ** If this function is called when the iterator does not point to a valid
9347 unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */
9352 ** CAPI3REF: Obtain old.* Values From A Changeset Iterator
9355 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
9366 ** If successful, this function sets *ppValue to point to a protected
9382 ** CAPI3REF: Obtain new.* Values From A Changeset Iterator
9385 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
9396 ** If successful, this function sets *ppValue to point to a protected
9400 ** a new value for the requested column, *ppValue is set to NULL and
9415 ** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator
9417 ** This function should only be used with iterator objects passed to a
9418 ** conflict-handler callback by [sqlite3changeset_apply()] with either
9427 ** If successful, this function sets *ppValue to point to a protected
9429 ** "conflicting row" associated with the current conflict-handler callback
9458 ** CAPI3REF: Finalize A Changeset Iterator
9465 ** function with an iterator passed to a conflict-handler by
9469 ** If an error was encountered within a call to an sqlite3changeset_xxx()
9473 ** returned. This is to allow the following pattern (pseudo-code):
9487 ** CAPI3REF: Invert A Changeset
9489 ** This function is used to "invert" a changeset object. Applying an inverted
9490 ** changeset to a database reverses the effects of applying the uninverted
9495 ** <li> Each INSERT change is changed to a DELETE, and
9502 ** If successful, a pointer to a buffer containing the inverted changeset
9508 ** on the *ppOut pointer to free the buffer allocation following a successful
9511 ** WARNING/TODO: This function currently assumes that the input is a valid
9522 ** This function is used to concatenate two changesets, A and B, into a
9523 ** single changeset. The result is a changeset equivalent to applying
9524 ** changeset A followed by changeset B.
9545 void *pA, /* Pointer to buffer containing changeset A */
9559 ** CAPI3REF: Create A New Changegroup Object
9562 ** (or patchsets) into a single changeset (or patchset). A single changegroup
9567 ** a pointer to a new sqlite3_changegroup object before returning. The caller
9568 ** should eventually free the returned object using a call to
9575 ** <li> It is created using a call to sqlite3changegroup_new().
9581 ** by the application via a call to sqlite3changegroup_output().
9583 ** <li> The object is deleted using a call to sqlite3changegroup_delete().
9596 ** CAPI3REF: Add A Changeset To A Changegroup
9601 ** If the buffer contains a patchset, then all prior calls to this function
9603 ** the buffer contains a changeset, so must have the earlier calls to this
9608 ** their PRIMARY KEY columns. A change in the changeset is considered to
9609 ** apply to the same row as a change already present in the changegroup if
9614 ** contain changes that apply to a single row, the final contents of the
9617 ** <table border=1 style="margin-left:8ex;margin-right:8ex">
9618 ** <tr><th style="white-space:pre">Existing Change </th>
9619 ** <th style="white-space:pre">New Change </th>
9659 ** If the new changeset contains changes to a table that is already present
9664 ** returned. Or, if an out-of-memory condition occurs during processing, this
9673 ** CAPI3REF: Obtain A Composite Changeset From A Changegroup
9675 ** Obtain a buffer containing a changeset (or patchset) representing the
9677 ** were themselves changesets, the output is a changeset. Or, if the
9678 ** inputs were patchsets, the output is also a patchset.
9681 ** sqlite3session_patchset() functions, all changes related to a single
9691 ** is returned and the output variables are set to the size of and a
9693 ** responsibility of the caller to eventually free the buffer using a
9703 ** CAPI3REF: Delete A Changegroup Object
9708 ** CAPI3REF: Apply A Changeset To A Database
9710 ** Apply a changeset to a database. This function attempts to update the
9717 ** the table name as the second argument, and a copy of the context pointer
9720 ** the table. Otherwise, if the return value is non-zero or the xFilter
9725 ** tests that the target database contains a compatible table. A table is
9738 ** changes associated with the table are applied. A warning message is issued
9742 ** For each change for which there is a compatible table, an attempt is made
9744 ** change. If a change cannot be applied cleanly, the conflict handler
9746 ** invoked. A description of exactly when the conflict handler is invoked for
9750 ** of passing anything other than a valid function pointer as the xConflict
9757 ** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
9761 ** returned by each invocation of the conflict-handler function. Refer to
9768 ** contains a row with the same primary key value (or values) as the
9770 ** stored in all non-primary key columns also match the values stored in
9773 ** If a row with matching primary key values is found, but one or more of
9774 ** the non-primary key fields contains a value different from the original
9775 ** row value stored in the changeset, the conflict-handler function is
9778 ** only the values of those non-primary key fields are compared against
9779 ** the current database contents - any trailing database table columns
9783 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
9787 ** (which can only happen if a foreign key constraint is violated), the
9788 ** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
9800 ** contains a row with the same primary key values, the conflict handler
9807 ** This includes the case where the INSERT operation is re-attempted because
9813 ** contains a row with the same primary key value (or values) as the
9815 ** stored in all modified non-primary key columns also match the values
9818 ** If a row with matching primary key values is found, but one or more of
9819 ** the modified non-primary key fields contains a value different from an
9820 ** original row value stored in the changeset, the conflict-handler function
9822 ** UPDATE changes only contain values for non-primary key fields that are
9824 ** avoid the SQLITE_CHANGESET_DATA conflict-handler callback.
9827 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
9831 ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
9843 ** All changes made by this function are enclosed in a savepoint transaction.
9844 ** If any other error (aside from a constraint failure when attempting to
9868 ** Values that may be passed as the second argument to a conflict-handler.
9873 ** when processing a DELETE or UPDATE change if a row with the required
9875 ** (non primary-key) fields modified by the update do not contain the
9883 ** argument when processing a DELETE or UPDATE change if a row with the
9898 ** If foreign key handling is enabled, and applying a changeset leaves the
9899 ** database in a state containing foreign key violations, the conflict
9911 ** If any other constraint violation occurs while applying a change (i.e.
9912 ** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
9929 ** A conflict handler callback must return one of the following three values.
9933 ** If a conflict handler returns this value no special action is taken. The
9948 ** handler, then the conflicting row is removed from the database and a
9965 ** corresponding non-streaming API functions:
9967 ** <table border=1 style="margin-left:8ex;margin-right:8ex">
9968 ** <tr><th>Streaming function<th>Non-streaming equivalent</th>
9977 ** Non-streaming functions that accept changesets (or patchsets) as input
9978 ** require that the entire changeset be stored in a single buffer in memory.
9979 ** Similarly, those that return a changeset or patchset do so by returning
9980 ** a pointer to a single large buffer allocated using sqlite3_malloc().
9981 ** Normally this is convenient. However, if an application running in a
9982 ** low-memory environment is required to handle very large changesets, the
9985 ** In order to avoid this problem, instead of a single large buffer, input
9986 ** is passed to a streaming API functions by way of a callback function that
9988 ** required. In all cases, a pair of API function parameters such as
10003 ** argument passed is a copy of the supplied pIn context pointer. The second
10004 ** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no
10011 ** returns a copy of the error code to the caller.
10020 ** return them in chunks by way of a callback function instead of via a
10021 ** pointer to a single large buffer. In this case, a pair of parameters such
10037 ** the application. The first parameter passed to each call is a copy of the
10039 ** points to a buffer nData bytes in size containing the chunk of output
10043 ** is immediately abandoned and the streaming API function returns a copy
10047 ** parameter set to a value less than or equal to zero. Other than this,
10119 ** a legal notice, here is a blessing:
10163 const unsigned char *a; member
10171 ** Return a copy of the context pointer the extension function was
10177 ** non-negative but less than the number of columns in the table, return
10192 ** non-negative but less than the number of columns in the table, set
10205 ** current document. If successful, (*pz) is set to point to a buffer
10206 ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes
10226 ** (i.e. if it is a contentless table), then this API always returns 0.
10238 ** set to -1.
10254 ** of the current query. Specifically, a query equivalent to:
10258 ** with $p set to a phrase equivalent to the phrase iPhrase of the
10264 ** Invoking Api.xUserData() returns a copy of the pointer passed as
10284 ** Each extension function is allocated a single auxiliary data slot for
10286 ** more than once for a single FTS query, then all invocations share a
10308 ** If the bClear argument is non-zero, then the auxiliary data is cleared
10322 ** method, to iterate through all instances of a single query phrase within
10330 ** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff);
10332 ** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff)
10338 ** modify this structure directly - it should only be used as shown above
10345 ** (i.e. if it is a contentless table), then this API always iterates
10346 ** through an empty set (all calls to xPhraseFirst() set iCol to -1).
10354 ** of iterating through all instances of a phrase in the current row, these
10356 ** that contain one or more instances of a specified phrase. For example:
10360 ** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol);
10362 ** pApi->xPhraseNextColumn(pFts, &iter, &iCol)
10369 ** "detail=none" "content=" option (i.e. if it is a contentless table),
10371 ** xPhraseFirstColumn() set iCol to -1).
10427 ** Applications may also register custom tokenizer types. A tokenizer
10428 ** is registered by providing fts5 with a populated instance of the
10434 ** This function is used to allocate and initialize a tokenizer instance.
10435 ** A tokenizer instance is required to actually tokenize text.
10437 ** The first argument passed to this function is a copy of the (void*)
10440 ** The second and third arguments are an array of nul-terminated strings
10452 ** This function is invoked to delete a tokenizer handle previously
10458 ** by argument pText. pText may or may not be nul-terminated. The first
10459 ** argument passed to this function is a pointer to an Fts5Tokenizer object
10466 ** <ul><li> <b>FTS5_TOKENIZE_DOCUMENT</b> - A document is being inserted into
10471 ** <li> <b>FTS5_TOKENIZE_QUERY</b> - A MATCH query is being executed
10473 ** a bareword or quoted string specified as part of the query.
10475 ** <li> <b>(FTS5_TOKENIZE_QUERY | FTS5_TOKENIZE_PREFIX)</b> - Same as
10477 ** followed by a "*" character, indicating that the last token
10478 ** returned by the tokenizer will be treated as a token prefix.
10480 ** <li> <b>FTS5_TOKENIZE_AUX</b> - The tokenizer is being invoked to
10483 ** on a columnsize=0 database.
10487 ** be invoked. The first argument to it should be a copy of the pointer
10489 ** arguments are a pointer to a buffer containing the token text, and the
10503 ** immediately return a copy of the xToken() return value. Or, if the
10511 ** Custom tokenizers may also support synonyms. Consider a case in which a
10512 ** user wishes to query for a phrase such as "first place". Using the
10513 ** built-in tokenizers, the FTS5 query 'first + place' will match instances
10521 ** <ol><li> By mapping all synonyms to a single token. In this case, the
10530 ** <li> By adding multiple synonyms for a single term to the FTS index.
10532 ** provide multiple synonyms for a single term within the document.
10540 ** first token in the MATCH query and FTS5 effectively runs a query
10547 ** still appears to contain just two phrases - "(first OR 1st)"
10548 ** being treated as a single phrase.
10550 ** <li> By adding multiple synonyms for a single term to the FTS index.
10552 ** provides multiple synonyms for each token. So that when a
10558 ** when tokenizing query text (it should not - to do would be
10565 ** specifies a <i>tflags</i> argument with the FTS5_TOKEN_COLOCATED bit
10566 ** is considered to supply a synonym for the previous token. For example,
10567 ** when parsing the document "I won first place", a tokenizer that supports
10579 ** xToken() is called. Multiple synonyms may be specified for a single token
10581 ** There is no limit to the number of synonyms that may be provided for a
10602 ** Method (2) offers a midpoint between (1) and (3). Using this method,
10603 ** a query such as '1s*' will match documents that contain the literal
10605 ** provide synonyms for prefixes). However, a non-prefix query like '1st'
10657 /* Create a new tokenizer */
10674 /* Create a new auxiliary function */