/db/sqlite3/src/sqlite3.c
C | 10964 lines | 2990 code | 425 blank | 7549 comment | 40 complexity | d8171ee7d693017778d52b17b26a1b22 MD5 | raw file
Possible License(s): LGPL-3.0, MIT, BSD-3-Clause, MPL-2.0-no-copyleft-exception, GPL-2.0, LGPL-2.1
Large files files are truncated, but you can click here to view the full file
- /******************************************************************************
- ** This file is an amalgamation of many separate C source files from SQLite
- ** version 3.6.10. By combining all the individual C code files into this
- ** single large file, the entire code can be compiled as a one translation
- ** unit. This allows many compilers to do optimizations that would not be
- ** possible if the files were compiled separately. Performance improvements
- ** of 5% are more are commonly seen when SQLite is compiled as a single
- ** translation unit.
- **
- ** This file is all you need to compile SQLite. To use SQLite in other
- ** programs, you need this file and the "sqlite3.h" header file that defines
- ** the programming interface to the SQLite library. (If you do not have
- ** the "sqlite3.h" header file at hand, you will find a copy in the first
- ** 6736 lines past this header comment.) Additional code files may be
- ** needed if you want a wrapper to interface SQLite with your choice of
- ** programming language. The code for the "sqlite3" command-line shell
- ** is also in a separate file. This file contains only code for the core
- ** SQLite library.
- **
- ** This amalgamation was generated on 2009-01-15 16:00:39 UTC.
- */
- #define SQLITE_CORE 1
- #define SQLITE_AMALGAMATION 1
- #ifndef SQLITE_PRIVATE
- # define SQLITE_PRIVATE static
- #endif
- #ifndef SQLITE_API
- # define SQLITE_API
- #endif
- /************** Begin file sqliteInt.h ***************************************/
- /*
- ** 2001 September 15
- **
- ** The author disclaims copyright to this source code. In place of
- ** a legal notice, here is a blessing:
- **
- ** May you do good and not evil.
- ** May you find forgiveness for yourself and forgive others.
- ** May you share freely, never taking more than you give.
- **
- *************************************************************************
- ** Internal interface definitions for SQLite.
- **
- ** @(#) $Id: sqliteInt.h,v 1.824 2009/01/14 23:03:41 drh Exp $
- */
- #ifndef _SQLITEINT_H_
- #define _SQLITEINT_H_
- /*
- ** Include the configuration header output by 'configure' if we're using the
- ** autoconf-based build
- */
- #ifdef _HAVE_SQLITE_CONFIG_H
- #include "config.h"
- #endif
- /************** Include sqliteLimit.h in the middle of sqliteInt.h ***********/
- /************** Begin file sqliteLimit.h *************************************/
- /*
- ** 2007 May 7
- **
- ** The author disclaims copyright to this source code. In place of
- ** a legal notice, here is a blessing:
- **
- ** May you do good and not evil.
- ** May you find forgiveness for yourself and forgive others.
- ** May you share freely, never taking more than you give.
- **
- *************************************************************************
- **
- ** This file defines various limits of what SQLite can process.
- **
- ** @(#) $Id: sqliteLimit.h,v 1.10 2009/01/10 16:15:09 danielk1977 Exp $
- */
- /*
- ** The maximum length of a TEXT or BLOB in bytes. This also
- ** limits the size of a row in a table or index.
- **
- ** The hard limit is the ability of a 32-bit signed integer
- ** to count the size: 2^31-1 or 2147483647.
- */
- #ifndef SQLITE_MAX_LENGTH
- # define SQLITE_MAX_LENGTH 1000000000
- #endif
- /*
- ** This is the maximum number of
- **
- ** * Columns in a table
- ** * Columns in an index
- ** * Columns in a view
- ** * Terms in the SET clause of an UPDATE statement
- ** * Terms in the result set of a SELECT statement
- ** * Terms in the GROUP BY or ORDER BY clauses of a SELECT statement.
- ** * Terms in the VALUES clause of an INSERT statement
- **
- ** The hard upper limit here is 32676. Most database people will
- ** tell you that in a well-normalized database, you usually should
- ** not have more than a dozen or so columns in any table. And if
- ** that is the case, there is no point in having more than a few
- ** dozen values in any of the other situations described above.
- */
- #ifndef SQLITE_MAX_COLUMN
- # define SQLITE_MAX_COLUMN 2000
- #endif
- /*
- ** The maximum length of a single SQL statement in bytes.
- **
- ** It used to be the case that setting this value to zero would
- ** turn the limit off. That is no longer true. It is not possible
- ** to turn this limit off.
- */
- #ifndef SQLITE_MAX_SQL_LENGTH
- # define SQLITE_MAX_SQL_LENGTH 1000000000
- #endif
- /*
- ** The maximum depth of an expression tree. This is limited to
- ** some extent by SQLITE_MAX_SQL_LENGTH. But sometime you might
- ** want to place more severe limits on the complexity of an
- ** expression.
- **
- ** A value of 0 used to mean that the limit was not enforced.
- ** But that is no longer true. The limit is now strictly enforced
- ** at all times.
- */
- #ifndef SQLITE_MAX_EXPR_DEPTH
- # define SQLITE_MAX_EXPR_DEPTH 1000
- #endif
- /*
- ** The maximum number of terms in a compound SELECT statement.
- ** The code generator for compound SELECT statements does one
- ** level of recursion for each term. A stack overflow can result
- ** if the number of terms is too large. In practice, most SQL
- ** never has more than 3 or 4 terms. Use a value of 0 to disable
- ** any limit on the number of terms in a compount SELECT.
- */
- #ifndef SQLITE_MAX_COMPOUND_SELECT
- # define SQLITE_MAX_COMPOUND_SELECT 500
- #endif
- /*
- ** The maximum number of opcodes in a VDBE program.
- ** Not currently enforced.
- */
- #ifndef SQLITE_MAX_VDBE_OP
- # define SQLITE_MAX_VDBE_OP 25000
- #endif
- /*
- ** The maximum number of arguments to an SQL function.
- */
- #ifndef SQLITE_MAX_FUNCTION_ARG
- # define SQLITE_MAX_FUNCTION_ARG 127
- #endif
- /*
- ** The maximum number of in-memory pages to use for the main database
- ** table and for temporary tables. The SQLITE_DEFAULT_CACHE_SIZE
- */
- #ifndef SQLITE_DEFAULT_CACHE_SIZE
- # define SQLITE_DEFAULT_CACHE_SIZE 2000
- #endif
- #ifndef SQLITE_DEFAULT_TEMP_CACHE_SIZE
- # define SQLITE_DEFAULT_TEMP_CACHE_SIZE 500
- #endif
- /*
- ** The maximum number of attached databases. This must be between 0
- ** and 30. The upper bound on 30 is because a 32-bit integer bitmap
- ** is used internally to track attached databases.
- */
- #ifndef SQLITE_MAX_ATTACHED
- # define SQLITE_MAX_ATTACHED 10
- #endif
- /*
- ** The maximum value of a ?nnn wildcard that the parser will accept.
- */
- #ifndef SQLITE_MAX_VARIABLE_NUMBER
- # define SQLITE_MAX_VARIABLE_NUMBER 999
- #endif
- /* Maximum page size. The upper bound on this value is 32768. This a limit
- ** imposed by the necessity of storing the value in a 2-byte unsigned integer
- ** and the fact that the page size must be a power of 2.
- **
- ** If this limit is changed, then the compiled library is technically
- ** incompatible with an SQLite library compiled with a different limit. If
- ** a process operating on a database with a page-size of 65536 bytes
- ** crashes, then an instance of SQLite compiled with the default page-size
- ** limit will not be able to rollback the aborted transaction. This could
- ** lead to database corruption.
- */
- #ifndef SQLITE_MAX_PAGE_SIZE
- # define SQLITE_MAX_PAGE_SIZE 32768
- #endif
- /*
- ** The default size of a database page.
- */
- #ifndef SQLITE_DEFAULT_PAGE_SIZE
- # define SQLITE_DEFAULT_PAGE_SIZE 1024
- #endif
- #if SQLITE_DEFAULT_PAGE_SIZE>SQLITE_MAX_PAGE_SIZE
- # undef SQLITE_DEFAULT_PAGE_SIZE
- # define SQLITE_DEFAULT_PAGE_SIZE SQLITE_MAX_PAGE_SIZE
- #endif
- /*
- ** Ordinarily, if no value is explicitly provided, SQLite creates databases
- ** with page size SQLITE_DEFAULT_PAGE_SIZE. However, based on certain
- ** device characteristics (sector-size and atomic write() support),
- ** SQLite may choose a larger value. This constant is the maximum value
- ** SQLite will choose on its own.
- */
- #ifndef SQLITE_MAX_DEFAULT_PAGE_SIZE
- # define SQLITE_MAX_DEFAULT_PAGE_SIZE 8192
- #endif
- #if SQLITE_MAX_DEFAULT_PAGE_SIZE>SQLITE_MAX_PAGE_SIZE
- # undef SQLITE_MAX_DEFAULT_PAGE_SIZE
- # define SQLITE_MAX_DEFAULT_PAGE_SIZE SQLITE_MAX_PAGE_SIZE
- #endif
- /*
- ** Maximum number of pages in one database file.
- **
- ** This is really just the default value for the max_page_count pragma.
- ** This value can be lowered (or raised) at run-time using that the
- ** max_page_count macro.
- */
- #ifndef SQLITE_MAX_PAGE_COUNT
- # define SQLITE_MAX_PAGE_COUNT 1073741823
- #endif
- /*
- ** Maximum length (in bytes) of the pattern in a LIKE or GLOB
- ** operator.
- */
- #ifndef SQLITE_MAX_LIKE_PATTERN_LENGTH
- # define SQLITE_MAX_LIKE_PATTERN_LENGTH 50000
- #endif
- /************** End of sqliteLimit.h *****************************************/
- /************** Continuing where we left off in sqliteInt.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
- /* Needed for various definitions... */
- #ifndef _GNU_SOURCE
- # define _GNU_SOURCE
- #endif
- /*
- ** Include standard header files as necessary
- */
- #ifdef HAVE_STDINT_H
- #include <stdint.h>
- #endif
- #ifdef HAVE_INTTYPES_H
- #include <inttypes.h>
- #endif
- /*
- * This macro is used to "hide" some ugliness in casting an int
- * value to a ptr value under the MSVC 64-bit compiler. Casting
- * non 64-bit values to ptr types results in a "hard" error with
- * the MSVC 64-bit compiler which this attempts to avoid.
- *
- * A simple compiler pragma or casting sequence could not be found
- * to correct this in all situations, so this macro was introduced.
- *
- * It could be argued that the intptr_t type could be used in this
- * case, but that type is not available on all compilers, or
- * requires the #include of specific headers which differs between
- * platforms.
- */
- #define SQLITE_INT_TO_PTR(X) ((void*)&((char*)0)[X])
- #define SQLITE_PTR_TO_INT(X) ((int)(((char*)X)-(char*)0))
- /*
- ** These #defines should enable >2GB file support on POSIX if the
- ** underlying operating system supports it. If the OS lacks
- ** large file support, or if the OS is windows, these should be no-ops.
- **
- ** Ticket #2739: The _LARGEFILE_SOURCE macro must appear before any
- ** system #includes. Hence, this block of code must be the very first
- ** code in all source files.
- **
- ** Large file support can be disabled using the -DSQLITE_DISABLE_LFS switch
- ** on the compiler command line. This is necessary if you are compiling
- ** on a recent machine (ex: Red Hat 7.2) but you want your code to work
- ** on an older machine (ex: Red Hat 6.0). If you compile on Red Hat 7.2
- ** without this option, LFS is enable. But LFS does not exist in the kernel
- ** in Red Hat 6.0, so the code won't work. Hence, for maximum binary
- ** portability you should omit LFS.
- **
- ** Similar is true for Mac OS X. LFS is only supported on Mac OS X 9 and later.
- */
- #ifndef SQLITE_DISABLE_LFS
- # define _LARGE_FILE 1
- # ifndef _FILE_OFFSET_BITS
- # define _FILE_OFFSET_BITS 64
- # endif
- # define _LARGEFILE_SOURCE 1
- #endif
- /*
- ** The SQLITE_THREADSAFE macro must be defined as either 0 or 1.
- ** Older versions of SQLite used an optional THREADSAFE macro.
- ** We support that for legacy
- */
- #if !defined(SQLITE_THREADSAFE)
- #if defined(THREADSAFE)
- # define SQLITE_THREADSAFE THREADSAFE
- #else
- # define SQLITE_THREADSAFE 1
- #endif
- #endif
- /*
- ** The SQLITE_DEFAULT_MEMSTATUS macro must be defined as either 0 or 1.
- ** It determines whether or not the features related to
- ** SQLITE_CONFIG_MEMSTATUS are available by default or not. This value can
- ** be overridden at runtime using the sqlite3_config() API.
- */
- #if !defined(SQLITE_DEFAULT_MEMSTATUS)
- # 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_MEMDEBUG // Debugging version of system malloc()
- ** SQLITE_MEMORY_SIZE // internal allocator #1
- ** SQLITE_MMAP_HEAP_SIZE // internal mmap() allocator
- ** SQLITE_POW2_MEMORY_SIZE // internal power-of-two allocator
- **
- ** If none of the above are defined, then set SQLITE_SYSTEM_MALLOC as
- ** the default.
- */
- #if defined(SQLITE_SYSTEM_MALLOC)+defined(SQLITE_MEMDEBUG)+\
- defined(SQLITE_MEMORY_SIZE)+defined(SQLITE_MMAP_HEAP_SIZE)+\
- defined(SQLITE_POW2_MEMORY_SIZE)>1
- # error "At most one of the following compile-time configuration options\
- is allows: SQLITE_SYSTEM_MALLOC, SQLITE_MEMDEBUG, SQLITE_MEMORY_SIZE,\
- SQLITE_MMAP_HEAP_SIZE, SQLITE_POW2_MEMORY_SIZE"
- #endif
- #if defined(SQLITE_SYSTEM_MALLOC)+defined(SQLITE_MEMDEBUG)+\
- defined(SQLITE_MEMORY_SIZE)+defined(SQLITE_MMAP_HEAP_SIZE)+\
- defined(SQLITE_POW2_MEMORY_SIZE)==0
- # define SQLITE_SYSTEM_MALLOC 1
- #endif
- /*
- ** If SQLITE_MALLOC_SOFT_LIMIT is defined, then try to keep the
- ** sizes of memory allocations below this value where possible.
- */
- #if defined(SQLITE_POW2_MEMORY_SIZE) && !defined(SQLITE_MALLOC_SOFT_LIMIT)
- # define SQLITE_MALLOC_SOFT_LIMIT 1024
- #endif
- /*
- ** We need to define _XOPEN_SOURCE as follows in order to enable
- ** recursive mutexes on most Unix systems. But Mac OS X is different.
- ** The _XOPEN_SOURCE define causes problems for Mac OS X we are told,
- ** so it is omitted there. See ticket #2673.
- **
- ** Later we learn that _XOPEN_SOURCE is poorly or incorrectly
- ** implemented on some systems. So we avoid defining it at all
- ** if it is already defined or if it is unneeded because we are
- ** not doing a threadsafe build. Ticket #2681.
- **
- ** See also ticket #2741.
- */
- #if !defined(_XOPEN_SOURCE) && !defined(__DARWIN__) && !defined(__APPLE__) && SQLITE_THREADSAFE
- # define _XOPEN_SOURCE 500 /* Needed to enable pthread recursive mutexes */
- #endif
- /*
- ** The TCL headers are only needed when compiling the TCL bindings.
- */
- #if defined(SQLITE_TCL) || defined(TCLSH)
- # include <tcl.h>
- #endif
- /*
- ** Many people are failing to set -DNDEBUG=1 when compiling SQLite.
- ** Setting NDEBUG makes the code smaller and run faster. So the following
- ** lines are added to automatically set NDEBUG unless the -DSQLITE_DEBUG=1
- ** option is set. Thus NDEBUG becomes an opt-in rather than an opt-out
- ** feature.
- */
- #if !defined(NDEBUG) && !defined(SQLITE_DEBUG)
- # define NDEBUG 1
- #endif
- /*
- ** The testcase() macro is used to aid in coverage testing. When
- ** doing coverage testing, the condition inside the argument to
- ** testcase() must be evaluated both true and false in order to
- ** get full branch coverage. The testcase() macro is inserted
- ** to help ensure adequate test coverage in places where simple
- ** condition/decision coverage is inadequate. For example, testcase()
- ** can be used to make sure boundary values are tested. For
- ** bitmask tests, testcase() can be used to make sure each bit
- ** is significant and used at least once. On switch statements
- ** where multiple cases go to the same block of code, testcase()
- ** can insure that all cases are evaluated.
- **
- */
- #ifdef SQLITE_COVERAGE_TEST
- SQLITE_PRIVATE void sqlite3Coverage(int);
- # define testcase(X) if( X ){ sqlite3Coverage(__LINE__); }
- #else
- # define testcase(X)
- #endif
- /*
- ** The TESTONLY macro is used to enclose variable declarations or
- ** other bits of code that are needed to support the arguments
- ** within testcase() and assert() macros.
- */
- #if !defined(NDEBUG) || defined(SQLITE_COVERAGE_TEST)
- # define TESTONLY(X) X
- #else
- # define TESTONLY(X)
- #endif
- /*
- ** The ALWAYS and NEVER macros surround boolean expressions which
- ** are intended to always be true or false, respectively. Such
- ** expressions could be omitted from the code completely. But they
- ** are included in a few cases in order to enhance the resilience
- ** of SQLite to unexpected behavior - to make the code "self-healing"
- ** or "ductile" rather than being "brittle" and crashing at the first
- ** hint of unplanned behavior.
- **
- ** In other words, ALWAYS and NEVER are added for defensive code.
- **
- ** When doing coverage testing ALWAYS and NEVER are hard-coded to
- ** be true and false so that the unreachable code then specify will
- ** not be counted as untested code.
- */
- #if defined(SQLITE_COVERAGE_TEST)
- # define ALWAYS(X) (1)
- # define NEVER(X) (0)
- #elif !defined(NDEBUG)
- SQLITE_PRIVATE int sqlite3Assert(void);
- # define ALWAYS(X) ((X)?1:sqlite3Assert())
- # define NEVER(X) ((X)?sqlite3Assert():0)
- #else
- # define ALWAYS(X) (X)
- # define NEVER(X) (X)
- #endif
- /*
- ** The macro unlikely() is a hint that surrounds a boolean
- ** expression that is usually false. Macro likely() surrounds
- ** a boolean expression that is usually true. GCC is able to
- ** use these hints to generate better code, sometimes.
- */
- #if defined(__GNUC__) && 0
- # define likely(X) __builtin_expect((X),1)
- # define unlikely(X) __builtin_expect((X),0)
- #else
- # define likely(X) !!(X)
- # define unlikely(X) !!(X)
- #endif
- /*
- ** Sometimes we need a small amount of code such as a variable initialization
- ** to setup for a later assert() statement. We do not want this code to
- ** appear when assert() is disabled. The following macro is therefore
- ** used to contain that setup code. The "VVA" acronym stands for
- ** "Verification, Validation, and Accreditation". In other words, the
- ** code within VVA_ONLY() will only run during verification processes.
- */
- #ifndef NDEBUG
- # define VVA_ONLY(X) X
- #else
- # define VVA_ONLY(X)
- #endif
- /************** Include sqlite3.h in the middle of sqliteInt.h ***************/
- /************** Begin file sqlite3.h *****************************************/
- /*
- ** 2001 September 15
- **
- ** The author disclaims copyright to this source code. In place of
- ** a legal notice, here is a blessing:
- **
- ** May you do good and not evil.
- ** May you find forgiveness for yourself and forgive others.
- ** May you share freely, never taking more than you give.
- **
- *************************************************************************
- ** 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 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 suppose 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.
- **
- ** @(#) $Id: sqlite.h.in,v 1.421 2008/12/30 06:24:58 danielk1977 Exp $
- */
- #ifndef _SQLITE3_H_
- #define _SQLITE3_H_
- #include <stdarg.h> /* Needed for the definition of va_list */
- /*
- ** Make sure we can call this stuff from C++.
- */
- #if 0
- extern "C" {
- #endif
- /*
- ** Add the ability to override 'extern'
- */
- #ifndef SQLITE_EXTERN
- # define SQLITE_EXTERN extern
- #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 intrfaces - they are support 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_DEPRECATED
- #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 {H10010} <S60100>
- **
- ** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in
- ** the sqlite3.h file specify the version of SQLite with which
- ** that header file is associated.
- **
- ** The "version" of SQLite is a string of the form "X.Y.Z".
- ** The phrase "alpha" or "beta" might be appended after the Z.
- ** The X value is major version number always 3 in SQLite3.
- ** The X value only changes when backwards compatibility is
- ** broken and we intend to never break backwards compatibility.
- ** The Y value is the minor version number and only changes when
- ** there are major feature enhancements that are forwards compatible
- ** but not backwards compatible.
- ** The Z value is the release number and is incremented with
- ** each release but resets back to 0 whenever Y is incremented.
- **
- ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
- **
- ** INVARIANTS:
- **
- ** {H10011} The SQLITE_VERSION #define in the sqlite3.h header file shall
- ** evaluate to a string literal that is the SQLite version
- ** with which the header file is associated.
- **
- ** {H10014} The SQLITE_VERSION_NUMBER #define shall resolve to an integer
- ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z
- ** are the major version, minor version, and release number.
- */
- #define SQLITE_VERSION "3.6.10"
- #define SQLITE_VERSION_NUMBER 3006010
- /*
- ** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100>
- ** KEYWORDS: sqlite3_version
- **
- ** These features provide the same information as the [SQLITE_VERSION]
- ** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated
- ** with the library instead of the header file. Cautious programmers might
- ** include a check in their application to verify that
- ** sqlite3_libversion_number() always returns the value
- ** [SQLITE_VERSION_NUMBER].
- **
- ** The sqlite3_libversion() function returns the same information as is
- ** in the sqlite3_version[] string constant. The function is provided
- ** for use in DLLs since DLL users usually do not have direct access to string
- ** constants within the DLL.
- **
- ** INVARIANTS:
- **
- ** {H10021} The [sqlite3_libversion_number()] interface shall return
- ** an integer equal to [SQLITE_VERSION_NUMBER].
- **
- ** {H10022} The [sqlite3_version] string constant shall contain
- ** the text of the [SQLITE_VERSION] string.
- **
- ** {H10023} The [sqlite3_libversion()] function shall return
- ** a pointer to the [sqlite3_version] string constant.
- */
- SQLITE_API const char sqlite3_version[] = SQLITE_VERSION;
- SQLITE_API const char *sqlite3_libversion(void);
- SQLITE_API int sqlite3_libversion_number(void);
- /*
- ** CAPI3REF: Test To See If The Library Is Threadsafe {H10100} <S60100>
- **
- ** SQLite can be compiled with or without mutexes. When
- ** the [SQLITE_THREADSAFE] C preprocessor macro 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 a program 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 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_MUTEX]. The return value of this function shows
- ** only the default compile-time setting, not any run-time changes
- ** to that setting.
- **
- ** See the [threading mode] documentation for additional information.
- **
- ** INVARIANTS:
- **
- ** {H10101} The [sqlite3_threadsafe()] function shall return zero if
- ** and only if SQLite was compiled with mutexing code omitted.
- **
- ** {H10102} The value returned by the [sqlite3_threadsafe()] function
- ** shall remain the same across calls to [sqlite3_config()].
- */
- SQLITE_API int sqlite3_threadsafe(void);
- /*
- ** CAPI3REF: Database Connection Handle {H12000} <S40200>
- ** 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()], [sqlite3_open16()], and
- ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
- ** is its destructor. 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 {H10200} <S10110>
- ** 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.
- **
- ** INVARIANTS:
- **
- ** {H10201} The [sqlite_int64] and [sqlite3_int64] type shall specify
- ** a 64-bit signed integer.
- **
- ** {H10202} The [sqlite_uint64] and [sqlite3_uint64] type shall specify
- ** a 64-bit unsigned integer.
- */
- #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 {H12010} <S30100><S40200>
- **
- ** This routine is the destructor for the [sqlite3] object.
- **
- ** Applications should [sqlite3_finalize | finalize] all [prepared statements]
- ** and [sqlite3_blob_close | close] all [BLOB handles] associated with
- ** the [sqlite3] object prior to attempting to close the object.
- ** The [sqlite3_next_stmt()] interface can be used to locate all
- ** [prepared statements] associated with a [database connection] if desired.
- ** Typical code might look like this:
- **
- ** <blockquote><pre>
- ** sqlite3_stmt *pStmt;
- ** while( (pStmt = sqlite3_next_stmt(db, 0))!=0 ){
- ** sqlite3_finalize(pStmt);
- ** }
- ** </pre></blockquote>
- **
- ** If [sqlite3_close()] is invoked while a transaction is open,
- ** the transaction is automatically rolled back.
- **
- ** INVARIANTS:
- **
- ** {H12011} A successful call to [sqlite3_close(C)] shall destroy the
- ** [database connection] object C.
- **
- ** {H12012} A successful call to [sqlite3_close(C)] shall return SQLITE_OK.
- **
- ** {H12013} A successful call to [sqlite3_close(C)] shall release all
- ** memory and system resources associated with [database connection]
- ** C.
- **
- ** {H12014} A call to [sqlite3_close(C)] on a [database connection] C that
- ** has one or more open [prepared statements] shall fail with
- ** an [SQLITE_BUSY] error code.
- **
- ** {H12015} A call to [sqlite3_close(C)] where C is a NULL pointer shall
- ** be a harmless no-op returning SQLITE_OK.
- **
- ** {H12019} When [sqlite3_close(C)] is invoked on a [database connection] C
- ** that has a pending transaction, the transaction shall be
- ** rolled back.
- **
- ** ASSUMPTIONS:
- **
- ** {A12016} The C parameter to [sqlite3_close(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.
- */
- SQLITE_API int sqlite3_close(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 {H12100} <S10000>
- **
- ** The sqlite3_exec() interface is a convenient way of running one or more
- ** SQL statements without having to write a lot of C code. The UTF-8 encoded
- ** SQL statements are passed in as the second parameter to sqlite3_exec().
- ** The statements are evaluated one by one until either an error or
- ** an interrupt is encountered, or until they are all done. The 3rd parameter
- ** is an optional callback that is invoked once for each row of any query
- ** results produced by the SQL statements. The 5th parameter tells where
- ** to write any error messages.
- **
- ** The error message passed back through the 5th parameter is held
- ** in memory obtained from [sqlite3_malloc()]. To avoid a memory leak,
- ** the calling application should call [sqlite3_free()] on any error
- ** message returned through the 5th parameter when it has finished using
- ** the error message.
- **
- ** If the SQL statement in the 2nd parameter is NULL or an empty string
- ** or a string containing only whitespace and comments, then no SQL
- ** statements are evaluated and the database is not changed.
- **
- ** The sqlite3_exec() interface is implemented in terms of
- ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
- ** The sqlite3_exec() routine does nothing to the database that cannot be done
- ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
- **
- ** INVARIANTS:
- **
- ** {H12101} A successful invocation of [sqlite3_exec(D,S,C,A,E)]
- ** shall sequentially evaluate all of the UTF-8 encoded,
- ** semicolon-separated SQL statements in the zero-terminated
- ** string S within the context of the [database connection] D.
- **
- ** {H12102} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL then
- ** the actions of the interface shall be the same as if the
- ** S parameter were an empty string.
- **
- ** {H12104} The return value of [sqlite3_exec()] shall be [SQLITE_OK] if all
- ** SQL statements run successfully and to completion.
- **
- ** {H12105} The return value of [sqlite3_exec()] shall be an appropriate
- ** non-zero [error code] if any SQL statement fails.
- **
- ** {H12107} If one or more of the SQL statements handed to [sqlite3_exec()]
- ** return results and the 3rd parameter is not NULL, then
- ** the callback function specified by the 3rd parameter shall be
- ** invoked once for each row of result.
- **
- ** {H12110} If the callback returns a non-zero value then [sqlite3_exec()]
- ** shall abort the SQL statement it is currently evaluating,
- ** skip all subsequent SQL statements, and return [SQLITE_ABORT].
- **
- ** {H12113} The [sqlite3_exec()] routine shall pass its 4th parameter through
- ** as the 1st parameter of the callback.
- **
- ** {H12116} The [sqlite3_exec()] routine shall set the 2nd parameter of its
- ** callback to be the number of columns in the current row of
- ** result.
- **
- ** {H12119} The [sqlite3_exec()] routine shall set the 3rd parameter of its
- ** callback to be an array of pointers to strings holding the
- ** values for each column in the current result set row as
- ** obtained from [sqlite3_column_text()].
- **
- ** {H12122} The [sqlite3_exec()] routine shall set the 4th parameter of its
- ** callback to be an array of pointers to strings holding the
- ** names of result columns as obtained from [sqlite3_column_name()].
- **
- ** {H12125} If the 3rd parameter to [sqlite3_exec()] is NULL then
- ** [sqlite3_exec()] shall silently discard query results.
- **
- ** {H12131} If an error occurs while parsing or evaluating any of the SQL
- ** statements in the S parameter of [sqlite3_exec(D,S,C,A,E)] and if
- ** the E parameter is not NULL, then [sqlite3_exec()] shall store
- ** in *E an appropriate error message written into memory obtained
- ** from [sqlite3_malloc()].
- **
- ** {H12134} The [sqlite3_exec(D,S,C,A,E)] routine shall set the value of
- ** *E to NULL if E is not NULL and there are no errors.
- **
- ** {H12137} The [sqlite3_exec(D,S,C,A,E)] function shall set the [error code]
- ** and message accessible via [sqlite3_errcode()],
- ** [sqlite3_extended_errcode()],
- ** [sqlite3_errmsg()], and [sqlite3_errmsg16()].
- **
- ** {H12138} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL or an
- ** empty string or contains nothing other than whitespace, comments,
- ** and/or semicolons, then results of [sqlite3_errcode()],
- ** [sqlite3_extended_errcode()],
- ** [sqlite3_errmsg()], and [sqlite3_errmsg16()]
- ** shall reset to indicate no errors.
- **
- ** ASSUMPTIONS:
- **
- ** {A12141} The first parameter to [sqlite3_exec()] must be an valid and open
- ** [database connection].
- **
- ** {A12142} The database connection must not be closed while
- ** [sqlite3_exec()] is running.
- **
- ** {A12143} The calling function should use [sqlite3_free()] to free
- ** the memory that *errmsg is left pointing at once the error
- ** message is no longer needed.
- **
- ** {A12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()]
- ** must remain unchanged 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 {H10210} <S10700>
- ** KEYWORDS: SQLITE_OK {error code} {error codes}
- ** KEYWORDS: {result code} {result codes}
- **
- ** Many SQLite functions return an integer result code from the set shown
- ** here in order to indicates success or failure.
- **
- ** New error codes may be added in future versions of SQLite.
- **
- ** See also: [SQLITE_IOERR_READ | extended result codes]
- */
- #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 /* NOT USED. Table or record not found */
- #define SQLITE_FULL 13 /* Insertion failed because database is full */
- #define SQLITE_CANTOPEN 14 /* Unable to open the database file */
- #define SQLITE_PROTOCOL 15 /* NOT USED. 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_AUTH 23 /* Authorization denied */
- #define SQLITE_FORMAT 24 /* Auxiliary database format error */
- #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
- #define SQLITE_NOTADB 26 /* File opened that is not a database file */
- #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 {H10220} <S10700>
- ** KEYWORDS: {extended error code} {extended error codes}
- ** KEYWORDS: {extended result code} {extended result codes}
- **
- ** In its default configuration, SQLite API routines return one of 26 integer
- ** [SQLITE_OK | 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 and later) include
- ** support for additional result codes that provide more detailed information
- ** about errors. The extended result codes are enabled or disabled
- ** on a per database connection basis using the
- ** [sqlite3_extended_result_codes()] API.
- **
- ** Some of the available extended result codes are listed here.
- ** One may expect the number of extended result codes will be expand
- ** over time. Software that uses extended result codes should expect
- ** to see new result codes in future releases of SQLite.
- **
- ** The SQLITE_OK result code will never be extended. It will always
- ** be exactly zero.
- **
- ** INVARIANTS:
- **
- ** {H10223} The symbolic name for an extended result code shall contains
- ** a related primary result code as a prefix.
- **
- ** {H10224} Primary result code names shall contain a single "_" character.
- **
- ** {H10225} Extended result code names shall contain two or more "_" characters.
- **
- ** {H10226} The numeric value of an extended result code shall contain the
- ** numeric value of its corresponding primary result code in
- ** its least significant 8 bits.
- */
- #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))
- /*
- ** CAPI3REF: Flags For File Open Operations {H10230} <H11120> <H12700>
- **
- ** These bit values are intended for use in the
- ** 3rd parameter to the [sqlite3_open_v2()] interface and
- ** in the 4th parameter to the xOpen method of the
- ** [sqlite3_vfs] object.
- */
- #define SQLITE_OPEN_READONLY 0x00000001
- #define SQLITE_OPEN_READWRITE 0x00000002
- #define SQLITE_OPEN_CREATE 0x00000004
- #define SQLITE_OPEN_DELETEONCLOSE 0x00000008
- #define SQLITE_OPEN_EXCLUSIVE 0x00000010
- #define SQLITE_OPEN_MAIN_DB 0x00000100
- #define SQLITE_OPEN_TEMP_DB 0x00000200
- #define SQLITE_OPEN_TRANSIENT_DB 0x00000400
- #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800
- #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000
- #define SQLITE_OPEN_SUBJOURNAL 0x00002000
- #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000
- #define SQLITE_OPEN_NOMUTEX 0x00008000
- #define SQLITE_OPEN_FULLMUTEX 0x00010000
- /*
- ** CAPI3REF: Device Characteristics {H10240} <H11120>
- **
- ** The xDeviceCapabilities method of the [sqlite3_io_methods]
- ** object returns an integer which is a vector of the 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().
- */
- #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
- /*
- ** CAPI3REF: File Locking Levels {H10250} <H11120> <H11310>
- **
- ** 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 {H10260} <H11120>
- **
- ** 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. The SQLITE_SYNC_NORMAL flag means
- ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means
- ** to use Mac OS X style fullsync instead of fsync().
- */
- #define SQLITE_SYNC_NORMAL 0x00002
- #define SQLITE_SYNC_FULL 0x00003
- #define SQLITE_SYNC_DATAONLY 0x00010
- /*
- ** CAPI3REF: OS Interface Open File Handle {H11110} <S20110>
- **
- ** An [sqlite3_file] object represents an open file in the 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 {H11120} <S20110>
- **
- ** 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.
- **
- ** 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
- ** <ul>
- ** <li> [SQLITE_LOCK_NONE],
- ** <li> [SQLITE_LOCK_SHARED],
- ** <li> [SQLITE_LOCK_RESERVED],
- ** <li> [SQLITE_LOCK_PENDING], or
- ** <li> [SQLITE_LOCK_EXCLUSIVE].
- ** </ul>
- ** 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 [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
- ** Applications that define a custom xFileControl method should use opcodes
- ** greater than 100 to avoid conflicts.
- **
- ** 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:
- **
- ** <ul>
- ** <li> [SQLITE_IOCAP_ATOMIC]
- ** <li> [SQLITE_IOCAP_ATOMIC512]
- ** <li> [SQLITE_IOCAP_ATOMIC1K]
- ** <li> [SQLITE_IOCAP_ATOMIC2K]
- ** <li> [SQLITE_IOCAP_ATOMIC4K]
- ** <li> [SQLITE_IOCAP_ATOMIC8K]
- ** <li> [SQLITE_IOCAP_ATOMIC16K]
- ** <li> [SQLITE_IOCAP_ATOMIC32K]
- ** <li> [SQLITE_IOCAP_ATOMIC64K]
- ** <li> [SQLITE_IOCAP_SAFE_APPEND]
- ** <li> [SQLITE_IOCAP_SEQUENTIAL]
- ** </ul>
- **
- ** 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*);
- /* Additional methods may be added in future releases */
- };
- /*
- ** CAPI3REF: Standard File Control Opcodes {H11310} <S30800>
- **
- ** These integer constants are opcodes for the xFileControl method
- ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
- ** interface.
- **
- ** 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 only needs to be supported when SQLITE_TEST
- ** is defined.
- */
- #define SQLITE_FCNTL_LOCKSTATE 1
- #define SQLITE_GET_LOCKPROXYFILE 2
- #define SQLITE_SET_LOCKPROXYFILE 3
- #define SQLITE_LAST_ERRNO 4
- /*
- ** CAPI3REF: Mutex Handle {H17110} <S20130>
- **
- ** 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: OS Interface Object {H11140} <S20100>
- **
- ** 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".
- **
- ** 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 t…
Large files files are truncated, but you can click here to view the full file