1515 1515 ** This option can be used to overload the default memory allocation
1516 1516 ** routines with a wrapper that simulations memory allocation failure or
1517 1517 ** tracks memory usage, for example. </dd>
1518 1518 **
1519 1519 ** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
1520 1520 ** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
1521 1521 ** interpreted as a boolean, which enables or disables the collection of
1522 -** memory allocation statistics. ^(When memory allocation statistics are disabled, the 1523 -** following SQLite interfaces become non-operational: 1522 +** memory allocation statistics. ^(When memory allocation statistics are 1523 +** disabled, the following SQLite interfaces become non-operational: 1524 1524 ** <ul>
1525 1525 ** <li> [sqlite3_memory_used()]
1526 1526 ** <li> [sqlite3_memory_highwater()]
1527 1527 ** <li> [sqlite3_soft_heap_limit64()]
1528 1528 ** <li> [sqlite3_status()]
1529 1529 ** </ul>)^
1530 1530 ** ^Memory allocation statistics are enabled by default unless SQLite is
................................................................................ 1557 1557 ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
1558 1558 ** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a static memory buffer
1559 1559 ** that SQLite can use for the database page cache with the default page
1560 1560 ** cache implementation.
1561 1561 ** This configuration should not be used if an application-define page
1562 1562 ** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2]
1563 1563 ** configuration option.
1564 -** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to 8-byte aligned 1564 +** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to 1565 +** 8-byte aligned 1565 1566 ** memory, the size of each page buffer (sz), and the number of pages (N).
1566 1567 ** The sz argument should be the size of the largest database page
1567 1568 ** (a power of two between 512 and 32768) plus some extra bytes for each
1568 1569 ** page header. ^The number of extra bytes needed by the page header
1569 1570 ** can be determined using the [SQLITE_CONFIG_PCACHE_HDRSZ] option
1570 1571 ** to [sqlite3_config()].
1571 1572 ** ^It is harmless, apart from the wasted memory,
................................................................................ 1577 1578 ** memory needs for the first N pages that it adds to cache. ^If additional
1578 1579 ** page cache memory is needed beyond what is provided by this option, then
1579 1580 ** SQLite goes to [sqlite3_malloc()] for the additional storage space.</dd>
1580 1581 **
1581 1582 ** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
1582 1583 ** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer
1583 1584 ** that SQLite will use for all of its dynamic memory allocation needs
1584 -** beyond those provided for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE]. 1585 +** beyond those provided for by [SQLITE_CONFIG_SCRATCH] and 1586 +** [SQLITE_CONFIG_PAGECACHE]. 1585 1587 ** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
1586 1588 ** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
1587 1589 ** [SQLITE_ERROR] if invoked otherwise.
1588 1590 ** ^There are three arguments to SQLITE_CONFIG_HEAP:
1589 1591 ** An 8-byte aligned pointer to the memory,
1590 1592 ** the number of bytes in the memory buffer, and the minimum allocation size.
1591 1593 ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
................................................................................ 1597 1599 ** boundary or subsequent behavior of SQLite will be undefined.
1598 1600 ** The minimum allocation size is capped at 2**12. Reasonable values
1599 1601 ** for the minimum allocation size are 2**5 through 2**8.</dd>
1600 1602 **
1601 1603 ** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
1602 1604 ** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
1603 1605 ** pointer to an instance of the [sqlite3_mutex_methods] structure.
1604 -** The argument specifies alternative low-level mutex routines to be used in place 1605 -** the mutex routines built into SQLite.)^ ^SQLite makes a copy of the 1606 -** content of the [sqlite3_mutex_methods] structure before the call to 1606 +** The argument specifies alternative low-level mutex routines to be used 1607 +** in place the mutex routines built into SQLite.)^ ^SQLite makes a copy of 1608 +** the content of the [sqlite3_mutex_methods] structure before the call to 1607 1609 ** [sqlite3_config()] returns. ^If SQLite is compiled with
1608 1610 ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1609 1611 ** the entire mutexing subsystem is omitted from the build and hence calls to
1610 1612 ** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
1611 1613 ** return [SQLITE_ERROR].</dd>
1612 1614 **
1613 1615 ** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
................................................................................ 1637 1639 ** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
1638 1640 ** a pointer to an [sqlite3_pcache_methods2] object. This object specifies
1639 1641 ** the interface to a custom page cache implementation.)^
1640 1642 ** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
1641 1643 **
1642 1644 ** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
1643 1645 ** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
1644 -** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of the current 1645 -** page cache implementation into that object.)^ </dd> 1646 +** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of 1647 +** the current page cache implementation into that object.)^ </dd> 1646 1648 **
1647 1649 ** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
1648 1650 ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
1649 1651 ** global [error log].
1650 1652 ** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
1651 1653 ** function with a call signature of void(*)(void*,int,const char*),
1652 1654 ** and a pointer to void. ^If the function pointer is not NULL, it is
................................................................................ 1663 1665 ** supplied by the application must not invoke any SQLite interface.
1664 1666 ** In a multi-threaded application, the application-defined logger
1665 1667 ** function must be threadsafe. </dd>
1666 1668 **
1667 1669 ** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
1668 1670 ** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
1669 1671 ** If non-zero, then URI handling is globally enabled. If the parameter is zero,
1670 -** then URI handling is globally disabled.)^ ^If URI handling is globally enabled, 1671 -** all filenames passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or 1672 +** then URI handling is globally disabled.)^ ^If URI handling is globally 1673 +** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()], 1674 +** [sqlite3_open16()] or 1672 1675 ** specified as part of [ATTACH] commands are interpreted as URIs, regardless
1673 1676 ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
1674 1677 ** connection is opened. ^If it is globally disabled, filenames are
1675 1678 ** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
1676 1679 ** database connection is opened. ^(By default, URI handling is globally
1677 1680 ** disabled. The default value may be changed by compiling with the
1678 1681 ** [SQLITE_USE_URI] symbol defined.)^
................................................................................ 1726 1729 ** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
1727 1730 ** ^If either argument to this option is negative, then that argument is
1728 1731 ** changed to its compile-time default.
1729 1732 **
1730 1733 ** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
1731 1734 ** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
1732 1735 ** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
1733 -** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro defined. 1734 -** ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value 1736 +** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro 1737 +** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value 1735 1738 ** that specifies the maximum size of the created heap.
1736 1739 ** </dl>
1737 1740 **
1738 1741 ** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
1739 1742 ** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
1740 1743 ** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
1741 1744 ** is a pointer to an integer and writes into that integer the number of extra
1742 -** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE]. The amount of 1743 -** extra space required can change depending on the compiler, 1745 +** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE]. 1746 +** The amount of extra space required can change depending on the compiler, 1744 1747 ** target platform, and SQLite version.
1745 1748 ** </dl>
1746 1749 */
1747 1750 #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
1748 1751 #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
1749 1752 #define SQLITE_CONFIG_SERIALIZED 3 /* nil */
1750 1753 #define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
................................................................................ 2040 2043 ** UTF-16 string in native byte order.
2041 2044 */
2042 2045 int sqlite3_complete(const char *sql);
2043 2046 int sqlite3_complete16(const void *sql);
2044 2047 2045 2048 /*
2046 2049 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
2050 +** KEYWORDS: {busy-handler callback} {busy handler} 2047 2051 **
2048 2052 ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
2049 2053 ** that might be invoked with argument P whenever
2050 2054 ** an attempt is made to access a database table associated with
2051 2055 ** [database connection] D when another thread
2052 2056 ** or process has the table locked.
2053 2057 ** The sqlite3_busy_handler() interface is used to implement
................................................................................ 4511 4515 ** kind of [sqlite3_value] object can be used with this interface.
4512 4516 **
4513 4517 ** If these routines are called from within the different thread
4514 4518 ** than the one containing the application-defined function that received
4515 4519 ** the [sqlite3_context] pointer, the results are undefined.
4516 4520 */
4517 4521 void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
4518 -void sqlite3_result_blob64(sqlite3_context*,const void*,sqlite3_uint64,void(*)(void*)); 4522 +void sqlite3_result_blob64(sqlite3_context*,const void*, 4523 + sqlite3_uint64,void(*)(void*)); 4519 4524 void sqlite3_result_double(sqlite3_context*, double);
4520 4525 void sqlite3_result_error(sqlite3_context*, const char*, int);
4521 4526 void sqlite3_result_error16(sqlite3_context*, const void*, int);
4522 4527 void sqlite3_result_error_toobig(sqlite3_context*);
4523 4528 void sqlite3_result_error_nomem(sqlite3_context*);
4524 4529 void sqlite3_result_error_code(sqlite3_context*, int);
4525 4530 void sqlite3_result_int(sqlite3_context*, int);
................................................................................ 7258 7263 ** complication) of [sqlite3_wal_checkpoint_v2()].
7259 7264 */
7260 7265 int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
7261 7266 7262 7267 /*
7263 7268 ** CAPI3REF: Checkpoint a database
7264 7269 **
7265 -** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint operation 7266 -** on database X of [database connection] D in mode M. Status information is 7267 -** written back into integers pointed to by L and C.)^ ^(The M parameter must be 7268 -** a valid [SQLITE_CHECKPOINT_PASSIVE|checkpoint mode]:)^ 7270 +** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint 7271 +** operation on database X of [database connection] D in mode M. Status 7272 +** information is written back into integers pointed to by L and C.)^ 7273 +** ^(The M parameter must be a valid [checkpoint mode]:)^ 7269 7274 **
7270 7275 ** <dl>
7271 7276 ** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
7272 7277 ** ^Checkpoint as many frames as possible without waiting for any database
7273 7278 ** readers or writers to finish, then sync the database file if all frames
7274 -** in the log were checkpointed. ^The [sqlite3_busy_handler|busy-handler callback] 7275 -** is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode. ^On the other hand, 7276 -** passive mode might leave the checkpoint unfinished if there are concurrent 7277 -** readers or writers. 7279 +** in the log were checkpointed. ^The [busy-handler callback] 7280 +** is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode. 7281 +** ^On the other hand, passive mode might leave the checkpoint unfinished 7282 +** if there are concurrent readers or writers. 7278 7283 **
7279 7284 ** <dt>SQLITE_CHECKPOINT_FULL<dd>
7280 7285 ** ^This mode blocks (it invokes the
7281 7286 ** [sqlite3_busy_handler|busy-handler callback]) until there is no
7282 7287 ** database writer and all readers are reading from the most recent database
7283 7288 ** snapshot. ^It then checkpoints all frames in the log file and syncs the
7284 7289 ** database file. ^This mode blocks new database writers while it is pending,
7285 7290 ** but new database readers are allowed to continue unimpeded.
7286 7291 **
7287 7292 ** <dt>SQLITE_CHECKPOINT_RESTART<dd>
7288 7293 ** ^This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition
7289 7294 ** that after checkpointing the log file it blocks (calls the
7290 -** [sqlite3_busy_handler|busy-handler callback]) 7295 +** [busy-handler callback]) 7291 7296 ** until all readers are reading from the database file only. ^This ensures
7292 7297 ** that the next writer will restart the log file from the beginning.
7293 7298 ** ^Like SQLITE_CHECKPOINT_FULL, this mode blocks new
7294 7299 ** database writer attempts while it is pending, but does not impede readers.
7295 7300 **
7296 7301 ** <dt>SQLITE_CHECKPOINT_TRUNCATE<dd>
7297 -** ^This mode works the same way as SQLITE_CHECKPOINT_RESTART with the addition 7298 -** that it also truncates the log file to zero bytes just prior to a successful 7299 -** return. 7302 +** ^This mode works the same way as SQLITE_CHECKPOINT_RESTART with the 7303 +** addition that it also truncates the log file to zero bytes just prior 7304 +** to a successful return. 7300 7305 ** </dl>
7301 7306 **
7302 7307 ** ^If pnLog is not NULL, then *pnLog is set to the total number of frames in
7303 7308 ** the log file or to -1 if the checkpoint could not run because
7304 -** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not NULL, 7305 -** then *pnCkpt is set to the total number of checkpointed frames in the log file 7306 -** (including any that were already checkpointed before the function was called) 7307 -** or to -1 if the checkpoint could not run due to an error or because the 7308 -** database is not in WAL mode. ^Note that upon successful completion of 7309 -** an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been truncated to 7310 -** zero bytes and so both *pnLog and *pnCkpt will be set to zero. 7309 +** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not 7310 +** NULL,then *pnCkpt is set to the total number of checkpointed frames in the 7311 +** log file (including any that were already checkpointed before the function 7312 +** was called) or to -1 if the checkpoint could not run due to an error or 7313 +** because the database is not in WAL mode. ^Note that upon successful 7314 +** completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been 7315 +** truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero. 7311 7316 **
7312 7317 ** ^All calls obtain an exclusive "checkpoint" lock on the database file. ^If
7313 7318 ** any other process is running a checkpoint operation at the same time, the
7314 7319 ** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a
7315 7320 ** busy-handler configured, it will not be invoked in this case.
7316 7321 **
7317 7322 ** ^The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the
................................................................................ 7363 7368 ** KEYWORDS: {checkpoint mode}
7364 7369 **
7365 7370 ** These constants define all valid values for the "checkpoint mode" passed
7366 7371 ** as the third parameter to the [sqlite3_wal_checkpoint_v2()] interface.
7367 7372 ** See the [sqlite3_wal_checkpoint_v2()] documentation for details on the
7368 7373 ** meaning of each of these checkpoint modes.
7369 7374 */
7370 -#define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible without blocking */ 7371 -#define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers to finish, then checkpoint */ 7372 -#define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but afterwards block for readers */ 7373 -#define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate the WAL file */ 7375 +#define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */ 7376 +#define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */ 7377 +#define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for for readers */ 7378 +#define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */ 7374 7379 7375 7380 /*
7376 7381 ** CAPI3REF: Virtual Table Interface Configuration
7377 7382 **
7378 7383 ** This function may be called by either the [xConnect] or [xCreate] method
7379 7384 ** of a [virtual table] implementation to configure
7380 7385 ** various facets of the virtual table interface.
................................................................................ 7465 7470 **
7466 7471 ** The following constants can be used for the T parameter to the
7467 7472 ** [sqlite3_stmt_scanstatus(S,X,T,V)] interface. Each constant designates a
7468 7473 ** different metric for sqlite3_stmt_scanstatus() to return.
7469 7474 **
7470 7475 ** <dl>
7471 7476 ** [[SQLITE_SCANSTAT_NLOOP]] <dt>SQLITE_SCANSTAT_NLOOP</dt>
7472 -** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set to the 7473 -** total number of times that the X-th loop has run.</dd> 7477 +** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be 7478 +** set to the total number of times that the X-th loop has run.</dd> 7474 7479 **
7475 7480 ** [[SQLITE_SCANSTAT_NVISIT]] <dt>SQLITE_SCANSTAT_NVISIT</dt>
7476 -** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set to the 7477 -** total number of rows examined by all iterations of the X-th loop.</dd> 7481 +** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set 7482 +** to the total number of rows examined by all iterations of the X-th loop.</dd> 7478 7483 **
7479 7484 ** [[SQLITE_SCANSTAT_EST]] <dt>SQLITE_SCANSTAT_EST</dt>
7480 7485 ** <dd>^The "double" variable pointed to by the T parameter will be set to the
7481 7486 ** query planner's estimate for the average number of rows output from each
7482 7487 ** iteration of the X-th loop. If the query planner's estimates was accurate,
7483 7488 ** then this value will approximate the quotient NVISIT/NLOOP and the
7484 7489 ** product of this value for all prior loops with the same SELECTID will
7485 7490 ** be the NLOOP value for the current loop.
7486 7491 **
7487 7492 ** [[SQLITE_SCANSTAT_NAME]] <dt>SQLITE_SCANSTAT_NAME</dt>
7488 -** <dd>^The "const char *" variable pointed to by the T parameter will be set to 7489 -** a zero-terminated UTF-8 string containing the name of the index or table used 7490 -** for the X-th loop. 7493 +** <dd>^The "const char *" variable pointed to by the T parameter will be set 7494 +** to a zero-terminated UTF-8 string containing the name of the index or table 7495 +** used for the X-th loop. 7491 7496 **
7492 7497 ** [[SQLITE_SCANSTAT_EXPLAIN]] <dt>SQLITE_SCANSTAT_EXPLAIN</dt>
7493 -** <dd>^The "const char *" variable pointed to by the T parameter will be set to 7494 -** a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN] description 7495 -** for the X-th loop. 7498 +** <dd>^The "const char *" variable pointed to by the T parameter will be set 7499 +** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN] 7500 +** description for the X-th loop. 7496 7501 **
7497 7502 ** [[SQLITE_SCANSTAT_SELECTID]] <dt>SQLITE_SCANSTAT_SELECT</dt>
7498 7503 ** <dd>^The "int" variable pointed to by the T parameter will be set to the
7499 7504 ** "select-id" for the X-th loop. The select-id identifies which query or
7500 7505 ** subquery the loop is part of. The main query has a select-id of zero.
7501 7506 ** The select-id is the same value as is output in the first column
7502 7507 ** of an [EXPLAIN QUERY PLAN] query.
................................................................................ 7511 7516 7512 7517 /*
7513 7518 ** CAPI3REF: Prepared Statement Scan Status
7514 7519 **
7515 7520 ** Return status data for a single loop within query pStmt.
7516 7521 **
7517 7522 ** The "iScanStatusOp" parameter determines which status information to return.
7518 -** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior of 7519 -** this interface is undefined. 7523 +** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior 7524 +** of this interface is undefined. 7520 7525 ** ^The requested measurement is written into a variable pointed to by
7521 7526 ** the "pOut" parameter.
7522 7527 ** Parameter "idx" identifies the specific loop to retrieve statistics for.
7523 7528 ** Loops are numbered starting from zero. ^If idx is out of range - less than
7524 7529 ** zero or greater than or equal to the total number of loops used to implement
7525 7530 ** the statement - a non-zero value is returned and the variable that pOut
7526 7531 ** points to is unchanged.

This page was generated in about
0.021s by
Fossil 2.7 [d3f454fa33] 2018-11-13 16:20:59