From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by turing.freelists.org (Avenir Technologies Mail Multiplex) with ESMTP id 84E0E2B6FE for ; Mon, 26 Mar 2018 11:57:19 -0400 (EDT) Received: from turing.freelists.org ([127.0.0.1]) by localhost (turing.freelists.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id Md_GwAL124fT for ; Mon, 26 Mar 2018 11:57:19 -0400 (EDT) Received: from smtp48.i.mail.ru (smtp48.i.mail.ru [94.100.177.108]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by turing.freelists.org (Avenir Technologies Mail Multiplex) with ESMTPS id A35CB26CE0 for ; Mon, 26 Mar 2018 11:57:16 -0400 (EDT) From: Kirill Yukhin Subject: [tarantool-patches] [PATCH 3/4] sql: remove dead memory allocation systems Date: Mon, 26 Mar 2018 18:56:57 +0300 Message-Id: In-Reply-To: References: In-Reply-To: References: Sender: tarantool-patches-bounce@freelists.org Errors-to: tarantool-patches-bounce@freelists.org Reply-To: tarantool-patches@freelists.org List-help: List-unsubscribe: List-software: Ecartis version 1.0.0 List-Id: tarantool-patches List-subscribe: List-owner: List-post: List-archive: To: v.shpilevoy@tarantool.org Cc: tarantool-patches@freelists.org, Kirill Yukhin Legacy SQL frontend contained about five different memory allocators, which were avaiable through dedicated API. Remove those allocators, limiting to simple malloc(). Remove API as well. --- src/box/sql/CMakeLists.txt | 5 - src/box/sql/global.c | 1 - src/box/sql/main.c | 73 +- src/box/sql/malloc.c | 142 +- src/box/sql/mem0.c | 116 - src/box/sql/mem1.c | 314 --- src/box/sql/mem2.c | 602 ---- src/box/sql/mem3.c | 767 ----- src/box/sql/mem5.c | 648 ----- src/box/sql/mutex.c | 211 -- src/box/sql/mutex.h | 82 - src/box/sql/mutex_noop.c | 300 -- src/box/sql/mutex_unix.c | 442 --- src/box/sql/sqlite3.h | 6728 -------------------------------------------- src/box/sql/sqliteInt.h | 48 +- src/box/sql/status.c | 3 +- 16 files changed, 109 insertions(+), 10373 deletions(-) delete mode 100644 src/box/sql/mem0.c delete mode 100644 src/box/sql/mem1.c delete mode 100644 src/box/sql/mem2.c delete mode 100644 src/box/sql/mem3.c delete mode 100644 src/box/sql/mem5.c delete mode 100644 src/box/sql/mutex.c delete mode 100644 src/box/sql/mutex.h delete mode 100644 src/box/sql/mutex_noop.c delete mode 100644 src/box/sql/mutex_unix.c delete mode 100644 src/box/sql/sqlite3.h diff --git a/src/box/sql/CMakeLists.txt b/src/box/sql/CMakeLists.txt index 8494e15..678eb4c 100644 --- a/src/box/sql/CMakeLists.txt +++ b/src/box/sql/CMakeLists.txt @@ -48,11 +48,6 @@ add_library(sql STATIC legacy.c main.c malloc.c - mem0.c - mem1.c - mem2.c - mem3.c - mem5.c os.c os_unix.c pragma.c diff --git a/src/box/sql/global.c b/src/box/sql/global.c index 6a78550..2304cbb 100644 --- a/src/box/sql/global.c +++ b/src/box/sql/global.c @@ -202,7 +202,6 @@ SQLITE_WSD struct Sqlite3Config sqlite3Config = { 512, /* szLookaside */ 125, /* nLookaside */ 0, /* nStmtSpill */ - {0, 0, 0, 0, 0, 0, 0, 0}, /* m */ {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}, /* pcache2 */ (void *)0, /* pHeap */ 0, /* nHeap */ diff --git a/src/box/sql/main.c b/src/box/sql/main.c index 1f8c026..89c028d 100644 --- a/src/box/sql/main.c +++ b/src/box/sql/main.c @@ -179,7 +179,7 @@ sqlite3_initialize(void) return SQLITE_OK; if (!sqlite3GlobalConfig.isMallocInit) - rc = sqlite3MallocInit(); + sqlite3MallocInit(); if (rc == SQLITE_OK) sqlite3GlobalConfig.isMallocInit = 1; @@ -326,29 +326,6 @@ sqlite3_config(int op, ...) va_start(ap, op); switch (op) { - case SQLITE_CONFIG_MALLOC:{ - /* EVIDENCE-OF: R-55594-21030 The SQLITE_CONFIG_MALLOC option takes a - * single argument which is a pointer to an instance of the - * sqlite3_mem_methods structure. The argument specifies alternative - * low-level memory allocation routines to be used in place of the memory - * allocation routines built into SQLite. - */ - sqlite3GlobalConfig.m = - *va_arg(ap, sqlite3_mem_methods *); - break; - } - case SQLITE_CONFIG_GETMALLOC:{ - /* EVIDENCE-OF: R-51213-46414 The SQLITE_CONFIG_GETMALLOC option takes a - * single argument which is a pointer to an instance of the - * sqlite3_mem_methods structure. The sqlite3_mem_methods structure is - * filled with the currently defined memory allocation routines. - */ - if (sqlite3GlobalConfig.m.xMalloc == 0) - sqlite3MemSetDefault(); - *va_arg(ap, sqlite3_mem_methods *) = - sqlite3GlobalConfig.m; - break; - } case SQLITE_CONFIG_MEMSTATUS:{ /* EVIDENCE-OF: R-61275-35157 The SQLITE_CONFIG_MEMSTATUS option takes * single argument of type int, interpreted as a boolean, which enables @@ -369,54 +346,6 @@ sqlite3_config(int op, ...) break; } -/* EVIDENCE-OF: R-06626-12911 The SQLITE_CONFIG_HEAP option is only - * available if SQLite is compiled with either SQLITE_ENABLE_MEMSYS3 or - * SQLITE_ENABLE_MEMSYS5 and returns SQLITE_ERROR if invoked otherwise. - */ -#if defined(SQLITE_ENABLE_MEMSYS3) || defined(SQLITE_ENABLE_MEMSYS5) - case SQLITE_CONFIG_HEAP:{ - /* EVIDENCE-OF: R-19854-42126 There are three arguments to - * SQLITE_CONFIG_HEAP: An 8-byte aligned pointer to the memory, the - * number of bytes in the memory buffer, and the minimum allocation size. - */ - sqlite3GlobalConfig.pHeap = va_arg(ap, void *); - sqlite3GlobalConfig.nHeap = va_arg(ap, int); - sqlite3GlobalConfig.mnReq = va_arg(ap, int); - - if (sqlite3GlobalConfig.mnReq < 1) { - sqlite3GlobalConfig.mnReq = 1; - } else if (sqlite3GlobalConfig.mnReq > (1 << 12)) { - /* cap min request size at 2^12 */ - sqlite3GlobalConfig.mnReq = (1 << 12); - } - - if (sqlite3GlobalConfig.pHeap == 0) { - /* EVIDENCE-OF: R-49920-60189 If the first pointer (the memory pointer) - * is NULL, then SQLite reverts to using its default memory allocator - * (the system malloc() implementation), undoing any prior invocation of - * SQLITE_CONFIG_MALLOC. - * - * Setting sqlite3GlobalConfig.m to all zeros will cause malloc to - * revert to its default implementation when sqlite3_initialize() is run - */ - memset(&sqlite3GlobalConfig.m, 0, - sizeof(sqlite3GlobalConfig.m)); - } else { - /* EVIDENCE-OF: R-61006-08918 If the memory pointer is not NULL then the - * alternative memory allocator is engaged to handle all of SQLites - * memory allocation needs. - */ -#ifdef SQLITE_ENABLE_MEMSYS3 - sqlite3GlobalConfig.m = *sqlite3MemGetMemsys3(); -#endif -#ifdef SQLITE_ENABLE_MEMSYS5 - sqlite3GlobalConfig.m = *sqlite3MemGetMemsys5(); -#endif - } - break; - } -#endif - case SQLITE_CONFIG_LOOKASIDE:{ sqlite3GlobalConfig.szLookaside = va_arg(ap, int); sqlite3GlobalConfig.nLookaside = va_arg(ap, int); diff --git a/src/box/sql/malloc.c b/src/box/sql/malloc.c index 0a8107a..9526cce 100644 --- a/src/box/sql/malloc.c +++ b/src/box/sql/malloc.c @@ -37,6 +37,93 @@ #include /* + * Like malloc(), but remember the size of the allocation + * so that we can find it later using sqlite3MemSize(). + * + * For this low-level routine, we are guaranteed that nByte>0 because + * cases of nByte<=0 will be intercepted and dealt with by higher level + * routines. + */ +static void * +sql_sized_malloc(int nByte) +{ + sqlite3_int64 *p; + assert(nByte > 0); + nByte = ROUND8(nByte); + p = malloc(nByte + 8); + if (p) { + p[0] = nByte; + p++; + } else { + testcase(sqlite3GlobalConfig.xLog != 0); + sqlite3_log(SQLITE_NOMEM, + "failed to allocate %u bytes of memory", nByte); + } + return (void *)p; +} + +/* + * Like free() but works for allocations obtained from sql_sized_malloc() + * or sql_sized_realloc(). + * + * For this low-level routine, we already know that pPrior!=0 since + * cases where pPrior==0 will have been intecepted and dealt with + * by higher-level routines. + */ +static void +sql_sized_free(void *pPrior) +{ + sqlite3_int64 *p = (sqlite3_int64 *) pPrior; + assert(pPrior != 0); + p--; + free(p); +} + +/* + * Report the allocated size of a prior return from sql_sized_malloc() + * or sql_sized_realloc(). + */ +static int +sql_sized_sizeof(void *pPrior) +{ + sqlite3_int64 *p; + assert(pPrior != 0); + p = (sqlite3_int64 *) pPrior; + p--; + return (int)p[0]; +} + +/* + * Like realloc(). Resize an allocation previously obtained from + * sqlite3MemMalloc(). + * + * For this low-level interface, we know that pPrior!=0. Cases where + * pPrior==0 while have been intercepted by higher-level routine and + * redirected to sql_sized_malloc. Similarly, we know that nByte>0 because + * cases where nByte<=0 will have been intercepted by higher-level + * routines and redirected to sql_sized_free. + */ +static void * +sql_sized_realloc(void *pPrior, int nByte) +{ + sqlite3_int64 *p = (sqlite3_int64 *) pPrior; + assert(pPrior != 0 && nByte > 0); + assert(nByte == ROUND8(nByte)); /* EV: R-46199-30249 */ + p--; + p = realloc(p, nByte + 8); + if (p) { + p[0] = nByte; + p++; + } else { + testcase(sqlite3GlobalConfig.xLog != 0); + sqlite3_log(SQLITE_NOMEM, + "failed memory resize %u to %u bytes", + sql_sized_sizeof(pPrior), nByte); + } + return (void *)p; +} + +/* * Attempt to release up to n bytes of non-essential memory currently * held by SQLite. An example of non-essential memory is memory used to * cache database pages that are not currently in use. @@ -130,13 +217,9 @@ sqlite3_soft_heap_limit(int n) /* * Initialize the memory allocation subsystem. */ -int +void sqlite3MallocInit(void) { - int rc; - if (sqlite3GlobalConfig.m.xMalloc == 0) { - sqlite3MemSetDefault(); - } memset(&mem0, 0, sizeof(mem0)); if (sqlite3GlobalConfig.pScratch && sqlite3GlobalConfig.szScratch >= 100 && sqlite3GlobalConfig.nScratch > 0) { @@ -165,10 +248,6 @@ sqlite3MallocInit(void) sqlite3GlobalConfig.pPage = 0; sqlite3GlobalConfig.szPage = 0; } - rc = sqlite3GlobalConfig.m.xInit(sqlite3GlobalConfig.m.pAppData); - if (rc != SQLITE_OK) - memset(&mem0, 0, sizeof(mem0)); - return rc; } /* @@ -188,9 +267,6 @@ sqlite3HeapNearlyFull(void) void sqlite3MallocEnd(void) { - if (sqlite3GlobalConfig.m.xShutdown) { - sqlite3GlobalConfig.m.xShutdown(sqlite3GlobalConfig.m.pAppData); - } memset(&mem0, 0, sizeof(mem0)); } @@ -238,7 +314,7 @@ mallocWithAlarm(int n, void **pp) { int nFull; void *p; - nFull = sqlite3GlobalConfig.m.xRoundup(n); + nFull = ROUND8(n); sqlite3StatusHighwater(SQLITE_STATUS_MALLOC_SIZE, n); if (mem0.alarmThreshold > 0) { sqlite3_int64 nUsed = @@ -250,11 +326,11 @@ mallocWithAlarm(int n, void **pp) mem0.nearlyFull = 0; } } - p = sqlite3GlobalConfig.m.xMalloc(nFull); + p = sql_sized_malloc(nFull); #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT if (p == 0 && mem0.alarmThreshold > 0) { sqlite3MallocAlarm(nFull); - p = sqlite3GlobalConfig.m.xMalloc(nFull); + p = sql_sized_malloc(nFull); } #endif if (p) { @@ -277,7 +353,7 @@ sqlite3Malloc(u64 n) if (n == 0 || n >= 0x7fffff00) { /* A memory allocation of a number of bytes which is near the maximum * signed integer value might cause an integer overflow inside of the - * xMalloc(). Hence we limit the maximum size to 0x7fffff00, giving + * sql_sized_malloc(). Hence we limit the maximum size to 0x7fffff00, giving * 255 bytes of overhead. SQLite itself will never use anything near * this amount. The only way to reach the limit is with sqlite3_malloc() */ @@ -285,7 +361,7 @@ sqlite3Malloc(u64 n) } else if (sqlite3GlobalConfig.bMemstat) { mallocWithAlarm((int)n, &p); } else { - p = sqlite3GlobalConfig.m.xMalloc((int)n); + p = sql_sized_malloc((int)n); } assert(EIGHT_BYTE_ALIGNMENT(p)); /* IMP: R-11148-40995 */ return p; @@ -409,10 +485,9 @@ sqlite3ScratchFree(void *p) iSize); sqlite3StatusDown(SQLITE_STATUS_MALLOC_COUNT, 1); - sqlite3GlobalConfig.m.xFree(p); - } else { - sqlite3GlobalConfig.m.xFree(p); - } + sql_sized_free(p); + } else + sql_sized_free(p); } } } @@ -438,7 +513,7 @@ int sqlite3MallocSize(void *p) { assert(sqlite3MemdebugHasType(p, MEMTYPE_HEAP)); - return sqlite3GlobalConfig.m.xSize(p); + return sql_sized_sizeof(p); } int @@ -457,7 +532,7 @@ sqlite3DbMallocSize(sqlite3 * db, void *p) (p, (u8) ~ (MEMTYPE_LOOKASIDE | MEMTYPE_HEAP))); } #endif - return sqlite3GlobalConfig.m.xSize(p); + return sql_sized_sizeof(p); } else return db->lookaside.sz; } @@ -467,7 +542,7 @@ sqlite3_msize(void *p) { assert(sqlite3MemdebugNoType(p, (u8) ~ MEMTYPE_HEAP)); assert(sqlite3MemdebugHasType(p, MEMTYPE_HEAP)); - return p ? sqlite3GlobalConfig.m.xSize(p) : 0; + return p ? sql_sized_sizeof(p) : 0; } /* @@ -484,10 +559,9 @@ sqlite3_free(void *p) sqlite3StatusDown(SQLITE_STATUS_MEMORY_USED, sqlite3MallocSize(p)); sqlite3StatusDown(SQLITE_STATUS_MALLOC_COUNT, 1); - sqlite3GlobalConfig.m.xFree(p); - } else { - sqlite3GlobalConfig.m.xFree(p); - } + sql_sized_free(p); + } else + sql_sized_free(p); } /* @@ -556,11 +630,7 @@ sqlite3Realloc(void *pOld, u64 nBytes) return 0; } nOld = sqlite3MallocSize(pOld); - /* IMPLEMENTATION-OF: R-46199-30249 SQLite guarantees that the second - * argument to xRealloc is always a value returned by a prior call to - * xRoundup. - */ - nNew = sqlite3GlobalConfig.m.xRoundup((int)nBytes); + nNew = ROUND8((int)nBytes); if (nOld == nNew) { pNew = pOld; } else if (sqlite3GlobalConfig.bMemstat) { @@ -571,17 +641,17 @@ sqlite3Realloc(void *pOld, u64 nBytes) mem0.alarmThreshold - nDiff) { sqlite3MallocAlarm(nDiff); } - pNew = sqlite3GlobalConfig.m.xRealloc(pOld, nNew); + pNew = sql_sized_realloc(pOld, nNew); if (pNew == 0 && mem0.alarmThreshold > 0) { sqlite3MallocAlarm((int)nBytes); - pNew = sqlite3GlobalConfig.m.xRealloc(pOld, nNew); + pNew = sql_sized_realloc(pOld, nNew); } if (pNew) { nNew = sqlite3MallocSize(pNew); sqlite3StatusUp(SQLITE_STATUS_MEMORY_USED, nNew - nOld); } } else { - pNew = sqlite3GlobalConfig.m.xRealloc(pOld, nNew); + pNew = sql_sized_realloc(pOld, nNew); } assert(EIGHT_BYTE_ALIGNMENT(pNew)); /* IMP: R-11148-40995 */ return pNew; diff --git a/src/box/sql/mem0.c b/src/box/sql/mem0.c deleted file mode 100644 index 39b4ab7..0000000 --- a/src/box/sql/mem0.c +++ /dev/null @@ -1,116 +0,0 @@ -/* - * Copyright 2010-2017, Tarantool AUTHORS, please see AUTHORS file. - * - * Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the - * following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED - * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL - * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, - * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - */ - -/* - * - * This file contains a no-op memory allocation drivers for use when - * SQLITE_ZERO_MALLOC is defined. The allocation drivers implemented - * here always fail. SQLite will not operate with these drivers. These - * are merely placeholders. Real drivers must be substituted using - * sqlite3_config() before SQLite will operate. - */ -#include "sqliteInt.h" - -/* - * This version of the memory allocator is the default. It is - * used when no other memory allocator is specified using compile-time - * macros. - */ -#ifdef SQLITE_ZERO_MALLOC - -/* - * No-op versions of all memory allocation routines - */ -static void * -sqlite3MemMalloc(int nByte) -{ - return 0; -} - -static void -sqlite3MemFree(void *pPrior) -{ - return; -} - -static void * -sqlite3MemRealloc(void *pPrior, int nByte) -{ - return 0; -} - -static int -sqlite3MemSize(void *pPrior) -{ - return 0; -} - -static int -sqlite3MemRoundup(int n) -{ - return n; -} - -static int -sqlite3MemInit(void *NotUsed) -{ - return SQLITE_OK; -} - -static void -sqlite3MemShutdown(void *NotUsed) -{ - return; -} - -/* - * This routine is the only routine in this file with external linkage. - * - * Populate the low-level memory allocation function pointers in - * sqlite3GlobalConfig.m with pointers to the routines in this file. - */ -void -sqlite3MemSetDefault(void) -{ - static const sqlite3_mem_methods defaultMethods = { - sqlite3MemMalloc, - sqlite3MemFree, - sqlite3MemRealloc, - sqlite3MemSize, - sqlite3MemRoundup, - sqlite3MemInit, - sqlite3MemShutdown, - 0 - }; - sqlite3_config(SQLITE_CONFIG_MALLOC, &defaultMethods); -} - -#endif /* SQLITE_ZERO_MALLOC */ diff --git a/src/box/sql/mem1.c b/src/box/sql/mem1.c deleted file mode 100644 index 2ea6731..0000000 --- a/src/box/sql/mem1.c +++ /dev/null @@ -1,314 +0,0 @@ -/* - * Copyright 2010-2017, Tarantool AUTHORS, please see AUTHORS file. - * - * Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the - * following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED - * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL - * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, - * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - */ - -/* - * - * This file contains low-level memory allocation drivers for when - * SQLite will use the standard C-library malloc/realloc/free interface - * to obtain the memory it needs. - * - * This file contains implementations of the low-level memory allocation - * routines specified in the sqlite3_mem_methods object. The content of - * this file is only used if SQLITE_SYSTEM_MALLOC is defined. The - * SQLITE_SYSTEM_MALLOC macro is defined automatically if - * SQLITE_MEMDEBUG macro is not defined. The - * default configuration is to use memory allocation routines in this - * file. - * - * C-preprocessor macro summary: - * - * HAVE_MALLOC_USABLE_SIZE The configure script sets this symbol if - * the malloc_usable_size() interface exists - * on the target platform. Or, this symbol - * can be set manually, if desired. - * If an equivalent interface exists by - * a different name, using a separate -D - * option to rename it. - * - * SQLITE_WITHOUT_ZONEMALLOC Some older macs lack support for the zone - * memory allocator. Set this symbol to enable - * building on older macs. - * - */ -#include "sqliteInt.h" - -/* - * This version of the memory allocator is the default. It is - * used when no other memory allocator is specified using compile-time - * macros. - */ -#ifdef SQLITE_SYSTEM_MALLOC -#if defined(__APPLE__) && !defined(SQLITE_WITHOUT_ZONEMALLOC) - -/* - * Use the zone allocator available on apple products unless the - * SQLITE_WITHOUT_ZONEMALLOC symbol is defined. - */ -#include -#include -#include -static malloc_zone_t *_sqliteZone_; -#define SQLITE_MALLOC(x) malloc_zone_malloc(_sqliteZone_, (x)) -#define SQLITE_FREE(x) malloc_zone_free(_sqliteZone_, (x)); -#define SQLITE_REALLOC(x,y) malloc_zone_realloc(_sqliteZone_, (x), (y)) -#define SQLITE_MALLOCSIZE(x) \ - (_sqliteZone_ ? _sqliteZone_->size(_sqliteZone_,x) : malloc_size(x)) - -#else /* if not __APPLE__ */ - -/* - * Use standard C library malloc and free on non-Apple systems. - * Also used by Apple systems if SQLITE_WITHOUT_ZONEMALLOC is defined. - */ -#define SQLITE_MALLOC(x) malloc(x) -#define SQLITE_FREE(x) free(x) -#define SQLITE_REALLOC(x,y) realloc((x),(y)) - -/* - * The malloc.h header file is needed for malloc_usable_size() function - * on some systems (e.g. Linux). - */ -#if HAVE_MALLOC_H && HAVE_MALLOC_USABLE_SIZE -#define SQLITE_USE_MALLOC_H 1 -#define SQLITE_USE_MALLOC_USABLE_SIZE 1 -#endif - -/* - * Include the malloc.h header file, if necessary. Also set define macro - * SQLITE_MALLOCSIZE to the appropriate function name, which is - * malloc_usable_size() for most systems (e.g. Linux). - * The memory size function can always be overridden manually by defining - * the macro SQLITE_MALLOCSIZE to the desired function name. - */ -#if defined(SQLITE_USE_MALLOC_H) -#include -#if defined(SQLITE_USE_MALLOC_USABLE_SIZE) -#if !defined(SQLITE_MALLOCSIZE) -#define SQLITE_MALLOCSIZE(x) malloc_usable_size(x) -#endif -#elif defined(SQLITE_USE_MSIZE) -#if !defined(SQLITE_MALLOCSIZE) -#define SQLITE_MALLOCSIZE _msize -#endif -#endif -#endif /* defined(SQLITE_USE_MALLOC_H) */ - -#endif /* __APPLE__ or not __APPLE__ */ - -/* - * Like malloc(), but remember the size of the allocation - * so that we can find it later using sqlite3MemSize(). - * - * For this low-level routine, we are guaranteed that nByte>0 because - * cases of nByte<=0 will be intercepted and dealt with by higher level - * routines. - */ -static void * -sqlite3MemMalloc(int nByte) -{ -#ifdef SQLITE_MALLOCSIZE - void *p = SQLITE_MALLOC(nByte); - if (p == 0) { - testcase(sqlite3GlobalConfig.xLog != 0); - sqlite3_log(SQLITE_NOMEM, - "failed to allocate %u bytes of memory", nByte); - } - return p; -#else - sqlite3_int64 *p; - assert(nByte > 0); - nByte = ROUND8(nByte); - p = SQLITE_MALLOC(nByte + 8); - if (p) { - p[0] = nByte; - p++; - } else { - testcase(sqlite3GlobalConfig.xLog != 0); - sqlite3_log(SQLITE_NOMEM, - "failed to allocate %u bytes of memory", nByte); - } - return (void *)p; -#endif -} - -/* - * Like free() but works for allocations obtained from sqlite3MemMalloc() - * or sqlite3MemRealloc(). - * - * For this low-level routine, we already know that pPrior!=0 since - * cases where pPrior==0 will have been intecepted and dealt with - * by higher-level routines. - */ -static void -sqlite3MemFree(void *pPrior) -{ -#ifdef SQLITE_MALLOCSIZE - SQLITE_FREE(pPrior); -#else - sqlite3_int64 *p = (sqlite3_int64 *) pPrior; - assert(pPrior != 0); - p--; - SQLITE_FREE(p); -#endif -} - -/* - * Report the allocated size of a prior return from xMalloc() - * or xRealloc(). - */ -static int -sqlite3MemSize(void *pPrior) -{ -#ifdef SQLITE_MALLOCSIZE - assert(pPrior != 0); - return (int)SQLITE_MALLOCSIZE(pPrior); -#else - sqlite3_int64 *p; - assert(pPrior != 0); - p = (sqlite3_int64 *) pPrior; - p--; - return (int)p[0]; -#endif -} - -/* - * Like realloc(). Resize an allocation previously obtained from - * sqlite3MemMalloc(). - * - * For this low-level interface, we know that pPrior!=0. Cases where - * pPrior==0 while have been intercepted by higher-level routine and - * redirected to xMalloc. Similarly, we know that nByte>0 because - * cases where nByte<=0 will have been intercepted by higher-level - * routines and redirected to xFree. - */ -static void * -sqlite3MemRealloc(void *pPrior, int nByte) -{ -#ifdef SQLITE_MALLOCSIZE - void *p = SQLITE_REALLOC(pPrior, nByte); - if (p == 0) { - testcase(sqlite3GlobalConfig.xLog != 0); - sqlite3_log(SQLITE_NOMEM, - "failed memory resize %u to %u bytes", - SQLITE_MALLOCSIZE(pPrior), nByte); - } - return p; -#else - sqlite3_int64 *p = (sqlite3_int64 *) pPrior; - assert(pPrior != 0 && nByte > 0); - assert(nByte == ROUND8(nByte)); /* EV: R-46199-30249 */ - p--; - p = SQLITE_REALLOC(p, nByte + 8); - if (p) { - p[0] = nByte; - p++; - } else { - testcase(sqlite3GlobalConfig.xLog != 0); - sqlite3_log(SQLITE_NOMEM, - "failed memory resize %u to %u bytes", - sqlite3MemSize(pPrior), nByte); - } - return (void *)p; -#endif -} - -/* - * Round up a request size to the next valid allocation size. - */ -static int -sqlite3MemRoundup(int n) -{ - return ROUND8(n); -} - -/* - * Initialize this module. - */ -static int -sqlite3MemInit(void *NotUsed) -{ -#if defined(__APPLE__) && !defined(SQLITE_WITHOUT_ZONEMALLOC) - int cpuCount; - size_t len; - if (_sqliteZone_) { - return SQLITE_OK; - } - len = sizeof(cpuCount); - /* One usually wants to use hw.acctivecpu for MT decisions, but not here */ - sysctlbyname("hw.ncpu", &cpuCount, &len, NULL, 0); - if (cpuCount > 1) { - /* defer MT decisions to system malloc */ - _sqliteZone_ = malloc_default_zone(); - } else { - /* only 1 core, use our own zone to contention over global locks, - * e.g. we have our own dedicated locks - */ - malloc_zone_t *newzone = malloc_create_zone(4096, 0); - malloc_set_zone_name(newzone, "Sqlite_Heap"); - } -#endif - UNUSED_PARAMETER(NotUsed); - return SQLITE_OK; -} - -/* - * Deinitialize this module. - */ -static void -sqlite3MemShutdown(void *NotUsed) -{ - UNUSED_PARAMETER(NotUsed); - return; -} - -/* - * This routine is the only routine in this file with external linkage. - * - * Populate the low-level memory allocation function pointers in - * sqlite3GlobalConfig.m with pointers to the routines in this file. - */ -void -sqlite3MemSetDefault(void) -{ - static const sqlite3_mem_methods defaultMethods = { - sqlite3MemMalloc, - sqlite3MemFree, - sqlite3MemRealloc, - sqlite3MemSize, - sqlite3MemRoundup, - sqlite3MemInit, - sqlite3MemShutdown, - 0 - }; - sqlite3_config(SQLITE_CONFIG_MALLOC, &defaultMethods); -} - -#endif /* SQLITE_SYSTEM_MALLOC */ diff --git a/src/box/sql/mem2.c b/src/box/sql/mem2.c deleted file mode 100644 index 0e8816e..0000000 --- a/src/box/sql/mem2.c +++ /dev/null @@ -1,602 +0,0 @@ -/* - * Copyright 2010-2017, Tarantool AUTHORS, please see AUTHORS file. - * - * Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the - * following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED - * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL - * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, - * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - */ - -/* - * - * This file contains low-level memory allocation drivers for when - * SQLite will use the standard C-library malloc/realloc/free interface - * to obtain the memory it needs while adding lots of additional debugging - * information to each allocation in order to help detect and fix memory - * leaks and memory usage errors. - * - * This file contains implementations of the low-level memory allocation - * routines specified in the sqlite3_mem_methods object. - */ -#include "sqliteInt.h" - -/* - * This version of the memory allocator is used only if the - * SQLITE_MEMDEBUG macro is defined - */ -#ifdef SQLITE_MEMDEBUG - -/* - * The backtrace functionality is only available with GLIBC - */ -#ifdef __GLIBC__ -extern int backtrace(void **, int); -extern void backtrace_symbols_fd(void *const *, int, int); -#else -#define backtrace(A,B) 1 -#define backtrace_symbols_fd(A,B,C) -#endif -#include - -/* - * Each memory allocation looks like this: - * - * ------------------------------------------------------------------------ - * | Title | backtrace pointers | MemBlockHdr | allocation | EndGuard | - * ------------------------------------------------------------------------ - * - * The application code sees only a pointer to the allocation. We have - * to back up from the allocation pointer to find the MemBlockHdr. The - * MemBlockHdr tells us the size of the allocation and the number of - * backtrace pointers. There is also a guard word at the end of the - * MemBlockHdr. - */ -struct MemBlockHdr { - i64 iSize; /* Size of this allocation */ - struct MemBlockHdr *pNext, *pPrev; /* Linked list of all unfreed memory */ - char nBacktrace; /* Number of backtraces on this alloc */ - char nBacktraceSlots; /* Available backtrace slots */ - u8 nTitle; /* Bytes of title; includes '\0' */ - u8 eType; /* Allocation type code */ - int iForeGuard; /* Guard word for sanity */ -}; - -/* - * Guard words - */ -#define FOREGUARD 0x80F5E153 -#define REARGUARD 0xE4676B53 - -/* - * Number of malloc size increments to track. - */ -#define NCSIZE 1000 - -/* - * All of the static variables used by this module are collected - * into a single structure named "mem". This is to keep the - * static variables organized and to reduce namespace pollution - * when this module is combined with other in the amalgamation. - */ -static struct { - - /* - * Mutex to control access to the memory allocation subsystem. - */ - sqlite3_mutex *mutex; - - /* - * Head and tail of a linked list of all outstanding allocations - */ - struct MemBlockHdr *pFirst; - struct MemBlockHdr *pLast; - - /* - * The number of levels of backtrace to save in new allocations. - */ - int nBacktrace; - void (*xBacktrace) (int, int, void **); - - /* - * Title text to insert in front of each block - */ - int nTitle; /* Bytes of zTitle to save. Includes '\0' and padding */ - char zTitle[100]; /* The title text */ - - /* - * sqlite3MallocDisallow() increments the following counter. - * sqlite3MallocAllow() decrements it. - */ - int disallow; /* Do not allow memory allocation */ - - /* - * Gather statistics on the sizes of memory allocations. - * nAlloc[i] is the number of allocation attempts of i*8 - * bytes. i==NCSIZE is the number of allocation attempts for - * sizes more than NCSIZE*8 bytes. - */ - int nAlloc[NCSIZE]; /* Total number of allocations */ - int nCurrent[NCSIZE]; /* Current number of allocations */ - int mxCurrent[NCSIZE]; /* Highwater mark for nCurrent */ - -} mem; - -/* - * Adjust memory usage statistics - */ -static void -adjustStats(int iSize, int increment) -{ - int i = ROUND8(iSize) / 8; - if (i > NCSIZE - 1) { - i = NCSIZE - 1; - } - if (increment > 0) { - mem.nAlloc[i]++; - mem.nCurrent[i]++; - if (mem.nCurrent[i] > mem.mxCurrent[i]) { - mem.mxCurrent[i] = mem.nCurrent[i]; - } - } else { - mem.nCurrent[i]--; - assert(mem.nCurrent[i] >= 0); - } -} - -/* - * Given an allocation, find the MemBlockHdr for that allocation. - * - * This routine checks the guards at either end of the allocation and - * if they are incorrect it asserts. - */ -static struct MemBlockHdr * -sqlite3MemsysGetHeader(void *pAllocation) -{ - struct MemBlockHdr *p; - int *pInt; - u8 *pU8; - int nReserve; - - p = (struct MemBlockHdr *)pAllocation; - p--; - assert(p->iForeGuard == (int)FOREGUARD); - nReserve = ROUND8(p->iSize); - pInt = (int *)pAllocation; - pU8 = (u8 *) pAllocation; - assert(pInt[nReserve / sizeof(int)] == (int)REARGUARD); - /* This checks any of the "extra" bytes allocated due - * to rounding up to an 8 byte boundary to ensure - * they haven't been overwritten. - */ - while (nReserve-- > p->iSize) - assert(pU8[nReserve] == 0x65); - return p; -} - -/* - * Return the number of bytes currently allocated at address p. - */ -static int -sqlite3MemSize(void *p) -{ - struct MemBlockHdr *pHdr; - if (!p) { - return 0; - } - pHdr = sqlite3MemsysGetHeader(p); - return (int)pHdr->iSize; -} - -/* - * Initialize the memory allocation subsystem. - */ -static int -sqlite3MemInit(void *NotUsed) -{ - UNUSED_PARAMETER(NotUsed); - assert((sizeof(struct MemBlockHdr) & 7) == 0); - if (!sqlite3GlobalConfig.bMemstat) { - /* If memory status is enabled, then the malloc.c wrapper will already - * hold the STATIC_MEM mutex when the routines here are invoked. - */ - mem.mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM); - } - return SQLITE_OK; -} - -/* - * Deinitialize the memory allocation subsystem. - */ -static void -sqlite3MemShutdown(void *NotUsed) -{ - UNUSED_PARAMETER(NotUsed); - mem.mutex = 0; -} - -/* - * Round up a request size to the next valid allocation size. - */ -static int -sqlite3MemRoundup(int n) -{ - return ROUND8(n); -} - -/* - * Fill a buffer with pseudo-random bytes. This is used to preset - * the content of a new memory allocation to unpredictable values and - * to clear the content of a freed allocation to unpredictable values. - */ -static void -randomFill(char *pBuf, int nByte) -{ - unsigned int x, y, r; - x = SQLITE_PTR_TO_INT(pBuf); - y = nByte | 1; - while (nByte >= 4) { - x = (x >> 1) ^ (-(int)(x & 1) & 0xd0000001); - y = y * 1103515245 + 12345; - r = x ^ y; - *(int *)pBuf = r; - pBuf += 4; - nByte -= 4; - } - while (nByte-- > 0) { - x = (x >> 1) ^ (-(int)(x & 1) & 0xd0000001); - y = y * 1103515245 + 12345; - r = x ^ y; - *(pBuf++) = r & 0xff; - } -} - -/* - * Allocate nByte bytes of memory. - */ -static void * -sqlite3MemMalloc(int nByte) -{ - struct MemBlockHdr *pHdr; - void **pBt; - char *z; - int *pInt; - void *p = 0; - int totalSize; - int nReserve; - sqlite3_mutex_enter(mem.mutex); - assert(mem.disallow == 0); - nReserve = ROUND8(nByte); - totalSize = nReserve + sizeof(*pHdr) + sizeof(int) + - mem.nBacktrace * sizeof(void *) + mem.nTitle; - p = malloc(totalSize); - if (p) { - z = p; - pBt = (void **)&z[mem.nTitle]; - pHdr = (struct MemBlockHdr *)&pBt[mem.nBacktrace]; - pHdr->pNext = 0; - pHdr->pPrev = mem.pLast; - if (mem.pLast) { - mem.pLast->pNext = pHdr; - } else { - mem.pFirst = pHdr; - } - mem.pLast = pHdr; - pHdr->iForeGuard = FOREGUARD; - pHdr->eType = MEMTYPE_HEAP; - pHdr->nBacktraceSlots = mem.nBacktrace; - pHdr->nTitle = mem.nTitle; - if (mem.nBacktrace) { - void *aAddr[40]; - pHdr->nBacktrace = - backtrace(aAddr, mem.nBacktrace + 1) - 1; - memcpy(pBt, &aAddr[1], - pHdr->nBacktrace * sizeof(void *)); - assert(pBt[0]); - if (mem.xBacktrace) { - mem.xBacktrace(nByte, pHdr->nBacktrace - 1, - &aAddr[1]); - } - } else { - pHdr->nBacktrace = 0; - } - if (mem.nTitle) { - memcpy(z, mem.zTitle, mem.nTitle); - } - pHdr->iSize = nByte; - adjustStats(nByte, +1); - pInt = (int *)&pHdr[1]; - pInt[nReserve / sizeof(int)] = REARGUARD; - randomFill((char *)pInt, nByte); - memset(((char *)pInt) + nByte, 0x65, nReserve - nByte); - p = (void *)pInt; - } - sqlite3_mutex_leave(mem.mutex); - return p; -} - -/* - * Free memory. - */ -static void -sqlite3MemFree(void *pPrior) -{ - struct MemBlockHdr *pHdr; - void **pBt; - char *z; - assert(sqlite3GlobalConfig.bMemstat - || sqlite3GlobalConfig.bCoreMutex == 0 || mem.mutex != 0); - pHdr = sqlite3MemsysGetHeader(pPrior); - pBt = (void **)pHdr; - pBt -= pHdr->nBacktraceSlots; - sqlite3_mutex_enter(mem.mutex); - if (pHdr->pPrev) { - assert(pHdr->pPrev->pNext == pHdr); - pHdr->pPrev->pNext = pHdr->pNext; - } else { - assert(mem.pFirst == pHdr); - mem.pFirst = pHdr->pNext; - } - if (pHdr->pNext) { - assert(pHdr->pNext->pPrev == pHdr); - pHdr->pNext->pPrev = pHdr->pPrev; - } else { - assert(mem.pLast == pHdr); - mem.pLast = pHdr->pPrev; - } - z = (char *)pBt; - z -= pHdr->nTitle; - adjustStats((int)pHdr->iSize, -1); - randomFill(z, sizeof(void *) * pHdr->nBacktraceSlots + sizeof(*pHdr) + - (int)pHdr->iSize + sizeof(int) + pHdr->nTitle); - free(z); - sqlite3_mutex_leave(mem.mutex); -} - -/* - * Change the size of an existing memory allocation. - * - * For this debugging implementation, we *always* make a copy of the - * allocation into a new place in memory. In this way, if the - * higher level code is using pointer to the old allocation, it is - * much more likely to break and we are much more liking to find - * the error. - */ -static void * -sqlite3MemRealloc(void *pPrior, int nByte) -{ - struct MemBlockHdr *pOldHdr; - void *pNew; - assert(mem.disallow == 0); - assert((nByte & 7) == 0); /* EV: R-46199-30249 */ - pOldHdr = sqlite3MemsysGetHeader(pPrior); - pNew = sqlite3MemMalloc(nByte); - if (pNew) { - memcpy(pNew, pPrior, - (int)(nByte < pOldHdr->iSize ? nByte : pOldHdr->iSize)); - if (nByte > pOldHdr->iSize) { - randomFill(&((char *)pNew)[pOldHdr->iSize], - nByte - (int)pOldHdr->iSize); - } - sqlite3MemFree(pPrior); - } - return pNew; -} - -/* - * Populate the low-level memory allocation function pointers in - * sqlite3GlobalConfig.m with pointers to the routines in this file. - */ -void -sqlite3MemSetDefault(void) -{ - static const sqlite3_mem_methods defaultMethods = { - sqlite3MemMalloc, - sqlite3MemFree, - sqlite3MemRealloc, - sqlite3MemSize, - sqlite3MemRoundup, - sqlite3MemInit, - sqlite3MemShutdown, - 0 - }; - sqlite3_config(SQLITE_CONFIG_MALLOC, &defaultMethods); -} - -/* - * Set the "type" of an allocation. - */ -void -sqlite3MemdebugSetType(void *p, u8 eType) -{ - if (p && sqlite3GlobalConfig.m.xMalloc == sqlite3MemMalloc) { - struct MemBlockHdr *pHdr; - pHdr = sqlite3MemsysGetHeader(p); - assert(pHdr->iForeGuard == FOREGUARD); - pHdr->eType = eType; - } -} - -/* - * Return TRUE if the mask of type in eType matches the type of the - * allocation p. Also return true if p==NULL. - * - * This routine is designed for use within an assert() statement, to - * verify the type of an allocation. For example: - * - * assert( sqlite3MemdebugHasType(p, MEMTYPE_HEAP) ); - */ -int -sqlite3MemdebugHasType(void *p, u8 eType) -{ - int rc = 1; - if (p && sqlite3GlobalConfig.m.xMalloc == sqlite3MemMalloc) { - struct MemBlockHdr *pHdr; - pHdr = sqlite3MemsysGetHeader(p); - assert(pHdr->iForeGuard == FOREGUARD); /* Allocation is valid */ - if ((pHdr->eType & eType) == 0) { - rc = 0; - } - } - return rc; -} - -/* - * Return TRUE if the mask of type in eType matches no bits of the type of the - * allocation p. Also return true if p==NULL. - * - * This routine is designed for use within an assert() statement, to - * verify the type of an allocation. For example: - * - * assert( sqlite3MemdebugNoType(p, MEMTYPE_LOOKASIDE) ); - */ -int -sqlite3MemdebugNoType(void *p, u8 eType) -{ - int rc = 1; - if (p && sqlite3GlobalConfig.m.xMalloc == sqlite3MemMalloc) { - struct MemBlockHdr *pHdr; - pHdr = sqlite3MemsysGetHeader(p); - assert(pHdr->iForeGuard == FOREGUARD); /* Allocation is valid */ - if ((pHdr->eType & eType) != 0) { - rc = 0; - } - } - return rc; -} - -/* - * Set the number of backtrace levels kept for each allocation. - * A value of zero turns off backtracing. The number is always rounded - * up to a multiple of 2. - */ -void -sqlite3MemdebugBacktrace(int depth) -{ - if (depth < 0) { - depth = 0; - } - if (depth > 20) { - depth = 20; - } - depth = (depth + 1) & 0xfe; - mem.nBacktrace = depth; -} - -void -sqlite3MemdebugBacktraceCallback(void (*xBacktrace) (int, int, void **)) -{ - mem.xBacktrace = xBacktrace; -} - -/* - * Set the title string for subsequent allocations. - */ -void -sqlite3MemdebugSettitle(const char *zTitle) -{ - unsigned int n = sqlite3Strlen30(zTitle) + 1; - sqlite3_mutex_enter(mem.mutex); - if (n >= sizeof(mem.zTitle)) - n = sizeof(mem.zTitle) - 1; - memcpy(mem.zTitle, zTitle, n); - mem.zTitle[n] = 0; - mem.nTitle = ROUND8(n); - sqlite3_mutex_leave(mem.mutex); -} - -void -sqlite3MemdebugSync() -{ - struct MemBlockHdr *pHdr; - for (pHdr = mem.pFirst; pHdr; pHdr = pHdr->pNext) { - void **pBt = (void **)pHdr; - pBt -= pHdr->nBacktraceSlots; - mem.xBacktrace((int)pHdr->iSize, pHdr->nBacktrace - 1, &pBt[1]); - } -} - -/* - * Open the file indicated and write a log of all unfreed memory - * allocations into that log. - */ -void -sqlite3MemdebugDump(const char *zFilename) -{ - FILE *out; - struct MemBlockHdr *pHdr; - void **pBt; - int i; - out = fopen(zFilename, "w"); - if (out == 0) { - fprintf(stderr, - "** Unable to output memory debug output log: %s **\n", - zFilename); - return; - } - for (pHdr = mem.pFirst; pHdr; pHdr = pHdr->pNext) { - char *z = (char *)pHdr; - z -= pHdr->nBacktraceSlots * sizeof(void *) + pHdr->nTitle; - fprintf(out, "**** %lld bytes at %p from %s ****\n", - pHdr->iSize, &pHdr[1], pHdr->nTitle ? z : "???"); - if (pHdr->nBacktrace) { - fflush(out); - pBt = (void **)pHdr; - pBt -= pHdr->nBacktraceSlots; - backtrace_symbols_fd(pBt, pHdr->nBacktrace, - fileno(out)); - fprintf(out, "\n"); - } - } - fprintf(out, "COUNTS:\n"); - for (i = 0; i < NCSIZE - 1; i++) { - if (mem.nAlloc[i]) { - fprintf(out, " %5d: %10d %10d %10d\n", - i * 8, mem.nAlloc[i], mem.nCurrent[i], - mem.mxCurrent[i]); - } - } - if (mem.nAlloc[NCSIZE - 1]) { - fprintf(out, " %5d: %10d %10d %10d\n", - NCSIZE * 8 - 8, mem.nAlloc[NCSIZE - 1], - mem.nCurrent[NCSIZE - 1], mem.mxCurrent[NCSIZE - 1]); - } - fclose(out); -} - -/* - * Return the number of times sqlite3MemMalloc() has been called. - */ -int -sqlite3MemdebugMallocCount() -{ - int i; - int nTotal = 0; - for (i = 0; i < NCSIZE; i++) { - nTotal += mem.nAlloc[i]; - } - return nTotal; -} - -#endif /* SQLITE_MEMDEBUG */ diff --git a/src/box/sql/mem3.c b/src/box/sql/mem3.c deleted file mode 100644 index b9f0b8c..0000000 --- a/src/box/sql/mem3.c +++ /dev/null @@ -1,767 +0,0 @@ -/* - * Copyright 2010-2017, Tarantool AUTHORS, please see AUTHORS file. - * - * Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the - * following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED - * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL - * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, - * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - */ - -/* - * This file contains the C functions that implement a memory - * allocation subsystem for use by SQLite. - * - * This version of the memory allocation subsystem omits all - * use of malloc(). The SQLite user supplies a block of memory - * before calling sqlite3_initialize() from which allocations - * are made and returned by the xMalloc() and xRealloc() - * implementations. Once sqlite3_initialize() has been called, - * the amount of memory available to SQLite is fixed and cannot - * be changed. - * - * This version of the memory allocation subsystem is included - * in the build only if SQLITE_ENABLE_MEMSYS3 is defined. - */ -#include "sqliteInt.h" - -/* - * This version of the memory allocator is only built into the library - * SQLITE_ENABLE_MEMSYS3 is defined. Defining this symbol does not - * mean that the library will use a memory-pool by default, just that - * it is available. The mempool allocator is activated by calling - * sqlite3_config(). - */ -#ifdef SQLITE_ENABLE_MEMSYS3 - -/* - * Maximum size (in Mem3Blocks) of a "small" chunk. - */ -#define MX_SMALL 10 - -/* - * Number of freelist hash slots - */ -#define N_HASH 61 - -/* - * A memory allocation (also called a "chunk") consists of two or - * more blocks where each block is 8 bytes. The first 8 bytes are - * a header that is not returned to the user. - * - * A chunk is two or more blocks that is either checked out or - * free. The first block has format u.hdr. u.hdr.size4x is 4 times the - * size of the allocation in blocks if the allocation is free. - * The u.hdr.size4x&1 bit is true if the chunk is checked out and - * false if the chunk is on the freelist. The u.hdr.size4x&2 bit - * is true if the previous chunk is checked out and false if the - * previous chunk is free. The u.hdr.prevSize field is the size of - * the previous chunk in blocks if the previous chunk is on the - * freelist. If the previous chunk is checked out, then - * u.hdr.prevSize can be part of the data for that chunk and should - * not be read or written. - * - * We often identify a chunk by its index in mem3.aPool[]. When - * this is done, the chunk index refers to the second block of - * the chunk. In this way, the first chunk has an index of 1. - * A chunk index of 0 means "no such chunk" and is the equivalent - * of a NULL pointer. - * - * The second block of free chunks is of the form u.list. The - * two fields form a double-linked list of chunks of related sizes. - * Pointers to the head of the list are stored in mem3.aiSmall[] - * for smaller chunks and mem3.aiHash[] for larger chunks. - * - * The second block of a chunk is user data if the chunk is checked - * out. If a chunk is checked out, the user data may extend into - * the u.hdr.prevSize value of the following chunk. - */ -typedef struct Mem3Block Mem3Block; -struct Mem3Block { - union { - struct { - u32 prevSize; /* Size of previous chunk in Mem3Block elements */ - u32 size4x; /* 4x the size of current chunk in Mem3Block elements */ - } hdr; - struct { - u32 next; /* Index in mem3.aPool[] of next free chunk */ - u32 prev; /* Index in mem3.aPool[] of previous free chunk */ - } list; - } u; -}; - -/* - * All of the static variables used by this module are collected - * into a single structure named "mem3". This is to keep the - * static variables organized and to reduce namespace pollution - * when this module is combined with other in the amalgamation. - */ -static SQLITE_WSD struct Mem3Global { - /* - * Memory available for allocation. nPool is the size of the array - * (in Mem3Blocks) pointed to by aPool less 2. - */ - u32 nPool; - Mem3Block *aPool; - - /* - * True if we are evaluating an out-of-memory callback. - */ - int alarmBusy; - - /* - * Mutex to control access to the memory allocation subsystem. - */ - sqlite3_mutex *mutex; - - /* - * The minimum amount of free space that we have seen. - */ - u32 mnMaster; - - /* - * iMaster is the index of the master chunk. Most new allocations - * occur off of this chunk. szMaster is the size (in Mem3Blocks) - * of the current master. iMaster is 0 if there is not master chunk. - * The master chunk is not in either the aiHash[] or aiSmall[]. - */ - u32 iMaster; - u32 szMaster; - - /* - * Array of lists of free blocks according to the block size - * for smaller chunks, or a hash on the block size for larger - * chunks. - */ - u32 aiSmall[MX_SMALL - 1]; /* For sizes 2 through MX_SMALL, inclusive */ - u32 aiHash[N_HASH]; /* For sizes MX_SMALL+1 and larger */ -} mem3 = { -97535575}; - -#define mem3 GLOBAL(struct Mem3Global, mem3) - -/* - * Unlink the chunk at mem3.aPool[i] from list it is currently - * on. *pRoot is the list that i is a member of. - */ -static void -memsys3UnlinkFromList(u32 i, u32 * pRoot) -{ - u32 next = mem3.aPool[i].u.list.next; - u32 prev = mem3.aPool[i].u.list.prev; - assert(sqlite3_mutex_held(mem3.mutex)); - if (prev == 0) { - *pRoot = next; - } else { - mem3.aPool[prev].u.list.next = next; - } - if (next) { - mem3.aPool[next].u.list.prev = prev; - } - mem3.aPool[i].u.list.next = 0; - mem3.aPool[i].u.list.prev = 0; -} - -/* - * Unlink the chunk at index i from - * whatever list is currently a member of. - */ -static void -memsys3Unlink(u32 i) -{ - u32 size, hash; - assert(sqlite3_mutex_held(mem3.mutex)); - assert((mem3.aPool[i - 1].u.hdr.size4x & 1) == 0); - assert(i >= 1); - size = mem3.aPool[i - 1].u.hdr.size4x / 4; - assert(size == mem3.aPool[i + size - 1].u.hdr.prevSize); - assert(size >= 2); - if (size <= MX_SMALL) { - memsys3UnlinkFromList(i, &mem3.aiSmall[size - 2]); - } else { - hash = size % N_HASH; - memsys3UnlinkFromList(i, &mem3.aiHash[hash]); - } -} - -/* - * Link the chunk at mem3.aPool[i] so that is on the list rooted - * at *pRoot. - */ -static void -memsys3LinkIntoList(u32 i, u32 * pRoot) -{ - assert(sqlite3_mutex_held(mem3.mutex)); - mem3.aPool[i].u.list.next = *pRoot; - mem3.aPool[i].u.list.prev = 0; - if (*pRoot) { - mem3.aPool[*pRoot].u.list.prev = i; - } - *pRoot = i; -} - -/* - * Link the chunk at index i into either the appropriate - * small chunk list, or into the large chunk hash table. - */ -static void -memsys3Link(u32 i) -{ - u32 size, hash; - assert(sqlite3_mutex_held(mem3.mutex)); - assert(i >= 1); - assert((mem3.aPool[i - 1].u.hdr.size4x & 1) == 0); - size = mem3.aPool[i - 1].u.hdr.size4x / 4; - assert(size == mem3.aPool[i + size - 1].u.hdr.prevSize); - assert(size >= 2); - if (size <= MX_SMALL) { - memsys3LinkIntoList(i, &mem3.aiSmall[size - 2]); - } else { - hash = size % N_HASH; - memsys3LinkIntoList(i, &mem3.aiHash[hash]); - } -} - -/* - * If the STATIC_MEM mutex is not already held, obtain it now. The mutex - * will already be held (obtained by code in malloc.c) if - * sqlite3GlobalConfig.bMemStat is true. - */ -static void -memsys3Enter(void) -{ - if (sqlite3GlobalConfig.bMemstat == 0 && mem3.mutex == 0) { - mem3.mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM); - } - sqlite3_mutex_enter(mem3.mutex); -} - -static void -memsys3Leave(void) -{ - sqlite3_mutex_leave(mem3.mutex); -} - -/* - * Called when we are unable to satisfy an allocation of nBytes. - */ -static void -memsys3OutOfMemory(int nByte) -{ - if (!mem3.alarmBusy) { - mem3.alarmBusy = 1; - assert(sqlite3_mutex_held(mem3.mutex)); - sqlite3_mutex_leave(mem3.mutex); - sqlite3_release_memory(nByte); - sqlite3_mutex_enter(mem3.mutex); - mem3.alarmBusy = 0; - } -} - -/* - * Chunk i is a free chunk that has been unlinked. Adjust its - * size parameters for check-out and return a pointer to the - * user portion of the chunk. - */ -static void * -memsys3Checkout(u32 i, u32 nBlock) -{ - u32 x; - assert(sqlite3_mutex_held(mem3.mutex)); - assert(i >= 1); - assert(mem3.aPool[i - 1].u.hdr.size4x / 4 == nBlock); - assert(mem3.aPool[i + nBlock - 1].u.hdr.prevSize == nBlock); - x = mem3.aPool[i - 1].u.hdr.size4x; - mem3.aPool[i - 1].u.hdr.size4x = nBlock * 4 | 1 | (x & 2); - mem3.aPool[i + nBlock - 1].u.hdr.prevSize = nBlock; - mem3.aPool[i + nBlock - 1].u.hdr.size4x |= 2; - return &mem3.aPool[i]; -} - -/* - * Carve a piece off of the end of the mem3.iMaster free chunk. - * Return a pointer to the new allocation. Or, if the master chunk - * is not large enough, return 0. - */ -static void * -memsys3FromMaster(u32 nBlock) -{ - assert(sqlite3_mutex_held(mem3.mutex)); - assert(mem3.szMaster >= nBlock); - if (nBlock >= mem3.szMaster - 1) { - /* Use the entire master */ - void *p = memsys3Checkout(mem3.iMaster, mem3.szMaster); - mem3.iMaster = 0; - mem3.szMaster = 0; - mem3.mnMaster = 0; - return p; - } else { - /* Split the master block. Return the tail. */ - u32 newi, x; - newi = mem3.iMaster + mem3.szMaster - nBlock; - assert(newi > mem3.iMaster + 1); - mem3.aPool[mem3.iMaster + mem3.szMaster - 1].u.hdr.prevSize = - nBlock; - mem3.aPool[mem3.iMaster + mem3.szMaster - 1].u.hdr.size4x |= 2; - mem3.aPool[newi - 1].u.hdr.size4x = nBlock * 4 + 1; - mem3.szMaster -= nBlock; - mem3.aPool[newi - 1].u.hdr.prevSize = mem3.szMaster; - x = mem3.aPool[mem3.iMaster - 1].u.hdr.size4x & 2; - mem3.aPool[mem3.iMaster - 1].u.hdr.size4x = - mem3.szMaster * 4 | x; - if (mem3.szMaster < mem3.mnMaster) { - mem3.mnMaster = mem3.szMaster; - } - return (void *)&mem3.aPool[newi]; - } -} - -/* - * *pRoot is the head of a list of free chunks of the same size - * or same size hash. In other words, *pRoot is an entry in either - * mem3.aiSmall[] or mem3.aiHash[]. - * - * This routine examines all entries on the given list and tries - * to coalesce each entries with adjacent free chunks. - * - * If it sees a chunk that is larger than mem3.iMaster, it replaces - * the current mem3.iMaster with the new larger chunk. In order for - * this mem3.iMaster replacement to work, the master chunk must be - * linked into the hash tables. That is not the normal state of - * affairs, of course. The calling routine must link the master - * chunk before invoking this routine, then must unlink the (possibly - * changed) master chunk once this routine has finished. - */ -static void -memsys3Merge(u32 * pRoot) -{ - u32 iNext, prev, size, i, x; - - assert(sqlite3_mutex_held(mem3.mutex)); - for (i = *pRoot; i > 0; i = iNext) { - iNext = mem3.aPool[i].u.list.next; - size = mem3.aPool[i - 1].u.hdr.size4x; - assert((size & 1) == 0); - if ((size & 2) == 0) { - memsys3UnlinkFromList(i, pRoot); - assert(i > mem3.aPool[i - 1].u.hdr.prevSize); - prev = i - mem3.aPool[i - 1].u.hdr.prevSize; - if (prev == iNext) { - iNext = mem3.aPool[prev].u.list.next; - } - memsys3Unlink(prev); - size = i + size / 4 - prev; - x = mem3.aPool[prev - 1].u.hdr.size4x & 2; - mem3.aPool[prev - 1].u.hdr.size4x = size * 4 | x; - mem3.aPool[prev + size - 1].u.hdr.prevSize = size; - memsys3Link(prev); - i = prev; - } else { - size /= 4; - } - if (size > mem3.szMaster) { - mem3.iMaster = i; - mem3.szMaster = size; - } - } -} - -/* - * Return a block of memory of at least nBytes in size. - * Return NULL if unable. - * - * This function assumes that the necessary mutexes, if any, are - * already held by the caller. Hence "Unsafe". - */ -static void * -memsys3MallocUnsafe(int nByte) -{ - u32 i; - u32 nBlock; - u32 toFree; - - assert(sqlite3_mutex_held(mem3.mutex)); - assert(sizeof(Mem3Block) == 8); - if (nByte <= 12) { - nBlock = 2; - } else { - nBlock = (nByte + 11) / 8; - } - assert(nBlock >= 2); - - /* STEP 1: - * Look for an entry of the correct size in either the small - * chunk table or in the large chunk hash table. This is - * successful most of the time (about 9 times out of 10). - */ - if (nBlock <= MX_SMALL) { - i = mem3.aiSmall[nBlock - 2]; - if (i > 0) { - memsys3UnlinkFromList(i, &mem3.aiSmall[nBlock - 2]); - return memsys3Checkout(i, nBlock); - } - } else { - int hash = nBlock % N_HASH; - for (i = mem3.aiHash[hash]; i > 0; - i = mem3.aPool[i].u.list.next) { - if (mem3.aPool[i - 1].u.hdr.size4x / 4 == nBlock) { - memsys3UnlinkFromList(i, &mem3.aiHash[hash]); - return memsys3Checkout(i, nBlock); - } - } - } - - /* STEP 2: - * Try to satisfy the allocation by carving a piece off of the end - * of the master chunk. This step usually works if step 1 fails. - */ - if (mem3.szMaster >= nBlock) { - return memsys3FromMaster(nBlock); - } - - /* STEP 3: - * Loop through the entire memory pool. Coalesce adjacent free - * chunks. Recompute the master chunk as the largest free chunk. - * Then try again to satisfy the allocation by carving a piece off - * of the end of the master chunk. This step happens very - * rarely (we hope!) - */ - for (toFree = nBlock * 16; toFree < (mem3.nPool * 16); toFree *= 2) { - memsys3OutOfMemory(toFree); - if (mem3.iMaster) { - memsys3Link(mem3.iMaster); - mem3.iMaster = 0; - mem3.szMaster = 0; - } - for (i = 0; i < N_HASH; i++) { - memsys3Merge(&mem3.aiHash[i]); - } - for (i = 0; i < MX_SMALL - 1; i++) { - memsys3Merge(&mem3.aiSmall[i]); - } - if (mem3.szMaster) { - memsys3Unlink(mem3.iMaster); - if (mem3.szMaster >= nBlock) { - return memsys3FromMaster(nBlock); - } - } - } - - /* If none of the above worked, then we fail. */ - return 0; -} - -/* - * Free an outstanding memory allocation. - * - * This function assumes that the necessary mutexes, if any, are - * already held by the caller. Hence "Unsafe". - */ -static void -memsys3FreeUnsafe(void *pOld) -{ - Mem3Block *p = (Mem3Block *) pOld; - int i; - u32 size, x; - assert(sqlite3_mutex_held(mem3.mutex)); - assert(p > mem3.aPool && p < &mem3.aPool[mem3.nPool]); - i = p - mem3.aPool; - assert((mem3.aPool[i - 1].u.hdr.size4x & 1) == 1); - size = mem3.aPool[i - 1].u.hdr.size4x / 4; - assert(i + size <= mem3.nPool + 1); - mem3.aPool[i - 1].u.hdr.size4x &= ~1; - mem3.aPool[i + size - 1].u.hdr.prevSize = size; - mem3.aPool[i + size - 1].u.hdr.size4x &= ~2; - memsys3Link(i); - - /* Try to expand the master using the newly freed chunk */ - if (mem3.iMaster) { - while ((mem3.aPool[mem3.iMaster - 1].u.hdr.size4x & 2) == 0) { - size = mem3.aPool[mem3.iMaster - 1].u.hdr.prevSize; - mem3.iMaster -= size; - mem3.szMaster += size; - memsys3Unlink(mem3.iMaster); - x = mem3.aPool[mem3.iMaster - 1].u.hdr.size4x & 2; - mem3.aPool[mem3.iMaster - 1].u.hdr.size4x = - mem3.szMaster * 4 | x; - mem3.aPool[mem3.iMaster + mem3.szMaster - - 1].u.hdr.prevSize = mem3.szMaster; - } - x = mem3.aPool[mem3.iMaster - 1].u.hdr.size4x & 2; - while ((mem3.aPool[mem3.iMaster + mem3.szMaster - 1].u.hdr. - size4x & 1) == 0) { - memsys3Unlink(mem3.iMaster + mem3.szMaster); - mem3.szMaster += - mem3.aPool[mem3.iMaster + mem3.szMaster - - 1].u.hdr.size4x / 4; - mem3.aPool[mem3.iMaster - 1].u.hdr.size4x = - mem3.szMaster * 4 | x; - mem3.aPool[mem3.iMaster + mem3.szMaster - - 1].u.hdr.prevSize = mem3.szMaster; - } - } -} - -/* - * Return the size of an outstanding allocation, in bytes. The - * size returned omits the 8-byte header overhead. This only - * works for chunks that are currently checked out. - */ -static int -memsys3Size(void *p) -{ - Mem3Block *pBlock; - assert(p != 0); - pBlock = (Mem3Block *) p; - assert((pBlock[-1].u.hdr.size4x & 1) != 0); - return (pBlock[-1].u.hdr.size4x & ~3) * 2 - 4; -} - -/* - * Round up a request size to the next valid allocation size. - */ -static int -memsys3Roundup(int n) -{ - if (n <= 12) { - return 12; - } else { - return ((n + 11) & ~7) - 4; - } -} - -/* - * Allocate nBytes of memory. - */ -static void * -memsys3Malloc(int nBytes) -{ - sqlite3_int64 *p; - assert(nBytes > 0); /* malloc.c filters out 0 byte requests */ - memsys3Enter(); - p = memsys3MallocUnsafe(nBytes); - memsys3Leave(); - return (void *)p; -} - -/* - * Free memory. - */ -static void -memsys3Free(void *pPrior) -{ - assert(pPrior); - memsys3Enter(); - memsys3FreeUnsafe(pPrior); - memsys3Leave(); -} - -/* - * Change the size of an existing memory allocation - */ -static void * -memsys3Realloc(void *pPrior, int nBytes) -{ - int nOld; - void *p; - if (pPrior == 0) { - return sqlite3_malloc(nBytes); - } - if (nBytes <= 0) { - sqlite3_free(pPrior); - return 0; - } - nOld = memsys3Size(pPrior); - if (nBytes <= nOld && nBytes >= nOld - 128) { - return pPrior; - } - memsys3Enter(); - p = memsys3MallocUnsafe(nBytes); - if (p) { - if (nOld < nBytes) { - memcpy(p, pPrior, nOld); - } else { - memcpy(p, pPrior, nBytes); - } - memsys3FreeUnsafe(pPrior); - } - memsys3Leave(); - return p; -} - -/* - * Initialize this module. - */ -static int -memsys3Init(void *NotUsed) -{ - UNUSED_PARAMETER(NotUsed); - if (!sqlite3GlobalConfig.pHeap) { - return SQLITE_ERROR; - } - - /* Store a pointer to the memory block in global structure mem3. */ - assert(sizeof(Mem3Block) == 8); - mem3.aPool = (Mem3Block *) sqlite3GlobalConfig.pHeap; - mem3.nPool = (sqlite3GlobalConfig.nHeap / sizeof(Mem3Block)) - 2; - - /* Initialize the master block. */ - mem3.szMaster = mem3.nPool; - mem3.mnMaster = mem3.szMaster; - mem3.iMaster = 1; - mem3.aPool[0].u.hdr.size4x = (mem3.szMaster << 2) + 2; - mem3.aPool[mem3.nPool].u.hdr.prevSize = mem3.nPool; - mem3.aPool[mem3.nPool].u.hdr.size4x = 1; - - return SQLITE_OK; -} - -/* - * Deinitialize this module. - */ -static void -memsys3Shutdown(void *NotUsed) -{ - UNUSED_PARAMETER(NotUsed); - mem3.mutex = 0; - return; -} - -/* - * Open the file indicated and write a log of all unfreed memory - * allocations into that log. - */ -void -sqlite3Memsys3Dump(const char *zFilename) -{ -#ifdef SQLITE_DEBUG - FILE *out; - u32 i, j; - u32 size; - if (zFilename == 0 || zFilename[0] == 0) { - out = stdout; - } else { - out = fopen(zFilename, "w"); - if (out == 0) { - fprintf(stderr, - "** Unable to output memory debug output log: %s **\n", - zFilename); - return; - } - } - memsys3Enter(); - fprintf(out, "CHUNKS:\n"); - for (i = 1; i <= mem3.nPool; i += size / 4) { - size = mem3.aPool[i - 1].u.hdr.size4x; - if (size / 4 <= 1) { - fprintf(out, "%p size error\n", &mem3.aPool[i]); - assert(0); - break; - } - if ((size & 1) == 0 - && mem3.aPool[i + size / 4 - 1].u.hdr.prevSize != - size / 4) { - fprintf(out, "%p tail size does not match\n", - &mem3.aPool[i]); - assert(0); - break; - } - if (((mem3.aPool[i + size / 4 - 1].u.hdr.size4x & 2) >> 1) != - (size & 1)) { - fprintf(out, "%p tail checkout bit is incorrect\n", - &mem3.aPool[i]); - assert(0); - break; - } - if (size & 1) { - fprintf(out, "%p %6d bytes checked out\n", - &mem3.aPool[i], (size / 4) * 8 - 8); - } else { - fprintf(out, "%p %6d bytes free%s\n", &mem3.aPool[i], - (size / 4) * 8 - 8, - i == mem3.iMaster ? " **master**" : ""); - } - } - for (i = 0; i < MX_SMALL - 1; i++) { - if (mem3.aiSmall[i] == 0) - continue; - fprintf(out, "small(%2d):", i); - for (j = mem3.aiSmall[i]; j > 0; j = mem3.aPool[j].u.list.next) { - fprintf(out, " %p(%d)", &mem3.aPool[j], - (mem3.aPool[j - 1].u.hdr.size4x / 4) * 8 - 8); - } - fprintf(out, "\n"); - } - for (i = 0; i < N_HASH; i++) { - if (mem3.aiHash[i] == 0) - continue; - fprintf(out, "hash(%2d):", i); - for (j = mem3.aiHash[i]; j > 0; j = mem3.aPool[j].u.list.next) { - fprintf(out, " %p(%d)", &mem3.aPool[j], - (mem3.aPool[j - 1].u.hdr.size4x / 4) * 8 - 8); - } - fprintf(out, "\n"); - } - fprintf(out, "master=%d\n", mem3.iMaster); - fprintf(out, "nowUsed=%d\n", mem3.nPool * 8 - mem3.szMaster * 8); - fprintf(out, "mxUsed=%d\n", mem3.nPool * 8 - mem3.mnMaster * 8); - sqlite3_mutex_leave(mem3.mutex); - if (out == stdout) { - fflush(stdout); - } else { - fclose(out); - } -#else - UNUSED_PARAMETER(zFilename); -#endif -} - -/* - * This routine is the only routine in this file with external - * linkage. - * - * Populate the low-level memory allocation function pointers in - * sqlite3GlobalConfig.m with pointers to the routines in this file. The - * arguments specify the block of memory to manage. - * - * This routine is only called by sqlite3_config(), and therefore - * is not required to be threadsafe (it is not). - */ -const sqlite3_mem_methods * -sqlite3MemGetMemsys3(void) -{ - static const sqlite3_mem_methods mempoolMethods = { - memsys3Malloc, - memsys3Free, - memsys3Realloc, - memsys3Size, - memsys3Roundup, - memsys3Init, - memsys3Shutdown, - 0 - }; - return &mempoolMethods; -} - -#endif /* SQLITE_ENABLE_MEMSYS3 */ diff --git a/src/box/sql/mem5.c b/src/box/sql/mem5.c deleted file mode 100644 index 73adde0..0000000 --- a/src/box/sql/mem5.c +++ /dev/null @@ -1,648 +0,0 @@ -/* - * Copyright 2010-2017, Tarantool AUTHORS, please see AUTHORS file. - * - * Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the - * following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED - * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL - * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, - * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - */ - -/* - * This file contains the C functions that implement a memory - * allocation subsystem for use by SQLite. - * - * This version of the memory allocation subsystem omits all - * use of malloc(). The application gives SQLite a block of memory - * before calling sqlite3_initialize() from which allocations - * are made and returned by the xMalloc() and xRealloc() - * implementations. Once sqlite3_initialize() has been called, - * the amount of memory available to SQLite is fixed and cannot - * be changed. - * - * This version of the memory allocation subsystem is included - * in the build only if SQLITE_ENABLE_MEMSYS5 is defined. - * - * This memory allocator uses the following algorithm: - * - * 1. All memory allocation sizes are rounded up to a power of 2. - * - * 2. If two adjacent free blocks are the halves of a larger block, - * then the two blocks are coalesced into the single larger block. - * - * 3. New memory is allocated from the first available free block. - * - * This algorithm is described in: J. M. Robson. "Bounds for Some Functions - * Concerning Dynamic Storage Allocation". Journal of the Association for - * Computing Machinery, Volume 21, Number 8, July 1974, pages 491-499. - * - * Let n be the size of the largest allocation divided by the minimum - * allocation size (after rounding all sizes up to a power of 2.) Let M - * be the maximum amount of memory ever outstanding at one time. Let - * N be the total amount of memory available for allocation. Robson - * proved that this memory allocator will never breakdown due to - * fragmentation as long as the following constraint holds: - * - * N >= M*(1 + log2(n)/2) - n + 1 - * - * The sqlite3_status() logic tracks the maximum values of n and M so - * that an application can, at any time, verify this constraint. - */ -#include "sqliteInt.h" - -/* - * This version of the memory allocator is used only when - * SQLITE_ENABLE_MEMSYS5 is defined. - */ -#ifdef SQLITE_ENABLE_MEMSYS5 - -/* - * A minimum allocation is an instance of the following structure. - * Larger allocations are an array of these structures where the - * size of the array is a power of 2. - * - * The size of this object must be a power of two. That fact is - * verified in memsys5Init(). - */ -typedef struct Mem5Link Mem5Link; -struct Mem5Link { - int next; /* Index of next free chunk */ - int prev; /* Index of previous free chunk */ -}; - -/* - * Maximum size of any allocation is ((1<= 0 && i < mem5.nBlock); - assert(iLogsize >= 0 && iLogsize <= LOGMAX); - assert((mem5.aCtrl[i] & CTRL_LOGSIZE) == iLogsize); - - next = MEM5LINK(i)->next; - prev = MEM5LINK(i)->prev; - if (prev < 0) { - mem5.aiFreelist[iLogsize] = next; - } else { - MEM5LINK(prev)->next = next; - } - if (next >= 0) { - MEM5LINK(next)->prev = prev; - } -} - -/* - * Link the chunk at mem5.aPool[i] so that is on the iLogsize - * free list. - */ -static void -memsys5Link(int i, int iLogsize) -{ - int x; - assert(sqlite3_mutex_held(mem5.mutex)); - assert(i >= 0 && i < mem5.nBlock); - assert(iLogsize >= 0 && iLogsize <= LOGMAX); - assert((mem5.aCtrl[i] & CTRL_LOGSIZE) == iLogsize); - - x = MEM5LINK(i)->next = mem5.aiFreelist[iLogsize]; - MEM5LINK(i)->prev = -1; - if (x >= 0) { - assert(x < mem5.nBlock); - MEM5LINK(x)->prev = i; - } - mem5.aiFreelist[iLogsize] = i; -} - -/* - * Obtain or release the mutex needed to access global data structures. - */ -static void -memsys5Enter(void) -{ - sqlite3_mutex_enter(mem5.mutex); -} - -static void -memsys5Leave(void) -{ - sqlite3_mutex_leave(mem5.mutex); -} - -/* - * Return the size of an outstanding allocation, in bytes. - * This only works for chunks that are currently checked out. - */ -static int -memsys5Size(void *p) -{ - int iSize, i; - assert(p != 0); - i = (int)(((u8 *) p - mem5.zPool) / mem5.szAtom); - assert(i >= 0 && i < mem5.nBlock); - iSize = mem5.szAtom * (1 << (mem5.aCtrl[i] & CTRL_LOGSIZE)); - return iSize; -} - -/* - * Return a block of memory of at least nBytes in size. - * Return NULL if unable. Return NULL if nBytes==0. - * - * The caller guarantees that nByte is positive. - * - * The caller has obtained a mutex prior to invoking this - * routine so there is never any chance that two or more - * threads can be in this routine at the same time. - */ -static void * -memsys5MallocUnsafe(int nByte) -{ - int i; /* Index of a mem5.aPool[] slot */ - int iBin; /* Index into mem5.aiFreelist[] */ - int iFullSz; /* Size of allocation rounded up to power of 2 */ - int iLogsize; /* Log2 of iFullSz/POW2_MIN */ - - /* nByte must be a positive */ - assert(nByte > 0); - - /* No more than 1GiB per allocation */ - if (nByte > 0x40000000) - return 0; - -#if defined(SQLITE_DEBUG) || defined(SQLITE_TEST) - /* Keep track of the maximum allocation request. Even unfulfilled - * requests are counted - */ - if ((u32) nByte > mem5.maxRequest) { - mem5.maxRequest = nByte; - } -#endif - - /* Round nByte up to the next valid power of two */ - for (iFullSz = mem5.szAtom, iLogsize = 0; iFullSz < nByte; - iFullSz *= 2, iLogsize++) { - } - - /* Make sure mem5.aiFreelist[iLogsize] contains at least one free - * block. If not, then split a block of the next larger power of - * two in order to create a new free block of size iLogsize. - */ - for (iBin = iLogsize; iBin <= LOGMAX && mem5.aiFreelist[iBin] < 0; - iBin++) { - } - if (iBin > LOGMAX) { - testcase(sqlite3GlobalConfig.xLog != 0); - sqlite3_log(SQLITE_NOMEM, "failed to allocate %u bytes", nByte); - return 0; - } - i = mem5.aiFreelist[iBin]; - memsys5Unlink(i, iBin); - while (iBin > iLogsize) { - int newSize; - - iBin--; - newSize = 1 << iBin; - mem5.aCtrl[i + newSize] = CTRL_FREE | iBin; - memsys5Link(i + newSize, iBin); - } - mem5.aCtrl[i] = iLogsize; - -#if defined(SQLITE_DEBUG) || defined(SQLITE_TEST) - /* Update allocator performance statistics. */ - mem5.nAlloc++; - mem5.totalAlloc += iFullSz; - mem5.totalExcess += iFullSz - nByte; - mem5.currentCount++; - mem5.currentOut += iFullSz; - if (mem5.maxCount < mem5.currentCount) - mem5.maxCount = mem5.currentCount; - if (mem5.maxOut < mem5.currentOut) - mem5.maxOut = mem5.currentOut; -#endif - -#ifdef SQLITE_DEBUG - /* Make sure the allocated memory does not assume that it is set to zero - * or retains a value from a previous allocation - */ - memset(&mem5.zPool[i * mem5.szAtom], 0xAA, iFullSz); -#endif - - /* Return a pointer to the allocated memory. */ - return (void *)&mem5.zPool[i * mem5.szAtom]; -} - -/* - * Free an outstanding memory allocation. - */ -static void -memsys5FreeUnsafe(void *pOld) -{ - u32 size, iLogsize; - int iBlock; - - /* Set iBlock to the index of the block pointed to by pOld in - * the array of mem5.szAtom byte blocks pointed to by mem5.zPool. - */ - iBlock = (int)(((u8 *) pOld - mem5.zPool) / mem5.szAtom); - - /* Check that the pointer pOld points to a valid, non-free block. */ - assert(iBlock >= 0 && iBlock < mem5.nBlock); - assert(((u8 *) pOld - mem5.zPool) % mem5.szAtom == 0); - assert((mem5.aCtrl[iBlock] & CTRL_FREE) == 0); - - iLogsize = mem5.aCtrl[iBlock] & CTRL_LOGSIZE; - size = 1 << iLogsize; - assert(iBlock + size - 1 < (u32) mem5.nBlock); - - mem5.aCtrl[iBlock] |= CTRL_FREE; - mem5.aCtrl[iBlock + size - 1] |= CTRL_FREE; - -#if defined(SQLITE_DEBUG) || defined(SQLITE_TEST) - assert(mem5.currentCount > 0); - assert(mem5.currentOut >= (size * mem5.szAtom)); - mem5.currentCount--; - mem5.currentOut -= size * mem5.szAtom; - assert(mem5.currentOut > 0 || mem5.currentCount == 0); - assert(mem5.currentCount > 0 || mem5.currentOut == 0); -#endif - - mem5.aCtrl[iBlock] = CTRL_FREE | iLogsize; - while (ALWAYS(iLogsize < LOGMAX)) { - int iBuddy; - if ((iBlock >> iLogsize) & 1) { - iBuddy = iBlock - size; - assert(iBuddy >= 0); - } else { - iBuddy = iBlock + size; - if (iBuddy >= mem5.nBlock) - break; - } - if (mem5.aCtrl[iBuddy] != (CTRL_FREE | iLogsize)) - break; - memsys5Unlink(iBuddy, iLogsize); - iLogsize++; - if (iBuddy < iBlock) { - mem5.aCtrl[iBuddy] = CTRL_FREE | iLogsize; - mem5.aCtrl[iBlock] = 0; - iBlock = iBuddy; - } else { - mem5.aCtrl[iBlock] = CTRL_FREE | iLogsize; - mem5.aCtrl[iBuddy] = 0; - } - size *= 2; - } - -#ifdef SQLITE_DEBUG - /* Overwrite freed memory with the 0x55 bit pattern to verify that it is - * not used after being freed - */ - memset(&mem5.zPool[iBlock * mem5.szAtom], 0x55, size); -#endif - - memsys5Link(iBlock, iLogsize); -} - -/* - * Allocate nBytes of memory. - */ -static void * -memsys5Malloc(int nBytes) -{ - sqlite3_int64 *p = 0; - if (nBytes > 0) { - memsys5Enter(); - p = memsys5MallocUnsafe(nBytes); - memsys5Leave(); - } - return (void *)p; -} - -/* - * Free memory. - * - * The outer layer memory allocator prevents this routine from - * being called with pPrior==0. - */ -static void -memsys5Free(void *pPrior) -{ - assert(pPrior != 0); - memsys5Enter(); - memsys5FreeUnsafe(pPrior); - memsys5Leave(); -} - -/* - * Change the size of an existing memory allocation. - * - * The outer layer memory allocator prevents this routine from - * being called with pPrior==0. - * - * nBytes is always a value obtained from a prior call to - * memsys5Round(). Hence nBytes is always a non-negative power - * of two. If nBytes==0 that means that an oversize allocation - * (an allocation larger than 0x40000000) was requested and this - * routine should return 0 without freeing pPrior. - */ -static void * -memsys5Realloc(void *pPrior, int nBytes) -{ - int nOld; - void *p; - assert(pPrior != 0); - assert((nBytes & (nBytes - 1)) == 0); /* EV: R-46199-30249 */ - assert(nBytes >= 0); - if (nBytes == 0) { - return 0; - } - nOld = memsys5Size(pPrior); - if (nBytes <= nOld) { - return pPrior; - } - p = memsys5Malloc(nBytes); - if (p) { - memcpy(p, pPrior, nOld); - memsys5Free(pPrior); - } - return p; -} - -/* - * Round up a request size to the next valid allocation size. If - * the allocation is too large to be handled by this allocation system, - * return 0. - * - * All allocations must be a power of two and must be expressed by a - * 32-bit signed integer. Hence the largest allocation is 0x40000000 - * or 1073741824 bytes. - */ -static int -memsys5Roundup(int n) -{ - int iFullSz; - if (n > 0x40000000) - return 0; - for (iFullSz = mem5.szAtom; iFullSz < n; iFullSz *= 2) ; - return iFullSz; -} - -/* - * Return the ceiling of the logarithm base 2 of iValue. - * - * Examples: memsys5Log(1) -> 0 - * memsys5Log(2) -> 1 - * memsys5Log(4) -> 2 - * memsys5Log(5) -> 3 - * memsys5Log(8) -> 3 - * memsys5Log(9) -> 4 - */ -static int -memsys5Log(int iValue) -{ - int iLog; - for (iLog = 0; - (iLog < (int)((sizeof(int) * 8) - 1)) && (1 << iLog) < iValue; - iLog++) ; - return iLog; -} - -/* - * Initialize the memory allocator. - * - * This routine is not threadsafe. The caller must be holding a mutex - * to prevent multiple threads from entering at the same time. - */ -static int -memsys5Init(void *NotUsed) -{ - int ii; /* Loop counter */ - int nByte; /* Number of bytes of memory available to this allocator */ - u8 *zByte; /* Memory usable by this allocator */ - int nMinLog; /* Log base 2 of minimum allocation size in bytes */ - int iOffset; /* An offset into mem5.aCtrl[] */ - - UNUSED_PARAMETER(NotUsed); - - /* For the purposes of this routine, disable the mutex */ - mem5.mutex = 0; - - /* The size of a Mem5Link object must be a power of two. Verify that - * this is case. - */ - assert((sizeof(Mem5Link) & (sizeof(Mem5Link) - 1)) == 0); - - nByte = sqlite3GlobalConfig.nHeap; - zByte = (u8 *) sqlite3GlobalConfig.pHeap; - assert(zByte != 0); /* sqlite3_config() does not allow otherwise */ - - /* boundaries on sqlite3GlobalConfig.mnReq are enforced in sqlite3_config() */ - nMinLog = memsys5Log(sqlite3GlobalConfig.mnReq); - mem5.szAtom = (1 << nMinLog); - while ((int)sizeof(Mem5Link) > mem5.szAtom) { - mem5.szAtom = mem5.szAtom << 1; - } - - mem5.nBlock = (nByte / (mem5.szAtom + sizeof(u8))); - mem5.zPool = zByte; - mem5.aCtrl = (u8 *) & mem5.zPool[mem5.nBlock * mem5.szAtom]; - - for (ii = 0; ii <= LOGMAX; ii++) { - mem5.aiFreelist[ii] = -1; - } - - iOffset = 0; - for (ii = LOGMAX; ii >= 0; ii--) { - int nAlloc = (1 << ii); - if ((iOffset + nAlloc) <= mem5.nBlock) { - mem5.aCtrl[iOffset] = ii | CTRL_FREE; - memsys5Link(iOffset, ii); - iOffset += nAlloc; - } - assert((iOffset + nAlloc) > mem5.nBlock); - } - - /* If a mutex is required for normal operation, allocate one */ - if (sqlite3GlobalConfig.bMemstat == 0) { - mem5.mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MEM); - } - - return SQLITE_OK; -} - -/* - * Deinitialize this module. - */ -static void -memsys5Shutdown(void *NotUsed) -{ - UNUSED_PARAMETER(NotUsed); - mem5.mutex = 0; - return; -} - -#ifdef SQLITE_TEST -/* - * Open the file indicated and write a log of all unfreed memory - * allocations into that log. - */ -void -sqlite3Memsys5Dump(const char *zFilename) -{ - FILE *out; - int i, j, n; - int nMinLog; - - if (zFilename == 0 || zFilename[0] == 0) { - out = stdout; - } else { - out = fopen(zFilename, "w"); - if (out == 0) { - fprintf(stderr, - "** Unable to output memory debug output log: %s **\n", - zFilename); - return; - } - } - memsys5Enter(); - nMinLog = memsys5Log(mem5.szAtom); - for (i = 0; i <= LOGMAX && i + nMinLog < 32; i++) { - for (n = 0, j = mem5.aiFreelist[i]; j >= 0; - j = MEM5LINK(j)->next, n++) { - } - fprintf(out, "freelist items of size %d: %d\n", - mem5.szAtom << i, n); - } - fprintf(out, "mem5.nAlloc = %llu\n", mem5.nAlloc); - fprintf(out, "mem5.totalAlloc = %llu\n", mem5.totalAlloc); - fprintf(out, "mem5.totalExcess = %llu\n", mem5.totalExcess); - fprintf(out, "mem5.currentOut = %u\n", mem5.currentOut); - fprintf(out, "mem5.currentCount = %u\n", mem5.currentCount); - fprintf(out, "mem5.maxOut = %u\n", mem5.maxOut); - fprintf(out, "mem5.maxCount = %u\n", mem5.maxCount); - fprintf(out, "mem5.maxRequest = %u\n", mem5.maxRequest); - memsys5Leave(); - if (out == stdout) { - fflush(stdout); - } else { - fclose(out); - } -} -#endif - -/* - * This routine is the only routine in this file with external - * linkage. It returns a pointer to a static sqlite3_mem_methods - * struct populated with the memsys5 methods. - */ -const sqlite3_mem_methods * -sqlite3MemGetMemsys5(void) -{ - static const sqlite3_mem_methods memsys5Methods = { - memsys5Malloc, - memsys5Free, - memsys5Realloc, - memsys5Size, - memsys5Roundup, - memsys5Init, - memsys5Shutdown, - 0 - }; - return &memsys5Methods; -} - -#endif /* SQLITE_ENABLE_MEMSYS5 */ diff --git a/src/box/sql/mutex.c b/src/box/sql/mutex.c deleted file mode 100644 index 56c8c17..0000000 --- a/src/box/sql/mutex.c +++ /dev/null @@ -1,211 +0,0 @@ -/* - * Copyright 2010-2017, Tarantool AUTHORS, please see AUTHORS file. - * - * Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the - * following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED - * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL - * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, - * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - */ - -/* - * This file contains the C functions that implement mutexes. - * - * This file contains code that is common across all mutex implementations. - */ -#include "sqliteInt.h" - -#if defined(SQLITE_DEBUG) && !defined(SQLITE_MUTEX_OMIT) -/* - * For debugging purposes, record when the mutex subsystem is initialized - * and uninitialized so that we can assert() if there is an attempt to - * allocate a mutex while the system is uninitialized. - */ -static SQLITE_WSD int mutexIsInit = 0; -#endif /* SQLITE_DEBUG && !defined(SQLITE_MUTEX_OMIT) */ - -#ifndef SQLITE_MUTEX_OMIT -/* - * Initialize the mutex system. - */ -int -sqlite3MutexInit(void) -{ - int rc = SQLITE_OK; - if (!sqlite3GlobalConfig.mutex.xMutexAlloc) { - /* If the xMutexAlloc method has not been set, then the user did not - * install a mutex implementation via sqlite3_config() prior to - * sqlite3_initialize() being called. This block copies pointers to - * the default implementation into the sqlite3GlobalConfig structure. - */ - sqlite3_mutex_methods const *pFrom; - sqlite3_mutex_methods *pTo = &sqlite3GlobalConfig.mutex; - - if (sqlite3GlobalConfig.bCoreMutex) { - pFrom = sqlite3DefaultMutex(); - } else { - pFrom = sqlite3NoopMutex(); - } - pTo->xMutexInit = pFrom->xMutexInit; - pTo->xMutexEnd = pFrom->xMutexEnd; - pTo->xMutexFree = pFrom->xMutexFree; - pTo->xMutexEnter = pFrom->xMutexEnter; - pTo->xMutexTry = pFrom->xMutexTry; - pTo->xMutexLeave = pFrom->xMutexLeave; - pTo->xMutexHeld = pFrom->xMutexHeld; - pTo->xMutexNotheld = pFrom->xMutexNotheld; - sqlite3MemoryBarrier(); - pTo->xMutexAlloc = pFrom->xMutexAlloc; - } - assert(sqlite3GlobalConfig.mutex.xMutexInit); - rc = sqlite3GlobalConfig.mutex.xMutexInit(); - -#ifdef SQLITE_DEBUG - GLOBAL(int, mutexIsInit) = 1; -#endif - - return rc; -} - -/* - * Shutdown the mutex system. This call frees resources allocated by - * sqlite3MutexInit(). - */ -int -sqlite3MutexEnd(void) -{ - int rc = SQLITE_OK; - if (sqlite3GlobalConfig.mutex.xMutexEnd) { - rc = sqlite3GlobalConfig.mutex.xMutexEnd(); - } -#ifdef SQLITE_DEBUG - GLOBAL(int, mutexIsInit) = 0; -#endif - - return rc; -} - -/* - * Retrieve a pointer to a static mutex or allocate a new dynamic one. - */ -sqlite3_mutex * -sqlite3_mutex_alloc(int id) -{ -#ifndef SQLITE_OMIT_AUTOINIT - if (id <= SQLITE_MUTEX_RECURSIVE && sqlite3_initialize()) - return 0; - if (id > SQLITE_MUTEX_RECURSIVE && sqlite3MutexInit()) - return 0; -#endif - assert(sqlite3GlobalConfig.mutex.xMutexAlloc); - return sqlite3GlobalConfig.mutex.xMutexAlloc(id); -} - -sqlite3_mutex * -sqlite3MutexAlloc(int id) -{ - if (!sqlite3GlobalConfig.bCoreMutex) { - return 0; - } - assert(GLOBAL(int, mutexIsInit)); - assert(sqlite3GlobalConfig.mutex.xMutexAlloc); - return sqlite3GlobalConfig.mutex.xMutexAlloc(id); -} - -/* - * Free a dynamic mutex. - */ -void -sqlite3_mutex_free(sqlite3_mutex * p) -{ - if (p) { - assert(sqlite3GlobalConfig.mutex.xMutexFree); - sqlite3GlobalConfig.mutex.xMutexFree(p); - } -} - -/* - * Obtain the mutex p. If some other thread already has the mutex, block - * until it can be obtained. - */ -void -sqlite3_mutex_enter(sqlite3_mutex * p) -{ - if (p) { - assert(sqlite3GlobalConfig.mutex.xMutexEnter); - sqlite3GlobalConfig.mutex.xMutexEnter(p); - } -} - -/* - * Obtain the mutex p. If successful, return SQLITE_OK. Otherwise, if another - * thread holds the mutex and it cannot be obtained, return SQLITE_BUSY. - */ -int -sqlite3_mutex_try(sqlite3_mutex * p) -{ - int rc = SQLITE_OK; - if (p) { - assert(sqlite3GlobalConfig.mutex.xMutexTry); - return sqlite3GlobalConfig.mutex.xMutexTry(p); - } - return rc; -} - -/* - * The sqlite3_mutex_leave() routine exits a mutex that was previously - * entered by the same thread. The behavior is undefined if the mutex - * is not currently entered. If a NULL pointer is passed as an argument - * this function is a no-op. - */ -void -sqlite3_mutex_leave(sqlite3_mutex * p) -{ - if (p) { - assert(sqlite3GlobalConfig.mutex.xMutexLeave); - sqlite3GlobalConfig.mutex.xMutexLeave(p); - } -} - -#ifndef NDEBUG -/* - * The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are - * intended for use inside assert() statements. - */ -int -sqlite3_mutex_held(sqlite3_mutex * p) -{ - assert(p == 0 || sqlite3GlobalConfig.mutex.xMutexHeld); - return p == 0 || sqlite3GlobalConfig.mutex.xMutexHeld(p); -} - -int -sqlite3_mutex_notheld(sqlite3_mutex * p) -{ - assert(p == 0 || sqlite3GlobalConfig.mutex.xMutexNotheld); - return p == 0 || sqlite3GlobalConfig.mutex.xMutexNotheld(p); -} -#endif - -#endif /* !defined(SQLITE_MUTEX_OMIT) */ diff --git a/src/box/sql/mutex.h b/src/box/sql/mutex.h deleted file mode 100644 index 10bf772..0000000 --- a/src/box/sql/mutex.h +++ /dev/null @@ -1,82 +0,0 @@ -/* - * Copyright 2010-2017, Tarantool AUTHORS, please see AUTHORS file. - * - * Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the - * following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED - * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL - * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, - * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - */ - -/* - * - * This file contains the common header for all mutex implementations. - * The sqliteInt.h header #includes this file so that it is available - * to all source files. We break it out in an effort to keep the code - * better organized. - * - * NOTE: source files should *not* #include this header file directly. - * Source files should #include the sqliteInt.h file and let that file - * include this one indirectly. - */ - -/* - * Figure out what version of the code to use. The choices are - * - * SQLITE_MUTEX_OMIT No mutex logic. Not even stubs. The - * mutexes implementation cannot be overridden - * at start-time. - * - * SQLITE_MUTEX_NOOP For single-threaded applications. No - * mutual exclusion is provided. But this - * implementation can be overridden at - * start-time. - * - * SQLITE_MUTEX_PTHREADS For multi-threaded applications on Unix. - */ -#if !SQLITE_THREADSAFE -#define SQLITE_MUTEX_OMIT -#endif -#if SQLITE_THREADSAFE && !defined(SQLITE_MUTEX_NOOP) -#define SQLITE_MUTEX_PTHREADS -#endif - -#ifdef SQLITE_MUTEX_OMIT -/* - * If this is a no-op implementation, implement everything as macros. - */ -#define sqlite3_mutex_alloc(X) ((sqlite3_mutex*)8) -#define sqlite3_mutex_free(X) -#define sqlite3_mutex_enter(X) -#define sqlite3_mutex_try(X) SQLITE_OK -#define sqlite3_mutex_leave(X) -#define sqlite3_mutex_held(X) ((void)(X),1) -#define sqlite3_mutex_notheld(X) ((void)(X),1) -#define sqlite3MutexAlloc(X) ((sqlite3_mutex*)8) -#define sqlite3MutexInit() SQLITE_OK -#define sqlite3MutexEnd() -#define MUTEX_LOGIC(X) -#else -#define MUTEX_LOGIC(X) X -#endif /* defined(SQLITE_MUTEX_OMIT) */ diff --git a/src/box/sql/mutex_noop.c b/src/box/sql/mutex_noop.c deleted file mode 100644 index 67af80a..0000000 --- a/src/box/sql/mutex_noop.c +++ /dev/null @@ -1,300 +0,0 @@ -/* - * Copyright 2010-2017, Tarantool AUTHORS, please see AUTHORS file. - * - * Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the - * following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED - * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL - * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, - * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - */ - -/* - * This file contains the C functions that implement mutexes. - * - * This implementation in this file does not provide any mutual - * exclusion and is thus suitable for use only in applications - * that use SQLite in a single thread. The routines defined - * here are place-holders. Applications can substitute working - * mutex routines at start-time using the - * - * sqlite3_config(SQLITE_CONFIG_MUTEX,...) - * - * interface. - * - * If compiled with SQLITE_DEBUG, then additional logic is inserted - * that does error checking on mutexes to make sure they are being - * called correctly. - */ -#include "sqliteInt.h" - -#ifndef SQLITE_MUTEX_OMIT - -#ifndef SQLITE_DEBUG -/* - * Stub routines for all mutex methods. - * - * This routines provide no mutual exclusion or error checking. - */ -static int -noopMutexInit(void) -{ - return SQLITE_OK; -} - -static int -noopMutexEnd(void) -{ - return SQLITE_OK; -} - -static sqlite3_mutex * -noopMutexAlloc(int id) -{ - UNUSED_PARAMETER(id); - return (sqlite3_mutex *) 8; -} - -static void -noopMutexFree(sqlite3_mutex * p) -{ - UNUSED_PARAMETER(p); - return; -} - -static void -noopMutexEnter(sqlite3_mutex * p) -{ - UNUSED_PARAMETER(p); - return; -} - -static int -noopMutexTry(sqlite3_mutex * p) -{ - UNUSED_PARAMETER(p); - return SQLITE_OK; -} - -static void -noopMutexLeave(sqlite3_mutex * p) -{ - UNUSED_PARAMETER(p); - return; -} - -sqlite3_mutex_methods const * -sqlite3NoopMutex(void) -{ - static const sqlite3_mutex_methods sMutex = { - noopMutexInit, - noopMutexEnd, - noopMutexAlloc, - noopMutexFree, - noopMutexEnter, - noopMutexTry, - noopMutexLeave, - - 0, - 0, - }; - - return &sMutex; -} -#endif /* !SQLITE_DEBUG */ - -#ifdef SQLITE_DEBUG -/* - * In this implementation, error checking is provided for testing - * and debugging purposes. The mutexes still do not provide any - * mutual exclusion. - */ - -/* - * The mutex object - */ -typedef struct sqlite3_debug_mutex { - int id; /* The mutex type */ - int cnt; /* Number of entries without a matching leave */ -} sqlite3_debug_mutex; - -/* - * The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are - * intended for use inside assert() statements. - */ -static int -debugMutexHeld(sqlite3_mutex * pX) -{ - sqlite3_debug_mutex *p = (sqlite3_debug_mutex *) pX; - return p == 0 || p->cnt > 0; -} - -static int -debugMutexNotheld(sqlite3_mutex * pX) -{ - sqlite3_debug_mutex *p = (sqlite3_debug_mutex *) pX; - return p == 0 || p->cnt == 0; -} - -/* - * Initialize and deinitialize the mutex subsystem. - */ -static int -debugMutexInit(void) -{ - return SQLITE_OK; -} - -static int -debugMutexEnd(void) -{ - return SQLITE_OK; -} - -/* - * The sqlite3_mutex_alloc() routine allocates a new - * mutex and returns a pointer to it. If it returns NULL - * that means that a mutex could not be allocated. - */ -static sqlite3_mutex * -debugMutexAlloc(int id) -{ - static sqlite3_debug_mutex aStatic[SQLITE_MUTEX_STATIC_VFS3 - 1]; - sqlite3_debug_mutex *pNew = 0; - switch (id) { - case SQLITE_MUTEX_FAST: - case SQLITE_MUTEX_RECURSIVE:{ - pNew = sqlite3Malloc(sizeof(*pNew)); - if (pNew) { - pNew->id = id; - pNew->cnt = 0; - } - break; - } - default:{ -#ifdef SQLITE_ENABLE_API_ARMOR - if (id - 2 < 0 || id - 2 >= ArraySize(aStatic)) { - (void)SQLITE_MISUSE_BKPT; - return 0; - } -#endif - pNew = &aStatic[id - 2]; - pNew->id = id; - break; - } - } - return (sqlite3_mutex *) pNew; -} - -/* - * This routine deallocates a previously allocated mutex. - */ -static void -debugMutexFree(sqlite3_mutex * pX) -{ - sqlite3_debug_mutex *p = (sqlite3_debug_mutex *) pX; - assert(p->cnt == 0); - if (p->id == SQLITE_MUTEX_RECURSIVE || p->id == SQLITE_MUTEX_FAST) { - sqlite3_free(p); - } else { -#ifdef SQLITE_ENABLE_API_ARMOR - (void)SQLITE_MISUSE_BKPT; -#endif - } -} - -/* - * The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt - * to enter a mutex. If another thread is already within the mutex, - * sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return - * SQLITE_BUSY. The sqlite3_mutex_try() interface returns SQLITE_OK - * upon successful entry. Mutexes created using SQLITE_MUTEX_RECURSIVE can - * be entered multiple times by the same thread. In such cases the, - * mutex must be exited an equal number of times before another thread - * can enter. If the same thread tries to enter any other kind of mutex - * more than once, the behavior is undefined. - */ -static void -debugMutexEnter(sqlite3_mutex * pX) -{ - sqlite3_debug_mutex *p = (sqlite3_debug_mutex *) pX; - assert(p->id == SQLITE_MUTEX_RECURSIVE || debugMutexNotheld(pX)); - p->cnt++; -} - -static int -debugMutexTry(sqlite3_mutex * pX) -{ - sqlite3_debug_mutex *p = (sqlite3_debug_mutex *) pX; - assert(p->id == SQLITE_MUTEX_RECURSIVE || debugMutexNotheld(pX)); - p->cnt++; - return SQLITE_OK; -} - -/* - * The sqlite3_mutex_leave() routine exits a mutex that was - * previously entered by the same thread. The behavior - * is undefined if the mutex is not currently entered or - * is not currently allocated. SQLite will never do either. - */ -static void -debugMutexLeave(sqlite3_mutex * pX) -{ - sqlite3_debug_mutex *p = (sqlite3_debug_mutex *) pX; - assert(debugMutexHeld(pX)); - p->cnt--; - assert(p->id == SQLITE_MUTEX_RECURSIVE || debugMutexNotheld(pX)); -} - -sqlite3_mutex_methods const * -sqlite3NoopMutex(void) -{ - static const sqlite3_mutex_methods sMutex = { - debugMutexInit, - debugMutexEnd, - debugMutexAlloc, - debugMutexFree, - debugMutexEnter, - debugMutexTry, - debugMutexLeave, - - debugMutexHeld, - debugMutexNotheld - }; - - return &sMutex; -} -#endif /* SQLITE_DEBUG */ - -/* - * If compiled with SQLITE_MUTEX_NOOP, then the no-op mutex implementation - * is used regardless of the run-time threadsafety setting. - */ -#ifdef SQLITE_MUTEX_NOOP -sqlite3_mutex_methods const * -sqlite3DefaultMutex(void) -{ - return sqlite3NoopMutex(); -} -#endif /* defined(SQLITE_MUTEX_NOOP) */ -#endif /* !defined(SQLITE_MUTEX_OMIT) */ diff --git a/src/box/sql/mutex_unix.c b/src/box/sql/mutex_unix.c deleted file mode 100644 index aec0de2..0000000 --- a/src/box/sql/mutex_unix.c +++ /dev/null @@ -1,442 +0,0 @@ -/* - * Copyright 2010-2017, Tarantool AUTHORS, please see AUTHORS file. - * - * Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the - * following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED - * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL - * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, - * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - */ - -/* - * This file contains the C functions that implement mutexes for pthreads - */ -#include "sqliteInt.h" - -/* - * The code in this file is only used if we are compiling threadsafe - * under unix with pthreads. - * - * Note that this implementation requires a version of pthreads that - * supports recursive mutexes. - */ -#ifdef SQLITE_MUTEX_PTHREADS - -#include - -/* - * The sqlite3_mutex.id, sqlite3_mutex.nRef, and sqlite3_mutex.owner fields - * are necessary under two condidtions: (1) Debug builds and (2) using - * home-grown mutexes. Encapsulate these conditions into a single #define. - */ -#if defined(SQLITE_DEBUG) || defined(SQLITE_HOMEGROWN_RECURSIVE_MUTEX) -#define SQLITE_MUTEX_NREF 1 -#else -#define SQLITE_MUTEX_NREF 0 -#endif - -/* - * Each recursive mutex is an instance of the following structure. - */ -struct sqlite3_mutex { - pthread_mutex_t mutex; /* Mutex controlling the lock */ -#if SQLITE_MUTEX_NREF || defined(SQLITE_ENABLE_API_ARMOR) - int id; /* Mutex type */ -#endif -#if SQLITE_MUTEX_NREF - volatile int nRef; /* Number of entrances */ - volatile pthread_t owner; /* Thread that is within this mutex */ - int trace; /* True to trace changes */ -#endif -}; -#if SQLITE_MUTEX_NREF -#define SQLITE3_MUTEX_INITIALIZER {PTHREAD_MUTEX_INITIALIZER,0,0,(pthread_t)0,0} -#elif defined(SQLITE_ENABLE_API_ARMOR) -#define SQLITE3_MUTEX_INITIALIZER { PTHREAD_MUTEX_INITIALIZER, 0 } -#else -#define SQLITE3_MUTEX_INITIALIZER { PTHREAD_MUTEX_INITIALIZER } -#endif - -/* - * The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are - * intended for use only inside assert() statements. On some platforms, - * there might be race conditions that can cause these routines to - * deliver incorrect results. In particular, if pthread_equal() is - * not an atomic operation, then these routines might delivery - * incorrect results. On most platforms, pthread_equal() is a - * comparison of two integers and is therefore atomic. - * - * On those platforms where pthread_equal() is not atomic, SQLite - * should be compiled without -DSQLITE_DEBUG and with -DNDEBUG to - * make sure no assert() statements are evaluated and hence these - * routines are never called. - */ -#if !defined(NDEBUG) || defined(SQLITE_DEBUG) -static int -pthreadMutexHeld(sqlite3_mutex * p) -{ - return (p->nRef != 0 && pthread_equal(p->owner, pthread_self())); -} - -static int -pthreadMutexNotheld(sqlite3_mutex * p) -{ - return p->nRef == 0 || pthread_equal(p->owner, pthread_self()) == 0; -} -#endif - -/* - * Try to provide a memory barrier operation, needed for initialization - * and also for the implementation of xShmBarrier in the VFS in cases - * where SQLite is compiled without mutexes. - */ -void -sqlite3MemoryBarrier(void) -{ -#if defined(SQLITE_MEMORY_BARRIER) - SQLITE_MEMORY_BARRIER; -#elif defined(__GNUC__) && GCC_VERSION>=4001000 - __sync_synchronize(); -#endif -} - -/* - * Initialize and deinitialize the mutex subsystem. - */ -static int -pthreadMutexInit(void) -{ - return SQLITE_OK; -} - -static int -pthreadMutexEnd(void) -{ - return SQLITE_OK; -} - -/* - * The sqlite3_mutex_alloc() routine allocates a new - * mutex and returns a pointer to it. If it returns NULL - * that means that a mutex could not be allocated. SQLite - * will unwind its stack and return an error. The argument - * to sqlite3_mutex_alloc() is one of these integer constants: - * - *
    - *
  • SQLITE_MUTEX_FAST - *
  • SQLITE_MUTEX_RECURSIVE - *
  • SQLITE_MUTEX_STATIC_MASTER - *
  • SQLITE_MUTEX_STATIC_MEM - *
  • SQLITE_MUTEX_STATIC_OPEN - *
  • SQLITE_MUTEX_STATIC_PRNG - *
  • SQLITE_MUTEX_STATIC_LRU - *
  • SQLITE_MUTEX_STATIC_PMEM - *
  • SQLITE_MUTEX_STATIC_APP1 - *
  • SQLITE_MUTEX_STATIC_APP2 - *
  • SQLITE_MUTEX_STATIC_APP3 - *
  • SQLITE_MUTEX_STATIC_VFS1 - *
  • SQLITE_MUTEX_STATIC_VFS2 - *
  • SQLITE_MUTEX_STATIC_VFS3 - *
- * - * The first two constants cause sqlite3_mutex_alloc() to create - * a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE - * is used but not necessarily so when SQLITE_MUTEX_FAST is used. - * The mutex implementation does not need to make a distinction - * between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does - * not want to. But SQLite will only request a recursive mutex in - * cases where it really needs one. If a faster non-recursive mutex - * implementation is available on the host platform, the mutex subsystem - * might return such a mutex in response to SQLITE_MUTEX_FAST. - * - * The other allowed parameters to sqlite3_mutex_alloc() each return - * a pointer to a static preexisting mutex. Six static mutexes are - * used by the current version of SQLite. Future versions of SQLite - * may add additional static mutexes. Static mutexes are for internal - * use by SQLite only. Applications that use SQLite mutexes should - * use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or - * SQLITE_MUTEX_RECURSIVE. - * - * Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST - * or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() - * returns a different mutex on every call. But for the static - * mutex types, the same mutex is returned on every call that has - * the same type number. - */ -static sqlite3_mutex * -pthreadMutexAlloc(int iType) -{ - static sqlite3_mutex staticMutexes[] = { - SQLITE3_MUTEX_INITIALIZER, - SQLITE3_MUTEX_INITIALIZER, - SQLITE3_MUTEX_INITIALIZER, - SQLITE3_MUTEX_INITIALIZER, - SQLITE3_MUTEX_INITIALIZER, - SQLITE3_MUTEX_INITIALIZER, - SQLITE3_MUTEX_INITIALIZER, - SQLITE3_MUTEX_INITIALIZER, - SQLITE3_MUTEX_INITIALIZER, - SQLITE3_MUTEX_INITIALIZER, - SQLITE3_MUTEX_INITIALIZER, - SQLITE3_MUTEX_INITIALIZER - }; - sqlite3_mutex *p; - switch (iType) { - case SQLITE_MUTEX_RECURSIVE:{ - p = sqlite3MallocZero(sizeof(*p)); - if (p) { -#ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX - /* If recursive mutexes are not available, we will have to - * build our own. See below. - */ - pthread_mutex_init(&p->mutex, 0); -#else - /* Use a recursive mutex if it is available */ - pthread_mutexattr_t recursiveAttr; - pthread_mutexattr_init(&recursiveAttr); - pthread_mutexattr_settype(&recursiveAttr, - PTHREAD_MUTEX_RECURSIVE); - pthread_mutex_init(&p->mutex, &recursiveAttr); - pthread_mutexattr_destroy(&recursiveAttr); -#endif - } - break; - } - case SQLITE_MUTEX_FAST:{ - p = sqlite3MallocZero(sizeof(*p)); - if (p) { - pthread_mutex_init(&p->mutex, 0); - } - break; - } - default:{ -#ifdef SQLITE_ENABLE_API_ARMOR - if (iType - 2 < 0 - || iType - 2 >= ArraySize(staticMutexes)) { - (void)SQLITE_MISUSE_BKPT; - return 0; - } -#endif - p = &staticMutexes[iType - 2]; - break; - } - } -#if SQLITE_MUTEX_NREF || defined(SQLITE_ENABLE_API_ARMOR) - if (p) - p->id = iType; -#endif - return p; -} - -/* - * This routine deallocates a previously - * allocated mutex. SQLite is careful to deallocate every - * mutex that it allocates. - */ -static void -pthreadMutexFree(sqlite3_mutex * p) -{ - assert(p->nRef == 0); -#if SQLITE_ENABLE_API_ARMOR - if (p->id == SQLITE_MUTEX_FAST || p->id == SQLITE_MUTEX_RECURSIVE) -#endif - { - pthread_mutex_destroy(&p->mutex); - sqlite3_free(p); - } -#ifdef SQLITE_ENABLE_API_ARMOR - else { - (void)SQLITE_MISUSE_BKPT; - } -#endif -} - -/* - * The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt - * to enter a mutex. If another thread is already within the mutex, - * sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return - * SQLITE_BUSY. The sqlite3_mutex_try() interface returns SQLITE_OK - * upon successful entry. Mutexes created using SQLITE_MUTEX_RECURSIVE can - * be entered multiple times by the same thread. In such cases the, - * mutex must be exited an equal number of times before another thread - * can enter. If the same thread tries to enter any other kind of mutex - * more than once, the behavior is undefined. - */ -static void -pthreadMutexEnter(sqlite3_mutex * p) -{ - assert(p->id == SQLITE_MUTEX_RECURSIVE || pthreadMutexNotheld(p)); - -#ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX - /* If recursive mutexes are not available, then we have to grow - * our own. This implementation assumes that pthread_equal() - * is atomic - that it cannot be deceived into thinking self - * and p->owner are equal if p->owner changes between two values - * that are not equal to self while the comparison is taking place. - * This implementation also assumes a coherent cache - that - * separate processes cannot read different values from the same - * address at the same time. If either of these two conditions - * are not met, then the mutexes will fail and problems will result. - */ - { - pthread_t self = pthread_self(); - if (p->nRef > 0 && pthread_equal(p->owner, self)) { - p->nRef++; - } else { - pthread_mutex_lock(&p->mutex); - assert(p->nRef == 0); - p->owner = self; - p->nRef = 1; - } - } -#else - /* Use the built-in recursive mutexes if they are available. - */ - pthread_mutex_lock(&p->mutex); -#if SQLITE_MUTEX_NREF - assert(p->nRef > 0 || p->owner == 0); - p->owner = pthread_self(); - p->nRef++; -#endif -#endif - -#ifdef SQLITE_DEBUG - if (p->trace) { - printf("enter mutex %p (%d) with nRef=%d\n", p, p->trace, - p->nRef); - } -#endif -} - -static int -pthreadMutexTry(sqlite3_mutex * p) -{ - int rc; - assert(p->id == SQLITE_MUTEX_RECURSIVE || pthreadMutexNotheld(p)); - -#ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX - /* If recursive mutexes are not available, then we have to grow - * our own. This implementation assumes that pthread_equal() - * is atomic - that it cannot be deceived into thinking self - * and p->owner are equal if p->owner changes between two values - * that are not equal to self while the comparison is taking place. - * This implementation also assumes a coherent cache - that - * separate processes cannot read different values from the same - * address at the same time. If either of these two conditions - * are not met, then the mutexes will fail and problems will result. - */ - { - pthread_t self = pthread_self(); - if (p->nRef > 0 && pthread_equal(p->owner, self)) { - p->nRef++; - rc = SQLITE_OK; - } else if (pthread_mutex_trylock(&p->mutex) == 0) { - assert(p->nRef == 0); - p->owner = self; - p->nRef = 1; - rc = SQLITE_OK; - } else { - rc = SQLITE_BUSY; - } - } -#else - /* Use the built-in recursive mutexes if they are available. - */ - if (pthread_mutex_trylock(&p->mutex) == 0) { -#if SQLITE_MUTEX_NREF - p->owner = pthread_self(); - p->nRef++; -#endif - rc = SQLITE_OK; - } else { - rc = SQLITE_BUSY; - } -#endif - -#ifdef SQLITE_DEBUG - if (rc == SQLITE_OK && p->trace) { - printf("enter mutex %p (%d) with nRef=%d\n", p, p->trace, - p->nRef); - } -#endif - return rc; -} - -/* - * The sqlite3_mutex_leave() routine exits a mutex that was - * previously entered by the same thread. The behavior - * is undefined if the mutex is not currently entered or - * is not currently allocated. SQLite will never do either. - */ -static void -pthreadMutexLeave(sqlite3_mutex * p) -{ - assert(pthreadMutexHeld(p)); -#if SQLITE_MUTEX_NREF - p->nRef--; - if (p->nRef == 0) - p->owner = 0; -#endif - assert(p->nRef == 0 || p->id == SQLITE_MUTEX_RECURSIVE); - -#ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX - if (p->nRef == 0) { - pthread_mutex_unlock(&p->mutex); - } -#else - pthread_mutex_unlock(&p->mutex); -#endif - -#ifdef SQLITE_DEBUG - if (p->trace) { - printf("leave mutex %p (%d) with nRef=%d\n", p, p->trace, - p->nRef); - } -#endif -} - -sqlite3_mutex_methods const * -sqlite3DefaultMutex(void) -{ - static const sqlite3_mutex_methods sMutex = { - pthreadMutexInit, - pthreadMutexEnd, - pthreadMutexAlloc, - pthreadMutexFree, - pthreadMutexEnter, - pthreadMutexTry, - pthreadMutexLeave, -#ifdef SQLITE_DEBUG - pthreadMutexHeld, - pthreadMutexNotheld -#else - 0, - 0 -#endif - }; - - return &sMutex; -} - -#endif /* SQLITE_MUTEX_PTHREADS */ diff --git a/src/box/sql/sqlite3.h b/src/box/sql/sqlite3.h deleted file mode 100644 index d60d74d..0000000 --- a/src/box/sql/sqlite3.h +++ /dev/null @@ -1,6728 +0,0 @@ -/* - * Copyright 2010-2017, Tarantool AUTHORS, please see AUTHORS file. - * - * Redistribution and use in source and binary forms, with or - * without modification, are permitted provided that the following - * conditions are met: - * - * 1. Redistributions of source code must retain the above - * copyright notice, this list of conditions and the - * following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above - * copyright notice, this list of conditions and the following - * disclaimer in the documentation and/or other materials - * provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED - * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL - * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, - * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - */ - -/* - * This header file defines the interface that the SQLite library - * presents to client programs. If a C-function, structure, datatype, - * or constant definition does not appear in this file, then it is - * not a published API of SQLite, is subject to change without - * notice, and should not be referenced by programs that use SQLite. - * - * Some of the definitions that are in this file are marked as - * "experimental". Experimental interfaces are normally new - * features recently added to SQLite. We do not anticipate changes - * to experimental interfaces but reserve the right to make minor changes - * if experience from use "in the wild" suggest such changes are prudent. - * - * The official C-language API documentation for SQLite is derived - * from comments in this file. This file is the authoritative source - * on how SQLite interfaces are supposed to operate. - * - * The name of this file under configuration management is "sqlite.h.in". - * The makefile makes some minor changes to this file (such as inserting - * the version number) and changes its name to "sqlite3.h" as - * part of the build process. -*/ -#ifndef SQLITE3_H -#define SQLITE3_H -#include /* Needed for the definition of va_list */ - -/* - * Make sure we can call this stuff from C++. -*/ -#ifdef __cplusplus -//extern "C" { -#endif - -/* - * Provide the ability to override linkage features of the interface. -*/ -#ifndef SQLITE_EXTERN -#define SQLITE_EXTERN extern -#endif -#ifndef SQLITE_API -#define SQLITE_API -#endif -#ifndef SQLITE_CDECL -#define SQLITE_CDECL -#endif -#ifndef SQLITE_APICALL -#define SQLITE_APICALL -#endif -#ifndef SQLITE_STDCALL -#define SQLITE_STDCALL SQLITE_APICALL -#endif -#ifndef SQLITE_CALLBACK -#define SQLITE_CALLBACK -#endif -#ifndef SQLITE_SYSAPI -#define SQLITE_SYSAPI -#endif - -/* - * These no-op macros are used in front of interfaces to mark those - * interfaces as either deprecated or experimental. New applications - * should not use deprecated interfaces - they are supported for backwards - * compatibility only. Application writers should be aware that - * experimental interfaces are subject to change in point releases. - * - * These macros used to resolve to various kinds of compiler magic that - * would generate warning messages when they were used. But that - * compiler magic ended up generating such a flurry of bug reports - * that we have taken it all out and gone back to using simple - * noop macros. -*/ -#define SQLITE_EXPERIMENTAL - -/* - * Ensure these symbols were not defined by some previous header file. -*/ -#ifdef SQLITE_VERSION -#undef SQLITE_VERSION -#endif -#ifdef SQLITE_VERSION_NUMBER -#undef SQLITE_VERSION_NUMBER -#endif - -/* - * CAPI3REF: Compile-Time Library Version Numbers - * - * ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header - * evaluates to a string literal that is the SQLite version in the - * format "X.Y.Z" where X is the major version number (always 3 for - * SQLite3) and Y is the minor version number and Z is the release number.)^ - * ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer - * with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same - * numbers used in [SQLITE_VERSION].)^ - * The SQLITE_VERSION_NUMBER for any given release of SQLite will also - * be larger than the release from which it is derived. Either Y will - * be held constant and Z will be incremented or else Y will be incremented - * and Z will be reset to zero. - * - * Since [version 3.6.18] ([dateof:3.6.18]), - * SQLite source code has been stored in the - * Fossil configuration management - * system. ^The SQLITE_SOURCE_ID macro evaluates to - * a string which identifies a particular check-in of SQLite - * within its configuration management system. ^The SQLITE_SOURCE_ID - * string contains the date and time of the check-in (UTC) and an SHA1 - * hash of the entire source tree. - * - * See also: [sqlite3_libversion()], - * [sqlite3_libversion_number()], [sqlite3_sourceid()], - * [sqlite_version()] and [sqlite_source_id()]. -*/ -#define SQLITE_VERSION "3.16.2" -#define SQLITE_VERSION_NUMBER 3016002 -#define SQLITE_SOURCE_ID "D 1970-01-01 00:00:00 00000000-0000-0000-0000-000000000000" - -/* - * CAPI3REF: Run-Time Library Version Numbers - * KEYWORDS: sqlite3_version sqlite3_sourceid - * - * These interfaces provide the same information as the [SQLITE_VERSION], - * [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros - * but are associated with the library instead of the header file. ^(Cautious - * programmers might include assert() statements in their application to - * verify that values returned by these interfaces match the macros in - * the header, and thus ensure that the application is - * compiled with matching library and header files. - * - * 
- * assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
- * assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
- * assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
- *
)^ - * - * ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION] - * macro. ^The sqlite3_libversion() function returns a pointer to the - * to the sqlite3_version[] string constant. The sqlite3_libversion() - * function is provided for use in DLLs since DLL users usually do not have - * direct access to string constants within the DLL. ^The - * sqlite3_libversion_number() function returns an integer equal to - * [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns - * a pointer to a string constant whose value is the same as the - * [SQLITE_SOURCE_ID] C preprocessor macro. - * - * See also: [sqlite_version()] and [sqlite_source_id()]. -*/ -SQLITE_API SQLITE_EXTERN const char sqlite3_version[]; - -SQLITE_API const char * -sqlite3_libversion(void); - -SQLITE_API const char * -sqlite3_sourceid(void); - -SQLITE_API int -sqlite3_libversion_number(void); - -/* - * CAPI3REF: Test To See If The Library Is Threadsafe - * - * ^The sqlite3_threadsafe() function returns zero if and only if - * SQLite was compiled with mutexing code omitted due to the - * [SQLITE_THREADSAFE] compile-time option being set to 0. - * - * SQLite can be compiled with or without mutexes. When - * the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes - * are enabled and SQLite is threadsafe. When the - * [SQLITE_THREADSAFE] macro is 0, - * the mutexes are omitted. Without the mutexes, it is not safe - * to use SQLite concurrently from more than one thread. - * - * Enabling mutexes incurs a measurable performance penalty. - * So if speed is of utmost importance, it makes sense to disable - * the mutexes. But for maximum safety, mutexes should be enabled. - * ^The default behavior is for mutexes to be enabled. - * - * This interface can be used by an application to make sure that the - * version of SQLite that it is linking against was compiled with - * the desired setting of the [SQLITE_THREADSAFE] macro. - * - * This interface only reports on the compile-time mutex setting - * of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with - * SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but - * can be fully or partially disabled using a call to [sqlite3_config()] - * with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD], - * or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the - * sqlite3_threadsafe() function shows only the compile-time setting of - * thread safety, not any run-time changes to that setting made by - * sqlite3_config(). In other words, the return value from sqlite3_threadsafe() - * is unchanged by calls to sqlite3_config().)^ - * - * See the [threading mode] documentation for additional information. -*/ -SQLITE_API int -sqlite3_threadsafe(void); - -/* - * CAPI3REF: Database Connection Handle - * KEYWORDS: {database connection} {database connections} - * - * Each open SQLite database is represented by a pointer to an instance of - * the opaque structure named "sqlite3". It is useful to think of an sqlite3 - * pointer as an object. The [sqlite3_open()], and - * [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()] - * and [sqlite3_close_v2()] are its destructors. There are many other - * interfaces (such as - * [sqlite3_prepare_v2()], [sqlite3_create_function()], and - * [sqlite3_busy_timeout()] to name but three) that are methods on an - * sqlite3 object. -*/ -typedef struct sqlite3 sqlite3; - -/* - * CAPI3REF: 64-Bit Integer Types - * KEYWORDS: sqlite_int64 sqlite_uint64 - * - * Because there is no cross-platform way to specify 64-bit integer types - * SQLite includes typedefs for 64-bit signed and unsigned integers. - * - * The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions. - * The sqlite_int64 and sqlite_uint64 types are supported for backwards - * compatibility only. - * - * ^The sqlite3_int64 and sqlite_int64 types can store integer values - * between -9223372036854775808 and +9223372036854775807 inclusive. ^The - * sqlite3_uint64 and sqlite_uint64 types can store integer values - * between 0 and +18446744073709551615 inclusive. -*/ -#ifdef SQLITE_INT64_TYPE -typedef SQLITE_INT64_TYPE sqlite_int64; -typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; -#elif defined(_MSC_VER) || defined(__BORLANDC__) -typedef __int64 sqlite_int64; -typedef unsigned __int64 sqlite_uint64; -#else -typedef long long int sqlite_int64; -typedef unsigned long long int sqlite_uint64; -#endif -typedef sqlite_int64 sqlite3_int64; -typedef sqlite_uint64 sqlite3_uint64; - -/* - * If compiling for a processor that lacks floating point support, - * substitute integer for floating-point. -*/ -#ifdef SQLITE_OMIT_FLOATING_POINT -#define double sqlite3_int64 -#endif - -/* - * CAPI3REF: Closing A Database Connection - * DESTRUCTOR: sqlite3 - * - * ^The sqlite3_close() and sqlite3_close_v2() routines are destructors - * for the [sqlite3] object. - * ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if - * the [sqlite3] object is successfully destroyed and all associated - * resources are deallocated. - * - * ^If the database connection is associated with unfinalized prepared - * statements objects then sqlite3_close() - * will leave the database connection open and return [SQLITE_BUSY]. - * ^If sqlite3_close_v2() is called with unfinalized prepared statements - * , then the database connection becomes - * an unusable "zombie" which will automatically be deallocated when the - * last prepared statement is finalized. - * The sqlite3_close_v2() interface is intended for use with - * host languages that are garbage collected, and where the order in which - * destructors are called is arbitrary. - * - * Applications should [sqlite3_finalize | finalize] all [prepared statements], - * [sqlite3_blob_close | close] all [BLOB handles], and - * [finish] all objects associated - * with the [sqlite3] object prior to attempting to close the object. ^If - * sqlite3_close_v2() is called on a [database connection] that still has - * outstanding [prepared statements], [BLOB handles] - * then it returns [SQLITE_OK] and the deallocation - * of resources is deferred until all [prepared statements], [BLOB handles] - * objects are also destroyed. - * - * ^If an [sqlite3] object is destroyed while a transaction is open, - * the transaction is automatically rolled back. - * - * The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)] - * must be either a NULL - * pointer or an [sqlite3] object pointer obtained - * from [sqlite3_open()], [sqlite3_open16()], or - * [sqlite3_open_v2()], and not previously closed. - * ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer - * argument is a harmless no-op. -*/ -SQLITE_API int -sqlite3_close(sqlite3 *); - -SQLITE_API int -sqlite3_close_v2(sqlite3 *); - -/* - * The type for a callback function. - * This is legacy and deprecated. It is included for historical - * compatibility and is not documented. -*/ -typedef int (*sqlite3_callback) (void *, int, char **, char **); - -/* - * CAPI3REF: One-Step Query Execution Interface - * METHOD: sqlite3 - * - * The sqlite3_exec() interface is a convenience wrapper around - * [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()], - * that allows an application to run multiple statements of SQL - * without having to use a lot of C code. - * - * ^The sqlite3_exec() interface runs zero or more UTF-8 encoded, - * semicolon-separate SQL statements passed into its 2nd argument, - * in the context of the [database connection] passed in as its 1st - * argument. ^If the callback function of the 3rd argument to - * sqlite3_exec() is not NULL, then it is invoked for each result row - * coming out of the evaluated SQL statements. ^The 4th argument to - * sqlite3_exec() is relayed through to the 1st argument of each - * callback invocation. ^If the callback pointer to sqlite3_exec() - * is NULL, then no callback is ever invoked and result rows are - * ignored. - * - * ^If an error occurs while evaluating the SQL statements passed into - * sqlite3_exec(), then execution of the current statement stops and - * subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec() - * is not NULL then any error message is written into memory obtained - * from [sqlite3_malloc()] and passed back through the 5th parameter. - * To avoid memory leaks, the application should invoke [sqlite3_free()] - * on error message strings returned through the 5th parameter of - * sqlite3_exec() after the error message string is no longer needed. - * ^If the 5th parameter to sqlite3_exec() is not NULL and no errors - * occur, then sqlite3_exec() sets the pointer in its 5th parameter to - * NULL before returning. - * - * ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec() - * routine returns SQLITE_ABORT without invoking the callback again and - * without running any subsequent SQL statements. - * - * ^The 2nd argument to the sqlite3_exec() callback function is the - * number of columns in the result. ^The 3rd argument to the sqlite3_exec() - * callback is an array of pointers to strings obtained as if from - * [sqlite3_column_text()], one for each column. ^If an element of a - * result row is NULL then the corresponding string pointer for the - * sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the - * sqlite3_exec() callback is an array of pointers to strings where each - * entry represents the name of corresponding result column as obtained - * from [sqlite3_column_name()]. - * - * ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer - * to an empty string, or a pointer that contains only whitespace and/or - * SQL comments, then no SQL statements are evaluated and the database - * is not changed. - * - * Restrictions: - * - *
    - *
  • The application must ensure that the 1st parameter to sqlite3_exec() - * is a valid and open [database connection]. - *
  • The application must not close the [database connection] specified by - * the 1st parameter to sqlite3_exec() while sqlite3_exec() is running. - *
  • The application must not modify the SQL statement text passed into - * the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running. - *
-*/ -SQLITE_API int -sqlite3_exec(sqlite3 *, /* An open database */ - const char *sql, /* SQL to be evaluated */ - int (*callback) (void *, int, char **, char **), /* Callback function */ - void *, /* 1st argument to callback */ - char **errmsg /* Error msg written here */ - ); - -/* - * CAPI3REF: Result Codes - * KEYWORDS: {result code definitions} - * - * Many SQLite functions return an integer result code from the set shown - * here in order to indicate success or failure. - * - * New error codes may be added in future versions of SQLite. - * - * See also: [extended result code definitions] -*/ -#define SQLITE_OK 0 /* Successful result */ -/* beginning-of-error-codes */ -#define SQLITE_ERROR 1 /* SQL error or missing database */ -#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */ -#define SQLITE_PERM 3 /* Access permission denied */ -#define SQLITE_ABORT 4 /* Callback routine requested an abort */ -#define SQLITE_BUSY 5 /* The database file is locked */ -#define SQLITE_LOCKED 6 /* A table in the database is locked */ -#define SQLITE_NOMEM 7 /* A malloc() failed */ -#define SQLITE_READONLY 8 /* Attempt to write a readonly database */ -#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt() */ -#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ -#define SQLITE_CORRUPT 11 /* The database disk image is malformed */ -#define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */ -#define SQLITE_FULL 13 /* Insertion failed because database is full */ -#define SQLITE_CANTOPEN 14 /* Unable to open the database file */ -#define SQLITE_PROTOCOL 15 /* Database lock protocol error */ -#define SQLITE_EMPTY 16 /* Database is empty */ -#define SQLITE_SCHEMA 17 /* The database schema changed */ -#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */ -#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */ -#define SQLITE_MISMATCH 20 /* Data type mismatch */ -#define SQLITE_MISUSE 21 /* Library used incorrectly */ -#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ -#define SQLITE_FORMAT 23 /* Auxiliary database format error */ -#define SQLITE_RANGE 24 /* 2nd parameter to sqlite3_bind out of range */ -#define SQLITE_NOTADB 25 /* File opened that is not a database file */ -#define SQL_TARANTOOL_ITERATOR_FAIL 26 -#define SQL_TARANTOOL_INSERT_FAIL 27 -#define SQL_TARANTOOL_DELETE_FAIL 28 -#define SQL_TARANTOOL_ERROR 29 -#define SQLITE_NOTICE 31 /* Notifications from sqlite3_log() */ -#define SQLITE_WARNING 32 /* Warnings from sqlite3_log() */ -#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ -#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ -/* end-of-error-codes */ - -/* - * CAPI3REF: Extended Result Codes - * KEYWORDS: {extended result code definitions} - * - * In its default configuration, SQLite API routines return one of 30 integer - * [result codes]. However, experience has shown that many of - * these result codes are too coarse-grained. They do not provide as - * much information about problems as programmers might like. In an effort to - * address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8] - * and later) include - * support for additional result codes that provide more detailed information - * about errors. These [extended result codes] are enabled or disabled - * on a per database connection basis using the - * [sqlite3_extended_result_codes()] API. Or, the extended code for - * the most recent error can be obtained using - * [sqlite3_extended_errcode()]. -*/ -#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) -#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) -#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) -#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) -#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) -#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) -#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) -#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) -#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) -#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) -#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) -#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) -#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8)) -#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8)) -#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8)) -#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8)) -#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8)) -#define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8)) -#define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8)) -#define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8)) -#define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8)) -#define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8)) -#define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR | (23<<8)) -#define SQLITE_IOERR_MMAP (SQLITE_IOERR | (24<<8)) -#define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25<<8)) -#define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8)) -#define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27<<8)) -#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8)) -#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8)) -#define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8)) -#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8)) -#define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8)) -#define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8)) -#define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8)) -#define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8)) -#define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8)) -#define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8)) -#define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8)) -#define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8)) -#define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8)) -#define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8)) -#define SQLITE_CONSTRAINT_FOREIGNKEY (SQLITE_CONSTRAINT | (3<<8)) -#define SQLITE_CONSTRAINT_FUNCTION (SQLITE_CONSTRAINT | (4<<8)) -#define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8)) -#define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8)) -#define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8)) -#define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8)) -#define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8)) -#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8)) -#define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8)) -#define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8)) - -/* - * CAPI3REF: Flags For File Open Operations - * - * These bit values are intended for use in the - * 3rd parameter to the [sqlite3_open_v2()] interface and - * in the 4th parameter to the [sqlite3_vfs.xOpen] method. -*/ -#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */ -#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */ -#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */ -#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */ -#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */ -#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */ -#define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */ -#define SQLITE_OPEN_MEMORY 0x00000080 /* Ok for sqlite3_open_v2() */ -#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */ -#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */ -#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */ -#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */ -#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */ -#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */ -#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */ - -/* Reserved: 0x00F00000 */ - -/* - * CAPI3REF: Device Characteristics - * - * The xDeviceCharacteristics method of the [sqlite3_io_methods] - * object returns an integer which is a vector of these - * bit values expressing I/O characteristics of the mass storage - * device that holds the file that the [sqlite3_io_methods] - * refers to. - * - * The SQLITE_IOCAP_ATOMIC property means that all writes of - * any size are atomic. The SQLITE_IOCAP_ATOMICnnn values - * mean that writes of blocks that are nnn bytes in size and - * are aligned to an address which is an integer multiple of - * nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means - * that when data is appended to a file, the data is appended - * first then the size of the file is extended, never the other - * way around. The SQLITE_IOCAP_SEQUENTIAL property means that - * information is written to disk in the same order as calls - * to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that - * after reboot following a crash or power loss, the only bytes in a - * file that were written at the application level might have changed - * and that adjacent bytes, even bytes within the same sector are - * guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN - * flag indicate that a file cannot be deleted when open. The - * SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on - * read-only media and cannot be changed even by processes with - * elevated privileges. -*/ -#define SQLITE_IOCAP_ATOMIC 0x00000001 -#define SQLITE_IOCAP_ATOMIC512 0x00000002 -#define SQLITE_IOCAP_ATOMIC1K 0x00000004 -#define SQLITE_IOCAP_ATOMIC2K 0x00000008 -#define SQLITE_IOCAP_ATOMIC4K 0x00000010 -#define SQLITE_IOCAP_ATOMIC8K 0x00000020 -#define SQLITE_IOCAP_ATOMIC16K 0x00000040 -#define SQLITE_IOCAP_ATOMIC32K 0x00000080 -#define SQLITE_IOCAP_ATOMIC64K 0x00000100 -#define SQLITE_IOCAP_SAFE_APPEND 0x00000200 -#define SQLITE_IOCAP_SEQUENTIAL 0x00000400 -#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800 -#define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000 -#define SQLITE_IOCAP_IMMUTABLE 0x00002000 - -/* - * CAPI3REF: File Locking Levels - * - * SQLite uses one of these integer values as the second - * argument to calls it makes to the xLock() and xUnlock() methods - * of an [sqlite3_io_methods] object. -*/ -#define SQLITE_LOCK_NONE 0 -#define SQLITE_LOCK_SHARED 1 -#define SQLITE_LOCK_RESERVED 2 -#define SQLITE_LOCK_PENDING 3 -#define SQLITE_LOCK_EXCLUSIVE 4 - -/* - * CAPI3REF: Synchronization Type Flags - * - * When SQLite invokes the xSync() method of an - * [sqlite3_io_methods] object it uses a combination of - * these integer values as the second argument. - * - * When the SQLITE_SYNC_DATAONLY flag is used, it means that the - * sync operation only needs to flush data to mass storage. Inode - * information need not be flushed. If the lower four bits of the flag - * equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics. - * If the lower four bits equal SQLITE_SYNC_FULL, that means - * to use Mac OS X style fullsync instead of fsync(). - * - * Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags - * with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL - * settings. The [synchronous pragma] determines when calls to the - * xSync VFS method occur and applies uniformly across all platforms. - * The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how - * energetic or rigorous or forceful the sync operations are and - * only make a difference on Mac OSX for the default SQLite code. - * (Third-party VFS implementations might also make the distinction - * between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the - * operating systems natively supported by SQLite, only Mac OSX - * cares about the difference.) -*/ -#define SQLITE_SYNC_NORMAL 0x00002 -#define SQLITE_SYNC_FULL 0x00003 -#define SQLITE_SYNC_DATAONLY 0x00010 - -/* - * CAPI3REF: OS Interface Open File Handle - * - * An [sqlite3_file] object represents an open file in the - * [sqlite3_vfs | OS interface layer]. Individual OS interface - * implementations will - * want to subclass this object by appending additional fields - * for their own use. The pMethods entry is a pointer to an - * [sqlite3_io_methods] object that defines methods for performing - * I/O operations on the open file. -*/ -typedef struct sqlite3_file sqlite3_file; -struct sqlite3_file { - const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ -}; - -/* - * CAPI3REF: OS Interface File Virtual Methods Object - * - * Every file opened by the [sqlite3_vfs.xOpen] method populates an - * [sqlite3_file] object (or, more commonly, a subclass of the - * [sqlite3_file] object) with a pointer to an instance of this object. - * This object defines the methods used to perform various operations - * against the open file represented by the [sqlite3_file] object. - * - * If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element - * to a non-NULL pointer, then the sqlite3_io_methods.xClose method - * may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed. The - * only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen] - * is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element - * to NULL. - * - * The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or - * [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). - * The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY] - * flag may be ORed in to indicate that only the data of the file - * and not its inode needs to be synced. - * - * The integer values to xLock() and xUnlock() are one of - *
    - *
  • [SQLITE_LOCK_NONE], - *
  • [SQLITE_LOCK_SHARED], - *
  • [SQLITE_LOCK_RESERVED], - *
  • [SQLITE_LOCK_PENDING], or - *
  • [SQLITE_LOCK_EXCLUSIVE]. - *
- * xLock() increases the lock. xUnlock() decreases the lock. - * The xCheckReservedLock() method checks whether any database connection, - * either in this process or in some other process, is holding a RESERVED, - * PENDING, or EXCLUSIVE lock on the file. It returns true - * if such a lock exists and false otherwise. - * - * The xFileControl() method is a generic interface that allows custom - * VFS implementations to directly control an open file using the - * [sqlite3_file_control()] interface. The second "op" argument is an - * integer opcode. The third argument is a generic pointer intended to - * point to a structure that may contain arguments or space in which to - * write return values. Potential uses for xFileControl() might be - * functions to enable blocking locks with timeouts, to change the - * locking strategy (for example to use dot-file locks), to inquire - * about the status of a lock, or to break stale locks. The SQLite - * core reserves all opcodes less than 100 for its own use. - * A [file control opcodes | list of opcodes] less than 100 is available. - * Applications that define a custom xFileControl method should use opcodes - * greater than 100 to avoid conflicts. VFS implementations should - * return [SQLITE_NOTFOUND] for file control opcodes that they do not - * recognize. - * - * The xSectorSize() method returns the sector size of the - * device that underlies the file. The sector size is the - * minimum write that can be performed without disturbing - * other bytes in the file. The xDeviceCharacteristics() - * method returns a bit vector describing behaviors of the - * underlying device: - * - *
    - *
  • [SQLITE_IOCAP_ATOMIC] - *
  • [SQLITE_IOCAP_ATOMIC512] - *
  • [SQLITE_IOCAP_ATOMIC1K] - *
  • [SQLITE_IOCAP_ATOMIC2K] - *
  • [SQLITE_IOCAP_ATOMIC4K] - *
  • [SQLITE_IOCAP_ATOMIC8K] - *
  • [SQLITE_IOCAP_ATOMIC16K] - *
  • [SQLITE_IOCAP_ATOMIC32K] - *
  • [SQLITE_IOCAP_ATOMIC64K] - *
  • [SQLITE_IOCAP_SAFE_APPEND] - *
  • [SQLITE_IOCAP_SEQUENTIAL] - *
- * - * The SQLITE_IOCAP_ATOMIC property means that all writes of - * any size are atomic. The SQLITE_IOCAP_ATOMICnnn values - * mean that writes of blocks that are nnn bytes in size and - * are aligned to an address which is an integer multiple of - * nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means - * that when data is appended to a file, the data is appended - * first then the size of the file is extended, never the other - * way around. The SQLITE_IOCAP_SEQUENTIAL property means that - * information is written to disk in the same order as calls - * to xWrite(). - * - * If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill - * in the unread portions of the buffer with zeros. A VFS that - * fails to zero-fill short reads might seem to work. However, - * failure to zero-fill short reads will eventually lead to - * database corruption. -*/ -typedef struct sqlite3_io_methods sqlite3_io_methods; -struct sqlite3_io_methods { - int iVersion; - int (*xClose) (sqlite3_file *); - int (*xRead) (sqlite3_file *, void *, int iAmt, - sqlite3_int64 iOfst); - int (*xWrite) (sqlite3_file *, const void *, int iAmt, - sqlite3_int64 iOfst); - int (*xTruncate) (sqlite3_file *, sqlite3_int64 size); - int (*xSync) (sqlite3_file *, int flags); - int (*xFileSize) (sqlite3_file *, sqlite3_int64 * pSize); - int (*xLock) (sqlite3_file *, int); - int (*xUnlock) (sqlite3_file *, int); - int (*xCheckReservedLock) (sqlite3_file *, int *pResOut); - int (*xFileControl) (sqlite3_file *, int op, void *pArg); - int (*xSectorSize) (sqlite3_file *); - int (*xDeviceCharacteristics) (sqlite3_file *); - /* Methods above are valid for version 1 */ - int (*xShmMap) (sqlite3_file *, int iPg, int pgsz, int, - void volatile **); - int (*xShmLock) (sqlite3_file *, int offset, int n, int flags); - void (*xShmBarrier) (sqlite3_file *); - int (*xShmUnmap) (sqlite3_file *, int deleteFlag); - /* Methods above are valid for version 2 */ - int (*xFetch) (sqlite3_file *, sqlite3_int64 iOfst, int iAmt, - void **pp); - int (*xUnfetch) (sqlite3_file *, sqlite3_int64 iOfst, void *p); - /* Methods above are valid for version 3 */ - /* Additional methods may be added in future releases */ -}; - -/* - * CAPI3REF: Standard File Control Opcodes - * KEYWORDS: {file control opcodes} {file control opcode} - * - * These integer constants are opcodes for the xFileControl method - * of the [sqlite3_io_methods] object and for the [sqlite3_file_control()] - * interface. - * - *
    - *
  • [[SQLITE_FCNTL_LOCKSTATE]] - * The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This - * opcode causes the xFileControl method to write the current state of - * the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED], - * [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE]) - * into an integer that the pArg argument points to. This capability - * is used during testing and is only available when the SQLITE_TEST - * compile-time option is used. - * - *
  • [[SQLITE_FCNTL_SIZE_HINT]] - * The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS - * layer a hint of how large the database file will grow to be during the - * current transaction. This hint is not guaranteed to be accurate but it - * is often close. The underlying VFS might choose to preallocate database - * file space based on this hint in order to help writes to the database - * file run faster. - * - *
  • [[SQLITE_FCNTL_CHUNK_SIZE]] - * The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS - * extends and truncates the database file in chunks of a size specified - * by the user. The fourth argument to [sqlite3_file_control()] should - * point to an integer (type int) containing the new chunk-size to use - * for the nominated database. Allocating database file space in large - * chunks (say 1MB at a time), may reduce file-system fragmentation and - * improve performance on some systems. - * - *
  • [[SQLITE_FCNTL_FILE_POINTER]] - * The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer - * to the [sqlite3_file] object associated with a particular database - * connection. - * - *
  • [[SQLITE_FCNTL_SYNC_OMITTED]] - * No longer in use. - * - *
  • [[SQLITE_FCNTL_SYNC]] - * The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and - * sent to the VFS immediately before the xSync method is invoked on a - * database file descriptor. Or, if the xSync method is not invoked - * because the user has configured SQLite with - * [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place - * of the xSync method. In most cases, the pointer argument passed with - * this file-control is NULL. However, if the database file is being synced - * as part of a multi-database commit, the argument points to a nul-terminated - * string containing the transactions master-journal file name. VFSes that - * do not need this signal should silently ignore this opcode. Applications - * should not call [sqlite3_file_control()] with this opcode as doing so may - * disrupt the operation of the specialized VFSes that do require it. - * - *
  • [[SQLITE_FCNTL_COMMIT_PHASETWO]] - * The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite - * and sent to the VFS after a transaction has been committed immediately - * but before the database is unlocked. VFSes that do not need this signal - * should silently ignore this opcode. Applications should not call - * [sqlite3_file_control()] with this opcode as doing so may disrupt the - * operation of the specialized VFSes that do require it. - * - *
  • [[SQLITE_FCNTL_POWERSAFE_OVERWRITE]] - * ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the - * persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting - * determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the - * xDeviceCharacteristics methods. The fourth parameter to - * [sqlite3_file_control()] for this opcode should be a pointer to an integer. - * That integer is 0 to disable zero-damage mode or 1 to enable zero-damage - * mode. If the integer is -1, then it is overwritten with the current - * zero-damage mode setting. - * - *
  • [[SQLITE_FCNTL_OVERWRITE]] - * ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening - * a write transaction to indicate that, unless it is rolled back for some - * reason, the entire database file will be overwritten by the current - * transaction. - * - *
  • [[SQLITE_FCNTL_VFSNAME]] - * ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of - * all [VFSes] in the VFS stack. The names are of all VFS shims and the - * final bottom-level VFS are written into memory obtained from - * [sqlite3_malloc()] and the result is stored in the char* variable - * that the fourth parameter of [sqlite3_file_control()] points to. - * The caller is responsible for freeing the memory when done. As with - * all file-control actions, there is no guarantee that this will actually - * do anything. Callers should initialize the char* variable to a NULL - * pointer in case this file-control is not implemented. This file-control - * is intended for diagnostic use only. - * - *
  • [[SQLITE_FCNTL_VFS_POINTER]] - * ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level - * [VFSes] currently in use. ^(The argument X in - * sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be - * of type "[sqlite3_vfs] **". This opcodes will set *X - * to a pointer to the top-level VFS.)^ - * ^When there are multiple VFS shims in the stack, this opcode finds the - * upper-most shim only. - * - *
  • [[SQLITE_FCNTL_PRAGMA]] - * ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA] - * file control is sent to the open [sqlite3_file] object corresponding - * to the database file to which the pragma statement refers. ^The argument - * to the [SQLITE_FCNTL_PRAGMA] file control is an array of - * pointers to strings (char**) in which the second element of the array - * is the name of the pragma and the third element is the argument to the - * pragma or NULL if the pragma has no argument. ^The handler for an - * [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element - * of the char** argument point to a string obtained from [sqlite3_mprintf()] - * or the equivalent and that string will become the result of the pragma or - * the error message if the pragma fails. ^If the - * [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal - * [PRAGMA] processing continues. ^If the [SQLITE_FCNTL_PRAGMA] - * file control returns [SQLITE_OK], then the parser assumes that the - * VFS has handled the PRAGMA itself and the parser generates a no-op - * prepared statement if result string is NULL, or that returns a copy - * of the result string if the string is non-NULL. - * ^If the [SQLITE_FCNTL_PRAGMA] file control returns - * any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means - * that the VFS encountered an error while handling the [PRAGMA] and the - * compilation of the PRAGMA fails with an error. ^The [SQLITE_FCNTL_PRAGMA] - * file control occurs at the beginning of pragma statement analysis and so - * it is able to override built-in [PRAGMA] statements. - * - *
  • [[SQLITE_FCNTL_BUSYHANDLER]] - * ^The [SQLITE_FCNTL_BUSYHANDLER] - * file-control may be invoked by SQLite on the database file handle - * shortly after it is opened in order to provide a custom VFS with access - * to the connections busy-handler callback. The argument is of type (void **) - * - an array of two (void *) values. The first (void *) actually points - * to a function of type (int (*)(void *)). In order to invoke the connections - * busy-handler, this function should be invoked with the second (void *) in - * the array as the only argument. If it returns non-zero, then the operation - * should be retried. If it returns zero, the custom VFS should abandon the - * current operation. - * - *
  • [[SQLITE_FCNTL_TEMPFILENAME]] - * ^Application can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control - * to have SQLite generate a - * temporary filename using the same algorithm that is followed to generate - * temporary filenames for TEMP tables and other internal uses. The - * argument should be a char** which will be filled with the filename - * written into memory obtained from [sqlite3_malloc()]. The caller should - * invoke [sqlite3_free()] on the result to avoid a memory leak. - * - *
  • [[SQLITE_FCNTL_MMAP_SIZE]] - * The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the - * maximum number of bytes that will be used for memory-mapped I/O. - * The argument is a pointer to a value of type sqlite3_int64 that - * is an advisory maximum number of bytes in the file to memory map. The - * pointer is overwritten with the old value. The limit is not changed if - * the value originally pointed to is negative, and so the current limit - * can be queried by passing in a pointer to a negative number. This - * file-control is used internally to implement [PRAGMA mmap_size]. - * - *
  • [[SQLITE_FCNTL_TRACE]] - * The [SQLITE_FCNTL_TRACE] file control provides advisory information - * to the VFS about what the higher layers of the SQLite stack are doing. - * This file control is used by some VFS activity tracing [shims]. - * The argument is a zero-terminated string. Higher layers in the - * SQLite stack may generate instances of this file control if - * the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled. - * - *
  • [[SQLITE_FCNTL_HAS_MOVED]] - * The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a - * pointer to an integer and it writes a boolean into that integer depending - * on whether or not the file has been renamed, moved, or deleted since it - * was first opened. - * - *
  • [[SQLITE_FCNTL_ZIPVFS]] - * The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other - * VFS should return SQLITE_NOTFOUND for this opcode. - * - *
  • [[SQLITE_FCNTL_RBU]] - * The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by - * the RBU extension only. All other VFS should return SQLITE_NOTFOUND for - * this opcode. - *
-*/ -#define SQLITE_FCNTL_LOCKSTATE 1 -#define SQLITE_FCNTL_GET_LOCKPROXYFILE 2 -#define SQLITE_FCNTL_SET_LOCKPROXYFILE 3 -#define SQLITE_FCNTL_LAST_ERRNO 4 -#define SQLITE_FCNTL_SIZE_HINT 5 -#define SQLITE_FCNTL_CHUNK_SIZE 6 -#define SQLITE_FCNTL_FILE_POINTER 7 -#define SQLITE_FCNTL_SYNC_OMITTED 8 -#define SQLITE_FCNTL_OVERWRITE 10 -#define SQLITE_FCNTL_VFSNAME 11 -#define SQLITE_FCNTL_POWERSAFE_OVERWRITE 12 -#define SQLITE_FCNTL_PRAGMA 13 -#define SQLITE_FCNTL_BUSYHANDLER 14 -#define SQLITE_FCNTL_TEMPFILENAME 15 -#define SQLITE_FCNTL_MMAP_SIZE 16 -#define SQLITE_FCNTL_TRACE 17 -#define SQLITE_FCNTL_HAS_MOVED 18 -#define SQLITE_FCNTL_SYNC 19 -#define SQLITE_FCNTL_COMMIT_PHASETWO 20 -#define SQLITE_FCNTL_ZIPVFS 22 -#define SQLITE_FCNTL_RBU 23 -#define SQLITE_FCNTL_VFS_POINTER 24 -#define SQLITE_FCNTL_PDB 26 - -/* - * CAPI3REF: Mutex Handle - * - * The mutex module within SQLite defines [sqlite3_mutex] to be an - * abstract type for a mutex object. The SQLite core never looks - * at the internal representation of an [sqlite3_mutex]. It only - * deals with pointers to the [sqlite3_mutex] object. - * - * Mutexes are created using [sqlite3_mutex_alloc()]. -*/ -typedef struct sqlite3_mutex sqlite3_mutex; - -/* - * CAPI3REF: Loadable Extension Thunk - * - * A pointer to the opaque sqlite3_api_routines structure is passed as - * the third parameter to entry points of [loadable extensions]. This - * structure must be typedefed in order to work around compiler warnings - * on some platforms. -*/ -typedef struct sqlite3_api_routines sqlite3_api_routines; - -/* - * CAPI3REF: OS Interface Object - * - * An instance of the sqlite3_vfs object defines the interface between - * the SQLite core and the underlying operating system. The "vfs" - * in the name of the object stands for "virtual file system". See - * the [VFS | VFS documentation] for further information. - * - * The value of the iVersion field is initially 1 but may be larger in - * future versions of SQLite. Additional fields may be appended to this - * object when the iVersion value is increased. Note that the structure - * of the sqlite3_vfs object changes in the transaction between - * SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not - * modified. - * - * The szOsFile field is the size of the subclassed [sqlite3_file] - * structure used by this VFS. mxPathname is the maximum length of - * a pathname in this VFS. - * - * Registered sqlite3_vfs objects are kept on a linked list formed by - * the pNext pointer. The [sqlite3_vfs_register()] - * and [sqlite3_vfs_unregister()] interfaces manage this list - * in a thread-safe way. The [sqlite3_vfs_find()] interface - * searches the list. Neither the application code nor the VFS - * implementation should use the pNext pointer. - * - * The pNext field is the only field in the sqlite3_vfs - * structure that SQLite will ever modify. SQLite will only access - * or modify this field while holding a particular static mutex. - * The application should never modify anything within the sqlite3_vfs - * object once the object has been registered. - * - * The zName field holds the name of the VFS module. The name must - * be unique across all VFS modules. - * - * [[sqlite3_vfs.xOpen]] - * ^SQLite guarantees that the zFilename parameter to xOpen - * is either a NULL pointer or string obtained - * from xFullPathname() with an optional suffix added. - * ^If a suffix is added to the zFilename parameter, it will - * consist of a single "-" character followed by no more than - * 11 alphanumeric and/or "-" characters. - * ^SQLite further guarantees that - * the string will be valid and unchanged until xClose() is - * called. Because of the previous sentence, - * the [sqlite3_file] can safely store a pointer to the - * filename if it needs to remember the filename for some reason. - * If the zFilename parameter to xOpen is a NULL pointer then xOpen - * must invent its own temporary name for the file. ^Whenever the - * xFilename parameter is NULL it will also be the case that the - * flags parameter will include [SQLITE_OPEN_DELETEONCLOSE]. - * - * The flags argument to xOpen() includes all bits set in - * the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()] - * or is used, then flags includes at least - * [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. - * If xOpen() opens a file read-only then it sets *pOutFlags to - * include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set. - * - * ^(SQLite will also add one of the following flags to the xOpen() - * call, depending on the object being opened: - * - *
    - *
  • [SQLITE_OPEN_MAIN_DB] - *
  • [SQLITE_OPEN_TEMP_DB] - *
  • [SQLITE_OPEN_TRANSIENT_DB] - *
)^ - * - * The file I/O implementation can use the object type flags to - * change the way it deals with files. For example, an application - * that does not care about crash recovery or rollback might make - * the open of a journal file a no-op. Writes to this journal would - * also be no-ops, and any attempt to read the journal would return - * SQLITE_IOERR. Or the implementation might recognize that a database - * file will be doing page-aligned sector reads and writes in a random - * order and set up its I/O subsystem accordingly. - * - * SQLite might also add one of the following flags to the xOpen method: - * - *
    - *
  • [SQLITE_OPEN_DELETEONCLOSE] - *
  • [SQLITE_OPEN_EXCLUSIVE] - *
- * - * The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be - * deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE] - * will be set for TEMP databases and their journals, transient - * databases, and subjournals. - * - * ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction - * with the [SQLITE_OPEN_CREATE] flag, which are both directly - * analogous to the O_EXCL and O_CREAT flags of the POSIX open() - * API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the - * SQLITE_OPEN_CREATE, is used to indicate that file should always - * be created, and that it is an error if it already exists. - * It is not used to indicate the file should be opened - * for exclusive access. - * - * ^At least szOsFile bytes of memory are allocated by SQLite - * to hold the [sqlite3_file] structure passed as the third - * argument to xOpen. The xOpen method does not have to - * allocate the structure; it should just fill it in. Note that - * the xOpen method must set the sqlite3_file.pMethods to either - * a valid [sqlite3_io_methods] object or to NULL. xOpen must do - * this even if the open fails. SQLite expects that the sqlite3_file.pMethods - * element will be valid after xOpen returns regardless of the success - * or failure of the xOpen call. - * - * [[sqlite3_vfs.xAccess]] - * ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] - * to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to - * test whether a file is readable and writable, or [SQLITE_ACCESS_READ] - * to test whether a file is at least readable. The file can be a - * directory. - * - * ^SQLite will always allocate at least mxPathname+1 bytes for the - * output buffer xFullPathname. The exact size of the output buffer - * is also passed as a parameter to both methods. If the output buffer - * is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is - * handled as a fatal error by SQLite, vfs implementations should endeavor - * to prevent this by setting mxPathname to a sufficiently large value. - * - * The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64() - * interfaces are not strictly a part of the filesystem, but they are - * included in the VFS structure for completeness. - * The xRandomness() function attempts to return nBytes bytes - * of good-quality randomness into zOut. The return value is - * the actual number of bytes of randomness obtained. - * The xSleep() method causes the calling thread to sleep for at - * least the number of microseconds given. ^The xCurrentTime() - * method returns a Julian Day Number for the current date and time as - * a floating point value. - * ^The xCurrentTimeInt64() method returns, as an integer, the Julian - * Day Number multiplied by 86400000 (the number of milliseconds in - * a 24-hour day). - * ^SQLite will use the xCurrentTimeInt64() method to get the current - * date and time if that method is available (if iVersion is 2 or - * greater and the function pointer is not NULL) and will fall back - * to xCurrentTime() if xCurrentTimeInt64() is unavailable. - * - * ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces - * are not used by the SQLite core. These optional interfaces are provided - * by some VFSes to facilitate testing of the VFS code. By overriding - * system calls with functions under its control, a test program can - * simulate faults and error conditions that would otherwise be difficult - * or impossible to induce. The set of system calls that can be overridden - * varies from one VFS to another, and from one version of the same VFS to the - * next. Applications that use these interfaces must be prepared for any - * or all of these interfaces to be NULL or for their behavior to change - * from one release to the next. Applications must not attempt to access - * any of these methods if the iVersion of the VFS is less than 3. -*/ -typedef struct sqlite3_vfs sqlite3_vfs; -typedef void (*sqlite3_syscall_ptr) (void); -struct sqlite3_vfs { - int iVersion; /* Structure version number (currently 3) */ - int szOsFile; /* Size of subclassed sqlite3_file */ - int mxPathname; /* Maximum file pathname length */ - sqlite3_vfs *pNext; /* Next registered VFS */ - const char *zName; /* Name of this virtual file system */ - void *pAppData; /* Pointer to application-specific data */ - int (*xOpen) (sqlite3_vfs *, const char *zName, sqlite3_file *, - int flags, int *pOutFlags); - int (*xDelete) (sqlite3_vfs *, const char *zName, int syncDir); - int (*xAccess) (sqlite3_vfs *, const char *zName, int flags, - int *pResOut); - int (*xFullPathname) (sqlite3_vfs *, const char *zName, - int nOut, char *zOut); - void *(*xDlOpen) (sqlite3_vfs *, const char *zFilename); - void (*xDlError) (sqlite3_vfs *, int nByte, char *zErrMsg); - void (*(*xDlSym) (sqlite3_vfs *, void *, const char *zSymbol)) - (void); - void (*xDlClose) (sqlite3_vfs *, void *); - int (*xRandomness) (sqlite3_vfs *, int nByte, char *zOut); - int (*xSleep) (sqlite3_vfs *, int microseconds); - int (*xCurrentTime) (sqlite3_vfs *, double *); - int (*xGetLastError) (sqlite3_vfs *, int, char *); - /* - ** The methods above are in version 1 of the sqlite_vfs object - ** definition. Those that follow are added in version 2 or later - */ - int (*xCurrentTimeInt64) (sqlite3_vfs *, sqlite3_int64 *); - /* - ** The methods above are in versions 1 and 2 of the sqlite_vfs object. - ** Those below are for version 3 and greater. - */ - int (*xSetSystemCall) (sqlite3_vfs *, const char *zName, - sqlite3_syscall_ptr); - sqlite3_syscall_ptr(*xGetSystemCall) (sqlite3_vfs *, - const char *zName); - const char *(*xNextSystemCall) (sqlite3_vfs *, - const char *zName); - /* - ** The methods above are in versions 1 through 3 of the sqlite_vfs object. - ** New fields may be appended in future versions. The iVersion - ** value will increment whenever this happens. - */ -}; - -/* - * CAPI3REF: Flags for the xAccess VFS method - * - * These integer constants can be used as the third parameter to - * the xAccess method of an [sqlite3_vfs] object. They determine - * what kind of permissions the xAccess method is looking for. - * With SQLITE_ACCESS_EXISTS, the xAccess method - * simply checks whether the file exists. - * With SQLITE_ACCESS_READWRITE, the xAccess method - * checks whether the named directory is both readable and writable - * (in other words, if files can be added, removed, and renamed within - * the directory). - * The SQLITE_ACCESS_READWRITE constant is currently used only by the - * [temp_store_directory pragma], though this could change in a future - * release of SQLite. - * With SQLITE_ACCESS_READ, the xAccess method - * checks whether the file is readable. The SQLITE_ACCESS_READ constant is - * currently unused, though it might be used in a future release of - * SQLite. -*/ -#define SQLITE_ACCESS_EXISTS 0 -#define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */ -#define SQLITE_ACCESS_READ 2 /* Unused */ - -/* - * CAPI3REF: Flags for the xShmLock VFS method - * - * These integer constants define the various locking operations - * allowed by the xShmLock method of [sqlite3_io_methods]. The - * following are the only legal combinations of flags to the - * xShmLock method: - * - *
    - *
  • SQLITE_SHM_LOCK | SQLITE_SHM_SHARED - *
  • SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE - *
  • SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED - *
  • SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE - *
- * - * When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as - * was given on the corresponding lock. - * - * The xShmLock method can transition between unlocked and SHARED or - * between unlocked and EXCLUSIVE. It cannot transition between SHARED - * and EXCLUSIVE. -*/ -#define SQLITE_SHM_UNLOCK 1 -#define SQLITE_SHM_LOCK 2 -#define SQLITE_SHM_SHARED 4 -#define SQLITE_SHM_EXCLUSIVE 8 - -/* - * CAPI3REF: Maximum xShmLock index - * - * The xShmLock method on [sqlite3_io_methods] may use values - * between 0 and this upper bound as its "offset" argument. - * The SQLite core will never attempt to acquire or release a - * lock outside of this range -*/ -#define SQLITE_SHM_NLOCK 8 - -/* - * CAPI3REF: Initialize The SQLite Library - * - * ^The sqlite3_initialize() routine initializes the - * SQLite library. ^The sqlite3_shutdown() routine - * deallocates any resources that were allocated by sqlite3_initialize(). - * These routines are designed to aid in process initialization and - * shutdown on embedded systems. Workstation applications using - * SQLite normally do not need to invoke either of these routines. - * - * A call to sqlite3_initialize() is an "effective" call if it is - * the first time sqlite3_initialize() is invoked during the lifetime of - * the process, or if it is the first time sqlite3_initialize() is invoked - * following a call to sqlite3_shutdown(). ^(Only an effective call - * of sqlite3_initialize() does any initialization. All other calls - * are harmless no-ops.)^ - * - * A call to sqlite3_shutdown() is an "effective" call if it is the first - * call to sqlite3_shutdown() since the last sqlite3_initialize(). ^(Only - * an effective call to sqlite3_shutdown() does any deinitialization. - * All other valid calls to sqlite3_shutdown() are harmless no-ops.)^ - * - * The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown() - * is not. The sqlite3_shutdown() interface must only be called from a - * single thread. All open [database connections] must be closed and all - * other SQLite resources must be deallocated prior to invoking - * sqlite3_shutdown(). - * - * Among other things, ^sqlite3_initialize() will invoke - * sqlite3_os_init(). Similarly, ^sqlite3_shutdown() - * will invoke sqlite3_os_end(). - * - * ^The sqlite3_initialize() routine returns [SQLITE_OK] on success. - * ^If for some reason, sqlite3_initialize() is unable to initialize - * the library (perhaps it is unable to allocate a needed resource such - * as a mutex) it returns an [error code] other than [SQLITE_OK]. - * - * ^The sqlite3_initialize() routine is called internally by many other - * SQLite interfaces so that an application usually does not need to - * invoke sqlite3_initialize() directly. For example, [sqlite3_open()] - * calls sqlite3_initialize() so the SQLite library will be automatically - * initialized when [sqlite3_open()] is called if it has not be initialized - * already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT] - * compile-time option, then the automatic calls to sqlite3_initialize() - * are omitted and the application must call sqlite3_initialize() directly - * prior to using any other SQLite interface. For maximum portability, - * it is recommended that applications always invoke sqlite3_initialize() - * directly prior to using any other SQLite interface. Future releases - * of SQLite may require this. In other words, the behavior exhibited - * when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the - * default behavior in some future release of SQLite. - * - * The sqlite3_os_init() routine does operating-system specific - * initialization of the SQLite library. The sqlite3_os_end() - * routine undoes the effect of sqlite3_os_init(). Typical tasks - * performed by these routines include allocation or deallocation - * of static resources, initialization of global variables, - * setting up a default [sqlite3_vfs] module, or setting up - * a default configuration using [sqlite3_config()]. - * - * The application should never invoke either sqlite3_os_init() - * or sqlite3_os_end() directly. The application should only invoke - * sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init() - * interface is called automatically by sqlite3_initialize() and - * sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate - * implementations for sqlite3_os_init() and sqlite3_os_end() - * are built into SQLite when it is compiled for Unix or OS/2. -*/ -SQLITE_API int -sqlite3_initialize(void); - -SQLITE_API int -sqlite3_shutdown(void); - -SQLITE_API int -sqlite3_os_init(void); - -SQLITE_API int -sqlite3_os_end(void); - -/* - * CAPI3REF: Configuring The SQLite Library - * - * The sqlite3_config() interface is used to make global configuration - * changes to SQLite in order to tune SQLite to the specific needs of - * the application. The default configuration is recommended for most - * applications and so this routine is usually not necessary. It is - * provided to support rare applications with unusual needs. - * - * The sqlite3_config() interface is not threadsafe. The application - * must ensure that no other SQLite interfaces are invoked by other - * threads while sqlite3_config() is running. - * - * The sqlite3_config() interface - * may only be invoked prior to library initialization using - * [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()]. - * ^If sqlite3_config() is called after [sqlite3_initialize()] and before - * [sqlite3_shutdown()] then it will return SQLITE_MISUSE. - * Note, however, that ^sqlite3_config() can be called as part of the - * implementation of an application-defined [sqlite3_os_init()]. - * - * The first argument to sqlite3_config() is an integer - * [configuration option] that determines - * what property of SQLite is to be configured. Subsequent arguments - * vary depending on the [configuration option] - * in the first argument. - * - * ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK]. - * ^If the option is unknown or SQLite is unable to set the option - * then this routine returns a non-zero [error code]. -*/ -SQLITE_API int -sqlite3_config(int, ...); - -/* - * CAPI3REF: Configure database connections - * METHOD: sqlite3 - * - * The sqlite3_db_config() interface is used to make configuration - * changes to a [database connection]. The interface is similar to - * [sqlite3_config()] except that the changes apply to a single - * [database connection] (specified in the first argument). - * - * The second argument to sqlite3_db_config(D,V,...) is the - * [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code - * that indicates what aspect of the [database connection] is being configured. - * Subsequent arguments vary depending on the configuration verb. - * - * ^Calls to sqlite3_db_config() return SQLITE_OK if and only if - * the call is considered successful. -*/ -SQLITE_API int -sqlite3_db_config(sqlite3 *, int op, ...); - -/* - * CAPI3REF: Memory Allocation Routines - * - * An instance of this object defines the interface between SQLite - * and low-level memory allocation routines. - * - * This object is used in only one place in the SQLite interface. - * A pointer to an instance of this object is the argument to - * [sqlite3_config()] when the configuration option is - * [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC]. - * By creating an instance of this object - * and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC]) - * during configuration, an application can specify an alternative - * memory allocation subsystem for SQLite to use for all of its - * dynamic memory needs. - * - * Note that SQLite comes with several [built-in memory allocators] - * that are perfectly adequate for the overwhelming majority of applications - * and that this object is only useful to a tiny minority of applications - * with specialized memory allocation requirements. This object is - * also used during testing of SQLite in order to specify an alternative - * memory allocator that simulates memory out-of-memory conditions in - * order to verify that SQLite recovers gracefully from such - * conditions. - * - * The xMalloc, xRealloc, and xFree methods must work like the - * malloc(), realloc() and free() functions from the standard C library. - * ^SQLite guarantees that the second argument to - * xRealloc is always a value returned by a prior call to xRoundup. - * - * xSize should return the allocated size of a memory allocation - * previously obtained from xMalloc or xRealloc. The allocated size - * is always at least as big as the requested size but may be larger. - * - * The xRoundup method returns what would be the allocated size of - * a memory allocation given a particular requested size. Most memory - * allocators round up memory allocations at least to the next multiple - * of 8. Some allocators round up to a larger multiple or to a power of 2. - * Every memory allocation request coming in through [sqlite3_malloc()] - * or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0, - * that causes the corresponding memory allocation to fail. - * - * The xInit method initializes the memory allocator. For example, - * it might allocate any require mutexes or initialize internal data - * structures. The xShutdown method is invoked (indirectly) by - * [sqlite3_shutdown()] and should deallocate any resources acquired - * by xInit. The pAppData pointer is used as the only parameter to - * xInit and xShutdown. - * - * SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes - * the xInit method, so the xInit method need not be threadsafe. The - * xShutdown method is only called from [sqlite3_shutdown()] so it does - * not need to be threadsafe either. For all other methods, SQLite - * holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the - * [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which - * it is by default) and so the methods are automatically serialized. - * However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other - * methods must be threadsafe or else make their own arrangements for - * serialization. - * - * SQLite will never invoke xInit() more than once without an intervening - * call to xShutdown(). -*/ -typedef struct sqlite3_mem_methods sqlite3_mem_methods; -struct sqlite3_mem_methods { - void *(*xMalloc) (int); /* Memory allocation function */ - void (*xFree) (void *); /* Free a prior allocation */ - void *(*xRealloc) (void *, int); /* Resize an allocation */ - int (*xSize) (void *); /* Return the size of an allocation */ - int (*xRoundup) (int); /* Round up request size to allocation size */ - int (*xInit) (void *); /* Initialize the memory allocator */ - void (*xShutdown) (void *); /* Deinitialize the memory allocator */ - void *pAppData; /* Argument to xInit() and xShutdown() */ -}; - -/* - * CAPI3REF: Configuration Options - * KEYWORDS: {configuration option} - * - * These constants are the available integer configuration options that - * can be passed as the first argument to the [sqlite3_config()] interface. - * - * New configuration options may be added in future releases of SQLite. - * Existing configuration options might be discontinued. Applications - * should check the return code from [sqlite3_config()] to make sure that - * the call worked. The [sqlite3_config()] interface will return a - * non-zero [error code] if a discontinued or unsupported configuration option - * is invoked. - * - *
- * [[SQLITE_CONFIG_SINGLETHREAD]]
SQLITE_CONFIG_SINGLETHREAD
- *
There are no arguments to this option. ^This option sets the - * [threading mode] to Single-thread. In other words, it disables - * all mutexing and puts SQLite into a mode where it can only be used - * by a single thread. ^If SQLite is compiled with - * the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then - * it is not possible to change the [threading mode] from its default - * value of Single-thread and so [sqlite3_config()] will return - * [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD - * configuration option.
- * - * [[SQLITE_CONFIG_MULTITHREAD]]
SQLITE_CONFIG_MULTITHREAD
- *
There are no arguments to this option. ^This option sets the - * [threading mode] to Multi-thread. In other words, it disables - * mutexing on [database connection] and [prepared statement] objects. - * The application is responsible for serializing access to - * [database connections] and [prepared statements]. But other mutexes - * are enabled so that SQLite will be safe to use in a multi-threaded - * environment as long as no two threads attempt to use the same - * [database connection] at the same time. ^If SQLite is compiled with - * the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then - * it is not possible to set the Multi-thread [threading mode] and - * [sqlite3_config()] will return [SQLITE_ERROR] if called with the - * SQLITE_CONFIG_MULTITHREAD configuration option.
- * - * [[SQLITE_CONFIG_SERIALIZED]]
SQLITE_CONFIG_SERIALIZED
- *
There are no arguments to this option. ^This option sets the - * [threading mode] to Serialized. In other words, this option enables - * all mutexes including the recursive - * mutexes on [database connection] and [prepared statement] objects. - * In this mode (which is the default when SQLite is compiled with - * [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access - * to [database connections] and [prepared statements] so that the - * application is free to use the same [database connection] or the - * same [prepared statement] in different threads at the same time. - * ^If SQLite is compiled with - * the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then - * it is not possible to set the Serialized [threading mode] and - * [sqlite3_config()] will return [SQLITE_ERROR] if called with the - * SQLITE_CONFIG_SERIALIZED configuration option.
- * - * [[SQLITE_CONFIG_MALLOC]]
SQLITE_CONFIG_MALLOC
- *
^(The SQLITE_CONFIG_MALLOC option takes a single argument which is - * a pointer to an instance of the [sqlite3_mem_methods] structure. - * The argument specifies - * alternative low-level memory allocation routines to be used in place of - * the memory allocation routines built into SQLite.)^ ^SQLite makes - * its own private copy of the content of the [sqlite3_mem_methods] structure - * before the [sqlite3_config()] call returns.
- * - * [[SQLITE_CONFIG_GETMALLOC]]
SQLITE_CONFIG_GETMALLOC
- *
^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which - * is a pointer to an instance of the [sqlite3_mem_methods] structure. - * The [sqlite3_mem_methods] - * structure is filled with the currently defined memory allocation routines.)^ - * This option can be used to overload the default memory allocation - * routines with a wrapper that simulations memory allocation failure or - * tracks memory usage, for example.
- * - * [[SQLITE_CONFIG_MEMSTATUS]]
SQLITE_CONFIG_MEMSTATUS
- *
^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int, - * interpreted as a boolean, which enables or disables the collection of - * memory allocation statistics. ^(When memory allocation statistics are - * disabled, the following SQLite interfaces become non-operational: - *
    - *
  • [sqlite3_memory_used()] - *
  • [sqlite3_memory_highwater()] - *
  • [sqlite3_soft_heap_limit64()] - *
  • [sqlite3_status64()] - *
)^ - * ^Memory allocation statistics are enabled by default unless SQLite is - * compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory - * allocation statistics are disabled by default. - *
- * - * [[SQLITE_CONFIG_SCRATCH]]
SQLITE_CONFIG_SCRATCH
- *
^The SQLITE_CONFIG_SCRATCH option specifies a static memory buffer - * that SQLite can use for scratch memory. ^(There are three arguments - * to SQLITE_CONFIG_SCRATCH: A pointer an 8-byte - * aligned memory buffer from which the scratch allocations will be - * drawn, the size of each scratch allocation (sz), - * and the maximum number of scratch allocations (N).)^ - * The first argument must be a pointer to an 8-byte aligned buffer - * of at least sz*N bytes of memory. - * ^SQLite will not use more than one scratch buffers per thread. - * ^SQLite will never request a scratch buffer that is more than 6 - * times the database page size. - * ^If SQLite needs needs additional - * scratch memory beyond what is provided by this configuration option, then - * [sqlite3_malloc()] will be used to obtain the memory needed.

- * ^When the application provides any amount of scratch memory using - * SQLITE_CONFIG_SCRATCH, SQLite avoids unnecessary large - * [sqlite3_malloc|heap allocations]. - * This can help [Robson proof|prevent memory allocation failures] due to heap - * fragmentation in low-memory embedded systems. - *

- * - * [[SQLITE_CONFIG_PAGECACHE]]
SQLITE_CONFIG_PAGECACHE
- *
^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool - * that SQLite can use for the database page cache with the default page - * cache implementation. - * This configuration option is a no-op if an application-define page - * cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2]. - * ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to - * 8-byte aligned memory (pMem), the size of each page cache line (sz), - * and the number of cache lines (N). - * The sz argument should be the size of the largest database page - * (a power of two between 512 and 65536) plus some extra bytes for each - * page header. ^The number of extra bytes needed by the page header - * can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ]. - * ^It is harmless, apart from the wasted memory, - * for the sz parameter to be larger than necessary. The pMem - * argument must be either a NULL pointer or a pointer to an 8-byte - * aligned block of memory of at least sz*N bytes, otherwise - * subsequent behavior is undefined. - * ^When pMem is not NULL, SQLite will strive to use the memory provided - * to satisfy page cache needs, falling back to [sqlite3_malloc()] if - * a page cache line is larger than sz bytes or if all of the pMem buffer - * is exhausted. - * ^If pMem is NULL and N is non-zero, then each database connection - * does an initial bulk allocation for page cache memory - * from [sqlite3_malloc()] sufficient for N cache lines if N is positive or - * of -1024*N bytes if N is negative, . ^If additional - * page cache memory is needed beyond what is provided by the initial - * allocation, then SQLite goes to [sqlite3_malloc()] separately for each - * additional cache line.
- * - * [[SQLITE_CONFIG_HEAP]]
SQLITE_CONFIG_HEAP
- *
^The SQLITE_CONFIG_HEAP option specifies a static memory buffer - * that SQLite will use for all of its dynamic memory allocation needs - * beyond those provided for by [SQLITE_CONFIG_SCRATCH] and - * [SQLITE_CONFIG_PAGECACHE]. - * ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled - * with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns - * [SQLITE_ERROR] if invoked otherwise. - * ^There are three arguments to SQLITE_CONFIG_HEAP: - * An 8-byte aligned pointer to the memory, - * the number of bytes in the memory buffer, and the minimum allocation size. - * ^If the first pointer (the memory pointer) is NULL, then SQLite reverts - * to using its default memory allocator (the system malloc() implementation), - * undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the - * memory pointer is not NULL then the alternative memory - * allocator is engaged to handle all of SQLites memory allocation needs. - * The first pointer (the memory pointer) must be aligned to an 8-byte - * boundary or subsequent behavior of SQLite will be undefined. - * The minimum allocation size is capped at 2**12. Reasonable values - * for the minimum allocation size are 2**5 through 2**8.
- * - * [[SQLITE_CONFIG_MUTEX]]
SQLITE_CONFIG_MUTEX
- *
^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a - * pointer to an instance of the [sqlite3_mutex_methods] structure. - * The argument specifies alternative low-level mutex routines to be used - * in place the mutex routines built into SQLite.)^ ^SQLite makes a copy of - * the content of the [sqlite3_mutex_methods] structure before the call to - * [sqlite3_config()] returns. ^If SQLite is compiled with - * the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then - * the entire mutexing subsystem is omitted from the build and hence calls to - * [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will - * return [SQLITE_ERROR].
- * - * [[SQLITE_CONFIG_GETMUTEX]]
SQLITE_CONFIG_GETMUTEX
- *
^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which - * is a pointer to an instance of the [sqlite3_mutex_methods] structure. The - * [sqlite3_mutex_methods] - * structure is filled with the currently defined mutex routines.)^ - * This option can be used to overload the default mutex allocation - * routines with a wrapper used to track mutex usage for performance - * profiling or testing, for example. ^If SQLite is compiled with - * the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then - * the entire mutexing subsystem is omitted from the build and hence calls to - * [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will - * return [SQLITE_ERROR].
- * - * [[SQLITE_CONFIG_LOOKASIDE]]
SQLITE_CONFIG_LOOKASIDE
- *
^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine - * the default size of lookaside memory on each [database connection]. - * The first argument is the - * size of each lookaside buffer slot and the second is the number of - * slots allocated to each database connection.)^ ^(SQLITE_CONFIG_LOOKASIDE - * sets the default lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE] - * option to [sqlite3_db_config()] can be used to change the lookaside - * configuration on individual connections.)^
- * - * [[SQLITE_CONFIG_PCACHE2]]
SQLITE_CONFIG_PCACHE2
- *
^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is - * a pointer to an [sqlite3_pcache_methods2] object. This object specifies - * the interface to a custom page cache implementation.)^ - * ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.
- * - * [[SQLITE_CONFIG_GETPCACHE2]]
SQLITE_CONFIG_GETPCACHE2
- *
^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which - * is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of - * the current page cache implementation into that object.)^
- * - * [[SQLITE_CONFIG_LOG]]
SQLITE_CONFIG_LOG
- *
The SQLITE_CONFIG_LOG option is used to configure the SQLite - * global [error log]. - * (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a - * function with a call signature of void(*)(void*,int,const char*), - * and a pointer to void. ^If the function pointer is not NULL, it is - * invoked by [sqlite3_log()] to process each logging event. ^If the - * function pointer is NULL, the [sqlite3_log()] interface becomes a no-op. - * ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is - * passed through as the first parameter to the application-defined logger - * function whenever that function is invoked. ^The second parameter to - * the logger function is a copy of the first parameter to the corresponding - * [sqlite3_log()] call and is intended to be a [result code] or an - * [extended result code]. ^The third parameter passed to the logger is - * log message after formatting via [sqlite3_snprintf()]. - * The SQLite logging interface is not reentrant; the logger function - * supplied by the application must not invoke any SQLite interface. - * In a multi-threaded application, the application-defined logger - * function must be threadsafe.
- * - * [[SQLITE_CONFIG_URI]]
SQLITE_CONFIG_URI - *
^(The SQLITE_CONFIG_URI option takes a single argument of type int. - * If non-zero, then URI handling is globally enabled. If the parameter is zero, - * then URI handling is globally disabled.)^ ^If URI handling is globally - * enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()], - * [sqlite3_open16()] or - * specified as part of [ATTACH] commands are interpreted as URIs, regardless - * of whether or not the [SQLITE_OPEN_URI] flag is set when the database - * connection is opened. ^If it is globally disabled, filenames are - * only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the - * database connection is opened. ^(By default, URI handling is globally - * disabled. The default value may be changed by compiling with the - * [SQLITE_USE_URI] symbol defined.)^ - * - * [[SQLITE_CONFIG_COVERING_INDEX_SCAN]]
SQLITE_CONFIG_COVERING_INDEX_SCAN - *
^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer - * argument which is interpreted as a boolean in order to enable or disable - * the use of covering indices for full table scans in the query optimizer. - * ^The default setting is determined - * by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on" - * if that compile-time option is omitted. - * The ability to disable the use of covering indices for full table scans - * is because some incorrectly coded legacy applications might malfunction - * when the optimization is enabled. Providing the ability to - * disable the optimization allows the older, buggy application code to work - * without change even with newer versions of SQLite. - * - * [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]] - *
SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE - *
These options are obsolete and should not be used by new code. - * They are retained for backwards compatibility but are now no-ops. - *
- * - * [[SQLITE_CONFIG_SQLLOG]] - *
SQLITE_CONFIG_SQLLOG - *
This option is only available if sqlite is compiled with the - * [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should - * be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int). - * The second should be of type (void*). The callback is invoked by the library - * in three separate circumstances, identified by the value passed as the - * fourth parameter. If the fourth parameter is 0, then the database connection - * passed as the second argument has just been opened. The third argument - * points to a buffer containing the name of the main database file. If the - * fourth parameter is 1, then the SQL statement that the third parameter - * points to has just been executed. Or, if the fourth parameter is 2, then - * the connection being passed as the second parameter is being closed. The - * third parameter is passed NULL In this case. An example of using this - * configuration option can be seen in the "test_sqllog.c" source file in - * the canonical SQLite source tree.
- * - * [[SQLITE_CONFIG_MMAP_SIZE]] - *
SQLITE_CONFIG_MMAP_SIZE - *
^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values - * that are the default mmap size limit (the default setting for - * [PRAGMA mmap_size]) and the maximum allowed mmap size limit. - * ^The default setting can be overridden by each database connection using - * either the [PRAGMA mmap_size] command, or by using the - * [SQLITE_FCNTL_MMAP_SIZE] file control. ^(The maximum allowed mmap size - * will be silently truncated if necessary so that it does not exceed the - * compile-time maximum mmap size set by the - * [SQLITE_MAX_MMAP_SIZE] compile-time option.)^ - * ^If either argument to this option is negative, then that argument is - * changed to its compile-time default. - * - * [[SQLITE_CONFIG_PCACHE_HDRSZ]] - *
SQLITE_CONFIG_PCACHE_HDRSZ - *
^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which - * is a pointer to an integer and writes into that integer the number of extra - * bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE]. - * The amount of extra space required can change depending on the compiler, - * target platform, and SQLite version. - * - * [[SQLITE_CONFIG_PMASZ]] - *
SQLITE_CONFIG_PMASZ - *
^The SQLITE_CONFIG_PMASZ option takes a single parameter which - * is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded - * sorter to that integer. The default minimum PMA Size is set by the - * [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched - * to help with sort operations when multithreaded sorting - * is enabled (using the [PRAGMA threads] command) and the amount of content - * to be sorted exceeds the page size times the minimum of the - * [PRAGMA cache_size] setting and this value. - * - * [[SQLITE_CONFIG_STMTJRNL_SPILL]] - *
SQLITE_CONFIG_STMTJRNL_SPILL - *
^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which - * becomes the [statement journal] spill-to-disk threshold. - * [Statement journals] are held in memory until their size (in bytes) - * exceeds this threshold, at which point they are written to disk. - * Or if the threshold is -1, statement journals are always held - * exclusively in memory. - * Since many statement journals never become large, setting the spill - * threshold to a value such as 64KiB can greatly reduce the amount of - * I/O required to support statement rollback. - * The default value for this setting is controlled by the - * [SQLITE_STMTJRNL_SPILL] compile-time option. - *
-*/ -#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ -#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ -#define SQLITE_CONFIG_SERIALIZED 3 /* nil */ -#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ -#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ -#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ -#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ -#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ -#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ -#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ -#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ -/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ -#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ -#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */ -#define SQLITE_CONFIG_URI 17 /* int */ -#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */ -#define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */ -#define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */ -#define SQLITE_CONFIG_PMASZ 24 /* unsigned int szPma */ -#define SQLITE_CONFIG_STMTJRNL_SPILL 25 /* int nByte */ - -/* - * CAPI3REF: Database Connection Configuration Options - * - * These constants are the available integer configuration options that - * can be passed as the second argument to the [sqlite3_db_config()] interface. - * - * New configuration options may be added in future releases of SQLite. - * Existing configuration options might be discontinued. Applications - * should check the return code from [sqlite3_db_config()] to make sure that - * the call worked. ^The [sqlite3_db_config()] interface will return a - * non-zero [error code] if a discontinued or unsupported configuration option - * is invoked. - * - *
- *
SQLITE_DBCONFIG_LOOKASIDE
- *
^This option takes three additional arguments that determine the - * [lookaside memory allocator] configuration for the [database connection]. - * ^The first argument (the third parameter to [sqlite3_db_config()] is a - * pointer to a memory buffer to use for lookaside memory. - * ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb - * may be NULL in which case SQLite will allocate the - * lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the - * size of each lookaside buffer slot. ^The third argument is the number of - * slots. The size of the buffer in the first argument must be greater than - * or equal to the product of the second and third arguments. The buffer - * must be aligned to an 8-byte boundary. ^If the second argument to - * SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally - * rounded down to the next smaller multiple of 8. ^(The lookaside memory - * configuration for a database connection can only be changed when that - * connection is not currently using lookaside memory, or in other words - * when the "current value" returned by - * [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero. - * Any attempt to change the lookaside memory configuration when lookaside - * memory is in use leaves the configuration unchanged and returns - * [SQLITE_BUSY].)^
- * - *
SQLITE_DBCONFIG_ENABLE_FKEY
- *
^This option is used to enable or disable the enforcement of - * [foreign key constraints]. There should be two additional arguments. - * The first argument is an integer which is 0 to disable FK enforcement, - * positive to enable FK enforcement or negative to leave FK enforcement - * unchanged. The second parameter is a pointer to an integer into which - * is written 0 or 1 to indicate whether FK enforcement is off or on - * following this call. The second parameter may be a NULL pointer, in - * which case the FK enforcement setting is not reported back.
- * - *
SQLITE_DBCONFIG_ENABLE_TRIGGER
- *
^This option is used to enable or disable [CREATE TRIGGER | triggers]. - * There should be two additional arguments. - * The first argument is an integer which is 0 to disable triggers, - * positive to enable triggers or negative to leave the setting unchanged. - * The second parameter is a pointer to an integer into which - * is written 0 or 1 to indicate whether triggers are disabled or enabled - * following this call. The second parameter may be a NULL pointer, in - * which case the trigger setting is not reported back.
- * - *
SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
- *
^This option is used to enable or disable the two-argument - * version of the [fts3_tokenizer()] function which is part of the - * [FTS3] full-text search engine extension. - * There should be two additional arguments. - * The first argument is an integer which is 0 to disable fts3_tokenizer() or - * positive to enable fts3_tokenizer() or negative to leave the setting - * unchanged. - * The second parameter is a pointer to an integer into which - * is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled - * following this call. The second parameter may be a NULL pointer, in - * which case the new setting is not reported back.
- * - *
SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
- *
^This option is used to enable or disable the [sqlite3_load_extension()] - * interface independently of the [load_extension()] SQL function. - * The [sqlite3_enable_load_extension()] API enables or disables both the - * C-API [sqlite3_load_extension()] and the SQL function [load_extension()]. - * There should be two additional arguments. - * When the first argument to this interface is 1, then only the C-API is - * enabled and the SQL function remains disabled. If the first argument to - * this interface is 0, then both the C-API and the SQL function are disabled. - * If the first argument is -1, then no changes are made to state of either the - * C-API or the SQL function. - * The second parameter is a pointer to an integer into which - * is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface - * is disabled or enabled following this call. The second parameter may - * be a NULL pointer, in which case the new setting is not reported back. - *
- * - *
SQLITE_DBCONFIG_MAINDBNAME
- *
^This option is used to change the name of the "main" database - * schema. ^The sole argument is a pointer to a constant UTF8 string - * which will become the new schema name in place of "main". ^SQLite - * does not make a copy of the new main schema name string, so the application - * must ensure that the argument passed into this DBCONFIG option is unchanged - * until after the database connection closes. - *
- * - *
SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
- *
Usually, when a database in wal mode is closed or detached from a - * database handle, SQLite checks if this will mean that there are now no - * connections at all to the database. If so, it performs a checkpoint - * operation before closing the connection. This option may be used to - * override this behaviour. The first parameter passed to this operation - * is an integer - non-zero to disable checkpoints-on-close, or zero (the - * default) to enable them. The second parameter is a pointer to an integer - * into which is written 0 or 1 to indicate whether checkpoints-on-close - * have been disabled - 0 if they are not disabled, 1 if they are. - *
- * - *
-*/ -#define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ -#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ -#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ -#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */ -#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */ -#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ -#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */ - -/* - * CAPI3REF: Enable Or Disable Extended Result Codes - * METHOD: sqlite3 - * - * ^The sqlite3_extended_result_codes() routine enables or disables the - * [extended result codes] feature of SQLite. ^The extended result - * codes are disabled by default for historical compatibility. -*/ -SQLITE_API int -sqlite3_extended_result_codes(sqlite3 *, int onoff); - -/* - * CAPI3REF: Count The Number Of Rows Modified - * METHOD: sqlite3 - * - * ^This function returns the number of rows modified, inserted or - * deleted by the most recently completed INSERT, UPDATE or DELETE - * statement on the database connection specified by the only parameter. - * ^Executing any other type of SQL statement does not modify the value - * returned by this function. - * - * ^Only changes made directly by the INSERT, UPDATE or DELETE statement are - * considered - auxiliary changes caused by [CREATE TRIGGER | triggers], - * [foreign key actions] or [REPLACE] constraint resolution are not counted. - * - * Changes to a view that are intercepted by - * [INSTEAD OF trigger | INSTEAD OF triggers] are not counted. ^The value - * returned by sqlite3_changes() immediately after an INSERT, UPDATE or - * DELETE statement run on a view is always zero. Only changes made to real - * tables are counted. - * - * Things are more complicated if the sqlite3_changes() function is - * executed while a trigger program is running. This may happen if the - * program uses the [changes() SQL function], or if some other callback - * function invokes sqlite3_changes() directly. Essentially: - * - *
    - *
  • ^(Before entering a trigger program the value returned by - * sqlite3_changes() function is saved. After the trigger program - * has finished, the original value is restored.)^ - * - *
  • ^(Within a trigger program each INSERT, UPDATE and DELETE - * statement sets the value returned by sqlite3_changes() - * upon completion as normal. Of course, this value will not include - * any changes performed by sub-triggers, as the sqlite3_changes() - * value will be saved and restored after each sub-trigger has run.)^ - *
- * - * ^This means that if the changes() SQL function (or similar) is used - * by the first INSERT, UPDATE or DELETE statement within a trigger, it - * returns the value as set when the calling statement began executing. - * ^If it is used by the second or subsequent such statement within a trigger - * program, the value returned reflects the number of rows modified by the - * previous INSERT, UPDATE or DELETE statement within the same trigger. - * - * See also the [sqlite3_total_changes()] interface, the - * [count_changes pragma], and the [changes() SQL function]. - * - * If a separate thread makes changes on the same database connection - * while [sqlite3_changes()] is running then the value returned - * is unpredictable and not meaningful. -*/ -SQLITE_API int -sqlite3_changes(sqlite3 *); - -/* - * CAPI3REF: Total Number Of Rows Modified - * METHOD: sqlite3 - * - * ^This function returns the total number of rows inserted, modified or - * deleted by all [INSERT], [UPDATE] or [DELETE] statements completed - * since the database connection was opened, including those executed as - * part of trigger programs. ^Executing any other type of SQL statement - * does not affect the value returned by sqlite3_total_changes(). - * - * ^Changes made as part of [foreign key actions] are included in the - * count, but those made as part of REPLACE constraint resolution are - * not. ^Changes to a view that are intercepted by INSTEAD OF triggers - * are not counted. - * - * See also the [sqlite3_changes()] interface, the - * [count_changes pragma], and the [total_changes() SQL function]. - * - * If a separate thread makes changes on the same database connection - * while [sqlite3_total_changes()] is running then the value - * returned is unpredictable and not meaningful. -*/ -SQLITE_API int -sqlite3_total_changes(sqlite3 *); - -/* - * CAPI3REF: Interrupt A Long-Running Query - * METHOD: sqlite3 - * - * ^This function causes any pending database operation to abort and - * return at its earliest opportunity. This routine is typically - * called in response to a user action such as pressing "Cancel" - * or Ctrl-C where the user wants a long query operation to halt - * immediately. - * - * ^It is safe to call this routine from a thread different from the - * thread that is currently running the database operation. But it - * is not safe to call this routine with a [database connection] that - * is closed or might close before sqlite3_interrupt() returns. - * - * ^If an SQL operation is very nearly finished at the time when - * sqlite3_interrupt() is called, then it might not have an opportunity - * to be interrupted and might continue to completion. - * - * ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT]. - * ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE - * that is inside an explicit transaction, then the entire transaction - * will be rolled back automatically. - * - * ^The sqlite3_interrupt(D) call is in effect until all currently running - * SQL statements on [database connection] D complete. ^Any new SQL statements - * that are started after the sqlite3_interrupt() call and before the - * running statements reaches zero are interrupted as if they had been - * running prior to the sqlite3_interrupt() call. ^New SQL statements - * that are started after the running statement count reaches zero are - * not effected by the sqlite3_interrupt(). - * ^A call to sqlite3_interrupt(D) that occurs when there are no running - * SQL statements is a no-op and has no effect on SQL statements - * that are started after the sqlite3_interrupt() call returns. - * - * If the database connection closes while [sqlite3_interrupt()] - * is running then bad things will likely happen. -*/ -SQLITE_API void -sqlite3_interrupt(sqlite3 *); - -/* - * CAPI3REF: Determine If An SQL Statement Is Complete - * - * These routines are useful during command-line input to determine if the - * currently entered text seems to form a complete SQL statement or - * if additional input is needed before sending the text into - * SQLite for parsing. ^These routines return 1 if the input string - * appears to be a complete SQL statement. ^A statement is judged to be - * complete if it ends with a semicolon token and is not a prefix of a - * well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within - * string literals or quoted identifier names or comments are not - * independent tokens (they are part of the token in which they are - * embedded) and thus do not count as a statement terminator. ^Whitespace - * and comments that follow the final semicolon are ignored. - * - * ^These routines return 0 if the statement is incomplete. ^If a - * memory allocation fails, then SQLITE_NOMEM is returned. - * - * ^These routines do not parse the SQL statements thus - * will not detect syntactically incorrect SQL. - * - * ^(If SQLite has not been initialized using [sqlite3_initialize()] prior - * to invoking sqlite3_complete16() then sqlite3_initialize() is invoked - * automatically by sqlite3_complete16(). If that initialization fails, - * then the return value from sqlite3_complete16() will be non-zero - * regardless of whether or not the input SQL is complete.)^ - * - * The input to [sqlite3_complete()] must be a zero-terminated - * UTF-8 string. - * - * The input to [sqlite3_complete16()] must be a zero-terminated - * UTF-16 string in native byte order. -*/ -SQLITE_API int -sqlite3_complete(const char *sql); - -/* - * CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors - * KEYWORDS: {busy-handler callback} {busy handler} - * METHOD: sqlite3 - * - * ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X - * that might be invoked with argument P whenever - * an attempt is made to access a database table associated with - * [database connection] D when another thread - * or process has the table locked. - * The sqlite3_busy_handler() interface is used to implement - * [sqlite3_busy_timeout()] and [PRAGMA busy_timeout]. - * - * ^If the busy callback is NULL, then [SQLITE_BUSY] - * is returned immediately upon encountering the lock. ^If the busy callback - * is not NULL, then the callback might be invoked with two arguments. - * - * ^The first argument to the busy handler is a copy of the void* pointer which - * is the third argument to sqlite3_busy_handler(). ^The second argument to - * the busy handler callback is the number of times that the busy handler has - * been invoked previously for the same locking event. ^If the - * busy callback returns 0, then no additional attempts are made to - * access the database and [SQLITE_BUSY] is returned - * to the application. - * ^If the callback returns non-zero, then another attempt - * is made to access the database and the cycle repeats. - * - * The presence of a busy handler does not guarantee that it will be invoked - * when there is lock contention. ^If SQLite determines that invoking the busy - * handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY] - * to the application instead of invoking the - * busy handler. - * Consider a scenario where one process is holding a read lock that - * it is trying to promote to a reserved lock and - * a second process is holding a reserved lock that it is trying - * to promote to an exclusive lock. The first process cannot proceed - * because it is blocked by the second and the second process cannot - * proceed because it is blocked by the first. If both processes - * invoke the busy handlers, neither will make any progress. Therefore, - * SQLite returns [SQLITE_BUSY] for the first process, hoping that this - * will induce the first process to release its read lock and allow - * the second process to proceed. - * - * ^The default busy callback is NULL. - * - * ^(There can only be a single busy handler defined for each - * [database connection]. Setting a new busy handler clears any - * previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()] - * or evaluating [PRAGMA busy_timeout=N] will change the - * busy handler and thus clear any previously set busy handler. - * - * The busy callback should not take any actions which modify the - * database connection that invoked the busy handler. In other words, - * the busy handler is not reentrant. Any such actions - * result in undefined behavior. - * - * A busy handler must not close the database connection - * or [prepared statement] that invoked the busy handler. -*/ -SQLITE_API int -sqlite3_busy_handler(sqlite3 *, int (*)(void *, int), - void *); - -/* - * CAPI3REF: Set A Busy Timeout - * METHOD: sqlite3 - * - * ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps - * for a specified amount of time when a table is locked. ^The handler - * will sleep multiple times until at least "ms" milliseconds of sleeping - * have accumulated. ^After at least "ms" milliseconds of sleeping, - * the handler returns 0 which causes [sqlite3_step()] to return - * [SQLITE_BUSY]. - * - * ^Calling this routine with an argument less than or equal to zero - * turns off all busy handlers. - * - * ^(There can only be a single busy handler for a particular - * [database connection] at any given moment. If another busy handler - * was defined (using [sqlite3_busy_handler()]) prior to calling - * this routine, that other busy handler is cleared.)^ - * - * See also: [PRAGMA busy_timeout] -*/ -SQLITE_API int -sqlite3_busy_timeout(sqlite3 *, int ms); - -/* - * CAPI3REF: Convenience Routines For Running Queries - * METHOD: sqlite3 - * - * This is a legacy interface that is preserved for backwards compatibility. - * Use of this interface is not recommended. - * - * Definition: A result table is memory data structure created by the - * [sqlite3_get_table()] interface. A result table records the - * complete query results from one or more queries. - * - * The table conceptually has a number of rows and columns. But - * these numbers are not part of the result table itself. These - * numbers are obtained separately. Let N be the number of rows - * and M be the number of columns. - * - * A result table is an array of pointers to zero-terminated UTF-8 strings. - * There are (N+1)*M elements in the array. The first M pointers point - * to zero-terminated strings that contain the names of the columns. - * The remaining entries all point to query results. NULL values result - * in NULL pointers. All other values are in their UTF-8 zero-terminated - * string representation as returned by [sqlite3_column_text()]. - * - * A result table might consist of one or more memory allocations. - * It is not safe to pass a result table directly to [sqlite3_free()]. - * A result table should be deallocated using [sqlite3_free_table()]. - * - * ^(As an example of the result table format, suppose a query result - * is as follows: - * - * 
- *        Name        | Age
- *        -----------------------
- *        Alice       | 43
- *        Bob         | 28
- *        Cindy       | 21
- *
- * - * There are two column (M==2) and three rows (N==3). Thus the - * result table has 8 entries. Suppose the result table is stored - * in an array names azResult. Then azResult holds this content: - * - * 
- *        azResult[0] = "Name";
- *        azResult[1] = "Age";
- *        azResult[2] = "Alice";
- *        azResult[3] = "43";
- *        azResult[4] = "Bob";
- *        azResult[5] = "28";
- *        azResult[6] = "Cindy";
- *        azResult[7] = "21";
- *
)^ - * - * ^The sqlite3_get_table() function evaluates one or more - * semicolon-separated SQL statements in the zero-terminated UTF-8 - * string of its 2nd parameter and returns a result table to the - * pointer given in its 3rd parameter. - * - * After the application has finished with the result from sqlite3_get_table(), - * it must pass the result table pointer to sqlite3_free_table() in order to - * release the memory that was malloced. Because of the way the - * [sqlite3_malloc()] happens within sqlite3_get_table(), the calling - * function must not try to call [sqlite3_free()] directly. Only - * [sqlite3_free_table()] is able to release the memory properly and safely. - * - * The sqlite3_get_table() interface is implemented as a wrapper around - * [sqlite3_exec()]. The sqlite3_get_table() routine does not have access - * to any internal data structures of SQLite. It uses only the public - * interface defined here. As a consequence, errors that occur in the - * wrapper layer outside of the internal [sqlite3_exec()] call are not - * reflected in subsequent calls to [sqlite3_errcode()] or - * [sqlite3_errmsg()]. -*/ -SQLITE_API int -sqlite3_get_table(sqlite3 * db, /* An open database */ - const char *zSql, /* SQL to be evaluated */ - char ***pazResult, /* Results of the query */ - int *pnRow, /* Number of result rows written here */ - int *pnColumn, /* Number of result columns written here */ - char **pzErrmsg /* Error msg written here */ - ); - -SQLITE_API void -sqlite3_free_table(char **result); - -/* - * CAPI3REF: Formatted String Printing Functions - * - * These routines are work-alikes of the "printf()" family of functions - * from the standard C library. - * These routines understand most of the common K&R formatting options, - * plus some additional non-standard formats, detailed below. - * Note that some of the more obscure formatting options from recent - * C-library standards are omitted from this implementation. - * - * ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their - * results into memory obtained from [sqlite3_malloc()]. - * The strings returned by these two routines should be - * released by [sqlite3_free()]. ^Both routines return a - * NULL pointer if [sqlite3_malloc()] is unable to allocate enough - * memory to hold the resulting string. - * - * ^(The sqlite3_snprintf() routine is similar to "snprintf()" from - * the standard C library. The result is written into the - * buffer supplied as the second parameter whose size is given by - * the first parameter. Note that the order of the - * first two parameters is reversed from snprintf().)^ This is an - * historical accident that cannot be fixed without breaking - * backwards compatibility. ^(Note also that sqlite3_snprintf() - * returns a pointer to its buffer instead of the number of - * characters actually written into the buffer.)^ We admit that - * the number of characters written would be a more useful return - * value but we cannot change the implementation of sqlite3_snprintf() - * now without breaking compatibility. - * - * ^As long as the buffer size is greater than zero, sqlite3_snprintf() - * guarantees that the buffer is always zero-terminated. ^The first - * parameter "n" is the total size of the buffer, including space for - * the zero terminator. So the longest string that can be completely - * written will be n-1 characters. - * - * ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf(). - * - * These routines all implement some additional formatting - * options that are useful for constructing SQL statements. - * All of the usual printf() formatting options apply. In addition, there - * is are "%q", "%Q", "%w" and "%z" options. - * - * ^(The %q option works like %s in that it substitutes a nul-terminated - * string from the argument list. But %q also doubles every '\'' character. - * %q is designed for use inside a string literal.)^ By doubling each '\'' - * character it escapes that character and allows it to be inserted into - * the string. - * - * For example, assume the string variable zText contains text as follows: - * - * 
- *  char *zText = "It's a happy day!";
- *
- * - * One can use this text in an SQL statement as follows: - * - * 
- *  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
- *  sqlite3_exec(db, zSQL, 0, 0, 0);
- *  sqlite3_free(zSQL);
- *
- * - * Because the %q format string is used, the '\'' character in zText - * is escaped and the SQL generated is as follows: - * - * 
- *  INSERT INTO table1 VALUES('It''s a happy day!')
- *
- * - * This is correct. Had we used %s instead of %q, the generated SQL - * would have looked like this: - * - * 
- *  INSERT INTO table1 VALUES('It's a happy day!');
- *
- * - * This second example is an SQL syntax error. As a general rule you should - * always use %q instead of %s when inserting text into a string literal. - * - * ^(The %Q option works like %q except it also adds single quotes around - * the outside of the total string. Additionally, if the parameter in the - * argument list is a NULL pointer, %Q substitutes the text "NULL" (without - * single quotes).)^ So, for example, one could say: - * - * 
- *  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
- *  sqlite3_exec(db, zSQL, 0, 0, 0);
- *  sqlite3_free(zSQL);
- *
- * - * The code above will render a correct SQL statement in the zSQL - * variable even if the zText variable is a NULL pointer. - * - * ^(The "%w" formatting option is like "%q" except that it expects to - * be contained within double-quotes instead of single quotes, and it - * escapes the double-quote character instead of the single-quote - * character.)^ The "%w" formatting option is intended for safely inserting - * table and column names into a constructed SQL statement. - * - * ^(The "%z" formatting option works like "%s" but with the - * addition that after the string has been read and copied into - * the result, [sqlite3_free()] is called on the input string.)^ -*/ -SQLITE_API char * -sqlite3_mprintf(const char *, ...); -SQLITE_API char * -sqlite3_vmprintf(const char *, va_list); -SQLITE_API char * -sqlite3_snprintf(int, char *, const char *, ...); -SQLITE_API char * -sqlite3_vsnprintf(int, char *, const char *, va_list); - -/* - * CAPI3REF: Memory Allocation Subsystem - * - * The SQLite core uses these three routines for all of its own - * internal memory allocation needs. "Core" in the previous sentence - * does not include operating-system specific VFS implementation. - * - * ^The sqlite3_malloc() routine returns a pointer to a block - * of memory at least N bytes in length, where N is the parameter. - * ^If sqlite3_malloc() is unable to obtain sufficient free - * memory, it returns a NULL pointer. ^If the parameter N to - * sqlite3_malloc() is zero or negative then sqlite3_malloc() returns - * a NULL pointer. - * - * ^The sqlite3_malloc64(N) routine works just like - * sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead - * of a signed 32-bit integer. - * - * ^Calling sqlite3_free() with a pointer previously returned - * by sqlite3_malloc() or sqlite3_realloc() releases that memory so - * that it might be reused. ^The sqlite3_free() routine is - * a no-op if is called with a NULL pointer. Passing a NULL pointer - * to sqlite3_free() is harmless. After being freed, memory - * should neither be read nor written. Even reading previously freed - * memory might result in a segmentation fault or other severe error. - * Memory corruption, a segmentation fault, or other severe error - * might result if sqlite3_free() is called with a non-NULL pointer that - * was not obtained from sqlite3_malloc() or sqlite3_realloc(). - * - * ^The sqlite3_realloc(X,N) interface attempts to resize a - * prior memory allocation X to be at least N bytes. - * ^If the X parameter to sqlite3_realloc(X,N) - * is a NULL pointer then its behavior is identical to calling - * sqlite3_malloc(N). - * ^If the N parameter to sqlite3_realloc(X,N) is zero or - * negative then the behavior is exactly the same as calling - * sqlite3_free(X). - * ^sqlite3_realloc(X,N) returns a pointer to a memory allocation - * of at least N bytes in size or NULL if insufficient memory is available. - * ^If M is the size of the prior allocation, then min(N,M) bytes - * of the prior allocation are copied into the beginning of buffer returned - * by sqlite3_realloc(X,N) and the prior allocation is freed. - * ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the - * prior allocation is not freed. - * - * ^The sqlite3_realloc64(X,N) interfaces works the same as - * sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead - * of a 32-bit signed integer. - * - * ^If X is a memory allocation previously obtained from sqlite3_malloc(), - * sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then - * sqlite3_msize(X) returns the size of that memory allocation in bytes. - * ^The value returned by sqlite3_msize(X) might be larger than the number - * of bytes requested when X was allocated. ^If X is a NULL pointer then - * sqlite3_msize(X) returns zero. If X points to something that is not - * the beginning of memory allocation, or if it points to a formerly - * valid memory allocation that has now been freed, then the behavior - * of sqlite3_msize(X) is undefined and possibly harmful. - * - * ^The memory returned by sqlite3_malloc(), sqlite3_realloc(), - * sqlite3_malloc64(), and sqlite3_realloc64() - * is always aligned to at least an 8 byte boundary, or to a - * 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time - * option is used. - * - * In SQLite version 3.5.0 and 3.5.1, it was possible to define - * the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in - * implementation of these routines to be omitted. That capability - * is no longer provided. Only built-in memory allocators can be used. - * - * The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] - * must be either NULL or else pointers obtained from a prior - * invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have - * not yet been released. - * - * The application must not read or write any part of - * a block of memory after it has been released using - * [sqlite3_free()] or [sqlite3_realloc()]. -*/ -SQLITE_API void * -sqlite3_malloc(int); - -SQLITE_API void * - -sqlite3_malloc64(sqlite3_uint64); - -SQLITE_API void * -sqlite3_realloc(void *, int); - -SQLITE_API void * -sqlite3_realloc64(void *, sqlite3_uint64); - -SQLITE_API void -sqlite3_free(void *); - -SQLITE_API sqlite3_uint64 -sqlite3_msize(void *); - -/* - * CAPI3REF: Memory Allocator Statistics - * - * SQLite provides these two interfaces for reporting on the status - * of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] - * routines, which form the built-in memory allocation subsystem. - * - * ^The [sqlite3_memory_used()] routine returns the number of bytes - * of memory currently outstanding (malloced but not freed). - * ^The [sqlite3_memory_highwater()] routine returns the maximum - * value of [sqlite3_memory_used()] since the high-water mark - * was last reset. ^The values returned by [sqlite3_memory_used()] and - * [sqlite3_memory_highwater()] include any overhead - * added by SQLite in its implementation of [sqlite3_malloc()], - * but not overhead added by the any underlying system library - * routines that [sqlite3_malloc()] may call. - * - * ^The memory high-water mark is reset to the current value of - * [sqlite3_memory_used()] if and only if the parameter to - * [sqlite3_memory_highwater()] is true. ^The value returned - * by [sqlite3_memory_highwater(1)] is the high-water mark - * prior to the reset. -*/ -SQLITE_API sqlite3_int64 -sqlite3_memory_used(void); - -SQLITE_API sqlite3_int64 -sqlite3_memory_highwater(int resetFlag); - -/* - * CAPI3REF: Pseudo-Random Number Generator - * - * SQLite contains a high-quality pseudo-random number generator (PRNG). - * The PRNG is used for the build-in random() and randomblob() SQL functions. - * This interface allows applications to access the same PRNG for other purposes. - * - * ^A call to this routine stores N bytes of randomness into buffer P. - * ^The P parameter can be a NULL pointer. - * - * ^If this routine has not been previously called or if the previous - * call had N less than one or a NULL pointer for P, then the PRNG is - * seeded using randomness obtained from the xRandomness method of - * the default [sqlite3_vfs] object. - * ^If the previous call to this routine had an N of 1 or more and a - * non-NULL P then the pseudo-randomness is generated - * internally and without recourse to the [sqlite3_vfs] xRandomness - * method. -*/ -SQLITE_API void -sqlite3_randomness(int N, void *P); - - -/* - * CAPI3REF: SQL Trace Event Codes - * KEYWORDS: SQLITE_TRACE - * - * These constants identify classes of events that can be monitored - * using the [sqlite3_trace_v2()] tracing logic. The third argument - * to [sqlite3_trace_v2()] is an OR-ed combination of one or more of - * the following constants. ^The first argument to the trace callback - * is one of the following constants. - * - * New tracing constants may be added in future releases. - * - * ^A trace callback has four arguments: xCallback(T,C,P,X). - * ^The T argument is one of the integer type codes above. - * ^The C argument is a copy of the context pointer passed in as the - * fourth argument to [sqlite3_trace_v2()]. - * The P and X arguments are pointers whose meanings depend on T. - * - *
- * [[SQLITE_TRACE_STMT]]
SQLITE_TRACE_STMT
- *
^An SQLITE_TRACE_STMT callback is invoked when a prepared statement - * first begins running and possibly at other times during the - * execution of the prepared statement, such as at the start of each - * trigger subprogram. ^The P argument is a pointer to the - * [prepared statement]. ^The X argument is a pointer to a string which - * is the unexpanded SQL text of the prepared statement or an SQL comment - * that indicates the invocation of a trigger. ^The callback can compute - * the same text that would have been returned by the legacy [sqlite3_trace()] - * interface by using the X argument when X begins with "--" and invoking - * [sqlite3_expanded_sql(P)] otherwise. - * - * [[SQLITE_TRACE_PROFILE]]
SQLITE_TRACE_PROFILE
- *
^An SQLITE_TRACE_PROFILE callback provides approximately the same - * information as is provided by the [sqlite3_profile()] callback. - * ^The P argument is a pointer to the [prepared statement] and the - * X argument points to a 64-bit integer which is the estimated of - * the number of nanosecond that the prepared statement took to run. - * ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes. - * - * [[SQLITE_TRACE_ROW]]
SQLITE_TRACE_ROW
- *
^An SQLITE_TRACE_ROW callback is invoked whenever a prepared - * statement generates a single row of result. - * ^The P argument is a pointer to the [prepared statement] and the - * X argument is unused. - * - * [[SQLITE_TRACE_CLOSE]]
SQLITE_TRACE_CLOSE
- *
^An SQLITE_TRACE_CLOSE callback is invoked when a database - * connection closes. - * ^The P argument is a pointer to the [database connection] object - * and the X argument is unused. - *
-*/ -#define SQLITE_TRACE_STMT 0x01 -#define SQLITE_TRACE_PROFILE 0x02 -#define SQLITE_TRACE_ROW 0x04 -#define SQLITE_TRACE_CLOSE 0x08 - -/* - * CAPI3REF: SQL Trace Hook - * METHOD: sqlite3 - * - * ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback - * function X against [database connection] D, using property mask M - * and context pointer P. ^If the X callback is - * NULL or if the M mask is zero, then tracing is disabled. The - * M argument should be the bitwise OR-ed combination of - * zero or more [SQLITE_TRACE] constants. - * - * ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides - * (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2(). - * - * ^The X callback is invoked whenever any of the events identified by - * mask M occur. ^The integer return value from the callback is currently - * ignored, though this may change in future releases. Callback - * implementations should return zero to ensure future compatibility. - * - * ^A trace callback is invoked with four arguments: callback(T,C,P,X). - * ^The T argument is one of the [SQLITE_TRACE] - * constants to indicate why the callback was invoked. - * ^The C argument is a copy of the context pointer. - * The P and X arguments are pointers whose meanings depend on T. - * - * The sqlite3_trace_v2() interface is intended to replace the legacy - * interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which - * are deprecated. -*/ -SQLITE_API int -sqlite3_trace_v2(sqlite3 *, - unsigned uMask, - int (*xCallback) (unsigned, void *, - void *, void *), - void *pCtx); - -/* - * CAPI3REF: Query Progress Callbacks - * METHOD: sqlite3 - * - * ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback - * function X to be invoked periodically during long running calls to - * [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for - * database connection D. An example use for this - * interface is to keep a GUI updated during a large query. - * - * ^The parameter P is passed through as the only parameter to the - * callback function X. ^The parameter N is the approximate number of - * [virtual machine instructions] that are evaluated between successive - * invocations of the callback X. ^If N is less than one then the progress - * handler is disabled. - * - * ^Only a single progress handler may be defined at one time per - * [database connection]; setting a new progress handler cancels the - * old one. ^Setting parameter X to NULL disables the progress handler. - * ^The progress handler is also disabled by setting N to a value less - * than 1. - * - * ^If the progress callback returns non-zero, the operation is - * interrupted. This feature can be used to implement a - * "Cancel" button on a GUI progress dialog box. - * - * The progress handler callback must not do anything that will modify - * the database connection that invoked the progress handler. - * Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their - * database connections for the meaning of "modify" in this paragraph. - * -*/ -SQLITE_API void -sqlite3_progress_handler(sqlite3 *, int, - int (*)(void *), void *); - -/* - * CAPI3REF: Opening A New Database Connection - * CONSTRUCTOR: sqlite3 - * - * ^These routines open an SQLite database file as specified by the - * filename argument. ^The filename argument is interpreted as UTF-8 for - * sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte - * order for sqlite3_open16(). ^(A [database connection] handle is usually - * returned in *ppDb, even if an error occurs. The only exception is that - * if SQLite is unable to allocate memory to hold the [sqlite3] object, - * a NULL will be written into *ppDb instead of a pointer to the [sqlite3] - * object.)^ ^(If the database is opened (and/or created) successfully, then - * [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The - * [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain - * an English language description of the error following a failure of any - * of the sqlite3_open() routines. - * - * ^The default encoding will be UTF-8 for databases created using - * sqlite3_open() or sqlite3_open_v2(). ^The default encoding for databases - * created using sqlite3_open16() will be UTF-16 in the native byte order. - * - * Whether or not an error occurs when it is opened, resources - * associated with the [database connection] handle should be released by - * passing it to [sqlite3_close()] when it is no longer required. - * - * The sqlite3_open_v2() interface works like sqlite3_open() - * except that it accepts two additional parameters for additional control - * over the new database connection. ^(The flags parameter to - * sqlite3_open_v2() can take one of - * the following three values, optionally combined with the - * [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE], - * [SQLITE_OPEN_PRIVATECACHE], and/or [SQLITE_OPEN_URI] flags:)^ - * - *
- * ^(
[SQLITE_OPEN_READONLY]
- *
The database is opened in read-only mode. If the database does not - * already exist, an error is returned.
)^ - * - * ^(
[SQLITE_OPEN_READWRITE]
- *
The database is opened for reading and writing if possible, or reading - * only if the file is write protected by the operating system. In either - * case the database must already exist, otherwise an error is returned.
)^ - * - * ^(
[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]
- *
The database is opened for reading and writing, and is created if - * it does not already exist. This is the behavior that is always used for - * sqlite3_open() and sqlite3_open16().
)^ - *
- * - * If the 3rd parameter to sqlite3_open_v2() is not one of the - * combinations shown above optionally combined with other - * [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits] - * then the behavior is undefined. - * - * ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection - * opens in the multi-thread [threading mode] as long as the single-thread - * mode has not been set at compile-time or start-time. ^If the - * [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens - * in the serialized [threading mode] unless single-thread was - * previously selected at compile-time or start-time. - * ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be - * eligible to use [shared cache mode], regardless of whether or not shared - * cache is enabled using [sqlite3_enable_shared_cache()]. ^The - * [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not - * participate in [shared cache mode] even if it is enabled. - * - * ^The fourth parameter to sqlite3_open_v2() is the name of the - * [sqlite3_vfs] object that defines the operating system interface that - * the new database connection should use. ^If the fourth parameter is - * a NULL pointer then the default [sqlite3_vfs] object is used. - * - * ^If the filename is ":memory:", then a private, temporary in-memory database - * is created for the connection. ^This in-memory database will vanish when - * the database connection is closed. Future versions of SQLite might - * make use of additional special filenames that begin with the ":" character. - * It is recommended that when a database filename actually does begin with - * a ":" character you should prefix the filename with a pathname such as - * "./" to avoid ambiguity. - * - * ^If the filename is an empty string, then a private, temporary - * on-disk database will be created. ^This private database will be - * automatically deleted as soon as the database connection is closed. - * - * [[URI filenames in sqlite3_open()]]

URI Filenames

- * - * ^If [URI filename] interpretation is enabled, and the filename argument - * begins with "file:", then the filename is interpreted as a URI. ^URI - * filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is - * set in the fourth argument to sqlite3_open_v2(), or if it has - * been enabled globally using the [SQLITE_CONFIG_URI] option with the - * [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option. - * As of SQLite version 3.7.7, URI filename interpretation is turned off - * by default, but future releases of SQLite might enable URI filename - * interpretation by default. See "[URI filenames]" for additional - * information. - * - * URI filenames are parsed according to RFC 3986. ^If the URI contains an - * authority, then it must be either an empty string or the string - * "localhost". ^If the authority is not an empty string or "localhost", an - * error is returned to the caller. ^The fragment component of a URI, if - * present, is ignored. - * - * ^SQLite uses the path component of the URI as the name of the disk file - * which contains the database. ^If the path begins with a '/' character, - * then it is interpreted as an absolute path. ^If the path does not begin - * with a '/' (meaning that the authority section is omitted from the URI) - * then the path is interpreted as a relative path. - * - * [[core URI query parameters]] - * The query component of a URI may contain parameters that are interpreted - * either by SQLite itself, or by a [VFS | custom VFS implementation]. - * SQLite and its built-in [VFSes] interpret the - * following query parameters: - * - *
    - *
  • vfs: ^The "vfs" parameter may be used to specify the name of - * a VFS object that provides the operating system interface that should - * be used to access the database file on disk. ^If this option is set to - * an empty string the default VFS object is used. ^Specifying an unknown - * VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is - * present, then the VFS specified by the option takes precedence over - * the value passed as the fourth parameter to sqlite3_open_v2(). - * - *
  • mode: ^(The mode parameter may be set to either "ro", "rw", - * "rwc", or "memory". Attempting to set it to any other value is - * an error)^. - * ^If "ro" is specified, then the database is opened for read-only - * access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the - * third argument to sqlite3_open_v2(). ^If the mode option is set to - * "rw", then the database is opened for read-write (but not create) - * access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had - * been set. ^Value "rwc" is equivalent to setting both - * SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If the mode option is - * set to "memory" then a pure [in-memory database] that never reads - * or writes from disk is used. ^It is an error to specify a value for - * the mode parameter that is less restrictive than that specified by - * the flags passed in the third parameter to sqlite3_open_v2(). - * - *
  • cache: ^The cache parameter may be set to either "shared" or - * "private". ^Setting it to "shared" is equivalent to setting the - * SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to - * sqlite3_open_v2(). ^Setting the cache parameter to "private" is - * equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit. - * ^If sqlite3_open_v2() is used and the "cache" parameter is present in - * a URI filename, its value overrides any behavior requested by setting - * SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag. - * - *
  • psow: ^The psow parameter indicates whether or not the - * [powersafe overwrite] property does or does not apply to the - * storage media on which the database file resides. - * - *
  • nolock: ^The nolock parameter is a boolean query parameter - * which if set disables file locking in rollback journal modes. This - * is useful for accessing a database on a filesystem that does not - * support locking. Caution: Database corruption might result if two - * or more processes write to the same database and any one of those - * processes uses nolock=1. - * - *
  • immutable: ^The immutable parameter is a boolean query - * parameter that indicates that the database file is stored on - * read-only media. ^When immutable is set, SQLite assumes that the - * database file cannot be changed, even by a process with higher - * privilege, and so the database is opened read-only and all locking - * and change detection is disabled. Caution: Setting the immutable - * property on a database file that does in fact change can result - * in incorrect query results and/or [SQLITE_CORRUPT] errors. - * See also: [SQLITE_IOCAP_IMMUTABLE]. - * - *
- * - * ^Specifying an unknown parameter in the query component of a URI is not an - * error. Future versions of SQLite might understand additional query - * parameters. See "[query parameters with special meaning to SQLite]" for - * additional information. - * - * [[URI filename examples]]

URI filename examples

- * - * - *
URI filenames Results - *
file:data.db - * Open the file "data.db" in the current directory. - *
file:/home/fred/data.db
- * file:///home/fred/data.db
- * file://localhost/home/fred/data.db
- * Open the database file "/home/fred/data.db". - *
file://darkstar/home/fred/data.db - * An error. "darkstar" is not a recognized authority. - *
file:data.db?mode=ro&cache=private - * Open file "data.db" in the current directory for read-only access. - * Regardless of whether or not shared-cache mode is enabled by - * default, use a private cache. - *
file:/home/fred/data.db?vfs=unix-dotfile - * Open file "/home/fred/data.db". Use the special VFS "unix-dotfile" - * that uses dot-files in place of posix advisory locking. - *
file:data.db?mode=readonly - * An error. "readonly" is not a valid option for the "mode" parameter. - *
- * - * ^URI hexadecimal escape sequences (%HH) are supported within the path and - * query components of a URI. A hexadecimal escape sequence consists of a - * percent sign - "%" - followed by exactly two hexadecimal digits - * specifying an octet value. ^Before the path or query components of a - * URI filename are interpreted, they are encoded using UTF-8 and all - * hexadecimal escape sequences replaced by a single byte containing the - * corresponding octet. If this process generates an invalid UTF-8 encoding, - * the results are undefined. - * - * See also: [sqlite3_temp_directory] -*/ - -int -sql_init_db(sqlite3 **db); - -SQLITE_API int -sqlite3_open16(const void *filename, /* Database filename (UTF-16) */ - sqlite3 ** ppDb /* OUT: SQLite db handle */ - ); - -SQLITE_API int -sqlite3_open_v2(const char *filename, /* Database filename (UTF-8) */ - sqlite3 ** ppDb, /* OUT: SQLite db handle */ - int flags, /* Flags */ - const char *zVfs /* Name of VFS module to use */ - ); - -/* - * CAPI3REF: Obtain Values For URI Parameters - * - * These are utility routines, useful to VFS implementations, that check - * to see if a database file was a URI that contained a specific query - * parameter, and if so obtains the value of that query parameter. - * - * If F is the database filename pointer passed into the xOpen() method of - * a VFS implementation when the flags parameter to xOpen() has one or - * more of the [SQLITE_OPEN_URI] or [SQLITE_OPEN_MAIN_DB] bits set and - * P is the name of the query parameter, then - * sqlite3_uri_parameter(F,P) returns the value of the P - * parameter if it exists or a NULL pointer if P does not appear as a - * query parameter on F. If P is a query parameter of F - * has no explicit value, then sqlite3_uri_parameter(F,P) returns - * a pointer to an empty string. - * - * The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean - * parameter and returns true (1) or false (0) according to the value - * of P. The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the - * value of query parameter P is one of "yes", "true", or "on" in any - * case or if the value begins with a non-zero number. The - * sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of - * query parameter P is one of "no", "false", or "off" in any case or - * if the value begins with a numeric zero. If P is not a query - * parameter on F or if the value of P is does not match any of the - * above, then sqlite3_uri_boolean(F,P,B) returns (B!=0). - * - * The sqlite3_uri_int64(F,P,D) routine converts the value of P into a - * 64-bit signed integer and returns that integer, or D if P does not - * exist. If the value of P is something other than an integer, then - * zero is returned. - * - * If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and - * sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and - * is not a database file pathname pointer that SQLite passed into the xOpen - * VFS method, then the behavior of this routine is undefined and probably - * undesirable. -*/ -SQLITE_API const char * -sqlite3_uri_parameter(const char *zFilename, - const char *zParam); - -SQLITE_API int -sqlite3_uri_boolean(const char *zFile, - const char *zParam, int bDefault); - -SQLITE_API sqlite3_int64 -sqlite3_uri_int64(const char *, const char *, - sqlite3_int64); - -/* - * CAPI3REF: Error Codes And Messages - * METHOD: sqlite3 - * - * ^If the most recent sqlite3_* API call associated with - * [database connection] D failed, then the sqlite3_errcode(D) interface - * returns the numeric [result code] or [extended result code] for that - * API call. - * If the most recent API call was successful, - * then the return value from sqlite3_errcode() is undefined. - * ^The sqlite3_extended_errcode() - * interface is the same except that it always returns the - * [extended result code] even when extended result codes are - * disabled. - * - * ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language - * text that describes the error, as either UTF-8 or UTF-16 respectively. - * ^(Memory to hold the error message string is managed internally. - * The application does not need to worry about freeing the result. - * However, the error string might be overwritten or deallocated by - * subsequent calls to other SQLite interface functions.)^ - * - * ^The sqlite3_errstr() interface returns the English-language text - * that describes the [result code], as UTF-8. - * ^(Memory to hold the error message string is managed internally - * and must not be freed by the application)^. - * - * When the serialized [threading mode] is in use, it might be the - * case that a second error occurs on a separate thread in between - * the time of the first error and the call to these interfaces. - * When that happens, the second error will be reported since these - * interfaces always report the most recent result. To avoid - * this, each thread can obtain exclusive use of the [database connection] D - * by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning - * to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after - * all calls to the interfaces listed here are completed. - * - * If an interface fails with SQLITE_MISUSE, that means the interface - * was invoked incorrectly by the application. In that case, the - * error code and message may or may not be set. -*/ -SQLITE_API int -sqlite3_errcode(sqlite3 * db); - -SQLITE_API int -sqlite3_extended_errcode(sqlite3 * db); - -SQLITE_API const char * -sqlite3_errmsg(sqlite3 *); - -SQLITE_API const char * -sqlite3_errstr(int); - -/* - * CAPI3REF: Prepared Statement Object - * KEYWORDS: {prepared statement} {prepared statements} - * - * An instance of this object represents a single SQL statement that - * has been compiled into binary form and is ready to be evaluated. - * - * Think of each SQL statement as a separate computer program. The - * original SQL text is source code. A prepared statement object - * is the compiled object code. All SQL must be converted into a - * prepared statement before it can be run. - * - * The life-cycle of a prepared statement object usually goes like this: - * - *
    - *
  1. Create the prepared statement object using [sqlite3_prepare_v2()]. - *
  2. Bind values to [parameters] using the sqlite3_bind_*() - * interfaces. - *
  3. Run the SQL by calling [sqlite3_step()] one or more times. - *
  4. Reset the prepared statement using [sqlite3_reset()] then go back - * to step 2. Do this zero or more times. - *
  5. Destroy the object using [sqlite3_finalize()]. - *
-*/ -typedef struct sqlite3_stmt sqlite3_stmt; - -/* - * CAPI3REF: Run-time Limits - * METHOD: sqlite3 - * - * ^(This interface allows the size of various constructs to be limited - * on a connection by connection basis. The first parameter is the - * [database connection] whose limit is to be set or queried. The - * second parameter is one of the [limit categories] that define a - * class of constructs to be size limited. The third parameter is the - * new limit for that construct.)^ - * - * ^If the new limit is a negative number, the limit is unchanged. - * ^(For each limit category SQLITE_LIMIT_NAME there is a - * [limits | hard upper bound] - * set at compile-time by a C preprocessor macro called - * [limits | SQLITE_MAX_NAME]. - * (The "_LIMIT_" in the name is changed to "_MAX_".))^ - * ^Attempts to increase a limit above its hard upper bound are - * silently truncated to the hard upper bound. - * - * ^Regardless of whether or not the limit was changed, the - * [sqlite3_limit()] interface returns the prior value of the limit. - * ^Hence, to find the current value of a limit without changing it, - * simply invoke this interface with the third parameter set to -1. - * - * Run-time limits are intended for use in applications that manage - * both their own internal database and also databases that are controlled - * by untrusted external sources. An example application might be a - * web browser that has its own databases for storing history and - * separate databases controlled by JavaScript applications downloaded - * off the Internet. The internal databases can be given the - * large, default limits. Databases managed by external sources can - * be given much smaller limits designed to prevent a denial of service - * attack.. The size of the database - * created by an untrusted script can be contained using the - * [max_page_count] [PRAGMA]. - * - * New run-time limit categories may be added in future releases. -*/ -SQLITE_API int -sqlite3_limit(sqlite3 *, int id, int newVal); - -/* - * CAPI3REF: Run-Time Limit Categories - * KEYWORDS: {limit category} {*limit categories} - * - * These constants define various performance limits - * that can be lowered at run-time using [sqlite3_limit()]. - * The synopsis of the meanings of the various limits is shown below. - * Additional information is available at [limits | Limits in SQLite]. - * - *
- * [[SQLITE_LIMIT_LENGTH]] ^(
SQLITE_LIMIT_LENGTH
- *
The maximum size of any string or BLOB or table row, in bytes.
)^ - * - * [[SQLITE_LIMIT_SQL_LENGTH]] ^(
SQLITE_LIMIT_SQL_LENGTH
- *
The maximum length of an SQL statement, in bytes.
)^ - * - * [[SQLITE_LIMIT_COLUMN]] ^(
SQLITE_LIMIT_COLUMN
- *
The maximum number of columns in a table definition or in the - * result set of a [SELECT] or the maximum number of columns in an index - * or in an ORDER BY or GROUP BY clause.
)^ - * - * [[SQLITE_LIMIT_EXPR_DEPTH]] ^(
SQLITE_LIMIT_EXPR_DEPTH
- *
The maximum depth of the parse tree on any expression.
)^ - * - * [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(
SQLITE_LIMIT_COMPOUND_SELECT
- *
The maximum number of terms in a compound SELECT statement.
)^ - * - * [[SQLITE_LIMIT_VDBE_OP]] ^(
SQLITE_LIMIT_VDBE_OP
- *
The maximum number of instructions in a virtual machine program - * used to implement an SQL statement. This limit is not currently - * enforced, though that might be added in some future release of - * SQLite.
)^ - * - * [[SQLITE_LIMIT_FUNCTION_ARG]] ^(
SQLITE_LIMIT_FUNCTION_ARG
- *
The maximum number of arguments on a function.
)^ - * - * [[SQLITE_LIMIT_ATTACHED]] ^(
SQLITE_LIMIT_ATTACHED
- *
The maximum number of [ATTACH | attached databases].)^
- * - * [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]] - * ^(
SQLITE_LIMIT_LIKE_PATTERN_LENGTH
- *
The maximum length of the pattern argument to the [LIKE] or - * [GLOB] operators.
)^ - * - * [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(
SQLITE_LIMIT_TRIGGER_DEPTH
- *
The maximum depth of recursion for triggers.
)^ - * - * [[SQLITE_LIMIT_WORKER_THREADS]] ^(
SQLITE_LIMIT_WORKER_THREADS
- *
The maximum number of auxiliary worker threads that a single - * [prepared statement] may start.
)^ - *
-*/ -#define SQLITE_LIMIT_LENGTH 0 -#define SQLITE_LIMIT_SQL_LENGTH 1 -#define SQLITE_LIMIT_COLUMN 2 -#define SQLITE_LIMIT_EXPR_DEPTH 3 -#define SQLITE_LIMIT_COMPOUND_SELECT 4 -#define SQLITE_LIMIT_VDBE_OP 5 -#define SQLITE_LIMIT_FUNCTION_ARG 6 -#define SQLITE_LIMIT_ATTACHED 7 -#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8 -#define SQLITE_LIMIT_TRIGGER_DEPTH 9 -#define SQLITE_LIMIT_WORKER_THREADS 10 - -/* - * CAPI3REF: Compiling An SQL Statement - * KEYWORDS: {SQL statement compiler} - * METHOD: sqlite3 - * CONSTRUCTOR: sqlite3_stmt - * - * To execute an SQL query, it must first be compiled into a byte-code - * program using one of these routines. - * - * The first argument, "db", is a [database connection] obtained from a - * prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or - * [sqlite3_open16()]. The database connection must not have been closed. - * - * The second argument, "zSql", is the statement to be compiled, encoded - * as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() - * interfaces use UTF-8, and sqlite3_prepare16(). - * - * ^If the nByte argument is negative, then zSql is read up to the - * first zero terminator. ^If nByte is positive, then it is the - * number of bytes read from zSql. ^If nByte is zero, then no prepared - * statement is generated. - * If the caller knows that the supplied string is nul-terminated, then - * there is a small performance advantage to passing an nByte parameter that - * is the number of bytes in the input string including - * the nul-terminator. - * - * ^If pzTail is not NULL then *pzTail is made to point to the first byte - * past the end of the first SQL statement in zSql. These routines only - * compile the first statement in zSql, so *pzTail is left pointing to - * what remains uncompiled. - * - * ^*ppStmt is left pointing to a compiled [prepared statement] that can be - * executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set - * to NULL. ^If the input text contains no SQL (if the input is an empty - * string or a comment) then *ppStmt is set to NULL. - * The calling procedure is responsible for deleting the compiled - * SQL statement using [sqlite3_finalize()] after it has finished with it. - * ppStmt may not be NULL. - * - * ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK]; - * otherwise an [error code] is returned. - * - * The sqlite3_prepare_v2() is - * recommended for all new programs. The two older interfaces are retained - * for backwards compatibility, but their use is discouraged. - * ^In the "v2" interfaces, the prepared statement - * that is returned (the [sqlite3_stmt] object) contains a copy of the - * original SQL text. This causes the [sqlite3_step()] interface to - * behave differently in three ways: - * - *
    - *
  1. - * ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it - * always used to do, [sqlite3_step()] will automatically recompile the SQL - * statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY] - * retries will occur before sqlite3_step() gives up and returns an error. - *
    2. - * - *
  2. - * ^When an error occurs, [sqlite3_step()] will return one of the detailed - * [error codes] or [extended error codes]. ^The legacy behavior was that - * [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code - * and the application would have to make a second call to [sqlite3_reset()] - * in order to find the underlying cause of the problem. With the "v2" prepare - * interfaces, the underlying reason for the error is returned immediately. - *
    3. - * - *
  3. - * ^If the specific value bound to [parameter | host parameter] in the - * WHERE clause might influence the choice of query plan for a statement, - * then the statement will be automatically recompiled, as if there had been - * a schema change, on the first [sqlite3_step()] call following any change - * to the [sqlite3_bind_text | bindings] of that [parameter]. - * ^The specific value of WHERE-clause [parameter] might influence the - * choice of query plan if the parameter is the left-hand side of a [LIKE] - * or [GLOB] operator or if the parameter is compared to an indexed column. - *
    4. - *
-*/ -SQLITE_API int -sqlite3_prepare(sqlite3 * db, /* Database handle */ - const char *zSql, /* SQL statement, UTF-8 encoded */ - int nByte, /* Maximum length of zSql in bytes. */ - sqlite3_stmt ** ppStmt, /* OUT: Statement handle */ - const char **pzTail /* OUT: Pointer to unused portion of zSql */ - ); - -SQLITE_API int -sqlite3_prepare_v2(sqlite3 * db, /* Database handle */ - const char *zSql, /* SQL statement, UTF-8 encoded */ - int nByte, /* Maximum length of zSql in bytes. */ - sqlite3_stmt ** ppStmt, /* OUT: Statement handle */ - const char **pzTail /* OUT: Pointer to unused portion of zSql */ - ); -/* - * CAPI3REF: Retrieving Statement SQL - * METHOD: sqlite3_stmt - * - * ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8 - * SQL text used to create [prepared statement] P if P was - * created by either [sqlite3_prepare_v2()] - * ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8 - * string containing the SQL text of prepared statement P with - * [bound parameters] expanded. - * - * ^(For example, if a prepared statement is created using the SQL - * text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345 - * and parameter :xyz is unbound, then sqlite3_sql() will return - * the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql() - * will return "SELECT 2345,NULL".)^ - * - * ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory - * is available to hold the result, or if the result would exceed the - * the maximum string length determined by the [SQLITE_LIMIT_LENGTH]. - * - * ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of - * bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time - * option causes sqlite3_expanded_sql() to always return NULL. - * - * ^The string returned by sqlite3_sql(P) is managed by SQLite and is - * automatically freed when the prepared statement is finalized. - * ^The string returned by sqlite3_expanded_sql(P), on the other hand, - * is obtained from [sqlite3_malloc()] and must be free by the application - * by passing it to [sqlite3_free()]. -*/ -SQLITE_API const char * -sqlite3_sql(sqlite3_stmt * pStmt); - -SQLITE_API char * -sqlite3_expanded_sql(sqlite3_stmt * pStmt); - -/* - * CAPI3REF: Determine If A Prepared Statement Has Been Reset - * METHOD: sqlite3_stmt - * - * ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the - * [prepared statement] S has been stepped at least once using - * [sqlite3_step(S)] but has neither run to completion (returned - * [SQLITE_DONE] from [sqlite3_step(S)]) nor - * been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S) - * interface returns false if S is a NULL pointer. If S is not a - * NULL pointer and is not a pointer to a valid [prepared statement] - * object, then the behavior is undefined and probably undesirable. - * - * This interface can be used in combination [sqlite3_next_stmt()] - * to locate all prepared statements associated with a database - * connection that are in need of being reset. This can be used, - * for example, in diagnostic routines to search for prepared - * statements that are holding a transaction open. -*/ -SQLITE_API int -sqlite3_stmt_busy(sqlite3_stmt *); - -/* - * CAPI3REF: Dynamically Typed Value Object - * KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} - * - * SQLite uses the sqlite3_value object to represent all values - * that can be stored in a database table. SQLite uses dynamic typing - * for the values it stores. ^Values stored in sqlite3_value objects - * can be integers, floating point values, strings, BLOBs, or NULL. - * - * An sqlite3_value object may be either "protected" or "unprotected". - * Some interfaces require a protected sqlite3_value. Other interfaces - * will accept either a protected or an unprotected sqlite3_value. - * Every interface that accepts sqlite3_value arguments specifies - * whether or not it requires a protected sqlite3_value. The - * [sqlite3_value_dup()] interface can be used to construct a new - * protected sqlite3_value from an unprotected sqlite3_value. - * - * The terms "protected" and "unprotected" refer to whether or not - * a mutex is held. An internal mutex is held for a protected - * sqlite3_value object but no mutex is held for an unprotected - * sqlite3_value object. If SQLite is compiled to be single-threaded - * (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0) - * or if SQLite is run in one of reduced mutex modes - * [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD] - * then there is no distinction between protected and unprotected - * sqlite3_value objects and they can be used interchangeably. However, - * for maximum code portability it is recommended that applications - * still make the distinction between protected and unprotected - * sqlite3_value objects even when not strictly required. - * - * ^The sqlite3_value objects that are passed as parameters into the - * implementation of [application-defined SQL functions] are protected. - * ^The sqlite3_value object returned by - * [sqlite3_column_value()] is unprotected. - * Unprotected sqlite3_value objects may only be used with - * [sqlite3_result_value()] and [sqlite3_bind_value()]. - * The [sqlite3_value_blob | sqlite3_value_type()] family of - * interfaces require protected sqlite3_value objects. -*/ -typedef struct Mem sqlite3_value; - -/* - * CAPI3REF: SQL Function Context Object - * - * The context in which an SQL function executes is stored in an - * sqlite3_context object. ^A pointer to an sqlite3_context object - * is always first parameter to [application-defined SQL functions]. - * The application-defined SQL function implementation will pass this - * pointer through into calls to [sqlite3_result_int | sqlite3_result()], - * [sqlite3_aggregate_context()], [sqlite3_user_data()], - * [sqlite3_context_db_handle()], [sqlite3_get_auxdata()], - * and/or [sqlite3_set_auxdata()]. -*/ -typedef struct sqlite3_context sqlite3_context; - -/* - * CAPI3REF: Binding Values To Prepared Statements - * KEYWORDS: {host parameter} {host parameters} {host parameter name} - * KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding} - * METHOD: sqlite3_stmt - * - * ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants, - * literals may be replaced by a [parameter] that matches one of following - * templates: - * - *
    - *
  • ? - *
  • ?NNN - *
  • :VVV - *
  • @VVV - *
  • $VVV - *
- * - * In the templates above, NNN represents an integer literal, - * and VVV represents an alphanumeric identifier.)^ ^The values of these - * parameters (also called "host parameter names" or "SQL parameters") - * can be set using the sqlite3_bind_*() routines defined here. - * - * ^The first argument to the sqlite3_bind_*() routines is always - * a pointer to the [sqlite3_stmt] object returned from - * [sqlite3_prepare_v2()] or its variants. - * - * ^The second argument is the index of the SQL parameter to be set. - * ^The leftmost SQL parameter has an index of 1. ^When the same named - * SQL parameter is used more than once, second and subsequent - * occurrences have the same index as the first occurrence. - * ^The index for named parameters can be looked up using the - * [sqlite3_bind_parameter_index()] API if desired. ^The index - * for "?NNN" parameters is the value of NNN. - * ^The NNN value must be between 1 and the - * SQL_BIND_PARAMETER_MAX. - * - * ^The third argument is the value to bind to the parameter. - * ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16() - * or sqlite3_bind_blob() is a NULL pointer then the fourth parameter - * is ignored and the end result is the same as sqlite3_bind_null(). - * - * ^(In those routines that have a fourth argument, its value is the - * number of bytes in the parameter. To be clear: the value is the - * number of bytes in the value, not the number of characters.)^ - * ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16() - * is negative, then the length of the string is - * the number of bytes up to the first zero terminator. - * If the fourth parameter to sqlite3_bind_blob() is negative, then - * the behavior is undefined. - * If a non-negative fourth parameter is provided to sqlite3_bind_text() - * or sqlite3_bind_text16() or sqlite3_bind_text64() then - * that parameter must be the byte offset - * where the NUL terminator would occur assuming the string were NUL - * terminated. If any NUL characters occur at byte offsets less than - * the value of the fourth parameter then the resulting string value will - * contain embedded NULs. The result of expressions involving strings - * with embedded NULs is undefined. - * - * ^The fifth argument to the BLOB and string binding interfaces - * is a destructor used to dispose of the BLOB or - * string after SQLite has finished with it. ^The destructor is called - * to dispose of the BLOB or string even if the call to bind API fails. - * ^If the fifth argument is - * the special value [SQLITE_STATIC], then SQLite assumes that the - * information is in static, unmanaged space and does not need to be freed. - * ^If the fifth argument has the value [SQLITE_TRANSIENT], then - * SQLite makes its own private copy of the data immediately, before - * the sqlite3_bind_*() routine returns. - * - * ^The sixth argument to sqlite3_bind_text64() must be one of - * [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE] - * to specify the encoding of the text in the third parameter. If - * the sixth argument to sqlite3_bind_text64() is not one of the - * allowed values shown above, or if the text encoding is different - * from the encoding specified by the sixth parameter, then the behavior - * is undefined. - * - * ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that - * is filled with zeroes. ^A zeroblob uses a fixed amount of memory - * (just an integer to hold its size) while it is being processed. - * Zeroblobs are intended to serve as placeholders for BLOBs whose - * content is later written using - * [sqlite3_blob_open | incremental BLOB I/O] routines. - * ^A negative value for the zeroblob results in a zero-length BLOB. - * - * ^If any of the sqlite3_bind_*() routines are called with a NULL pointer - * for the [prepared statement] or with a prepared statement for which - * [sqlite3_step()] has been called more recently than [sqlite3_reset()], - * then the call will return [SQLITE_MISUSE]. If any sqlite3_bind_() - * routine is passed a [prepared statement] that has been finalized, the - * result is undefined and probably harmful. - * - * ^Bindings are not cleared by the [sqlite3_reset()] routine. - * ^Unbound parameters are interpreted as NULL. - * - * ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an - * [error code] if anything goes wrong. - * ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB - * exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or - * [SQLITE_MAX_LENGTH]. - * ^[SQLITE_RANGE] is returned if the parameter - * index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails. - * - * See also: [sqlite3_bind_parameter_count()], - * [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. -*/ -SQLITE_API int -sqlite3_bind_blob(sqlite3_stmt *, int, const void *, - int n, void (*)(void *)); - -SQLITE_API int -sqlite3_bind_blob64(sqlite3_stmt *, int, const void *, - sqlite3_uint64, void (*)(void *)); - -SQLITE_API int -sqlite3_bind_double(sqlite3_stmt *, int, double); - -SQLITE_API int -sqlite3_bind_int(sqlite3_stmt *, int, int); - -SQLITE_API int -sqlite3_bind_int64(sqlite3_stmt *, int, sqlite3_int64); - -SQLITE_API int -sqlite3_bind_null(sqlite3_stmt *, int); - -SQLITE_API int -sqlite3_bind_text(sqlite3_stmt *, int, const char *, int, - void (*)(void *)); - -SQLITE_API int -sqlite3_bind_text64(sqlite3_stmt *, int, const char *, - sqlite3_uint64, void (*)(void *)); -SQLITE_API int -sqlite3_bind_value(sqlite3_stmt *, int, - const sqlite3_value *); - -SQLITE_API int -sqlite3_bind_zeroblob(sqlite3_stmt *, int, int n); - -SQLITE_API int -sqlite3_bind_zeroblob64(sqlite3_stmt *, int, - sqlite3_uint64); - -/* - * CAPI3REF: Number Of SQL Parameters - * METHOD: sqlite3_stmt - * - * ^This routine can be used to find the number of [SQL parameters] - * in a [prepared statement]. SQL parameters are tokens of the - * form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as - * placeholders for values that are [sqlite3_bind_blob | bound] - * to the parameters at a later time. - * - * ^(This routine actually returns the index of the largest (rightmost) - * parameter. For all forms except ?NNN, this will correspond to the - * number of unique parameters. If parameters of the ?NNN form are used, - * there may be gaps in the list.)^ - * - * See also: [sqlite3_bind_blob|sqlite3_bind()], - * [sqlite3_bind_parameter_name()], and - * [sqlite3_bind_parameter_index()]. -*/ -SQLITE_API int -sqlite3_bind_parameter_count(sqlite3_stmt *); - -/* - * CAPI3REF: Name Of A Host Parameter - * METHOD: sqlite3_stmt - * - * ^The sqlite3_bind_parameter_name(P,N) interface returns - * the name of the N-th [SQL parameter] in the [prepared statement] P. - * ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" - * have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" - * respectively. - * In other words, the initial ":" or "$" or "@" or "?" - * is included as part of the name.)^ - * ^Parameters of the form "?" without a following integer have no name - * and are referred to as "nameless" or "anonymous parameters". - * - * ^The first host parameter has an index of 1, not 0. - * - * ^If the value N is out of range or if the N-th parameter is - * nameless, then NULL is returned. ^The returned string is - * always in UTF-8 encoding even if the named parameter was - * originally specified as UTF-16 in - * - * See also: [sqlite3_bind_blob|sqlite3_bind()], - * [sqlite3_bind_parameter_count()], and - * [sqlite3_bind_parameter_index()]. -*/ -SQLITE_API const char * -sqlite3_bind_parameter_name(sqlite3_stmt *, int); - -/* - * CAPI3REF: Index Of A Parameter With A Given Name - * METHOD: sqlite3_stmt - * - * ^Return the index of an SQL parameter given its name. ^The - * index value returned is suitable for use as the second - * parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero - * is returned if no matching parameter is found. ^The parameter - * name must be given in UTF-8 - * - * See also: [sqlite3_bind_blob|sqlite3_bind()], - * [sqlite3_bind_parameter_count()], and - * [sqlite3_bind_parameter_name()]. -*/ -SQLITE_API int -sqlite3_bind_parameter_index(sqlite3_stmt *, - const char *zName); - -/** - * Get number of the named parameter in the prepared sql - * statement. - * @param pStmt Prepared statement. - * @param zName Parameter name. - * @param nName Parameter name length. - * - * @retval > 0 Number of the parameter. - * @retval 0 Parameter is not found. - */ -int -sqlite3_bind_parameter_lindex(sqlite3_stmt * pStmt, const char *zName, - int nName); - -/* - * CAPI3REF: Reset All Bindings On A Prepared Statement - * METHOD: sqlite3_stmt - * - * ^Contrary to the intuition of many, [sqlite3_reset()] does not reset - * the [sqlite3_bind_blob | bindings] on a [prepared statement]. - * ^Use this routine to reset all host parameters to NULL. -*/ -SQLITE_API int -sqlite3_clear_bindings(sqlite3_stmt *); - -/* - * CAPI3REF: Number Of Columns In A Result Set - * METHOD: sqlite3_stmt - * - * ^Return the number of columns in the result set returned by the - * [prepared statement]. ^If this routine returns 0, that means the - * [prepared statement] returns no data (for example an [UPDATE]). - * ^However, just because this routine returns a positive number does not - * mean that one or more rows of data will be returned. ^A SELECT statement - * will always have a positive sqlite3_column_count() but depending on the - * WHERE clause constraints and the table content, it might return no rows. - * - * See also: [sqlite3_data_count()] -*/ -SQLITE_API int -sqlite3_column_count(sqlite3_stmt * pStmt); - -/* - * CAPI3REF: Column Names In A Result Set - * METHOD: sqlite3_stmt - * - * ^These routines return the name assigned to a particular column - * in the result set of a [SELECT] statement. ^The sqlite3_column_name() - * interface returns a pointer to a zero-terminated UTF-8 string - * and sqlite3_column_name16() returns a pointer to a zero-terminated - * UTF-16 string. ^The first parameter is the [prepared statement] - * that implements the [SELECT] statement. ^The second parameter is the - * column number. ^The leftmost column is number 0. - * - * ^The returned string pointer is valid until either the [prepared statement] - * is destroyed by [sqlite3_finalize()] or until the statement is automatically - * reprepared by the first call to [sqlite3_step()] for a particular run - * or until the next call to - * sqlite3_column_name() or sqlite3_column_name16() on the same column. - * - * ^If sqlite3_malloc() fails during the processing of either routine - * (for example during a conversion from UTF-8 to UTF-16) then a - * NULL pointer is returned. - * - * ^The name of a result column is the value of the "AS" clause for - * that column, if there is an AS clause. If there is no AS clause - * then the name of the column is unspecified and may change from - * one release of SQLite to the next. -*/ -SQLITE_API const char * -sqlite3_column_name(sqlite3_stmt *, int N); - -/* - * CAPI3REF: Source Of Data In A Query Result - * METHOD: sqlite3_stmt - * - * ^These routines provide a means to determine the database, table, and - * table column that is the origin of a particular result column in - * [SELECT] statement. - * ^The name of the database or table or column can be returned as - * either a UTF-8 or UTF-16 string. ^The _database_ routines return - * the database name, the _table_ routines return the table name, and - * the origin_ routines return the column name. - * ^The returned string is valid until the [prepared statement] is destroyed - * using [sqlite3_finalize()] or until the statement is automatically - * reprepared by the first call to [sqlite3_step()] for a particular run - * or until the same information is requested - * again in a different encoding. - * - * ^The names returned are the original un-aliased names of the - * database, table, and column. - * - * ^The first argument to these interfaces is a [prepared statement]. - * ^These functions return information about the Nth result column returned by - * the statement, where N is the second function argument. - * ^The left-most column is column 0 for these routines. - * - * ^If the Nth column returned by the statement is an expression or - * subquery and is not a column value, then all of these functions return - * NULL. ^These routine might also return NULL if a memory allocation error - * occurs. ^Otherwise, they return the name of the attached database, table, - * or column that query result column was extracted from. - * - * ^As with all other SQLite APIs, those whose names end with "16" return - * UTF-16 encoded strings and the other functions return UTF-8. - * - * ^These APIs are only available if the library was compiled with the - * [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol. - * - * If two or more threads call one or more of these routines against the same - * prepared statement and column at the same time then the results are - * undefined. - * - * If two or more threads call one or more - * [sqlite3_column_database_name | column metadata interfaces] - * for the same [prepared statement] and result column - * at the same time then the results are undefined. -*/ -SQLITE_API const char * -sqlite3_column_database_name(sqlite3_stmt *, - int); -SQLITE_API const char * -sqlite3_column_table_name(sqlite3_stmt *, int); - -SQLITE_API const char * -sqlite3_column_origin_name(sqlite3_stmt *, int); - -/* - * CAPI3REF: Declared Datatype Of A Query Result - * METHOD: sqlite3_stmt - * - * ^(The first parameter is a [prepared statement]. - * If this statement is a [SELECT] statement and the Nth column of the - * returned result set of that [SELECT] is a table column (not an - * expression or subquery) then the declared type of the table - * column is returned.)^ ^If the Nth column of the result set is an - * expression or subquery, then a NULL pointer is returned. - * ^The returned string is always UTF-8 encoded. - * - * ^(For example, given the database schema: - * - * CREATE TABLE t1(c1 VARIANT); - * - * and the following statement to be compiled: - * - * SELECT c1 + 1, c1 FROM t1; - * - * this routine would return the string "VARIANT" for the second result - * column (i==1), and a NULL pointer for the first result column (i==0).)^ - * - * ^SQLite uses dynamic run-time typing. ^So just because a column - * is declared to contain a particular type does not mean that the - * data stored in that column is of the declared type. SQLite is - * strongly typed, but the typing is dynamic not static. ^Type - * is associated with individual values, not with the containers - * used to hold those values. -*/ -SQLITE_API const char * -sqlite3_column_decltype(sqlite3_stmt *, int); - -/* - * CAPI3REF: Evaluate An SQL Statement - * METHOD: sqlite3_stmt - * - * After a [prepared statement] has been prepared using either - * [sqlite3_prepare_v2()] one of the legacy - * interfaces [sqlite3_prepare()] function - * must be called one or more times to evaluate the statement. - * - * The details of the behavior of the sqlite3_step() interface depend - * on whether the statement was prepared using the newer "v2" interface - * [sqlite3_prepare_v2()] the older legacy - * interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the - * new "v2" interface is recommended for new applications but the legacy - * interface will continue to be supported. - * - * ^In the legacy interface, the return value will be either [SQLITE_BUSY], - * [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. - * ^With the "v2" interface, any of the other [result codes] or - * [extended result codes] might be returned as well. - * - * ^[SQLITE_BUSY] means that the database engine was unable to acquire the - * database locks it needs to do its job. ^If the statement is a [COMMIT] - * or occurs outside of an explicit transaction, then you can retry the - * statement. If the statement is not a [COMMIT] and occurs within an - * explicit transaction then you should rollback the transaction before - * continuing. - * - * ^[SQLITE_DONE] means that the statement has finished executing - * successfully. sqlite3_step() should not be called again on this virtual - * machine without first calling [sqlite3_reset()] to reset the virtual - * machine back to its initial state. - * - * ^If the SQL statement being executed returns any data, then [SQLITE_ROW] - * is returned each time a new row of data is ready for processing by the - * caller. The values may be accessed using the [column access functions]. - * sqlite3_step() is called again to retrieve the next row of data. - * - * ^[SQLITE_ERROR] means that a run-time error (such as a constraint - * violation) has occurred. sqlite3_step() should not be called again on - * the VM. More information may be found by calling [sqlite3_errmsg()]. - * ^With the legacy interface, a more specific error code (for example, - * [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth) - * can be obtained by calling [sqlite3_reset()] on the - * [prepared statement]. ^In the "v2" interface, - * the more specific error code is returned directly by sqlite3_step(). - * - * [SQLITE_MISUSE] means that the this routine was called inappropriately. - * Perhaps it was called on a [prepared statement] that has - * already been [sqlite3_finalize | finalized] or on one that had - * previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could - * be the case that the same database connection is being used by two or - * more threads at the same moment in time. - * - * For all versions of SQLite up to and including 3.6.23.1, a call to - * [sqlite3_reset()] was required after sqlite3_step() returned anything - * other than [SQLITE_ROW] before any subsequent invocation of - * sqlite3_step(). Failure to reset the prepared statement using - * [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from - * sqlite3_step(). But after [version 3.6.23.1] ([dateof:3.6.23.1], - * sqlite3_step() began - * calling [sqlite3_reset()] automatically in this circumstance rather - * than returning [SQLITE_MISUSE]. This is not considered a compatibility - * break because any application that ever receives an SQLITE_MISUSE error - * is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option - * can be used to restore the legacy behavior. - * - * Goofy Interface Alert: In the legacy interface, the sqlite3_step() - * API always returns a generic error code, [SQLITE_ERROR], following any - * error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call - * [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the - * specific [error codes] that better describes the error. - * We admit that this is a goofy design. The problem has been fixed - * with the "v2" interface. If you prepare all of your SQL statements - * using either [sqlite3_prepare_v2()] instead - * of the legacy [sqlite3_prepare()] interfaces, - * then the more specific [error codes] are returned directly - * by sqlite3_step(). The use of the "v2" interface is recommended. -*/ -SQLITE_API int -sqlite3_step(sqlite3_stmt *); - -/* - * CAPI3REF: Number of columns in a result set - * METHOD: sqlite3_stmt - * - * ^The sqlite3_data_count(P) interface returns the number of columns in the - * current row of the result set of [prepared statement] P. - * ^If prepared statement P does not have results ready to return - * (via calls to the [sqlite3_column_int | sqlite3_column_*()] of - * interfaces) then sqlite3_data_count(P) returns 0. - * ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer. - * ^The sqlite3_data_count(P) routine returns 0 if the previous call to - * [sqlite3_step](P) returned [SQLITE_DONE]. ^The sqlite3_data_count(P) - * will return non-zero if previous call to [sqlite3_step](P) returned - * [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum] - * where it always returns zero since each step of that multi-step - * pragma returns 0 columns of data. - * - * See also: [sqlite3_column_count()] -*/ -SQLITE_API int -sqlite3_data_count(sqlite3_stmt * pStmt); - -/* - * CAPI3REF: Fundamental Datatypes - * KEYWORDS: SQLITE_TEXT - * - * ^(Every value in SQLite has one of five fundamental datatypes: - * - *
    - *
  • 64-bit signed integer - *
  • 64-bit IEEE floating point number - *
  • string - *
  • BLOB - *
  • NULL - *
)^ - * - * These constants are codes for each of those types. - * - * Note that the SQLITE_TEXT constant was also used in SQLite version 2 - * for a completely different meaning. Software that links against both - * SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not - * SQLITE_TEXT. -*/ -enum sql_type { - SQLITE_INTEGER = 1, - SQLITE_FLOAT = 2, - SQLITE_TEXT = 3, - SQLITE_BLOB = 4, - SQLITE_NULL = 5, -}; -/** SQLite type name by code. */ -extern const char *sql_type_strs[]; - -/* - * CAPI3REF: Result Values From A Query - * KEYWORDS: {column access functions} - * METHOD: sqlite3_stmt - * - * ^These routines return information about a single column of the current - * result row of a query. ^In every case the first argument is a pointer - * to the [prepared statement] that is being evaluated (the [sqlite3_stmt*] - * that was returned from [sqlite3_prepare_v2()] or one of its variants) - * and the second argument is the index of the column for which information - * should be returned. ^The leftmost column of the result set has the index 0. - * ^The number of columns in the result can be determined using - * [sqlite3_column_count()]. - * - * If the SQL statement does not currently point to a valid row, or if the - * column index is out of range, the result is undefined. - * These routines may only be called when the most recent call to - * [sqlite3_step()] has returned [SQLITE_ROW] and neither - * [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently. - * If any of these routines are called after [sqlite3_reset()] or - * [sqlite3_finalize()] or after [sqlite3_step()] has returned - * something other than [SQLITE_ROW], the results are undefined. - * If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()] - * are called from a different thread while any of these routines - * are pending, then the results are undefined. - * - * ^The sqlite3_column_type() routine returns the - * [SQLITE_INTEGER | datatype code] for the initial data type - * of the result column. ^The returned value is one of [SQLITE_INTEGER], - * [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value - * returned by sqlite3_column_type() is only meaningful if no type - * conversions have occurred as described below. After a type conversion, - * the value returned by sqlite3_column_type() is undefined. Future - * versions of SQLite may change the behavior of sqlite3_column_type() - * following a type conversion. - * - * ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() - * routine returns the number of bytes in that BLOB or string. - * ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts - * the string to UTF-8 and then returns the number of bytes. - * ^If the result is a numeric value then sqlite3_column_bytes() uses - * [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns - * the number of bytes in that string. - * ^If the result is NULL, then sqlite3_column_bytes() returns zero. - * - * ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16() - * routine returns the number of bytes in that BLOB or string. - * ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts - * the string to UTF-16 and then returns the number of bytes. - * ^If the result is a numeric value then sqlite3_column_bytes16() uses - * [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns - * the number of bytes in that string. - * ^If the result is NULL, then sqlite3_column_bytes16() returns zero. - * - * ^The values returned by [sqlite3_column_bytes()] and - * [sqlite3_column_bytes16()] do not include the zero terminators at the end - * of the string. ^For clarity: the values returned by - * [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of - * bytes in the string, not the number of characters. - * - * ^Strings returned by sqlite3_column_text() - * even empty strings, are always zero-terminated. ^The return - * value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer. - * - * Warning: ^The object returned by [sqlite3_column_value()] is an - * [unprotected sqlite3_value] object. In a multithreaded environment, - * an unprotected sqlite3_value object may only be used safely with - * [sqlite3_bind_value()] and [sqlite3_result_value()]. - * If the [unprotected sqlite3_value] object returned by - * [sqlite3_column_value()] is used in any other way, including calls - * to routines like [sqlite3_value_int()], [sqlite3_value_text()], - * or [sqlite3_value_bytes()], the behavior is not threadsafe. - * - * These routines attempt to convert the value where appropriate. ^For - * example, if the internal representation is FLOAT and a text result - * is requested, [sqlite3_snprintf()] is used internally to perform the - * conversion automatically. ^(The following table details the conversions - * that are applied: - * - *
- * - *
Internal
Type 		Requested
Type 		Conversion - * - *
NULL INTEGER Result is 0 - *
NULL FLOAT Result is 0.0 - *
NULL TEXT Result is a NULL pointer - *
NULL BLOB Result is a NULL pointer - *
INTEGER FLOAT Convert from integer to float - *
INTEGER TEXT ASCII rendering of the integer - *
INTEGER BLOB Same as INTEGER->TEXT - *
FLOAT INTEGER [CAST] to INTEGER - *
FLOAT TEXT ASCII rendering of the float - *
FLOAT BLOB [CAST] to BLOB - *
TEXT INTEGER [CAST] to INTEGER - *
TEXT FLOAT [CAST] to REAL - *
TEXT BLOB No change - *
BLOB INTEGER [CAST] to INTEGER - *
BLOB FLOAT [CAST] to REAL - *
BLOB TEXT Add a zero terminator if needed - *
- *
)^ - * - * Note that when type conversions occur, pointers returned by prior - * calls to sqlite3_column_blob(), sqlite3_column_text(), and/or - * sqlite3_column_text16() may be invalidated. - * Type conversions and pointer invalidations might occur - * in the following cases: - * - *
    - *
  • The initial content is a BLOB and sqlite3_column_text() or - * sqlite3_column_text16() is called. A zero-terminator might - * need to be added to the string.
    • - *
  • The initial content is UTF-8 text and sqlite3_column_bytes16() or - * sqlite3_column_text16() is called. The content must be converted - * to UTF-16.
    • - *
  • The initial content is UTF-16 text and sqlite3_column_bytes() or - * sqlite3_column_text() is called. The content must be converted - * to UTF-8.
    • - *
- * - * ^Conversions between UTF-16be and UTF-16le are always done in place and do - * not invalidate a prior pointer, though of course the content of the buffer - * that the prior pointer references will have been modified. Other kinds - * of conversion are done in place when it is possible, but sometimes they - * are not possible and in those cases prior pointers are invalidated. - * - * The safest policy is to invoke these routines - * in one of the following ways: - * - *
    - *
  • sqlite3_column_text() followed by sqlite3_column_bytes()
    • - *
  • sqlite3_column_blob() followed by sqlite3_column_bytes()
    • - *
  • sqlite3_column_text16() followed by sqlite3_column_bytes16()
    • - *
- * - * In other words, you should call sqlite3_column_text(), - * sqlite3_column_blob(), or sqlite3_column_text16() first to force the result - * into the desired format, then invoke sqlite3_column_bytes() or - * sqlite3_column_bytes16() to find the size of the result. Do not mix calls - * to sqlite3_column_text() or sqlite3_column_blob() with calls to - * sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() - * with calls to sqlite3_column_bytes(). - * - * ^The pointers returned are valid until a type conversion occurs as - * described above, or until [sqlite3_step()] or [sqlite3_reset()] or - * [sqlite3_finalize()] is called. ^The memory space used to hold strings - * and BLOBs is freed automatically. Do not pass the pointers returned - * from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into - * [sqlite3_free()]. - * - * ^(If a memory allocation error occurs during the evaluation of any - * of these routines, a default value is returned. The default value - * is either the integer 0, the floating point number 0.0, or a NULL - * pointer. Subsequent calls to [sqlite3_errcode()] will return - * [SQLITE_NOMEM].)^ -*/ -SQLITE_API const void * -sqlite3_column_blob(sqlite3_stmt *, int iCol); - -SQLITE_API int -sqlite3_column_bytes(sqlite3_stmt *, int iCol); - -SQLITE_API int -sqlite3_column_bytes16(sqlite3_stmt *, int iCol); - -SQLITE_API double -sqlite3_column_double(sqlite3_stmt *, int iCol); - -SQLITE_API int -sqlite3_column_int(sqlite3_stmt *, int iCol); - -SQLITE_API sqlite3_int64 -sqlite3_column_int64(sqlite3_stmt *, int iCol); - -SQLITE_API const unsigned char * -sqlite3_column_text(sqlite3_stmt *, - int iCol); - -SQLITE_API int -sqlite3_column_type(sqlite3_stmt *, int iCol); - -SQLITE_API sqlite3_value * -sqlite3_column_value(sqlite3_stmt *, - int iCol); - -/* - * CAPI3REF: Destroy A Prepared Statement Object - * DESTRUCTOR: sqlite3_stmt - * - * ^The sqlite3_finalize() function is called to delete a [prepared statement]. - * ^If the most recent evaluation of the statement encountered no errors - * or if the statement is never been evaluated, then sqlite3_finalize() returns - * SQLITE_OK. ^If the most recent evaluation of statement S failed, then - * sqlite3_finalize(S) returns the appropriate [error code] or - * [extended error code]. - * - * ^The sqlite3_finalize(S) routine can be called at any point during - * the life cycle of [prepared statement] S: - * before statement S is ever evaluated, after - * one or more calls to [sqlite3_reset()], or after any call - * to [sqlite3_step()] regardless of whether or not the statement has - * completed execution. - * - * ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op. - * - * The application must finalize every [prepared statement] in order to avoid - * resource leaks. It is a grievous error for the application to try to use - * a prepared statement after it has been finalized. Any use of a prepared - * statement after it has been finalized can result in undefined and - * undesirable behavior such as segfaults and heap corruption. -*/ -SQLITE_API int -sqlite3_finalize(sqlite3_stmt * pStmt); - -/* - * CAPI3REF: Reset A Prepared Statement Object - * METHOD: sqlite3_stmt - * - * The sqlite3_reset() function is called to reset a [prepared statement] - * object back to its initial state, ready to be re-executed. - * ^Any SQL statement variables that had values bound to them using - * the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. - * Use [sqlite3_clear_bindings()] to reset the bindings. - * - * ^The [sqlite3_reset(S)] interface resets the [prepared statement] S - * back to the beginning of its program. - * - * ^If the most recent call to [sqlite3_step(S)] for the - * [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE], - * or if [sqlite3_step(S)] has never before been called on S, - * then [sqlite3_reset(S)] returns [SQLITE_OK]. - * - * ^If the most recent call to [sqlite3_step(S)] for the - * [prepared statement] S indicated an error, then - * [sqlite3_reset(S)] returns an appropriate [error code]. - * - * ^The [sqlite3_reset(S)] interface does not change the values - * of any [sqlite3_bind_blob|bindings] on the [prepared statement] S. -*/ -SQLITE_API int -sqlite3_reset(sqlite3_stmt * pStmt); - -/* - * CAPI3REF: Create Or Redefine SQL Functions - * KEYWORDS: {function creation routines} - * KEYWORDS: {application-defined SQL function} - * KEYWORDS: {application-defined SQL functions} - * METHOD: sqlite3 - * - * ^These functions (collectively known as "function creation routines") - * are used to add SQL functions or aggregates or to redefine the behavior - * of existing SQL functions or aggregates. The only differences between - * these routines are the text encoding expected for - * the second parameter (the name of the function being created) - * and the presence or absence of a destructor callback for - * the application data pointer. - * - * ^The first parameter is the [database connection] to which the SQL - * function is to be added. ^If an application uses more than one database - * connection then application-defined SQL functions must be added - * to each database connection separately. - * - * ^The second parameter is the name of the SQL function to be created or - * redefined. ^The length of the name is limited to 255 bytes in a UTF-8 - * representation, exclusive of the zero-terminator. ^Note that the name - * length limit is in UTF-8 bytes, not characters nor UTF-16 bytes. - * ^Any attempt to create a function with a longer name - * will result in [SQLITE_MISUSE] being returned. - * - * ^The third parameter (nArg) - * is the number of arguments that the SQL function or - * aggregate takes. ^If this parameter is -1, then the SQL function or - * aggregate may take any number of arguments between 0 and the limit - * set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third - * parameter is less than -1 or greater than 127 then the behavior is - * undefined. - * - * ^The fourth parameter, eTextRep, specifies what - * [SQLITE_UTF8 | text encoding] this SQL function prefers for - * its parameters. The application should set this parameter to - * [SQLITE_UTF16LE] if the function implementation invokes - * [sqlite3_value_text16le()] on an input, or [SQLITE_UTF16BE] if the - * implementation invokes [sqlite3_value_text16be()] on an input, or - * [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8] - * otherwise. ^The same SQL function may be registered multiple times using - * different preferred text encodings, with different implementations for - * each encoding. - * ^When multiple implementations of the same function are available, SQLite - * will pick the one that involves the least amount of data conversion. - * - * ^The fourth parameter may optionally be ORed with [SQLITE_DETERMINISTIC] - * to signal that the function will always return the same result given - * the same inputs within a single SQL statement. Most SQL functions are - * deterministic. The built-in [random()] SQL function is an example of a - * function that is not deterministic. The SQLite query planner is able to - * perform additional optimizations on deterministic functions, so use - * of the [SQLITE_DETERMINISTIC] flag is recommended where possible. - * - * ^(The fifth parameter is an arbitrary pointer. The implementation of the - * function can gain access to this pointer using [sqlite3_user_data()].)^ - * - * ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are - * pointers to C-language functions that implement the SQL function or - * aggregate. ^A scalar SQL function requires an implementation of the xFunc - * callback only; NULL pointers must be passed as the xStep and xFinal - * parameters. ^An aggregate SQL function requires an implementation of xStep - * and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing - * SQL function or aggregate, pass NULL pointers for all three function - * callbacks. - * - * ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL, - * then it is destructor for the application data pointer. - * The destructor is invoked when the function is deleted, either by being - * overloaded or when the database connection closes.)^ - * ^The destructor is also invoked if the call to - * sqlite3_create_function_v2() fails. - * ^When the destructor callback of the tenth parameter is invoked, it - * is passed a single argument which is a copy of the application data - * pointer which was the fifth parameter to sqlite3_create_function_v2(). - * - * ^It is permitted to register multiple implementations of the same - * functions with the same name but with either differing numbers of - * arguments or differing preferred text encodings. ^SQLite will use - * the implementation that most closely matches the way in which the - * SQL function is used. ^A function implementation with a non-negative - * nArg parameter is a better match than a function implementation with - * a negative nArg. ^A function where the preferred text encoding - * matches the database encoding is a better - * match than a function where the encoding is different. - * ^A function where the encoding difference is between UTF16le and UTF16be - * is a closer match than a function where the encoding difference is - * between UTF8 and UTF16. - * - * ^Built-in functions may be overloaded by new application-defined functions. - * - * ^An application-defined function is permitted to call other - * SQLite interfaces. However, such calls must not - * close the database connection nor finalize or reset the prepared - * statement in which the function is running. -*/ -SQLITE_API int -sqlite3_create_function(sqlite3 * db, - const char *zFunctionName, - int nArg, - int flags, - void *pApp, - void (*xFunc) (sqlite3_context *, - int, - sqlite3_value **), - void (*xStep) (sqlite3_context *, - int, - sqlite3_value **), - void (*xFinal) (sqlite3_context *) - ); - - -SQLITE_API int -sqlite3_create_function_v2(sqlite3 * db, - const char *zFunctionName, - int nArg, - int flags, - void *pApp, - void (*xFunc) (sqlite3_context *, - int, - sqlite3_value **), - void (*xStep) (sqlite3_context *, - int, - sqlite3_value **), - void (*xFinal) - (sqlite3_context *), - void (*xDestroy) (void *) - ); - -/* - * CAPI3REF: Function Flags - * - * These constants may be ORed together with the - * [SQLITE_UTF8 | preferred text encoding] as the fourth argument - * to [sqlite3_create_function()], [sqlite3_create_function16()], or - * [sqlite3_create_function_v2()]. -*/ -#define SQLITE_DETERMINISTIC 0x800 - -/* - * CAPI3REF: Obtaining SQL Values - * METHOD: sqlite3_value - * - * The C-language implementation of SQL functions and aggregates uses - * this set of interface routines to access the parameter values on - * the function or aggregate. - * - * The xFunc (for scalar functions) or xStep (for aggregates) parameters - * to [sqlite3_create_function()] and [sqlite3_create_function16()] - * define callbacks that implement the SQL functions and aggregates. - * The 3rd parameter to these callbacks is an array of pointers to - * [protected sqlite3_value] objects. There is one [sqlite3_value] object for - * each parameter to the SQL function. These routines are used to - * extract values from the [sqlite3_value] objects. - * - * These routines work only with [protected sqlite3_value] objects. - * Any attempt to use these routines on an [unprotected sqlite3_value] - * object results in undefined behavior. - * - * ^These routines work just like the corresponding [column access functions] - * except that these routines take a single [protected sqlite3_value] object - * pointer instead of a [sqlite3_stmt*] pointer and an integer column number. - * - * ^The sqlite3_value_text16() interface extracts a UTF-16 string - * in the native byte-order of the host machine. ^The - * sqlite3_value_text16be() and sqlite3_value_text16le() interfaces - * extract UTF-16 strings as big-endian and little-endian respectively. - * - * ^(The sqlite3_value_numeric_type() interface attempts to apply - * numeric affinity to the value. This means that an attempt is - * made to convert the value to an integer or floating point. If - * such a conversion is possible without loss of information (in other - * words, if the value is a string that looks like a number) - * then the conversion is performed. Otherwise no conversion occurs. - * The [SQLITE_INTEGER | datatype] after conversion is returned.)^ - * - * Please pay particular attention to the fact that the pointer returned - * from [sqlite3_value_blob()], [sqlite3_value_text()], or - * [sqlite3_value_text16()] can be invalidated by a subsequent call to - * [sqlite3_value_bytes()], [sqlite3_value_text()]. - * - * These routines must be called from the same thread as - * the SQL function that supplied the [sqlite3_value*] parameters. -*/ -SQLITE_API const void * -sqlite3_value_blob(sqlite3_value *); - -SQLITE_API int -sqlite3_value_bytes(sqlite3_value *); - -SQLITE_API double -sqlite3_value_double(sqlite3_value *); - -SQLITE_API int -sqlite3_value_int(sqlite3_value *); - -SQLITE_API sqlite3_int64 -sqlite3_value_int64(sqlite3_value *); - -SQLITE_API const unsigned char * -sqlite3_value_text(sqlite3_value *); - -SQLITE_API int -sqlite3_value_type(sqlite3_value *); - -SQLITE_API int -sqlite3_value_numeric_type(sqlite3_value *); - -/* - * CAPI3REF: Finding The Subtype Of SQL Values - * METHOD: sqlite3_value - * - * The sqlite3_value_subtype(V) function returns the subtype for - * an [application-defined SQL function] argument V. The subtype - * information can be used to pass a limited amount of context from - * one SQL function to another. Use the [sqlite3_result_subtype()] - * routine to set the subtype for the return value of an SQL function. - * - * SQLite makes no use of subtype itself. It merely passes the subtype - * from the result of one [application-defined SQL function] into the - * input of another. -*/ -SQLITE_API unsigned int -sqlite3_value_subtype(sqlite3_value *); - -/* - * CAPI3REF: Copy And Free SQL Values - * METHOD: sqlite3_value - * - * ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value] - * object D and returns a pointer to that copy. ^The [sqlite3_value] returned - * is a [protected sqlite3_value] object even if the input is not. - * ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a - * memory allocation fails. - * - * ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object - * previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer - * then sqlite3_value_free(V) is a harmless no-op. -*/ -SQLITE_API sqlite3_value * -sqlite3_value_dup(const sqlite3_value *); - -SQLITE_API void -sqlite3_value_free(sqlite3_value *); - -/* - * CAPI3REF: Obtain Aggregate Function Context - * METHOD: sqlite3_context - * - * Implementations of aggregate SQL functions use this - * routine to allocate memory for storing their state. - * - * ^The first time the sqlite3_aggregate_context(C,N) routine is called - * for a particular aggregate function, SQLite - * allocates N of memory, zeroes out that memory, and returns a pointer - * to the new memory. ^On second and subsequent calls to - * sqlite3_aggregate_context() for the same aggregate function instance, - * the same buffer is returned. Sqlite3_aggregate_context() is normally - * called once for each invocation of the xStep callback and then one - * last time when the xFinal callback is invoked. ^(When no rows match - * an aggregate query, the xStep() callback of the aggregate function - * implementation is never called and xFinal() is called exactly once. - * In those cases, sqlite3_aggregate_context() might be called for the - * first time from within xFinal().)^ - * - * ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer - * when first called if N is less than or equal to zero or if a memory - * allocate error occurs. - * - * ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is - * determined by the N parameter on first successful call. Changing the - * value of N in subsequent call to sqlite3_aggregate_context() within - * the same aggregate function instance will not resize the memory - * allocation.)^ Within the xFinal callback, it is customary to set - * N=0 in calls to sqlite3_aggregate_context(C,N) so that no - * pointless memory allocations occur. - * - * ^SQLite automatically frees the memory allocated by - * sqlite3_aggregate_context() when the aggregate query concludes. - * - * The first parameter must be a copy of the - * [sqlite3_context | SQL function context] that is the first parameter - * to the xStep or xFinal callback routine that implements the aggregate - * function. - * - * This routine must be called from the same thread in which - * the aggregate SQL function is running. -*/ -SQLITE_API void * -sqlite3_aggregate_context(sqlite3_context *, - int nBytes); - -/* - * CAPI3REF: User Data For Functions - * METHOD: sqlite3_context - * - * ^The sqlite3_user_data() interface returns a copy of - * the pointer that was the pUserData parameter (the 5th parameter) - * of the [sqlite3_create_function()] - * and [sqlite3_create_function16()] routines that originally - * registered the application defined function. - * - * This routine must be called from the same thread in which - * the application-defined function is running. -*/ -SQLITE_API void * -sqlite3_user_data(sqlite3_context *); - -/* - * CAPI3REF: Database Connection For Functions - * METHOD: sqlite3_context - * - * ^The sqlite3_context_db_handle() interface returns a copy of - * the pointer to the [database connection] (the 1st parameter) - * of the [sqlite3_create_function()] - * and [sqlite3_create_function16()] routines that originally - * registered the application defined function. -*/ -SQLITE_API sqlite3 * -sqlite3_context_db_handle(sqlite3_context *); - -/* - * CAPI3REF: Function Auxiliary Data - * METHOD: sqlite3_context - * - * These functions may be used by (non-aggregate) SQL functions to - * associate metadata with argument values. If the same value is passed to - * multiple invocations of the same SQL function during query execution, under - * some circumstances the associated metadata may be preserved. An example - * of where this might be useful is in a regular-expression matching - * function. The compiled version of the regular expression can be stored as - * metadata associated with the pattern string. - * Then as long as the pattern string remains the same, - * the compiled regular expression can be reused on multiple - * invocations of the same function. - * - * ^The sqlite3_get_auxdata() interface returns a pointer to the metadata - * associated by the sqlite3_set_auxdata() function with the Nth argument - * value to the application-defined function. ^If there is no metadata - * associated with the function argument, this sqlite3_get_auxdata() interface - * returns a NULL pointer. - * - * ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th - * argument of the application-defined function. ^Subsequent - * calls to sqlite3_get_auxdata(C,N) return P from the most recent - * sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or - * NULL if the metadata has been discarded. - * ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL, - * SQLite will invoke the destructor function X with parameter P exactly - * once, when the metadata is discarded. - * SQLite is free to discard the metadata at any time, including:
    - *
  • ^(when the corresponding function parameter changes)^, or - *
  • ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the - * SQL statement)^, or - *
  • ^(when sqlite3_set_auxdata() is invoked again on the same - * parameter)^, or - *
  • ^(during the original sqlite3_set_auxdata() call when a memory - * allocation error occurs.)^
- * - * Note the last bullet in particular. The destructor X in - * sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the - * sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata() - * should be called near the end of the function implementation and the - * function implementation should not make any use of P after - * sqlite3_set_auxdata() has been called. - * - * ^(In practice, metadata is preserved between function calls for - * function parameters that are compile-time constants, including literal - * values and [parameters] and expressions composed from the same.)^ - * - * These routines must be called from the same thread in which - * the SQL function is running. -*/ -SQLITE_API void * -sqlite3_get_auxdata(sqlite3_context *, int N); - -SQLITE_API void -sqlite3_set_auxdata(sqlite3_context *, int N, void *, - void (*)(void *)); - -/* - * CAPI3REF: Constants Defining Special Destructor Behavior - * - * These are special values for the destructor that is passed in as the - * final argument to routines like [sqlite3_result_blob()]. ^If the destructor - * argument is SQLITE_STATIC, it means that the content pointer is constant - * and will never change. It does not need to be destroyed. ^The - * SQLITE_TRANSIENT value means that the content will likely change in - * the near future and that SQLite should make its own private copy of - * the content before returning. - * - * The typedef is necessary to work around problems in certain - * C++ compilers. -*/ -typedef void (*sqlite3_destructor_type) (void *); -#define SQLITE_STATIC ((sqlite3_destructor_type)0) -#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) - -/* - * CAPI3REF: Setting The Result Of An SQL Function - * METHOD: sqlite3_context - * - * These routines are used by the xFunc or xFinal callbacks that - * implement SQL functions and aggregates. See - * [sqlite3_create_function()] and [sqlite3_create_function16()] - * for additional information. - * - * These functions work very much like the [parameter binding] family of - * functions used to bind values to host parameters in prepared statements. - * Refer to the [SQL parameter] documentation for additional information. - * - * ^The sqlite3_result_blob() interface sets the result from - * an application-defined function to be the BLOB whose content is pointed - * to by the second parameter and which is N bytes long where N is the - * third parameter. - * - * ^The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N) - * interfaces set the result of the application-defined function to be - * a BLOB containing all zero bytes and N bytes in size. - * - * ^The sqlite3_result_double() interface sets the result from - * an application-defined function to be a floating point value specified - * by its 2nd argument. - * - * ^The sqlite3_result_error() - * cause the implemented SQL function to throw an exception. - * ^SQLite uses the string pointed to by the - * 2nd parameter of sqlite3_result_error() as the text of an error message. ^SQLite interprets the error - * message string from sqlite3_result_error() as UTF-8. - * ^If the third parameter to sqlite3_result_error() - * negative then SQLite takes as the error - * message all text up through the first zero character. - * ^If the third parameter to sqlite3_result_error() or - * sqlite3_result_error16() is non-negative then SQLite takes that many - * bytes (not characters) from the 2nd parameter as the error message. - * ^The sqlite3_result_error() and sqlite3_result_error16() - * routines make a private copy of the error message text before - * they return. Hence, the calling function can deallocate or - * modify the text after they return without harm. - * ^The sqlite3_result_error_code() function changes the error code - * returned by SQLite as a result of an error in a function. ^By default, - * the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error() - * or sqlite3_result_error16() resets the error code to SQLITE_ERROR. - * - * ^The sqlite3_result_error_toobig() interface causes SQLite to throw an - * error indicating that a string or BLOB is too long to represent. - * - * ^The sqlite3_result_error_nomem() interface causes SQLite to throw an - * error indicating that a memory allocation failed. - * - * ^The sqlite3_result_int() interface sets the return value - * of the application-defined function to be the 32-bit signed integer - * value given in the 2nd argument. - * ^The sqlite3_result_int64() interface sets the return value - * of the application-defined function to be the 64-bit signed integer - * value given in the 2nd argument. - * - * ^The sqlite3_result_null() interface sets the return value - * of the application-defined function to be NULL. - * - * ^The sqlite3_result_text() - * set the return value of the application-defined function to be - * a text string which is represented as UTF-8, UTF-16 native byte order, - * UTF-16 little endian, or UTF-16 big endian, respectively. - * ^The sqlite3_result_text64() interface sets the return value of an - * application-defined function to be a text string in an encoding - * specified by the fifth (and last) parameter, which must be one - * of [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]. - * ^SQLite takes the text result from the application from - * the 2nd parameter of the sqlite3_result_text* interfaces. - * ^If the 3rd parameter to the sqlite3_result_text* interfaces - * is negative, then SQLite takes result text from the 2nd parameter - * through the first zero character. - * ^If the 3rd parameter to the sqlite3_result_text* interfaces - * is non-negative, then as many bytes (not characters) of the text - * pointed to by the 2nd parameter are taken as the application-defined - * function result. If the 3rd parameter is non-negative, then it - * must be the byte offset into the string where the NUL terminator would - * appear if the string where NUL terminated. If any NUL characters occur - * in the string at a byte offset that is less than the value of the 3rd - * parameter, then the resulting string will contain embedded NULs and the - * result of expressions operating on strings with embedded NULs is undefined. - * ^If the 4th parameter to the sqlite3_result_text* interfaces - * or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that - * function as the destructor on the text or BLOB result when it has - * finished using that result. - * ^If the 4th parameter to the sqlite3_result_text* interfaces or to - * sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite - * assumes that the text or BLOB result is in constant space and does not - * copy the content of the parameter nor call a destructor on the content - * when it has finished using that result. - * ^If the 4th parameter to the sqlite3_result_text* interfaces - * or sqlite3_result_blob is the special constant SQLITE_TRANSIENT - * then SQLite makes a copy of the result into space obtained from - * from [sqlite3_malloc()] before it returns. - * - * ^The sqlite3_result_value() interface sets the result of - * the application-defined function to be a copy of the - * [unprotected sqlite3_value] object specified by the 2nd parameter. ^The - * sqlite3_result_value() interface makes a copy of the [sqlite3_value] - * so that the [sqlite3_value] specified in the parameter may change or - * be deallocated after sqlite3_result_value() returns without harm. - * ^A [protected sqlite3_value] object may always be used where an - * [unprotected sqlite3_value] object is required, so either - * kind of [sqlite3_value] object can be used with this interface. - * - * If these routines are called from within the different thread - * than the one containing the application-defined function that received - * the [sqlite3_context] pointer, the results are undefined. -*/ -SQLITE_API void -sqlite3_result_blob(sqlite3_context *, const void *, - int, void (*)(void *)); - -SQLITE_API void -sqlite3_result_blob64(sqlite3_context *, const void *, - sqlite3_uint64, void (*)(void *)); - -SQLITE_API void -sqlite3_result_double(sqlite3_context *, double); - -SQLITE_API void -sqlite3_result_error(sqlite3_context *, const char *, - int); - -SQLITE_API void -sqlite3_result_error_toobig(sqlite3_context *); - -SQLITE_API void -sqlite3_result_error_nomem(sqlite3_context *); - -SQLITE_API void -sqlite3_result_error_code(sqlite3_context *, int); - -SQLITE_API void -sqlite3_result_int(sqlite3_context *, int); - -SQLITE_API void -sqlite3_result_int64(sqlite3_context *, sqlite3_int64); - -SQLITE_API void -sqlite3_result_null(sqlite3_context *); - -SQLITE_API void -sqlite3_result_text(sqlite3_context *, const char *, - int, void (*)(void *)); - -SQLITE_API void -sqlite3_result_text64(sqlite3_context *, const char *, - sqlite3_uint64, void (*)(void *)); - -SQLITE_API void -sqlite3_result_value(sqlite3_context *, - sqlite3_value *); - -SQLITE_API void -sqlite3_result_zeroblob(sqlite3_context *, int n); - -SQLITE_API int -sqlite3_result_zeroblob64(sqlite3_context *, - sqlite3_uint64 n); - -/* - * CAPI3REF: Setting The Subtype Of An SQL Function - * METHOD: sqlite3_context - * - * The sqlite3_result_subtype(C,T) function causes the subtype of - * the result from the [application-defined SQL function] with - * [sqlite3_context] C to be the value T. Only the lower 8 bits - * of the subtype T are preserved in current versions of SQLite; - * higher order bits are discarded. - * The number of subtype bytes preserved by SQLite might increase - * in future releases of SQLite. -*/ -SQLITE_API void -sqlite3_result_subtype(sqlite3_context *, unsigned int); - -#ifdef SQLITE_HAS_CODEC -/* - * Specify the key for an encrypted database. This routine should be - * called right after sqlite3_open(). - * - * The code to implement this API is not available in the public release - * of SQLite. -*/ -SQLITE_API int -sqlite3_key(sqlite3 * db, /* Database to be rekeyed */ - const void *pKey, int nKey /* The key */ - ); - -SQLITE_API int -sqlite3_key_v2(sqlite3 * db, /* Database to be rekeyed */ - const void *pKey, int nKey /* The key */ - ); - -/* - * Change the key on an open database. If the current database is not - * encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the - * database is decrypted. - * - * The code to implement this API is not available in the public release - * of SQLite. -*/ -SQLITE_API int -sqlite3_rekey(sqlite3 * db, /* Database to be rekeyed */ - const void *pKey, int nKey /* The new key */ - ); - -SQLITE_API int -sqlite3_rekey_v2(sqlite3 * db, /* Database to be rekeyed */ - const void *pKey, int nKey /* The new key */ - ); - -/* - * Specify the activation key for a SEE database. Unless - * activated, none of the SEE routines will work. -*/ -SQLITE_API void -sqlite3_activate_see(const char *zPassPhrase /* Activation phrase */ - ); -#endif - -#ifdef SQLITE_ENABLE_CEROD -/* - * Specify the activation key for a CEROD database. Unless - * activated, none of the CEROD routines will work. -*/ -SQLITE_API void -sqlite3_activate_cerod(const char *zPassPhrase /* Activation phrase */ - ); -#endif - -/* - * CAPI3REF: Suspend Execution For A Short Time - * - * The sqlite3_sleep() function causes the current thread to suspend execution - * for at least a number of milliseconds specified in its parameter. - * - * If the operating system does not support sleep requests with - * millisecond time resolution, then the time will be rounded up to - * the nearest second. The number of milliseconds of sleep actually - * requested from the operating system is returned. - * - * ^SQLite implements this interface by calling the xSleep() - * method of the default [sqlite3_vfs] object. If the xSleep() method - * of the default VFS is not implemented correctly, or not implemented at - * all, then the behavior of sqlite3_sleep() may deviate from the description - * in the previous paragraphs. -*/ -SQLITE_API int -sqlite3_sleep(int); - -/* - * CAPI3REF: Name Of The Folder Holding Temporary Files - * - * ^(If this global variable is made to point to a string which is - * the name of a folder (a.k.a. directory), then all temporary files - * created by SQLite when using a built-in [sqlite3_vfs | VFS] - * will be placed in that directory.)^ ^If this variable - * is a NULL pointer, then SQLite performs a search for an appropriate - * temporary file directory. - * - * Applications are strongly discouraged from using this global variable. - * It is highly recommended that applications - * neither read nor write this variable. This global variable is a relic - * that exists for backwards compatibility of legacy applications and should - * be avoided in new projects. - * - * It is not safe to read or modify this variable in more than one - * thread at a time. It is not safe to read or modify this variable - * if a [database connection] is being used at the same time in a separate - * thread. - * It is intended that this variable be set once - * as part of process initialization and before any SQLite interface - * routines have been called and that this variable remain unchanged - * thereafter. - * - * ^The [temp_store_directory pragma] may modify this variable and cause - * it to point to memory obtained from [sqlite3_malloc]. ^Furthermore, - * the [temp_store_directory pragma] always assumes that any string - * that this variable points to is held in memory obtained from - * [sqlite3_malloc] and the pragma may attempt to free that memory - * using [sqlite3_free]. - * Hence, if this variable is modified directly, either it should be - * made NULL or made to point to memory obtained from [sqlite3_malloc] - * or else the use of the [temp_store_directory pragma] should be avoided. - * Except when requested by the [temp_store_directory pragma], SQLite - * does not free the memory that sqlite3_temp_directory points to. If - * the application wants that memory to be freed, it must do - * so itself, taking care to only do so after all [database connection] - * objects have been destroyed. -*/ -SQLITE_API SQLITE_EXTERN char * -sqlite3_temp_directory; - -/* - * CAPI3REF: Name Of The Folder Holding Database Files - * - * ^(If this global variable is made to point to a string which is - * the name of a folder (a.k.a. directory), then all database files - * specified with a relative pathname and created or accessed by - * SQLite when using a built-in windows [sqlite3_vfs | VFS] will be assumed - * to be relative to that directory.)^ ^If this variable is a NULL - * pointer, then SQLite assumes that all database files specified - * with a relative pathname are relative to the current directory - * for the process. It is ignored by the unix VFS. - * - * Changing the value of this variable while a database connection is - * open can result in a corrupt database. - * - * It is not safe to read or modify this variable in more than one - * thread at a time. It is not safe to read or modify this variable - * if a [database connection] is being used at the same time in a separate - * thread. - * It is intended that this variable be set once - * as part of process initialization and before any SQLite interface - * routines have been called and that this variable remain unchanged - * thereafter. - * - * ^The [data_store_directory pragma] may modify this variable and cause - * it to point to memory obtained from [sqlite3_malloc]. ^Furthermore, - * the [data_store_directory pragma] always assumes that any string - * that this variable points to is held in memory obtained from - * [sqlite3_malloc] and the pragma may attempt to free that memory - * using [sqlite3_free]. - * Hence, if this variable is modified directly, either it should be - * made NULL or made to point to memory obtained from [sqlite3_malloc] - * or else the use of the [data_store_directory pragma] should be avoided. -*/ -SQLITE_API SQLITE_EXTERN char * -sqlite3_data_directory; - -/* - * CAPI3REF: Test For Auto-Commit Mode - * KEYWORDS: {autocommit mode} - * METHOD: sqlite3 - * - * ^The sqlite3_get_autocommit() interface returns non-zero or - * zero if the given database connection is or is not in autocommit mode, - * respectively. ^Autocommit mode is on by default. - * ^Autocommit mode is disabled by a [BEGIN] statement. - * ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK]. - * - * If certain kinds of errors occur on a statement within a multi-statement - * transaction (errors including [SQLITE_FULL], [SQLITE_IOERR], - * [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the - * transaction might be rolled back automatically. The only way to - * find out whether SQLite automatically rolled back the transaction after - * an error is to use this function. - * - * If another thread changes the autocommit status of the database - * connection while this routine is running, then the return value - * is undefined. -*/ -SQLITE_API int -sqlite3_get_autocommit(sqlite3 *); - -/* - * CAPI3REF: Find The Database Handle Of A Prepared Statement - * METHOD: sqlite3_stmt - * - * ^The sqlite3_db_handle interface returns the [database connection] handle - * to which a [prepared statement] belongs. ^The [database connection] - * returned by sqlite3_db_handle is the same [database connection] - * that was the first argument - * to the [sqlite3_prepare_v2()] call (or its variants) that was used to - * create the statement in the first place. -*/ -SQLITE_API sqlite3 * -sqlite3_db_handle(sqlite3_stmt *); - -/* - * CAPI3REF: Return The Filename For A Database Connection - * METHOD: sqlite3 - * - * ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename - * associated with database N of connection D. ^The main database file - * has the name "main". If there is no attached database N on the database - * connection D, or if database N is a temporary or in-memory database, then - * a NULL pointer is returned. - * - * ^The filename returned by this function is the output of the - * xFullPathname method of the [VFS]. ^In other words, the filename - * will be an absolute pathname, even if the filename used - * to open the database originally was a URI or relative pathname. -*/ -SQLITE_API const char * -sqlite3_db_filename(sqlite3 * db); - -/* - * CAPI3REF: Determine if a database is read-only - * METHOD: sqlite3 - * - * ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N - * of connection D is read-only, 0 if it is read/write, or -1 if N is not - * the name of a database on connection D. -*/ -SQLITE_API int -sqlite3_db_readonly(sqlite3 * db); - -/* - * CAPI3REF: Find the next prepared statement - * METHOD: sqlite3 - * - * ^This interface returns a pointer to the next [prepared statement] after - * pStmt associated with the [database connection] pDb. ^If pStmt is NULL - * then this interface returns a pointer to the first prepared statement - * associated with the database connection pDb. ^If no prepared statement - * satisfies the conditions of this routine, it returns NULL. - * - * The [database connection] pointer D in a call to - * [sqlite3_next_stmt(D,S)] must refer to an open database - * connection and in particular must not be a NULL pointer. -*/ -SQLITE_API sqlite3_stmt * -sqlite3_next_stmt(sqlite3 * pDb, - sqlite3_stmt * pStmt); - -/* - * CAPI3REF: Commit And Rollback Notification Callbacks - * METHOD: sqlite3 - * - * ^The sqlite3_commit_hook() interface registers a callback - * function to be invoked whenever a transaction is [COMMIT | committed]. - * ^Any callback set by a previous call to sqlite3_commit_hook() - * for the same database connection is overridden. - * ^The sqlite3_rollback_hook() interface registers a callback - * function to be invoked whenever a transaction is [ROLLBACK | rolled back]. - * ^Any callback set by a previous call to sqlite3_rollback_hook() - * for the same database connection is overridden. - * ^The pArg argument is passed through to the callback. - * ^If the callback on a commit hook function returns non-zero, - * then the commit is converted into a rollback. - * - * ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions - * return the P argument from the previous call of the same function - * on the same [database connection] D, or NULL for - * the first call for each function on D. - * - * The commit and rollback hook callbacks are not reentrant. - * The callback implementation must not do anything that will modify - * the database connection that invoked the callback. Any actions - * to modify the database connection must be deferred until after the - * completion of the [sqlite3_step()] call that triggered the commit - * or rollback hook in the first place. - * Note that running any other SQL statements, including SELECT statements, - * or merely calling [sqlite3_prepare_v2()] and [sqlite3_step()] will modify - * the database connections for the meaning of "modify" in this paragraph. - * - * ^Registering a NULL function disables the callback. - * - * ^When the commit hook callback routine returns zero, the [COMMIT] - * operation is allowed to continue normally. ^If the commit hook - * returns non-zero, then the [COMMIT] is converted into a [ROLLBACK]. - * ^The rollback hook is invoked on a rollback that results from a commit - * hook returning non-zero, just as it would be with any other rollback. - * - * ^For the purposes of this API, a transaction is said to have been - * rolled back if an explicit "ROLLBACK" statement is executed, or - * an error or constraint causes an implicit rollback to occur. - * ^The rollback callback is not invoked if a transaction is - * automatically rolled back because the database connection is closed. - * - * See also the [sqlite3_update_hook()] interface. -*/ -SQLITE_API void * -sqlite3_commit_hook(sqlite3 *, int (*)(void *), - void *); - -SQLITE_API void * -sqlite3_rollback_hook(sqlite3 *, void (*)(void *), - void *); - -/* - * CAPI3REF: Enable Or Disable Shared Pager Cache - * - * ^(This routine enables or disables the sharing of the database cache - * and schema data structures between [database connection | connections] - * to the same database. Sharing is enabled if the argument is true - * and disabled if the argument is false.)^ - * - * ^Cache sharing is enabled and disabled for an entire process. - * This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]). - * In prior versions of SQLite, - * sharing was enabled or disabled for each thread separately. - * - * ^(The cache sharing mode set by this interface effects all subsequent - * calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. - * Existing database connections continue use the sharing mode - * that was in effect at the time they were opened.)^ - * - * ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled - * successfully. An [error code] is returned otherwise.)^ - * - * ^Shared cache is disabled by default. But this might change in - * future releases of SQLite. Applications that care about shared - * cache setting should set it explicitly. - * - * Note: This method is disabled on MacOS X 10.7 and iOS version 5.0 - * and will always return SQLITE_MISUSE. On those systems, - * shared cache mode should be enabled per-database connection via - * [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE]. - * - * This interface is threadsafe on processors where writing a - * 32-bit integer is atomic. - * - * See Also: [SQLite Shared-Cache Mode] -*/ -SQLITE_API int -sqlite3_enable_shared_cache(int); - -/* - * CAPI3REF: Attempt To Free Heap Memory - * - * ^The sqlite3_release_memory() interface attempts to free N bytes - * of heap memory by deallocating non-essential memory allocations - * held by the database library. Memory used to cache database - * pages to improve performance is an example of non-essential memory. - * ^sqlite3_release_memory() returns the number of bytes actually freed, - * which might be more or less than the amount requested. - * ^The sqlite3_release_memory() routine is a no-op returning zero - * if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT]. - * - * See also: [sqlite3_db_release_memory()] -*/ -SQLITE_API int -sqlite3_release_memory(int); - -/* - * CAPI3REF: Free Memory Used By A Database Connection - * METHOD: sqlite3 - * - * ^The sqlite3_db_release_memory(D) interface attempts to free as much heap - * memory as possible from database connection D. Unlike the - * [sqlite3_release_memory()] interface, this interface is in effect even - * when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is - * omitted. - * - * See also: [sqlite3_release_memory()] -*/ -SQLITE_API int -sqlite3_db_release_memory(sqlite3 *); - -/* - * CAPI3REF: Impose A Limit On Heap Size - * - * ^The sqlite3_soft_heap_limit64() interface sets and/or queries the - * soft limit on the amount of heap memory that may be allocated by SQLite. - * ^SQLite strives to keep heap memory utilization below the soft heap - * limit by reducing the number of pages held in the page cache - * as heap memory usages approaches the limit. - * ^The soft heap limit is "soft" because even though SQLite strives to stay - * below the limit, it will exceed the limit rather than generate - * an [SQLITE_NOMEM] error. In other words, the soft heap limit - * is advisory only. - * - * ^The return value from sqlite3_soft_heap_limit64() is the size of - * the soft heap limit prior to the call, or negative in the case of an - * error. ^If the argument N is negative - * then no change is made to the soft heap limit. Hence, the current - * size of the soft heap limit can be determined by invoking - * sqlite3_soft_heap_limit64() with a negative argument. - * - * ^If the argument N is zero then the soft heap limit is disabled. - * - * ^(The soft heap limit is not enforced in the current implementation - * if one or more of following conditions are true: - * - *
    - *
  • The soft heap limit is set to zero. - *
  • Memory accounting is disabled using a combination of the - * [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and - * the [SQLITE_DEFAULT_MEMSTATUS] compile-time option. - *
  • An alternative page cache implementation is specified using - * [sqlite3_config]([SQLITE_CONFIG_PCACHE2],...). - *
  • The page cache allocates from its own memory pool supplied - * by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than - * from the heap. - *
)^ - * - * Beginning with SQLite [version 3.7.3] ([dateof:3.7.3]), - * the soft heap limit is enforced - * regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT] - * compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT], - * the soft heap limit is enforced on every memory allocation. Without - * [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced - * when memory is allocated by the page cache. Testing suggests that because - * the page cache is the predominate memory user in SQLite, most - * applications will achieve adequate soft heap limit enforcement without - * the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT]. - * - * The circumstances under which SQLite will enforce the soft heap limit may - * changes in future releases of SQLite. -*/ -SQLITE_API sqlite3_int64 -sqlite3_soft_heap_limit64(sqlite3_int64 N); - -/* - * CAPI3REF: Extract Metadata About A Column Of A Table - * METHOD: sqlite3 - * - * ^(The sqlite3_table_column_metadata(X,D,T,C,....) routine returns - * information about column C of table T in database D - * on [database connection] X.)^ ^The sqlite3_table_column_metadata() - * interface returns SQLITE_OK and fills in the non-NULL pointers in - * the final five arguments with appropriate values if the specified - * column exists. ^The sqlite3_table_column_metadata() interface returns - * SQLITE_ERROR and if the specified column does not exist. - * ^If the column-name parameter to sqlite3_table_column_metadata() is a - * NULL pointer, then this routine simply checks for the existence of the - * table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it - * does not. - * - * ^The column is identified by the second, third and fourth parameters to - * this function. ^(The second parameter is either the name of the database - * (i.e. "main", "temp", or an attached database) containing the specified - * table or NULL.)^ ^If it is NULL, then all attached databases are searched - * for the table using the same algorithm used by the database engine to - * resolve unqualified table references. - * - * ^The third and fourth parameters to this function are the table and column - * name of the desired column, respectively. - * - * ^Metadata is returned by writing to the memory locations passed as the 5th - * and subsequent parameters to this function. ^Any of these arguments may be - * NULL, in which case the corresponding element of metadata is omitted. - * - * ^(
- * - *
Parameter Output
Type 		Description - * - *
5th const char* Data type - *
6th const char* Name of default collation sequence - *
7th int True if column has a NOT NULL constraint - *
8th int True if column is part of the PRIMARY KEY - *
9th int True if column is [AUTOINCREMENT] - *
- *
)^ - * - * ^The memory pointed to by the character pointers returned for the - * declaration type and collation sequence is valid until the next - * call to any SQLite API function. - * - * ^If the specified table is actually a view, an [error code] is returned. - * - * ^This function causes all database schemas to be read from disk and - * parsed, if that has not already been done, and returns an error if - * any errors are encountered while loading the schema. -*/ -SQLITE_API int -sqlite3_table_column_metadata(sqlite3 * db, - const char *zTableName, - const char *zColumnName, - char const **pzDataType, - char const **pzCollSeq, - int *pNotNull, - int *pPrimaryKey, - int *pAutoinc); - -/* - * CAPI3REF: A Handle To An Open BLOB - * KEYWORDS: {BLOB handle} {BLOB handles} - * - * An instance of this object represents an open BLOB on which - * [sqlite3_blob_open | incremental BLOB I/O] can be performed. - * ^Objects of this type are created by [sqlite3_blob_open()] - * and destroyed by [sqlite3_blob_close()]. - * ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces - * can be used to read or write small subsections of the BLOB. - * ^The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes. -*/ -typedef struct sqlite3_blob sqlite3_blob; - -/* - * CAPI3REF: Close A BLOB Handle - * DESTRUCTOR: sqlite3_blob - * - * ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed - * unconditionally. Even if this routine returns an error code, the - * handle is still closed.)^ - * - * ^If the blob handle being closed was opened for read-write access, and if - * the database is in auto-commit mode and there are no other open read-write - * blob handles or active write statements, the current transaction is - * committed. ^If an error occurs while committing the transaction, an error - * code is returned and the transaction rolled back. - * - * Calling this function with an argument that is not a NULL pointer or an - * open blob handle results in undefined behaviour. ^Calling this routine - * with a null pointer (such as would be returned by a failed call to - * [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function - * is passed a valid open blob handle, the values returned by the - * sqlite3_errcode() and sqlite3_errmsg() functions are set before returning. -*/ -SQLITE_API int -sqlite3_blob_close(sqlite3_blob *); - -/* - * CAPI3REF: Return The Size Of An Open BLOB - * METHOD: sqlite3_blob - * - * ^Returns the size in bytes of the BLOB accessible via the - * successfully opened [BLOB handle] in its only argument. ^The - * incremental blob I/O routines can only read or overwriting existing - * blob content; they cannot change the size of a blob. - * - * This routine only works on a [BLOB handle] which has been created - * by a prior successful call to [sqlite3_blob_open()] and which has not - * been closed by [sqlite3_blob_close()]. Passing any other pointer in - * to this routine results in undefined and probably undesirable behavior. -*/ -SQLITE_API int -sqlite3_blob_bytes(sqlite3_blob *); - -/* - * CAPI3REF: Read Data From A BLOB Incrementally - * METHOD: sqlite3_blob - * - * ^(This function is used to read data from an open [BLOB handle] into a - * caller-supplied buffer. N bytes of data are copied into buffer Z - * from the open BLOB, starting at offset iOffset.)^ - * - * ^If offset iOffset is less than N bytes from the end of the BLOB, - * [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is - * less than zero, [SQLITE_ERROR] is returned and no data is read. - * ^The size of the blob (and hence the maximum value of N+iOffset) - * can be determined using the [sqlite3_blob_bytes()] interface. - * - * ^An attempt to read from an expired [BLOB handle] fails with an - * error code of [SQLITE_ABORT]. - * - * ^(On success, sqlite3_blob_read() returns SQLITE_OK. - * Otherwise, an [error code] or an [extended error code] is returned.)^ - * - * This routine only works on a [BLOB handle] which has been created - * by a prior successful call to [sqlite3_blob_open()] and which has not - * been closed by [sqlite3_blob_close()]. Passing any other pointer in - * to this routine results in undefined and probably undesirable behavior. - * - * See also: [sqlite3_blob_write()]. -*/ -SQLITE_API int -sqlite3_blob_read(sqlite3_blob *, void *Z, int N, - int iOffset); - -/* - * CAPI3REF: Write Data Into A BLOB Incrementally - * METHOD: sqlite3_blob - * - * ^(This function is used to write data into an open [BLOB handle] from a - * caller-supplied buffer. N bytes of data are copied from the buffer Z - * into the open BLOB, starting at offset iOffset.)^ - * - * ^(On success, sqlite3_blob_write() returns SQLITE_OK. - * Otherwise, an [error code] or an [extended error code] is returned.)^ - * ^Unless SQLITE_MISUSE is returned, this function sets the - * [database connection] error code and message accessible via - * [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions. - * - * ^If the [BLOB handle] passed as the first argument was not opened for - * writing (the flags parameter to [sqlite3_blob_open()] was zero), - * this function returns [SQLITE_READONLY]. - * - * This function may only modify the contents of the BLOB; it is - * not possible to increase the size of a BLOB using this API. - * ^If offset iOffset is less than N bytes from the end of the BLOB, - * [SQLITE_ERROR] is returned and no data is written. The size of the - * BLOB (and hence the maximum value of N+iOffset) can be determined - * using the [sqlite3_blob_bytes()] interface. ^If N or iOffset are less - * than zero [SQLITE_ERROR] is returned and no data is written. - * - * ^An attempt to write to an expired [BLOB handle] fails with an - * error code of [SQLITE_ABORT]. ^Writes to the BLOB that occurred - * before the [BLOB handle] expired are not rolled back by the - * expiration of the handle, though of course those changes might - * have been overwritten by the statement that expired the BLOB handle - * or by other independent statements. - * - * This routine only works on a [BLOB handle] which has been created - * by a prior successful call to [sqlite3_blob_open()] and which has not - * been closed by [sqlite3_blob_close()]. Passing any other pointer in - * to this routine results in undefined and probably undesirable behavior. - * - * See also: [sqlite3_blob_read()]. -*/ -SQLITE_API int -sqlite3_blob_write(sqlite3_blob *, const void *z, int n, - int iOffset); - -/* - * CAPI3REF: Virtual File System Objects - * - * A virtual filesystem (VFS) is an [sqlite3_vfs] object - * that SQLite uses to interact - * with the underlying operating system. Most SQLite builds come with a - * single default VFS that is appropriate for the host computer. - * New VFSes can be registered and existing VFSes can be unregistered. - * The following interfaces are provided. - * - * ^The sqlite3_vfs_find() interface returns a pointer to a VFS given its name. - * ^Names are case sensitive. - * ^Names are zero-terminated UTF-8 strings. - * ^If there is no match, a NULL pointer is returned. - * ^If zVfsName is NULL then the default VFS is returned. - * - * ^New VFSes are registered with sqlite3_vfs_register(). - * ^Each new VFS becomes the default VFS if the makeDflt flag is set. - * ^The same VFS can be registered multiple times without injury. - * ^To make an existing VFS into the default VFS, register it again - * with the makeDflt flag set. If two different VFSes with the - * same name are registered, the behavior is undefined. If a - * VFS is registered with a name that is NULL or an empty string, - * then the behavior is undefined. - * - * ^Unregister a VFS with the sqlite3_vfs_unregister() interface. - * ^(If the default VFS is unregistered, another VFS is chosen as - * the default. The choice for the new VFS is arbitrary.)^ -*/ -SQLITE_API sqlite3_vfs * -sqlite3_vfs_find(const char *zVfsName); - -SQLITE_API int -sqlite3_vfs_register(sqlite3_vfs *, int makeDflt); - -SQLITE_API int -sqlite3_vfs_unregister(sqlite3_vfs *); - -/* - * CAPI3REF: Mutexes - * - * The SQLite core uses these routines for thread - * synchronization. Though they are intended for internal - * use by SQLite, code that links against SQLite is - * permitted to use any of these routines. - * - * The SQLite source code contains multiple implementations - * of these mutex routines. An appropriate implementation - * is selected automatically at compile-time. The following - * implementations are available in the SQLite core: - * - *
    - *
  • SQLITE_MUTEX_PTHREADS - *
  • SQLITE_MUTEX_W32 - *
  • SQLITE_MUTEX_NOOP - *
- * - * The SQLITE_MUTEX_NOOP implementation is a set of routines - * that does no real locking and is appropriate for use in - * a single-threaded application. - * - * If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor - * macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex - * implementation is included with the library. In this case the - * application must supply a custom mutex implementation using the - * [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function - * before calling sqlite3_initialize() or any other public sqlite3_ - * function that calls sqlite3_initialize(). - * - * ^The sqlite3_mutex_alloc() routine allocates a new - * mutex and returns a pointer to it. ^The sqlite3_mutex_alloc() - * routine returns NULL if it is unable to allocate the requested - * mutex. The argument to sqlite3_mutex_alloc() must one of these - * integer constants: - * - *
    - *
  • SQLITE_MUTEX_FAST - *
  • SQLITE_MUTEX_RECURSIVE - *
  • SQLITE_MUTEX_STATIC_MASTER - *
  • SQLITE_MUTEX_STATIC_MEM - *
  • SQLITE_MUTEX_STATIC_OPEN - *
  • SQLITE_MUTEX_STATIC_PRNG - *
  • SQLITE_MUTEX_STATIC_LRU - *
  • SQLITE_MUTEX_STATIC_PMEM - *
  • SQLITE_MUTEX_STATIC_APP1 - *
  • SQLITE_MUTEX_STATIC_APP2 - *
  • SQLITE_MUTEX_STATIC_APP3 - *
  • SQLITE_MUTEX_STATIC_VFS1 - *
  • SQLITE_MUTEX_STATIC_VFS2 - *
  • SQLITE_MUTEX_STATIC_VFS3 - *
- * - * ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) - * cause sqlite3_mutex_alloc() to create - * a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE - * is used but not necessarily so when SQLITE_MUTEX_FAST is used. - * The mutex implementation does not need to make a distinction - * between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does - * not want to. SQLite will only request a recursive mutex in - * cases where it really needs one. If a faster non-recursive mutex - * implementation is available on the host platform, the mutex subsystem - * might return such a mutex in response to SQLITE_MUTEX_FAST. - * - * ^The other allowed parameters to sqlite3_mutex_alloc() (anything other - * than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return - * a pointer to a static preexisting mutex. ^Nine static mutexes are - * used by the current version of SQLite. Future versions of SQLite - * may add additional static mutexes. Static mutexes are for internal - * use by SQLite only. Applications that use SQLite mutexes should - * use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or - * SQLITE_MUTEX_RECURSIVE. - * - * ^Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST - * or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() - * returns a different mutex on every call. ^For the static - * mutex types, the same mutex is returned on every call that has - * the same type number. - * - * ^The sqlite3_mutex_free() routine deallocates a previously - * allocated dynamic mutex. Attempting to deallocate a static - * mutex results in undefined behavior. - * - * ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt - * to enter a mutex. ^If another thread is already within the mutex, - * sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return - * SQLITE_BUSY. ^The sqlite3_mutex_try() interface returns [SQLITE_OK] - * upon successful entry. ^(Mutexes created using - * SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. - * In such cases, the - * mutex must be exited an equal number of times before another thread - * can enter.)^ If the same thread tries to enter any mutex other - * than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined. - * - * ^The sqlite3_mutex_leave() routine exits a mutex that was - * previously entered by the same thread. The behavior - * is undefined if the mutex is not currently entered by the - * calling thread or is not currently allocated. - * - * ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or - * sqlite3_mutex_leave() is a NULL pointer, then all three routines - * behave as no-ops. - * - * See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. -*/ -SQLITE_API sqlite3_mutex * -sqlite3_mutex_alloc(int); - -SQLITE_API void -sqlite3_mutex_free(sqlite3_mutex *); - -SQLITE_API void -sqlite3_mutex_enter(sqlite3_mutex *); - -SQLITE_API int -sqlite3_mutex_try(sqlite3_mutex *); - -SQLITE_API void -sqlite3_mutex_leave(sqlite3_mutex *); - -/* - * CAPI3REF: Mutex Methods Object - * - * An instance of this structure defines the low-level routines - * used to allocate and use mutexes. - * - * Usually, the default mutex implementations provided by SQLite are - * sufficient, however the application has the option of substituting a custom - * implementation for specialized deployments or systems for which SQLite - * does not provide a suitable implementation. In this case, the application - * creates and populates an instance of this structure to pass - * to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option. - * Additionally, an instance of this structure can be used as an - * output variable when querying the system for the current mutex - * implementation, using the [SQLITE_CONFIG_GETMUTEX] option. - * - * ^The xMutexInit method defined by this structure is invoked as - * part of system initialization by the sqlite3_initialize() function. - * ^The xMutexInit routine is called by SQLite exactly once for each - * effective call to [sqlite3_initialize()]. - * - * ^The xMutexEnd method defined by this structure is invoked as - * part of system shutdown by the sqlite3_shutdown() function. The - * implementation of this method is expected to release all outstanding - * resources obtained by the mutex methods implementation, especially - * those obtained by the xMutexInit method. ^The xMutexEnd() - * interface is invoked exactly once for each call to [sqlite3_shutdown()]. - * - * ^(The remaining seven methods defined by this structure (xMutexAlloc, - * xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and - * xMutexNotheld) implement the following interfaces (respectively): - * - *
    - *
  • [sqlite3_mutex_alloc()]
    • - *
  • [sqlite3_mutex_free()]
    • - *
  • [sqlite3_mutex_enter()]
    • - *
  • [sqlite3_mutex_try()]
    • - *
  • [sqlite3_mutex_leave()]
    • - *
  • [sqlite3_mutex_held()]
    • - *
  • [sqlite3_mutex_notheld()]
    • - *
)^ - * - * The only difference is that the public sqlite3_XXX functions enumerated - * above silently ignore any invocations that pass a NULL pointer instead - * of a valid mutex handle. The implementations of the methods defined - * by this structure are not required to handle this case, the results - * of passing a NULL pointer instead of a valid mutex handle are undefined - * (i.e. it is acceptable to provide an implementation that segfaults if - * it is passed a NULL pointer). - * - * The xMutexInit() method must be threadsafe. It must be harmless to - * invoke xMutexInit() multiple times within the same process and without - * intervening calls to xMutexEnd(). Second and subsequent calls to - * xMutexInit() must be no-ops. - * - * xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()] - * and its associates). Similarly, xMutexAlloc() must not use SQLite memory - * allocation for a static mutex. ^However xMutexAlloc() may use SQLite - * memory allocation for a fast or recursive mutex. - * - * ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is - * called, but only if the prior call to xMutexInit returned SQLITE_OK. - * If xMutexInit fails in any way, it is expected to clean up after itself - * prior to returning. -*/ -typedef struct sqlite3_mutex_methods sqlite3_mutex_methods; -struct sqlite3_mutex_methods { - int (*xMutexInit) (void); - int (*xMutexEnd) (void); - sqlite3_mutex *(*xMutexAlloc) (int); - void (*xMutexFree) (sqlite3_mutex *); - void (*xMutexEnter) (sqlite3_mutex *); - int (*xMutexTry) (sqlite3_mutex *); - void (*xMutexLeave) (sqlite3_mutex *); - int (*xMutexHeld) (sqlite3_mutex *); - int (*xMutexNotheld) (sqlite3_mutex *); -}; - -/* - * CAPI3REF: Mutex Verification Routines - * - * The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines - * are intended for use inside assert() statements. The SQLite core - * never uses these routines except inside an assert() and applications - * are advised to follow the lead of the core. The SQLite core only - * provides implementations for these routines when it is compiled - * with the SQLITE_DEBUG flag. External mutex implementations - * are only required to provide these routines if SQLITE_DEBUG is - * defined and if NDEBUG is not defined. - * - * These routines should return true if the mutex in their argument - * is held or not held, respectively, by the calling thread. - * - * The implementation is not required to provide versions of these - * routines that actually work. If the implementation does not provide working - * versions of these routines, it should at least provide stubs that always - * return true so that one does not get spurious assertion failures. - * - * If the argument to sqlite3_mutex_held() is a NULL pointer then - * the routine should return 1. This seems counter-intuitive since - * clearly the mutex cannot be held if it does not exist. But - * the reason the mutex does not exist is because the build is not - * using mutexes. And we do not want the assert() containing the - * call to sqlite3_mutex_held() to fail, so a non-zero return is - * the appropriate thing to do. The sqlite3_mutex_notheld() - * interface should also return 1 when given a NULL pointer. -*/ -#ifndef NDEBUG -SQLITE_API int -sqlite3_mutex_held(sqlite3_mutex *); - -SQLITE_API int -sqlite3_mutex_notheld(sqlite3_mutex *); -#endif - -/* - * CAPI3REF: Mutex Types - * - * The [sqlite3_mutex_alloc()] interface takes a single argument - * which is one of these integer constants. - * - * The set of static mutexes may change from one SQLite release to the - * next. Applications that override the built-in mutex logic must be - * prepared to accommodate additional static mutexes. -*/ -#define SQLITE_MUTEX_FAST 0 -#define SQLITE_MUTEX_RECURSIVE 1 -#define SQLITE_MUTEX_STATIC_MASTER 2 -#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ -#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */ -#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ -#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_randomness() */ -#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ -#define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */ -#define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */ -#define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */ -#define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */ -#define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */ -#define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */ -#define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */ -#define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */ - -/* - * CAPI3REF: Retrieve the mutex for a database connection - * METHOD: sqlite3 - * - * ^This interface returns a pointer the [sqlite3_mutex] object that - * serializes access to the [database connection] given in the argument - * when the [threading mode] is Serialized. - * ^If the [threading mode] is Single-thread or Multi-thread then this - * routine returns a NULL pointer. -*/ -SQLITE_API sqlite3_mutex * -sqlite3_db_mutex(sqlite3 *); - -/* - * CAPI3REF: Low-Level Control Of Database Files - * METHOD: sqlite3 - * - * ^The [sqlite3_file_control()] interface makes a direct call to the - * xFileControl method for the [sqlite3_io_methods] object associated - * with a particular database identified by the second argument. ^The - * name of the database is "main" for the main database or "temp" for the - * TEMP database, or the name that appears after the AS keyword for - * databases that are added using the [ATTACH] SQL command. - * ^A NULL pointer can be used in place of "main" to refer to the - * main database file. - * ^The third and fourth parameters to this routine - * are passed directly through to the second and third parameters of - * the xFileControl method. ^The return value of the xFileControl - * method becomes the return value of this routine. - * - * ^The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes - * a pointer to the underlying [sqlite3_file] object to be written into - * the space pointed to by the 4th parameter. ^The SQLITE_FCNTL_FILE_POINTER - * case is a short-circuit path which does not actually invoke the - * underlying sqlite3_io_methods.xFileControl method. - * - * ^If the second parameter (zDbName) does not match the name of any - * open database file, then SQLITE_ERROR is returned. ^This error - * code is not remembered and will not be recalled by [sqlite3_errcode()] - * or [sqlite3_errmsg()]. The underlying xFileControl method might - * also return SQLITE_ERROR. There is no way to distinguish between - * an incorrect zDbName and an SQLITE_ERROR return from the underlying - * xFileControl method. - * - * See also: [SQLITE_FCNTL_LOCKSTATE] -*/ -SQLITE_API int -sqlite3_file_control(sqlite3 *, int op, void *); - -/* - * CAPI3REF: Testing Interface - * - * ^The sqlite3_test_control() interface is used to read out internal - * state of SQLite and to inject faults into SQLite for testing - * purposes. ^The first parameter is an operation code that determines - * the number, meaning, and operation of all subsequent parameters. - * - * This interface is not for use by applications. It exists solely - * for verifying the correct operation of the SQLite library. Depending - * on how the SQLite library is compiled, this interface might not exist. - * - * The details of the operation codes, their meanings, the parameters - * they take, and what they do are all subject to change without notice. - * Unlike most of the SQLite API, this function is not guaranteed to - * operate consistently from one release to the next. -*/ -SQLITE_API int -sqlite3_test_control(int op, ...); - -/* - * CAPI3REF: Testing Interface Operation Codes - * - * These constants are the valid operation code parameters used - * as the first argument to [sqlite3_test_control()]. - * - * These parameters and their meanings are subject to change - * without notice. These values are for testing purposes only. - * Applications should not use any of these parameters or the - * [sqlite3_test_control()] interface. -*/ -#define SQLITE_TESTCTRL_FIRST 5 -#define SQLITE_TESTCTRL_PRNG_SAVE 5 -#define SQLITE_TESTCTRL_PRNG_RESTORE 6 -#define SQLITE_TESTCTRL_PRNG_RESET 7 -#define SQLITE_TESTCTRL_BITVEC_TEST 8 -#define SQLITE_TESTCTRL_FAULT_INSTALL 9 -#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 -#define SQLITE_TESTCTRL_PENDING_BYTE 11 -#define SQLITE_TESTCTRL_ASSERT 12 -#define SQLITE_TESTCTRL_ALWAYS 13 -#define SQLITE_TESTCTRL_RESERVE 14 -#define SQLITE_TESTCTRL_OPTIMIZATIONS 15 -#define SQLITE_TESTCTRL_ISKEYWORD 16 -#define SQLITE_TESTCTRL_SCRATCHMALLOC 17 -#define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 -#define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */ -#define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19 -#define SQLITE_TESTCTRL_NEVER_CORRUPT 20 -#define SQLITE_TESTCTRL_VDBE_COVERAGE 21 -#define SQLITE_TESTCTRL_BYTEORDER 22 -#define SQLITE_TESTCTRL_ISINIT 23 -#define SQLITE_TESTCTRL_SORTER_MMAP 24 -#define SQLITE_TESTCTRL_IMPOSTER 25 -#define SQLITE_TESTCTRL_LAST 25 - -/* - * CAPI3REF: SQLite Runtime Status - * - * ^These interfaces are used to retrieve runtime status information - * about the performance of SQLite, and optionally to reset various - * highwater marks. ^The first argument is an integer code for - * the specific parameter to measure. ^(Recognized integer codes - * are of the form [status parameters | SQLITE_STATUS_...].)^ - * ^The current value of the parameter is returned into *pCurrent. - * ^The highest recorded value is returned in *pHighwater. ^If the - * resetFlag is true, then the highest record value is reset after - * *pHighwater is written. ^(Some parameters do not record the highest - * value. For those parameters - * nothing is written into *pHighwater and the resetFlag is ignored.)^ - * ^(Other parameters record only the highwater mark and not the current - * value. For these latter parameters nothing is written into *pCurrent.)^ - * - * ^The sqlite3_status() and sqlite3_status64() routines return - * SQLITE_OK on success and a non-zero [error code] on failure. - * - * If either the current value or the highwater mark is too large to - * be represented by a 32-bit integer, then the values returned by - * sqlite3_status() are undefined. - * - * See also: [sqlite3_db_status()] -*/ -SQLITE_API int -sqlite3_status(int op, int *pCurrent, int *pHighwater, - int resetFlag); - -SQLITE_API int -sqlite3_status64(int op, sqlite3_int64 * pCurrent, - sqlite3_int64 * pHighwater, - int resetFlag); - -/* - * CAPI3REF: Status Parameters - * KEYWORDS: {status parameters} - * - * These integer constants designate various run-time status parameters - * that can be returned by [sqlite3_status()]. - * - *
- * [[SQLITE_STATUS_MEMORY_USED]] ^(
SQLITE_STATUS_MEMORY_USED
- *
This parameter is the current amount of memory checked out - * using [sqlite3_malloc()], either directly or indirectly. The - * figure includes calls made to [sqlite3_malloc()] by the application - * and internal memory usage by the SQLite library. Scratch memory - * controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache - * memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in - * this parameter. The amount returned is the sum of the allocation - * sizes as reported by the xSize method in [sqlite3_mem_methods].
)^ - * - * [[SQLITE_STATUS_MALLOC_SIZE]] ^(
SQLITE_STATUS_MALLOC_SIZE
- *
This parameter records the largest memory allocation request - * handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their - * internal equivalents). Only the value returned in the - * *pHighwater parameter to [sqlite3_status()] is of interest. - * The value written into the *pCurrent parameter is undefined.
)^ - * - * [[SQLITE_STATUS_MALLOC_COUNT]] ^(
SQLITE_STATUS_MALLOC_COUNT
- *
This parameter records the number of separate memory allocations - * currently checked out.
)^ - * - * [[SQLITE_STATUS_PAGECACHE_USED]] ^(
SQLITE_STATUS_PAGECACHE_USED
- *
This parameter returns the number of pages used out of the - * [pagecache memory allocator] that was configured using - * [SQLITE_CONFIG_PAGECACHE]. The - * value returned is in pages, not in bytes.
)^ - * - * [[SQLITE_STATUS_PAGECACHE_OVERFLOW]] - * ^(
SQLITE_STATUS_PAGECACHE_OVERFLOW
- *
This parameter returns the number of bytes of page cache - * allocation which could not be satisfied by the [SQLITE_CONFIG_PAGECACHE] - * buffer and where forced to overflow to [sqlite3_malloc()]. The - * returned value includes allocations that overflowed because they - * where too large (they were larger than the "sz" parameter to - * [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because - * no space was left in the page cache.
)^ - * - * [[SQLITE_STATUS_PAGECACHE_SIZE]] ^(
SQLITE_STATUS_PAGECACHE_SIZE
- *
This parameter records the largest memory allocation request - * handed to [pagecache memory allocator]. Only the value returned in the - * *pHighwater parameter to [sqlite3_status()] is of interest. - * The value written into the *pCurrent parameter is undefined.
)^ - * - * [[SQLITE_STATUS_SCRATCH_USED]] ^(
SQLITE_STATUS_SCRATCH_USED
- *
This parameter returns the number of allocations used out of the - * [scratch memory allocator] configured using - * [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not - * in bytes. Since a single thread may only have one scratch allocation - * outstanding at time, this parameter also reports the number of threads - * using scratch memory at the same time.
)^ - * - * [[SQLITE_STATUS_SCRATCH_OVERFLOW]] ^(
SQLITE_STATUS_SCRATCH_OVERFLOW
- *
This parameter returns the number of bytes of scratch memory - * allocation which could not be satisfied by the [SQLITE_CONFIG_SCRATCH] - * buffer and where forced to overflow to [sqlite3_malloc()]. The values - * returned include overflows because the requested allocation was too - * larger (that is, because the requested allocation was larger than the - * "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer - * slots were available. - *
)^ - * - * [[SQLITE_STATUS_SCRATCH_SIZE]] ^(
SQLITE_STATUS_SCRATCH_SIZE
- *
This parameter records the largest memory allocation request - * handed to [scratch memory allocator]. Only the value returned in the - * *pHighwater parameter to [sqlite3_status()] is of interest. - * The value written into the *pCurrent parameter is undefined.
)^ - * - * [[SQLITE_STATUS_PARSER_STACK]] ^(
SQLITE_STATUS_PARSER_STACK
- *
The *pHighwater parameter records the deepest parser stack. - * The *pCurrent value is undefined. The *pHighwater value is only - * meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].
)^ - *
- * - * New status parameters may be added from time to time. -*/ -#define SQLITE_STATUS_MEMORY_USED 0 -#define SQLITE_STATUS_PAGECACHE_USED 1 -#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2 -#define SQLITE_STATUS_SCRATCH_USED 3 -#define SQLITE_STATUS_SCRATCH_OVERFLOW 4 -#define SQLITE_STATUS_MALLOC_SIZE 5 -#define SQLITE_STATUS_PARSER_STACK 6 -#define SQLITE_STATUS_PAGECACHE_SIZE 7 -#define SQLITE_STATUS_SCRATCH_SIZE 8 -#define SQLITE_STATUS_MALLOC_COUNT 9 - -/* - * CAPI3REF: Database Connection Status - * METHOD: sqlite3 - * - * ^This interface is used to retrieve runtime status information - * about a single [database connection]. ^The first argument is the - * database connection object to be interrogated. ^The second argument - * is an integer constant, taken from the set of - * [SQLITE_DBSTATUS options], that - * determines the parameter to interrogate. The set of - * [SQLITE_DBSTATUS options] is likely - * to grow in future releases of SQLite. - * - * ^The current value of the requested parameter is written into *pCur - * and the highest instantaneous value is written into *pHiwtr. ^If - * the resetFlg is true, then the highest instantaneous value is - * reset back down to the current value. - * - * ^The sqlite3_db_status() routine returns SQLITE_OK on success and a - * non-zero [error code] on failure. - * - * See also: [sqlite3_status()] and [sqlite3_stmt_status()]. -*/ -SQLITE_API int -sqlite3_db_status(sqlite3 *, int op, int *pCur, - int *pHiwtr, int resetFlg); - -/* - * CAPI3REF: Status Parameters for database connections - * KEYWORDS: {SQLITE_DBSTATUS options} - * - * These constants are the available integer "verbs" that can be passed as - * the second argument to the [sqlite3_db_status()] interface. - * - * New verbs may be added in future releases of SQLite. Existing verbs - * might be discontinued. Applications should check the return code from - * [sqlite3_db_status()] to make sure that the call worked. - * The [sqlite3_db_status()] interface will return a non-zero error code - * if a discontinued or unsupported verb is invoked. - * - *
- * [[SQLITE_DBSTATUS_LOOKASIDE_USED]] ^(
SQLITE_DBSTATUS_LOOKASIDE_USED
- *
This parameter returns the number of lookaside memory slots currently - * checked out.
)^ - * - * [[SQLITE_DBSTATUS_LOOKASIDE_HIT]] ^(
SQLITE_DBSTATUS_LOOKASIDE_HIT
- *
This parameter returns the number malloc attempts that were - * satisfied using lookaside memory. Only the high-water value is meaningful; - * the current value is always zero.)^ - * - * [[SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE]] - * ^(
SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE
- *
This parameter returns the number malloc attempts that might have - * been satisfied using lookaside memory but failed due to the amount of - * memory requested being larger than the lookaside slot size. - * Only the high-water value is meaningful; - * the current value is always zero.)^ - * - * [[SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL]] - * ^(
SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL
- *
This parameter returns the number malloc attempts that might have - * been satisfied using lookaside memory but failed due to all lookaside - * memory already being in use. - * Only the high-water value is meaningful; - * the current value is always zero.)^ - * - * [[SQLITE_DBSTATUS_CACHE_USED]] ^(
SQLITE_DBSTATUS_CACHE_USED
- *
This parameter returns the approximate number of bytes of heap - * memory used by all pager caches associated with the database connection.)^ - * ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0. - * - * [[SQLITE_DBSTATUS_CACHE_USED_SHARED]] - * ^(
SQLITE_DBSTATUS_CACHE_USED_SHARED
- *
This parameter is similar to DBSTATUS_CACHE_USED, except that if a - * pager cache is shared between two or more connections the bytes of heap - * memory used by that pager cache is divided evenly between the attached - * connections.)^ In other words, if none of the pager caches associated - * with the database connection are shared, this request returns the same - * value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are - * shared, the value returned by this call will be smaller than that returned - * by DBSTATUS_CACHE_USED. ^The highwater mark associated with - * SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0. - * - * [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(
SQLITE_DBSTATUS_SCHEMA_USED
- *
This parameter returns the approximate number of bytes of heap - * memory used to store the schema for all databases associated - * with the connection - main, temp, and any [ATTACH]-ed databases.)^ - * ^The full amount of memory used by the schemas is reported, even if the - * schema memory is shared with other database connections due to - * [shared cache mode] being enabled. - * ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0. - * - * [[SQLITE_DBSTATUS_STMT_USED]] ^(
SQLITE_DBSTATUS_STMT_USED
- *
This parameter returns the approximate number of bytes of heap - * and lookaside memory used by all prepared statements associated with - * the database connection.)^ - * ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0. - *
- * - * [[SQLITE_DBSTATUS_CACHE_HIT]] ^(
SQLITE_DBSTATUS_CACHE_HIT
- *
This parameter returns the number of pager cache hits that have - * occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT - * is always 0. - *
- * - * [[SQLITE_DBSTATUS_CACHE_MISS]] ^(
SQLITE_DBSTATUS_CACHE_MISS
- *
This parameter returns the number of pager cache misses that have - * occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS - * is always 0. - *
- * - * [[SQLITE_DBSTATUS_CACHE_WRITE]] ^(
SQLITE_DBSTATUS_CACHE_WRITE
- *
This parameter returns the number of dirty cache entries that have - * been written to disk. Specifically, the number of pages written to the - * wal file in wal mode databases, or the number of pages written to the - * database file in rollback mode databases. Any pages written as part of - * transaction rollback or database recovery operations are not included. - * If an IO or other error occurs while writing a page to disk, the effect - * on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The - * highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0. - *
- * - * [[SQLITE_DBSTATUS_DEFERRED_FKS]] ^(
SQLITE_DBSTATUS_DEFERRED_FKS
- *
This parameter returns zero for the current value if and only if - * all foreign key constraints (deferred or immediate) have been - * resolved.)^ ^The highwater mark is always 0. - *
- *
-*/ -#define SQLITE_DBSTATUS_LOOKASIDE_USED 0 -#define SQLITE_DBSTATUS_CACHE_USED 1 -#define SQLITE_DBSTATUS_SCHEMA_USED 2 -#define SQLITE_DBSTATUS_STMT_USED 3 -#define SQLITE_DBSTATUS_LOOKASIDE_HIT 4 -#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5 -#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6 -#define SQLITE_DBSTATUS_CACHE_HIT 7 -#define SQLITE_DBSTATUS_CACHE_MISS 8 -#define SQLITE_DBSTATUS_CACHE_WRITE 9 -#define SQLITE_DBSTATUS_DEFERRED_FKS 10 -#define SQLITE_DBSTATUS_CACHE_USED_SHARED 11 -#define SQLITE_DBSTATUS_MAX 11 /* Largest defined DBSTATUS */ - -/* - * CAPI3REF: Prepared Statement Status - * METHOD: sqlite3_stmt - * - * ^(Each prepared statement maintains various - * [SQLITE_STMTSTATUS counters] that measure the number - * of times it has performed specific operations.)^ These counters can - * be used to monitor the performance characteristics of the prepared - * statements. For example, if the number of table steps greatly exceeds - * the number of table searches or result rows, that would tend to indicate - * that the prepared statement is using a full table scan rather than - * an index. - * - * ^(This interface is used to retrieve and reset counter values from - * a [prepared statement]. The first argument is the prepared statement - * object to be interrogated. The second argument - * is an integer code for a specific [SQLITE_STMTSTATUS counter] - * to be interrogated.)^ - * ^The current value of the requested counter is returned. - * ^If the resetFlg is true, then the counter is reset to zero after this - * interface call returns. - * - * See also: [sqlite3_status()] and [sqlite3_db_status()]. -*/ -SQLITE_API int -sqlite3_stmt_status(sqlite3_stmt *, int op, - int resetFlg); - -/* - * CAPI3REF: Status Parameters for prepared statements - * KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters} - * - * These preprocessor macros define integer codes that name counter - * values associated with the [sqlite3_stmt_status()] interface. - * The meanings of the various counters are as follows: - * - *
- * [[SQLITE_STMTSTATUS_FULLSCAN_STEP]]
SQLITE_STMTSTATUS_FULLSCAN_STEP
- *
^This is the number of times that SQLite has stepped forward in - * a table as part of a full table scan. Large numbers for this counter - * may indicate opportunities for performance improvement through - * careful use of indices.
- * - * [[SQLITE_STMTSTATUS_SORT]]
SQLITE_STMTSTATUS_SORT
- *
^This is the number of sort operations that have occurred. - * A non-zero value in this counter may indicate an opportunity to - * improvement performance through careful use of indices.
- * - * [[SQLITE_STMTSTATUS_AUTOINDEX]]
SQLITE_STMTSTATUS_AUTOINDEX
- *
^This is the number of rows inserted into transient indices that - * were created automatically in order to help joins run faster. - * A non-zero value in this counter may indicate an opportunity to - * improvement performance by adding permanent indices that do not - * need to be reinitialized each time the statement is run.
- * - * [[SQLITE_STMTSTATUS_VM_STEP]]
SQLITE_STMTSTATUS_VM_STEP
- *
^This is the number of virtual machine operations executed - * by the prepared statement if that number is less than or equal - * to 2147483647. The number of virtual machine operations can be - * used as a proxy for the total work done by the prepared statement. - * If the number of virtual machine operations exceeds 2147483647 - * then the value returned by this statement status code is undefined. - *
- *
-*/ -#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1 -#define SQLITE_STMTSTATUS_SORT 2 -#define SQLITE_STMTSTATUS_AUTOINDEX 3 -#define SQLITE_STMTSTATUS_VM_STEP 4 - -/* - * CAPI3REF: Custom Page Cache Object - * - * The sqlite3_pcache type is opaque. It is implemented by - * the pluggable module. The SQLite core has no knowledge of - * its size or internal structure and never deals with the - * sqlite3_pcache object except by holding and passing pointers - * to the object. - * - * See [sqlite3_pcache_methods2] for additional information. -*/ -typedef struct sqlite3_pcache sqlite3_pcache; - -/* - * CAPI3REF: Custom Page Cache Object - * - * The sqlite3_pcache_page object represents a single page in the - * page cache. The page cache will allocate instances of this - * object. Various methods of the page cache use pointers to instances - * of this object as parameters or as their return value. - * - * See [sqlite3_pcache_methods2] for additional information. -*/ -typedef struct sqlite3_pcache_page sqlite3_pcache_page; -struct sqlite3_pcache_page { - void *pBuf; /* The content of the page */ - void *pExtra; /* Extra information associated with the page */ -}; - -/* - * CAPI3REF: Application Defined Page Cache. - * KEYWORDS: {page cache} - * - * ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE2], ...) interface can - * register an alternative page cache implementation by passing in an - * instance of the sqlite3_pcache_methods2 structure.)^ - * In many applications, most of the heap memory allocated by - * SQLite is used for the page cache. - * By implementing a - * custom page cache using this API, an application can better control - * the amount of memory consumed by SQLite, the way in which - * that memory is allocated and released, and the policies used to - * determine exactly which parts of a database file are cached and for - * how long. - * - * The alternative page cache mechanism is an - * extreme measure that is only needed by the most demanding applications. - * The built-in page cache is recommended for most uses. - * - * ^(The contents of the sqlite3_pcache_methods2 structure are copied to an - * internal buffer by SQLite within the call to [sqlite3_config]. Hence - * the application may discard the parameter after the call to - * [sqlite3_config()] returns.)^ - * - * [[the xInit() page cache method]] - * ^(The xInit() method is called once for each effective - * call to [sqlite3_initialize()])^ - * (usually only once during the lifetime of the process). ^(The xInit() - * method is passed a copy of the sqlite3_pcache_methods2.pArg value.)^ - * The intent of the xInit() method is to set up global data structures - * required by the custom page cache implementation. - * ^(If the xInit() method is NULL, then the - * built-in default page cache is used instead of the application defined - * page cache.)^ - * - * [[the xShutdown() page cache method]] - * ^The xShutdown() method is called by [sqlite3_shutdown()]. - * It can be used to clean up - * any outstanding resources before process shutdown, if required. - * ^The xShutdown() method may be NULL. - * - * ^SQLite automatically serializes calls to the xInit method, - * so the xInit method need not be threadsafe. ^The - * xShutdown method is only called from [sqlite3_shutdown()] so it does - * not need to be threadsafe either. All other methods must be threadsafe - * in multithreaded applications. - * - * ^SQLite will never invoke xInit() more than once without an intervening - * call to xShutdown(). - * - * [[the xCreate() page cache methods]] - * ^SQLite invokes the xCreate() method to construct a new cache instance. - * SQLite will typically create one cache instance for each open database file, - * though this is not guaranteed. ^The - * first parameter, szPage, is the size in bytes of the pages that must - * be allocated by the cache. ^szPage will always a power of two. ^The - * second parameter szExtra is a number of bytes of extra storage - * associated with each page cache entry. ^The szExtra parameter will - * a number less than 250. SQLite will use the - * extra szExtra bytes on each page to store metadata about the underlying - * database page on disk. The value passed into szExtra depends - * on the SQLite version, the target platform, and how SQLite was compiled. - * ^The third argument to xCreate(), bPurgeable, is true if the cache being - * created will be used to cache database pages of a file stored on disk, or - * false if it is used for an in-memory database. The cache implementation - * does not have to do anything special based with the value of bPurgeable; - * it is purely advisory. ^On a cache where bPurgeable is false, SQLite will - * never invoke xUnpin() except to deliberately delete a page. - * ^In other words, calls to xUnpin() on a cache with bPurgeable set to - * false will always have the "discard" flag set to true. - * ^Hence, a cache created with bPurgeable false will - * never contain any unpinned pages. - * - * [[the xCachesize() page cache method]] - * ^(The xCachesize() method may be called at any time by SQLite to set the - * suggested maximum cache-size (number of pages stored by) the cache - * instance passed as the first argument. This is the value configured using - * the SQLite "[PRAGMA cache_size]" command.)^ As with the bPurgeable - * parameter, the implementation is not required to do anything with this - * value; it is advisory only. - * - * [[the xPagecount() page cache methods]] - * The xPagecount() method must return the number of pages currently - * stored in the cache, both pinned and unpinned. - * - * [[the xFetch() page cache methods]] - * The xFetch() method locates a page in the cache and returns a pointer to - * an sqlite3_pcache_page object associated with that page, or a NULL pointer. - * The pBuf element of the returned sqlite3_pcache_page object will be a - * pointer to a buffer of szPage bytes used to store the content of a - * single database page. The pExtra element of sqlite3_pcache_page will be - * a pointer to the szExtra bytes of extra storage that SQLite has requested - * for each entry in the page cache. - * - * The page to be fetched is determined by the key. ^The minimum key value - * is 1. After it has been retrieved using xFetch, the page is considered - * to be "pinned". - * - * If the requested page is already in the page cache, then the page cache - * implementation must return a pointer to the page buffer with its content - * intact. If the requested page is not already in the cache, then the - * cache implementation should use the value of the createFlag - * parameter to help it determined what action to take: - * - * - *
createFlag Behavior when page is not already in cache - *
0 Do not allocate a new page. Return NULL. - *
1 Allocate a new page if it easy and convenient to do so. - * Otherwise return NULL. - *
2 Make every effort to allocate a new page. Only return - * NULL if allocating a new page is effectively impossible. - *
- * - * ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite - * will only use a createFlag of 2 after a prior call with a createFlag of 1 - * failed.)^ In between the to xFetch() calls, SQLite may - * attempt to unpin one or more cache pages by spilling the content of - * pinned pages to disk and synching the operating system disk cache. - * - * [[the xUnpin() page cache method]] - * ^xUnpin() is called by SQLite with a pointer to a currently pinned page - * as its second argument. If the third parameter, discard, is non-zero, - * then the page must be evicted from the cache. - * ^If the discard parameter is - * zero, then the page may be discarded or retained at the discretion of - * page cache implementation. ^The page cache implementation - * may choose to evict unpinned pages at any time. - * - * The cache must not perform any reference counting. A single - * call to xUnpin() unpins the page regardless of the number of prior calls - * to xFetch(). - * - * [[the xRekey() page cache methods]] - * The xRekey() method is used to change the key value associated with the - * page passed as the second argument. If the cache - * previously contains an entry associated with newKey, it must be - * discarded. ^Any prior cache entry associated with newKey is guaranteed not - * to be pinned. - * - * When SQLite calls the xTruncate() method, the cache must discard all - * existing cache entries with page numbers (keys) greater than or equal - * to the value of the iLimit parameter passed to xTruncate(). If any - * of these pages are pinned, they are implicitly unpinned, meaning that - * they can be safely discarded. - * - * [[the xDestroy() page cache method]] - * ^The xDestroy() method is used to delete a cache allocated by xCreate(). - * All resources associated with the specified cache should be freed. ^After - * calling the xDestroy() method, SQLite considers the [sqlite3_pcache*] - * handle invalid, and will not use it with any other sqlite3_pcache_methods2 - * functions. - * - * [[the xShrink() page cache method]] - * ^SQLite invokes the xShrink() method when it wants the page cache to - * free up as much of heap memory as possible. The page cache implementation - * is not obligated to free any memory, but well-behaved implementations should - * do their best. -*/ -typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2; -struct sqlite3_pcache_methods2 { - int iVersion; - void *pArg; - int (*xInit) (void *); - void (*xShutdown) (void *); - sqlite3_pcache *(*xCreate) (int szPage, int szExtra, - int bPurgeable); - void (*xCachesize) (sqlite3_pcache *, int nCachesize); - int (*xPagecount) (sqlite3_pcache *); - sqlite3_pcache_page *(*xFetch) (sqlite3_pcache *, unsigned key, - int createFlag); - void (*xUnpin) (sqlite3_pcache *, sqlite3_pcache_page *, - int discard); - void (*xRekey) (sqlite3_pcache *, sqlite3_pcache_page *, - unsigned oldKey, unsigned newKey); - void (*xTruncate) (sqlite3_pcache *, unsigned iLimit); - void (*xDestroy) (sqlite3_pcache *); - void (*xShrink) (sqlite3_pcache *); -}; - -/* - * This is the obsolete pcache_methods object that has now been replaced - * by sqlite3_pcache_methods2. This object is not used by SQLite. It is - * retained in the header file for backwards compatibility only. -*/ -typedef struct sqlite3_pcache_methods sqlite3_pcache_methods; -struct sqlite3_pcache_methods { - void *pArg; - int (*xInit) (void *); - void (*xShutdown) (void *); - sqlite3_pcache *(*xCreate) (int szPage, int bPurgeable); - void (*xCachesize) (sqlite3_pcache *, int nCachesize); - int (*xPagecount) (sqlite3_pcache *); - void *(*xFetch) (sqlite3_pcache *, unsigned key, - int createFlag); - void (*xUnpin) (sqlite3_pcache *, void *, int discard); - void (*xRekey) (sqlite3_pcache *, void *, unsigned oldKey, - unsigned newKey); - void (*xTruncate) (sqlite3_pcache *, unsigned iLimit); - void (*xDestroy) (sqlite3_pcache *); -}; - -/* - * CAPI3REF: String Comparison - * - * ^The [sqlite3_stricmp()] and [sqlite3_strnicmp()] APIs allow applications - * and extensions to compare the contents of two buffers containing UTF-8 - * strings in a case-independent fashion, using the same definition of "case - * independence" that SQLite uses internally when comparing identifiers. -*/ -SQLITE_API int -sqlite3_stricmp(const char *, const char *); - -SQLITE_API int -sqlite3_strnicmp(const char *, const char *, int); - -/* - * CAPI3REF: String Globbing -* - * ^The [sqlite3_strglob(P,X)] interface returns zero if and only if - * string X matches the [GLOB] pattern P. - * ^The definition of [GLOB] pattern matching used in - * [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the - * SQL dialect understood by SQLite. ^The [sqlite3_strglob(P,X)] function - * is case sensitive. - * - * Note that this routine returns zero on a match and non-zero if the strings - * do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()]. - * - * See also: [sqlite3_strlike()]. -*/ -SQLITE_API int -sqlite3_strglob(const char *zGlob, const char *zStr); - -/* - * CAPI3REF: String LIKE Matching -* - * ^The [sqlite3_strlike(P,X,E)] interface returns zero if and only if - * string X matches the [LIKE] pattern P with escape character E. - * ^The definition of [LIKE] pattern matching used in - * [sqlite3_strlike(P,X,E)] is the same as for the "X LIKE P ESCAPE E" - * operator in the SQL dialect understood by SQLite. ^For "X LIKE P" without - * the ESCAPE clause, set the E parameter of [sqlite3_strlike(P,X,E)] to 0. - * ^As with the LIKE operator, the [sqlite3_strlike(P,X,E)] function is case - * insensitive - equivalent upper and lower case ASCII characters match - * one another. - * - * ^The [sqlite3_strlike(P,X,E)] function matches Unicode characters, though - * only ASCII characters are case folded. - * - * Note that this routine returns zero on a match and non-zero if the strings - * do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()]. - * - * See also: [sqlite3_strglob()]. -*/ -SQLITE_API int -sqlite3_strlike(const char *zGlob, const char *zStr, - unsigned int cEsc); - -/* - * CAPI3REF: Error Logging Interface - * - * ^The [sqlite3_log()] interface writes a message into the [error log] - * established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()]. - * ^If logging is enabled, the zFormat string and subsequent arguments are - * used with [sqlite3_snprintf()] to generate the final output string. - * - * The sqlite3_log() interface is intended for use by extensions, - * collating functions, and SQL functions. While there is nothing - * to prevent an application from calling sqlite3_log(), doing so - * is considered bad form. - * - * The zFormat string must not be NULL. - * - * To avoid deadlocks and other threading problems, the sqlite3_log() routine - * will not use dynamically allocated memory. The log message is stored in - * a fixed-length buffer on the stack. If the log message is longer than - * a few hundred characters, it will be truncated to the length of the - * buffer. -*/ -SQLITE_API void -sqlite3_log(int iErrCode, const char *zFormat, ...); - -/* - * CAPI3REF: Write-Ahead Log Commit Hook - * METHOD: sqlite3 - * - * ^The [sqlite3_wal_hook()] function is used to register a callback that - * is invoked each time data is committed to a database in wal mode. - * - * ^(The callback is invoked by SQLite after the commit has taken place and - * the associated write-lock on the database released)^, so the implementation - * may read, write or [checkpoint] the database as required. - * - * ^The first parameter passed to the callback function when it is invoked - * is a copy of the third parameter passed to sqlite3_wal_hook() when - * registering the callback. ^The second is a copy of the database handle. - * ^The third parameter is the name of the database that was written to - - * either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter - * is the number of pages currently in the write-ahead log file, - * including those that were just committed. - * - * The callback function should normally return [SQLITE_OK]. ^If an error - * code is returned, that error will propagate back up through the - * SQLite code base to cause the statement that provoked the callback - * to report an error, though the commit will have still occurred. If the - * callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value - * that does not correspond to any valid SQLite error code, the results - * are undefined. - * - * A single database handle may have at most a single write-ahead log callback - * registered at one time. ^Calling [sqlite3_wal_hook()] replaces any - * previously registered write-ahead log callback. ^Note that the - * [sqlite3_wal_autocheckpoint()] interface and the - * [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will - * overwrite any prior [sqlite3_wal_hook()] settings. -*/ -SQLITE_API void * -sqlite3_wal_hook(sqlite3 *, - int (*)(void *, sqlite3 *, - const char *, int), void *); - -/* - * CAPI3REF: Checkpoint Mode Values - * KEYWORDS: {checkpoint mode} - * - * These constants define all valid values for the "checkpoint mode" passed - * as the third parameter to the [sqlite3_wal_checkpoint_v2()] interface. - * See the [sqlite3_wal_checkpoint_v2()] documentation for details on the - * meaning of each of these checkpoint modes. -*/ -#define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */ -#define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */ -#define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for for readers */ -#define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */ - -/* - * CAPI3REF: Prepared Statement Scan Status Opcodes - * KEYWORDS: {scanstatus options} - * - * The following constants can be used for the T parameter to the - * [sqlite3_stmt_scanstatus(S,X,T,V)] interface. Each constant designates a - * different metric for sqlite3_stmt_scanstatus() to return. - * - * When the value returned to V is a string, space to hold that string is - * managed by the prepared statement S and will be automatically freed when - * S is finalized. - * - *
- * [[SQLITE_SCANSTAT_NLOOP]]
SQLITE_SCANSTAT_NLOOP
- *
^The [sqlite3_int64] variable pointed to by the T parameter will be - * set to the total number of times that the X-th loop has run.
- * - * [[SQLITE_SCANSTAT_NVISIT]]
SQLITE_SCANSTAT_NVISIT
- *
^The [sqlite3_int64] variable pointed to by the T parameter will be set - * to the total number of rows examined by all iterations of the X-th loop.
- * - * [[SQLITE_SCANSTAT_EST]]
SQLITE_SCANSTAT_EST
- *
^The "double" variable pointed to by the T parameter will be set to the - * query planner's estimate for the average number of rows output from each - * iteration of the X-th loop. If the query planner's estimates was accurate, - * then this value will approximate the quotient NVISIT/NLOOP and the - * product of this value for all prior loops with the same SELECTID will - * be the NLOOP value for the current loop. - * - * [[SQLITE_SCANSTAT_NAME]]
SQLITE_SCANSTAT_NAME
- *
^The "const char *" variable pointed to by the T parameter will be set - * to a zero-terminated UTF-8 string containing the name of the index or table - * used for the X-th loop. - * - * [[SQLITE_SCANSTAT_EXPLAIN]]
SQLITE_SCANSTAT_EXPLAIN
- *
^The "const char *" variable pointed to by the T parameter will be set - * to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN] - * description for the X-th loop. - * - * [[SQLITE_SCANSTAT_SELECTID]]
SQLITE_SCANSTAT_SELECT
- *
^The "int" variable pointed to by the T parameter will be set to the - * "select-id" for the X-th loop. The select-id identifies which query or - * subquery the loop is part of. The main query has a select-id of zero. - * The select-id is the same value as is output in the first column - * of an [EXPLAIN QUERY PLAN] query. - *
-*/ -#define SQLITE_SCANSTAT_NLOOP 0 -#define SQLITE_SCANSTAT_NVISIT 1 -#define SQLITE_SCANSTAT_EST 2 -#define SQLITE_SCANSTAT_NAME 3 -#define SQLITE_SCANSTAT_EXPLAIN 4 -#define SQLITE_SCANSTAT_SELECTID 5 - -/* - * CAPI3REF: Prepared Statement Scan Status - * METHOD: sqlite3_stmt - * - * This interface returns information about the predicted and measured - * performance for pStmt. Advanced applications can use this - * interface to compare the predicted and the measured performance and - * issue warnings and/or rerun [ANALYZE] if discrepancies are found. - * - * Since this interface is expected to be rarely used, it is only - * available if SQLite is compiled using the [SQLITE_ENABLE_STMT_SCANSTATUS] - * compile-time option. - * - * The "iScanStatusOp" parameter determines which status information to return. - * The "iScanStatusOp" must be one of the [scanstatus options] or the behavior - * of this interface is undefined. - * ^The requested measurement is written into a variable pointed to by - * the "pOut" parameter. - * Parameter "idx" identifies the specific loop to retrieve statistics for. - * Loops are numbered starting from zero. ^If idx is out of range - less than - * zero or greater than or equal to the total number of loops used to implement - * the statement - a non-zero value is returned and the variable that pOut - * points to is unchanged. - * - * ^Statistics might not be available for all loops in all statements. ^In cases - * where there exist loops with no available statistics, this function behaves - * as if the loop did not exist - it returns non-zero and leave the variable - * that pOut points to unchanged. - * - * See also: [sqlite3_stmt_scanstatus_reset()] -*/ -SQLITE_API int -sqlite3_stmt_scanstatus(sqlite3_stmt * pStmt, /* Prepared statement for which info desired */ - int idx, /* Index of loop to report on */ - int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ - void *pOut /* Result written here */ - ); - -/* - * CAPI3REF: Zero Scan-Status Counters - * METHOD: sqlite3_stmt - * - * ^Zero all [sqlite3_stmt_scanstatus()] related event counters. - * - * This API is only available if the library is built with pre-processor - * symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined. -*/ -SQLITE_API void -sqlite3_stmt_scanstatus_reset(sqlite3_stmt *); - -/* - * CAPI3REF: Flush caches to disk mid-transaction - * - * ^If a write-transaction is open on [database connection] D when the - * [sqlite3_db_cacheflush(D)] interface invoked, any dirty - * pages in the pager-cache that are not currently in use are written out - * to disk. A dirty page may be in use if a database cursor created by an - * active SQL statement is reading from it, or if it is page 1 of a database - * file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)] - * interface flushes caches for all schemas - "main", "temp", and - * any [attached] databases. - * - * ^If this function needs to obtain extra database locks before dirty pages - * can be flushed to disk, it does so. ^If those locks cannot be obtained - * immediately and there is a busy-handler callback configured, it is invoked - * in the usual manner. ^If the required lock still cannot be obtained, then - * the database is skipped and an attempt made to flush any dirty pages - * belonging to the next (if any) database. ^If any databases are skipped - * because locks cannot be obtained, but no other error occurs, this - * function returns SQLITE_BUSY. - * - * ^If any other error occurs while flushing dirty pages to disk (for - * example an IO error or out-of-memory condition), then processing is - * abandoned and an SQLite [error code] is returned to the caller immediately. - * - * ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK. - * - * ^This function does not set the database handle error code or message - * returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions. -*/ -SQLITE_API int -sqlite3_db_cacheflush(sqlite3 *); - -/* - * CAPI3REF: Low-level system error code - * - * ^Attempt to return the underlying operating system error code or error - * number that caused the most recent I/O error or failure to open a file. - * The return value is OS-dependent. For example, on unix systems, after - * [sqlite3_open_v2()] returns [SQLITE_CANTOPEN], this interface could be - * called to get back the underlying "errno" that caused the problem, such - * as ENOSPC, EAUTH, EISDIR, and so forth. -*/ -SQLITE_API int -sqlite3_system_errno(sqlite3 *); - -/* - * CAPI3REF: Database Snapshot - * KEYWORDS: {snapshot} {sqlite3_snapshot} - * EXPERIMENTAL - * - * An instance of the snapshot object records the state of a [WAL mode] - * database for some specific point in history. - * - * In [WAL mode], multiple [database connections] that are open on the - * same database file can each be reading a different historical version - * of the database file. When a [database connection] begins a read - * transaction, that connection sees an unchanging copy of the database - * as it existed for the point in time when the transaction first started. - * Subsequent changes to the database from other connections are not seen - * by the reader until a new read transaction is started. - * - * The sqlite3_snapshot object records state information about an historical - * version of the database file so that it is possible to later open a new read - * transaction that sees that historical version of the database rather than - * the most recent version. - * - * The constructor for this object is [sqlite3_snapshot_get()]. The - * [sqlite3_snapshot_open()] method causes a fresh read transaction to refer - * to an historical snapshot (if possible). The destructor for - * sqlite3_snapshot objects is [sqlite3_snapshot_free()]. -*/ -typedef struct sqlite3_snapshot { - unsigned char hidden[48]; -} sqlite3_snapshot; - -/* - * CAPI3REF: Record A Database Snapshot - * EXPERIMENTAL - * - * ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a - * new [sqlite3_snapshot] object that records the current state of - * schema S in database connection D. ^On success, the - * [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly - * created [sqlite3_snapshot] object into *P and returns SQLITE_OK. - * If there is not already a read-transaction open on schema S when - * this function is called, one is opened automatically. - * - * The following must be true for this function to succeed. If any of - * the following statements are false when sqlite3_snapshot_get() is - * called, SQLITE_ERROR is returned. The final value of *P is undefined - * in this case. - * - *
    - *
  • The database handle must be in [autocommit mode]. - * - *
  • Schema S of [database connection] D must be a [WAL mode] database. - * - *
  • There must not be a write transaction open on schema S of database - * connection D. - * - *
  • One or more transactions must have been written to the current wal - * file since it was created on disk (by any connection). This means - * that a snapshot cannot be taken on a wal mode database with no wal - * file immediately after it is first opened. At least one transaction - * must be written to it first. - *
- * - * This function may also return SQLITE_NOMEM. If it is called with the - * database handle in autocommit mode but fails for some other reason, - * whether or not a read transaction is opened on schema S is undefined. - * - * The [sqlite3_snapshot] object returned from a successful call to - * [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()] - * to avoid a memory leak. - * - * The [sqlite3_snapshot_get()] interface is only available when the - * SQLITE_ENABLE_SNAPSHOT compile-time option is used. -*/ -SQLITE_API SQLITE_EXPERIMENTAL int -sqlite3_snapshot_get(sqlite3 * db, - const char *zSchema, - sqlite3_snapshot ** ppSnapshot); - -/* - * CAPI3REF: Start a read transaction on an historical snapshot - * EXPERIMENTAL - * - * ^The [sqlite3_snapshot_open(D,S,P)] interface starts a - * read transaction for schema S of - * [database connection] D such that the read transaction - * refers to historical [snapshot] P, rather than the most - * recent change to the database. - * ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success - * or an appropriate [error code] if it fails. - * - * ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be - * the first operation following the [BEGIN] that takes the schema S - * out of [autocommit mode]. - * ^In other words, schema S must not currently be in - * a transaction for [sqlite3_snapshot_open(D,S,P)] to work, but the - * database connection D must be out of [autocommit mode]. - * ^A [snapshot] will fail to open if it has been overwritten by a - * [checkpoint]. - * ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the - * database connection D does not know that the database file for - * schema S is in [WAL mode]. A database connection might not know - * that the database file is in [WAL mode] if there has been no prior - * I/O on that database connection, or if the database entered [WAL mode] - * after the most recent I/O on the database connection.)^ - * (Hint: Run "[PRAGMA application_id]" against a newly opened - * database connection in order to make it ready to use snapshots.) - * - * The [sqlite3_snapshot_open()] interface is only available when the - * SQLITE_ENABLE_SNAPSHOT compile-time option is used. -*/ -SQLITE_API SQLITE_EXPERIMENTAL int -sqlite3_snapshot_open(sqlite3 * db, - const char *zSchema, - sqlite3_snapshot *pSnapshot); - -/* - * CAPI3REF: Destroy a snapshot - * EXPERIMENTAL - * - * ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P. - * The application must eventually free every [sqlite3_snapshot] object - * using this routine to avoid a memory leak. - * - * The [sqlite3_snapshot_free()] interface is only available when the - * SQLITE_ENABLE_SNAPSHOT compile-time option is used. -*/ -SQLITE_API SQLITE_EXPERIMENTAL void -sqlite3_snapshot_free(sqlite3_snapshot *); - -/* - * CAPI3REF: Compare the ages of two snapshot handles. - * EXPERIMENTAL - * - * The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages - * of two valid snapshot handles. - * - * If the two snapshot handles are not associated with the same database - * file, the result of the comparison is undefined. - * - * Additionally, the result of the comparison is only valid if both of the - * snapshot handles were obtained by calling sqlite3_snapshot_get() since the - * last time the wal file was deleted. The wal file is deleted when the - * database is changed back to rollback mode or when the number of database - * clients drops to zero. If either snapshot handle was obtained before the - * wal file was last deleted, the value returned by this function - * is undefined. - * - * Otherwise, this API returns a negative value if P1 refers to an older - * snapshot than P2, zero if the two handles refer to the same database - * snapshot, and a positive value if P1 is a newer snapshot than P2. -*/ -SQLITE_API SQLITE_EXPERIMENTAL int -sqlite3_snapshot_cmp(sqlite3_snapshot - * p1, - sqlite3_snapshot - * p2); - -/* - * CAPI3REF: Recover snapshots from a wal file - * EXPERIMENTAL - * - * If all connections disconnect from a database file but do not perform - * a checkpoint, the existing wal file is opened along with the database - * file the next time the database is opened. At this point it is only - * possible to successfully call sqlite3_snapshot_open() to open the most - * recent snapshot of the database (the one at the head of the wal file), - * even though the wal file may contain other valid snapshots for which - * clients have sqlite3_snapshot handles. - * - * This function attempts to scan the wal file associated with database zDb - * of database handle db and make all valid snapshots available to - * sqlite3_snapshot_open(). It is an error if there is already a read - * transaction open on the database, or if the database is not a wal mode - * database. - * - * SQLITE_OK is returned if successful, or an SQLite error code otherwise. -*/ -SQLITE_API SQLITE_EXPERIMENTAL int -sqlite3_snapshot_recover(sqlite3 * db, - const char * zDb); - -/* - * Undo the hack that converts floating point types to integer for - * builds on processors without floating point support. -*/ -#ifdef SQLITE_OMIT_FLOATING_POINT -#undef double -#endif - -#ifdef __cplusplus -//} /* End of the 'extern "C"' block */ -#endif -#endif /* SQLITE3_H */ diff --git a/src/box/sql/sqliteInt.h b/src/box/sql/sqliteInt.h index f2a74ce..54456a2 100644 --- a/src/box/sql/sqliteInt.h +++ b/src/box/sql/sqliteInt.h @@ -123,15 +123,6 @@ #include "sqliteLimit.h" -/* Disable nuisance warnings on Borland compilers */ -#if defined(__BORLANDC__) -#pragma warn -rch /* unreachable code */ -#pragma warn -ccc /* Condition is always true or false */ -#pragma warn -aus /* Assigned value is never used */ -#pragma warn -csu /* Comparing signed and unsigned */ -#pragma warn -spa /* Suspicious pointer arithmetic */ -#endif - /* * Include standard header files as necessary */ @@ -197,17 +188,6 @@ #define SQLITE_DEFAULT_MEMSTATUS 1 #endif -/* - * Exactly one of the following macros must be defined in order to - * specify which memory allocation subsystem to use. - * - * SQLITE_SYSTEM_MALLOC // Use normal system malloc() - * SQLITE_ZERO_MALLOC // Use a stub allocator that always fails - * SQLITE_MEMDEBUG // Debugging version of system malloc() - * - * If none of the above are defined, then set SQLITE_SYSTEM_MALLOC as - * the default. - */ #if defined(SQLITE_SYSTEM_MALLOC) \ + defined(SQLITE_ZERO_MALLOC) \ + defined(SQLITE_MEMDEBUG)>1 @@ -432,18 +412,6 @@ struct sqlite3_vfs { #define SQLITE_LIMIT_TRIGGER_DEPTH 9 #define SQLITE_LIMIT_WORKER_THREADS 10 -typedef struct sqlite3_mem_methods sqlite3_mem_methods; -struct sqlite3_mem_methods { - void *(*xMalloc) (int); /* Memory allocation function */ - void (*xFree) (void *); /* Free a prior allocation */ - void *(*xRealloc) (void *, int); /* Resize an allocation */ - int (*xSize) (void *); /* Return the size of an allocation */ - int (*xRoundup) (int); /* Round up request size to allocation size */ - int (*xInit) (void *); /* Initialize the memory allocator */ - void (*xShutdown) (void *); /* Deinitialize the memory allocator */ - void *pAppData; /* Argument to xInit() and xShutdown() */ -}; - typedef struct sqlite3_pcache sqlite3_pcache; typedef struct sqlite3_pcache_page sqlite3_pcache_page; @@ -804,8 +772,6 @@ sqlite3_os_end(void); #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ #define SQLITE_CONFIG_SERIALIZED 3 /* nil */ -#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ -#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ #define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ @@ -3326,7 +3292,6 @@ struct Sqlite3Config { int szLookaside; /* Default lookaside buffer size */ int nLookaside; /* Default lookaside buffer count */ int nStmtSpill; /* Stmt-journal spill-to-disk threshold */ - sqlite3_mem_methods m; /* Low-level memory allocation interface */ sqlite3_pcache_methods2 pcache2; /* Low-level page-cache interface */ void *pHeap; /* Heap storage space */ int nHeap; /* Size of pHeap[] */ @@ -3534,7 +3499,7 @@ unsigned sqlite3Strlen30(const char *); enum field_type sqlite3ColumnType(Column *); #define sqlite3StrNICmp sqlite3_strnicmp -int sqlite3MallocInit(void); +void sqlite3MallocInit(void); void sqlite3MallocEnd(void); void *sqlite3Malloc(u64); void *sqlite3MallocZero(u64); @@ -3577,17 +3542,6 @@ int sqlite3HeapNearlyFull(void); #define sqlite3StackFree(D,P) sqlite3DbFree(D,P) #endif -/* Do not allow both MEMSYS5 and MEMSYS3 to be defined together. If they - * are, disable MEMSYS3 - */ -#ifdef SQLITE_ENABLE_MEMSYS5 -const sqlite3_mem_methods *sqlite3MemGetMemsys5(void); -#undef SQLITE_ENABLE_MEMSYS3 -#endif -#ifdef SQLITE_ENABLE_MEMSYS3 -const sqlite3_mem_methods *sqlite3MemGetMemsys3(void); -#endif - sqlite3_int64 sqlite3StatusValue(int); void sqlite3StatusUp(int, int); void sqlite3StatusDown(int, int); diff --git a/src/box/sql/status.c b/src/box/sql/status.c index 963d3d8..8742bbf 100644 --- a/src/box/sql/status.c +++ b/src/box/sql/status.c @@ -246,8 +246,7 @@ sqlite3_db_status(sqlite3 * db, /* The database connection whose status is desir HashElem *p; nByte += - sqlite3GlobalConfig.m. - xRoundup(sizeof(HashElem)) * + ROUND8(sizeof(HashElem)) * (pSchema->tblHash.count + pSchema->trigHash.count + pSchema->fkeyHash.count); -- 2.11.0