sqlite3.h.svn-base
上传用户:sunhongbo
上传日期:2022-01-25
资源大小:3010k
文件大小:251k
- /*
- ** 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.305 2008/04/16 00:28:14 drh 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++.
- */
- #ifdef __cplusplus
- extern "C" {
- #endif
- /*
- ** Add the ability to override 'extern'
- */
- #ifndef SQLITE_EXTERN
- # define SQLITE_EXTERN extern
- #endif
- /*
- ** Make sure these symbols where 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 {F10010}
- **
- ** 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 release number
- ** and is incremented with
- ** each release but resets back to 0 when Y is incremented.
- **
- ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
- **
- ** INVARIANTS:
- **
- ** {F10011} The SQLITE_VERSION #define in the sqlite3.h header file
- ** evaluates to a string literal that is the SQLite version
- ** with which the header file is associated.
- **
- ** {F10014} The SQLITE_VERSION_NUMBER #define resolves 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.5.8"
- #define SQLITE_VERSION_NUMBER 3005008
- /*
- ** CAPI3REF: Run-Time Library Version Numbers {F10020}
- ** 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:
- **
- ** {F10021} The [sqlite3_libversion_number()] interface returns an integer
- ** equal to [SQLITE_VERSION_NUMBER].
- **
- ** {F10022} The [sqlite3_version] string constant contains the text of the
- ** [SQLITE_VERSION] string.
- **
- ** {F10023} The [sqlite3_libversion()] function returns
- ** a pointer to the [sqlite3_version] string constant.
- */
- SQLITE_EXTERN const char sqlite3_version[];
- const char *sqlite3_libversion(void);
- int sqlite3_libversion_number(void);
- /*
- ** CAPI3REF: Test To See If The Library Is Threadsafe {F10100}
- **
- ** SQLite can be compiled with or without mutexes. When
- ** the SQLITE_THREADSAFE C preprocessor macro is true, mutexes
- ** are enabled and SQLite is threadsafe. When that macro is false,
- ** the mutexes are omitted. Without the mutexes, it is not safe
- ** to use SQLite from more than one thread.
- **
- ** There is a measurable performance penalty for enabling mutexes.
- ** 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.
- **
- ** INVARIANTS:
- **
- ** {F10101} The [sqlite3_threadsafe()] function returns nonzero if
- ** SQLite was compiled with its mutexes enabled or zero
- ** if SQLite was compiled with mutexes disabled.
- */
- int sqlite3_threadsafe(void);
- /*
- ** CAPI3REF: Database Connection Handle {F12000}
- ** KEYWORDS: {database connection}
- **
- ** Each open SQLite database is represented by 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 this
- ** object.
- */
- typedef struct sqlite3 sqlite3;
- /*
- ** CAPI3REF: 64-Bit Integer Types {F10200}
- ** 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:
- **
- ** {F10201} The [sqlite_int64] and [sqlite3_int64] types specify a
- ** 64-bit signed integer.
- **
- ** {F10202} The [sqlite_uint64] and [sqlite3_uint64] types 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 {F12010}
- **
- ** This routine is the destructor for the [sqlite3] object.
- **
- ** Applications should [sqlite3_finalize | finalize] all
- ** [prepared statements] and
- ** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs]
- ** associated with the [sqlite3] object prior
- ** to attempting to close the [sqlite3] object.
- **
- ** <todo>What happens to pending transactions? Are they
- ** rolled back, or abandoned?</todo>
- **
- ** INVARIANTS:
- **
- ** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object
- ** allocated by a prior call to [sqlite3_open()],
- ** [sqlite3_open16()], or [sqlite3_open_v2()].
- **
- ** {F12012} The [sqlite3_close()] function releases all memory used by the
- ** connection and closes all open files.
- **
- ** {F12013} If the database connection contains
- ** [prepared statements] that have not been
- ** finalized by [sqlite3_finalize()], then [sqlite3_close()]
- ** returns [SQLITE_BUSY] and leaves the connection open.
- **
- ** {F12014} Giving sqlite3_close() a NULL pointer is a harmless no-op.
- **
- ** LIMITATIONS:
- **
- ** {U12015} The parameter to [sqlite3_close()] must be an [sqlite3] object
- ** pointer previously obtained from [sqlite3_open()] or the
- ** equivalent, or NULL.
- **
- ** {U12016} The parameter to [sqlite3_close()] must not have been previously
- ** closed.
- */
- 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 {F12100}
- **
- ** The sqlite3_exec() interface is a convenient way of running
- ** one or more SQL statements without a lot of C code. The
- ** 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 sqlite3_exec() interface is implemented in terms of
- ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
- ** The sqlite3_exec() routine does nothing that cannot be done
- ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
- ** The sqlite3_exec() is just a convenient wrapper.
- **
- ** INVARIANTS:
- **
- ** {F12101} The [sqlite3_exec()] interface evaluates zero or more UTF-8
- ** encoded, semicolon-separated, SQL statements in the
- ** zero-terminated string of its 2nd parameter within the
- ** context of the [sqlite3] object given in the 1st parameter.
- **
- ** {F12104} The return value of [sqlite3_exec()] is SQLITE_OK if all
- ** SQL statements run successfully.
- **
- ** {F12105} The return value of [sqlite3_exec()] is an appropriate
- ** non-zero error code if any SQL statement fails.
- **
- ** {F12107} 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 is
- ** invoked once for each row of result.
- **
- ** {F12110} If the callback returns a non-zero value then [sqlite3_exec()]
- ** will aborted the SQL statement it is currently evaluating,
- ** skip all subsequent SQL statements, and return [SQLITE_ABORT].
- ** <todo>What happens to *errmsg here? Does the result code for
- ** sqlite3_errcode() get set?</todo>
- **
- ** {F12113} The [sqlite3_exec()] routine will pass its 4th parameter through
- ** as the 1st parameter of the callback.
- **
- ** {F12116} The [sqlite3_exec()] routine sets the 2nd parameter of its
- ** callback to be the number of columns in the current row of
- ** result.
- **
- ** {F12119} The [sqlite3_exec()] routine sets 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()].
- **
- ** {F12122} The [sqlite3_exec()] routine sets 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()].
- **
- ** {F12125} If the 3rd parameter to [sqlite3_exec()] is NULL then
- ** [sqlite3_exec()] never invokes a callback. All query
- ** results are silently discarded.
- **
- ** {F12128} If an error occurs while parsing or evaluating any of the SQL
- ** statements handed to [sqlite3_exec()] then [sqlite3_exec()] will
- ** return an [error code] other than [SQLITE_OK].
- **
- ** {F12131} If an error occurs while parsing or evaluating any of the SQL
- ** handed to [sqlite3_exec()] and if the 5th parameter (errmsg)
- ** to [sqlite3_exec()] is not NULL, then an error message is
- ** allocated using the equivalent of [sqlite3_mprintf()] and
- ** *errmsg is made to point to that message.
- **
- ** {F12134} The [sqlite3_exec()] routine does not change the value of
- ** *errmsg if errmsg is NULL or if there are no errors.
- **
- ** {F12137} The [sqlite3_exec()] function sets the error code and message
- ** accessible via [sqlite3_errcode()], [sqlite3_errmsg()], and
- ** [sqlite3_errmsg16()].
- **
- ** LIMITATIONS:
- **
- ** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open
- ** [database connection].
- **
- ** {U12142} The database connection must not be closed while
- ** [sqlite3_exec()] is running.
- **
- ** {U12143} The calling function is should use [sqlite3_free()] to free
- ** the memory that *errmsg is left pointing at once the error
- ** message is no longer needed.
- **
- ** {U12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()]
- ** must remain unchanged while [sqlite3_exec()] is running.
- */
- int sqlite3_exec(
- sqlite3*, /* An open database */
- const char *sql, /* SQL to be evaluted */
- int (*callback)(void*,int,char**,char**), /* Callback function */
- void *, /* 1st argument to callback */
- char **errmsg /* Error msg written here */
- );
- /*
- ** CAPI3REF: Result Codes {F10210}
- ** KEYWORDS: SQLITE_OK {error code} {error codes}
- **
- ** Many SQLite functions return an integer result code from the set shown
- ** here in order to indicates success or failure.
- **
- ** 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 {F10220}
- ** KEYWORDS: {extended error code} {extended error codes}
- ** KEYWORDS: {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 course-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
- ** for each database connection 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:
- **
- ** {F10223} The symbolic name for an extended result code always contains
- ** a related primary result code as a prefix.
- **
- ** {F10224} Primary result code names contain a single "_" character.
- **
- ** {F10225} Extended result code names contain two or more "_" characters.
- **
- ** {F10226} The numeric value of an extended result code contains 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))
- /*
- ** CAPI3REF: Flags For File Open Operations {F10230}
- **
- ** 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
- /*
- ** CAPI3REF: Device Characteristics {F10240}
- **
- ** 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 {F10250}
- **
- ** 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 {F10260}
- **
- ** 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 {F11110}
- **
- ** 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 {F11120}
- **
- ** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to
- ** an instance of this object. This object defines the
- ** methods used to perform various operations against the open file.
- **
- ** 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 an
- ** OS-X style fullsync. The SQLITE_SYNC_DATA 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 looks
- ** to see if any database connection, either in this
- ** process or in some other process, is holding an RESERVED,
- ** PENDING, or EXCLUSIVE lock on the file. It returns true
- ** if such a lock exists and false if not.
- **
- ** 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 which is intended to be a pointer
- ** 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 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().
- */
- 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 (*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 {F11310}
- **
- ** These integer constants are opcodes for the xFileControl method
- ** of the [sqlite3_io_methods] object and to 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
- /*
- ** CAPI3REF: Mutex Handle {F17110}
- **
- ** 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 {F11140}
- **
- ** An instance of this 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 iVersion field is initially 1 but may be larger for future
- ** versions of SQLite. Additional fields may be appended to this
- ** object when the iVersion value is increased.
- **
- ** 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.
- **
- ** 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.
- **
- ** {F11141} SQLite will guarantee that the zFilename string passed to
- ** xOpen() is a full pathname as generated by xFullPathname() and
- ** that the string will be valid and unchanged until xClose() is
- ** called. {END} So the [sqlite3_file] can store a pointer to the
- ** filename if it needs to remember the filename for some reason.
- **
- ** {F11142} The flags argument to xOpen() includes all bits set in
- ** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
- ** or [sqlite3_open16()] is used, then flags includes at least
- ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END}
- ** If xOpen() opens a file read-only then it sets *pOutFlags to
- ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be
- ** set.
- **
- ** {F11143} SQLite will also add one of the following flags to the xOpen()
- ** call, depending on the object being opened:
- **
- ** <ul>
- ** <li> [SQLITE_OPEN_MAIN_DB]
- ** <li> [SQLITE_OPEN_MAIN_JOURNAL]
- ** <li> [SQLITE_OPEN_TEMP_DB]
- ** <li> [SQLITE_OPEN_TEMP_JOURNAL]
- ** <li> [SQLITE_OPEN_TRANSIENT_DB]
- ** <li> [SQLITE_OPEN_SUBJOURNAL]
- ** <li> [SQLITE_OPEN_MASTER_JOURNAL]
- ** </ul> {END}
- **
- ** The file I/O implementation can use the object type flags to
- ** changes 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:
- **
- ** <ul>
- ** <li> [SQLITE_OPEN_DELETEONCLOSE]
- ** <li> [SQLITE_OPEN_EXCLUSIVE]
- ** </ul>
- **
- ** {F11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
- ** deleted when it is closed. {F11146} The [SQLITE_OPEN_DELETEONCLOSE]
- ** will be set for TEMP databases, journals and for subjournals.
- ** {F11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
- ** for exclusive access. This flag is set for all files except
- ** for the main database file. {END}
- **
- ** {F11148} At least szOsFile bytes of memory are allocated by SQLite
- ** to hold the [sqlite3_file] structure passed as the third
- ** argument to xOpen. {END} The xOpen method does not have to
- ** allocate the structure; it should just fill it in.
- **
- ** {F11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
- ** to test for the existance of a file,
- ** or [SQLITE_ACCESS_READWRITE] to test to see
- ** if a file is readable and writable, or [SQLITE_ACCESS_READ]
- ** to test to see if a file is at least readable. {END} The file can be a
- ** directory.
- **
- ** {F11150} SQLite will always allocate at least mxPathname+1 bytes for
- ** the output buffers for xGetTempname and xFullPathname. {F11151} The exact
- ** size of the output buffer is also passed as a parameter to both
- ** methods. {END} If the output buffer is not large enough, SQLITE_CANTOPEN
- ** should be returned. As 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(), and xCurrentTime() 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.
- */
- typedef struct sqlite3_vfs sqlite3_vfs;
- struct sqlite3_vfs {
- int iVersion; /* Structure version number */
- 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 (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut);
- 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 (*xDlClose)(sqlite3_vfs*, void*);
- int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
- int (*xSleep)(sqlite3_vfs*, int microseconds);
- int (*xCurrentTime)(sqlite3_vfs*, double*);
- /* New fields may be appended in figure versions. The iVersion
- ** value will increment whenever this happens. */
- };
- /*
- ** CAPI3REF: Flags for the xAccess VFS method {F11190}
- **
- ** {F11191} These integer constants can be used as the third parameter to
- ** the xAccess method of an [sqlite3_vfs] object. {END} They determine
- ** what kind of permissions the xAccess method is
- ** looking for. {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method
- ** simply checks to see if the file exists. {F11193} With
- ** SQLITE_ACCESS_READWRITE, the xAccess method checks to see
- ** if the file is both readable and writable. {F11194} With
- ** SQLITE_ACCESS_READ the xAccess method
- ** checks to see if the file is readable.
- */
- #define SQLITE_ACCESS_EXISTS 0
- #define SQLITE_ACCESS_READWRITE 1
- #define SQLITE_ACCESS_READ 2
- /*
- ** CAPI3REF: Enable Or Disable Extended Result Codes {F12200}
- **
- ** The sqlite3_extended_result_codes() routine enables or disables the
- ** [SQLITE_IOERR_READ | extended result codes] feature of SQLite.
- ** The extended result codes are disabled by default for historical
- ** compatibility.
- **
- ** INVARIANTS:
- **
- ** {F12201} Each new [database connection] has the
- ** [extended result codes] feature
- ** disabled by default.
- **
- ** {F12202} The [sqlite3_extended_result_codes(D,F)] interface will enable
- ** [extended result codes] for the
- ** [database connection] D if the F parameter
- ** is true, or disable them if F is false.
- */
- int sqlite3_extended_result_codes(sqlite3*, int onoff);
- /*
- ** CAPI3REF: Last Insert Rowid {F12220}
- **
- ** Each entry in an SQLite table has a unique 64-bit signed
- ** integer key called the "rowid". The rowid is always available
- ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
- ** names are not also used by explicitly declared columns. If
- ** the table has a column of type INTEGER PRIMARY KEY then that column
- ** is another alias for the rowid.
- **
- ** This routine returns the rowid of the most recent
- ** successful INSERT into the database from the database connection
- ** shown in the first argument. If no successful inserts
- ** have ever occurred on this database connection, zero is returned.
- **
- ** If an INSERT occurs within a trigger, then the rowid of the
- ** inserted row is returned by this routine as long as the trigger
- ** is running. But once the trigger terminates, the value returned
- ** by this routine reverts to the last value inserted before the
- ** trigger fired.
- **
- ** An INSERT that fails due to a constraint violation is not a
- ** successful insert and does not change the value returned by this
- ** routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
- ** and INSERT OR ABORT make no changes to the return value of this
- ** routine when their insertion fails. When INSERT OR REPLACE
- ** encounters a constraint violation, it does not fail. The
- ** INSERT continues to completion after deleting rows that caused
- ** the constraint problem so INSERT OR REPLACE will always change
- ** the return value of this interface.
- **
- ** For the purposes of this routine, an insert is considered to
- ** be successful even if it is subsequently rolled back.
- **
- ** INVARIANTS:
- **
- ** {F12221} The [sqlite3_last_insert_rowid()] function returns the
- ** rowid of the most recent successful insert done
- ** on the same database connection and within the same
- ** trigger context, or zero if there have
- ** been no qualifying inserts on that connection.
- **
- ** {F12223} The [sqlite3_last_insert_rowid()] function returns
- ** same value when called from the same trigger context
- ** immediately before and after a ROLLBACK.
- **
- ** LIMITATIONS:
- **
- ** {U12232} If a separate thread does a new insert on the same
- ** database connection while the [sqlite3_last_insert_rowid()]
- ** function is running and thus changes the last insert rowid,
- ** then the value returned by [sqlite3_last_insert_rowid()] is
- ** unpredictable and might not equal either the old or the new
- ** last insert rowid.
- */
- sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
- /*
- ** CAPI3REF: Count The Number Of Rows Modified {F12240}
- **
- ** This function returns the number of database rows that were changed
- ** or inserted or deleted by the most recently completed SQL statement
- ** on the connection specified by the first parameter. Only
- ** changes that are directly specified by the INSERT, UPDATE, or
- ** DELETE statement are counted. Auxiliary changes caused by
- ** triggers are not counted. Use the [sqlite3_total_changes()] function
- ** to find the total number of changes including changes caused by triggers.
- **
- ** A "row change" is a change to a single row of a single table
- ** caused by an INSERT, DELETE, or UPDATE statement. Rows that
- ** are changed as side effects of REPLACE constraint resolution,
- ** rollback, ABORT processing, DROP TABLE, or by any other
- ** mechanisms do not count as direct row changes.
- **
- ** A "trigger context" is a scope of execution that begins and
- ** ends with the script of a trigger. Most SQL statements are
- ** evaluated outside of any trigger. This is the "top level"
- ** trigger context. If a trigger fires from the top level, a
- ** new trigger context is entered for the duration of that one
- ** trigger. Subtriggers create subcontexts for their duration.
- **
- ** Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
- ** not create a new trigger context.
- **
- ** This function returns the number of direct row changes in the
- ** most recent INSERT, UPDATE, or DELETE statement within the same
- ** trigger context.
- **
- ** So when called from the top level, this function returns the
- ** number of changes in the most recent INSERT, UPDATE, or DELETE
- ** that also occurred at the top level.
- ** Within the body of a trigger, the sqlite3_changes() interface
- ** can be called to find the number of
- ** changes in the most recently completed INSERT, UPDATE, or DELETE
- ** statement within the body of the same trigger.
- ** However, the number returned does not include in changes
- ** caused by subtriggers since they have their own context.
- **
- ** SQLite implements the command "DELETE FROM table" without
- ** a WHERE clause by dropping and recreating the table. (This is much
- ** faster than going through and deleting individual elements from the
- ** table.) Because of this optimization, the deletions in
- ** "DELETE FROM table" are not row changes and will not be counted
- ** by the sqlite3_changes() or [sqlite3_total_changes()] functions.
- ** To get an accurate count of the number of rows deleted, use
- ** "DELETE FROM table WHERE 1" instead.
- **
- ** INVARIANTS:
- **
- ** {F12241} The [sqlite3_changes()] function returns the number of
- ** row changes caused by the most recent INSERT, UPDATE,
- ** or DELETE statement on the same database connection and
- ** within the same trigger context, or zero if there have
- ** not been any qualifying row changes.
- **
- ** LIMITATIONS:
- **
- ** {U12252} If a separate thread makes changes on the same database connection
- ** while [sqlite3_changes()] is running then the value returned
- ** is unpredictable and unmeaningful.
- */
- int sqlite3_changes(sqlite3*);
- /*
- ** CAPI3REF: Total Number Of Rows Modified {F12260}
- ***
- ** This function returns the number of row changes caused
- ** by INSERT, UPDATE or DELETE statements since the database handle
- ** was opened. The count includes all changes from all trigger
- ** contexts. But the count does not include changes used to
- ** implement REPLACE constraints, do rollbacks or ABORT processing,
- ** or DROP table processing.
- ** The changes
- ** are counted as soon as the statement that makes them is completed
- ** (when the statement handle is passed to [sqlite3_reset()] or
- ** [sqlite3_finalize()]).
- **
- ** SQLite implements the command "DELETE FROM table" without
- ** a WHERE clause by dropping and recreating the table. (This is much
- ** faster than going
- ** through and deleting individual elements from the table.) Because of
- ** this optimization, the change count for "DELETE FROM table" will be
- ** zero regardless of the number of elements that were originally in the
- ** table. To get an accurate count of the number of rows deleted, use
- ** "DELETE FROM table WHERE 1" instead.
- **
- ** See also the [sqlite3_changes()] interface.
- **
- ** INVARIANTS:
- **
- ** {F12261} The [sqlite3_total_changes()] returns the total number
- ** of row changes caused by INSERT, UPDATE, and/or DELETE
- ** statements on the same [database connection], in any
- ** trigger context, since the database connection was
- ** created.
- **
- ** LIMITATIONS:
- **
- ** {U12264} If a separate thread makes changes on the same database connection
- ** while [sqlite3_total_changes()] is running then the value
- ** returned is unpredictable and unmeaningful.
- */
- int sqlite3_total_changes(sqlite3*);
- /*
- ** CAPI3REF: Interrupt A Long-Running Query {F12270}
- **
- ** 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 is very nearly finished at the time when sqlite3_interrupt()
- ** is called, then it might not have an opportunity to be interrupted.
- ** It 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.
- ** A call to sqlite3_interrupt() has no effect on SQL statements
- ** that are started after sqlite3_interrupt() returns.
- **
- ** INVARIANTS:
- **
- ** {F12271} The [sqlite3_interrupt()] interface will force all running
- ** SQL statements associated with the same database connection
- ** to halt after processing at most one additional row of
- ** data.
- **
- ** {F12272} Any SQL statement that is interrupted by [sqlite3_interrupt()]
- ** will return [SQLITE_INTERRUPT].
- **
- ** LIMITATIONS:
- **
- ** {U12279} If the database connection closes while [sqlite3_interrupt()]
- ** is running then bad things will likely happen.
- */
- void sqlite3_interrupt(sqlite3*);
- /*
- ** CAPI3REF: Determine If An SQL Statement Is Complete {F10510}
- **
- ** These routines are useful for command-line input to determine if the
- ** currently entered text seems to form complete a SQL statement or
- ** if additional input is needed before sending the text into
- ** SQLite for parsing. These routines return true 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 fragment of a
- ** 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.
- **
- ** These routines do not parse the SQL and
- ** so will not detect syntactically incorrect SQL.
- **
- ** INVARIANTS:
- **
- ** {F10511} The sqlite3_complete() and sqlite3_complete16() functions
- ** return true (non-zero) if and only if the last
- ** non-whitespace token in their input is a semicolon that
- ** is not in between the BEGIN and END of a CREATE TRIGGER
- ** statement.
- **
- ** LIMITATIONS:
- **
- ** {U10512} The input to sqlite3_complete() must be a zero-terminated
- ** UTF-8 string.
- **
- ** {U10513} The input to sqlite3_complete16() must be a zero-terminated
- ** UTF-16 string in native byte order.
- */
- int sqlite3_complete(const char *sql);
- int sqlite3_complete16(const void *sql);
- /*
- ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {F12310}
- **
- ** This routine identifies a callback function that might be
- ** invoked whenever an attempt is made to open a database table
- ** that another thread or process has locked.
- ** If the busy callback is NULL, then [SQLITE_BUSY]
- ** or [SQLITE_IOERR_BLOCKED]
- ** is returned immediately upon encountering the lock.
- ** If the busy callback is not NULL, then the
- ** callback will be invoked with two arguments. The
- ** first argument to the handler is a copy of the void* pointer which
- ** is the third argument to this routine. The second argument to
- ** the handler is the number of times that the busy handler has
- ** been invoked for this locking event. If the
- ** busy callback returns 0, then no additional attempts are made to
- ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
- ** If the callback returns non-zero, then another attempt
- ** is made to open the database for reading 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] or
- ** [SQLITE_IOERR_BLOCKED] 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.
- **
- ** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
- ** when SQLite is in the middle of a large transaction where all the
- ** changes will not fit into the in-memory cache. SQLite will
- ** already hold a RESERVED lock on the database file, but it needs
- ** to promote this lock to EXCLUSIVE so that it can spill cache
- ** pages into the database file without harm to concurrent
- ** readers. If it is unable to promote the lock, then the in-memory
- ** cache will be left in an inconsistent state and so the error
- ** code is promoted from the relatively benign [SQLITE_BUSY] to
- ** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion
- ** forces an automatic rollback of the changes. See the
- ** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
- ** CorruptionFollowingBusyError</a> wiki page for a discussion of why
- ** this is important.
- **
- ** There can only be a single busy handler defined for each database
- ** connection. Setting a new busy handler clears any previous one.
- ** Note that calling [sqlite3_busy_timeout()] will also set or clear
- ** the busy handler.
- **
- ** INVARIANTS:
- **
- ** {F12311} The [sqlite3_busy_handler()] function replaces the busy handler
- ** callback in the database connection identified by the 1st
- ** parameter with a new busy handler identified by the 2nd and 3rd
- ** parameters.
- **
- ** {F12312} The default busy handler for new database connections is NULL.
- **
- ** {F12314} When two or more database connection share a common cache,
- ** the busy handler for the database connection currently using
- ** the cache is invoked when the cache encounters a lock.
- **
- ** {F12316} If a busy handler callback returns zero, then the SQLite
- ** interface that provoked the locking event will return
- ** [SQLITE_BUSY].
- **
- ** {F12318} SQLite will invokes the busy handler with two argument which
- ** are a copy of the pointer supplied by the 3rd parameter to
- ** [sqlite3_busy_handler()] and a count of the number of prior
- ** invocations of the busy handler for the same locking event.
- **
- ** LIMITATIONS:
- **
- ** {U12319} A busy handler should not call close the database connection
- ** or prepared statement that invoked the busy handler.
- */
- int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
- /*
- ** CAPI3REF: Set A Busy Timeout {F12340}
- **
- ** This routine sets a [sqlite3_busy_handler | busy handler]
- ** that sleeps for a while when a
- ** table is locked. The handler will sleep multiple times until
- ** at least "ms" milliseconds of sleeping have been done. {F12343} After
- ** "ms" milliseconds of sleeping, the handler returns 0 which
- ** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
- **
- ** 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. If another busy handler was defined
- ** (using [sqlite3_busy_handler()]) prior to calling
- ** this routine, that other busy handler is cleared.
- **
- ** INVARIANTS:
- **
- ** {F12341} The [sqlite3_busy_timeout()] function overrides any prior
- ** [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting
- ** on the same database connection.
- **
- ** {F12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than
- ** or equal to zero, then the busy handler is cleared so that
- ** all subsequent locking events immediately return [SQLITE_BUSY].
- **
- ** {F12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive
- ** number N, then a busy handler is set that repeatedly calls
- ** the xSleep() method in the VFS interface until either the
- ** lock clears or until the cumulative sleep time reported back
- ** by xSleep() exceeds N milliseconds.
- */
- int sqlite3_busy_timeout(sqlite3*, int ms);
- /*
- ** CAPI3REF: Convenience Routines For Running Queries {F12370}
- **
- ** Definition: A <b>result table</b> 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 are give a NULL pointer. All other values are in
- ** their UTF-8 zero-terminated string representation as returned by
- ** [sqlite3_column_text()].
- **
- ** A result table might consists 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:
- **
- ** <blockquote><pre>
- ** Name | Age
- ** -----------------------
- ** Alice | 43
- ** Bob | 28
- ** Cindy | 21
- ** </pre></blockquote>
- **
- ** 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:
- **
- ** <blockquote><pre>
- ** azResult[0] = "Name";
- ** azResult[1] = "Age";
- ** azResult[2] = "Alice";
- ** azResult[3] = "43";
- ** azResult[4] = "Bob";
- ** azResult[5] = "28";
- ** azResult[6] = "Cindy";
- ** azResult[7] = "21";
- ** </pre></blockquote>
- **
- ** The sqlite3_get_table() function evaluates one or more
- ** semicolon-separated SQL statements in the zero-terminated UTF-8
- ** string of its 2nd parameter. It returns a result table to the
- ** pointer given in its 3rd parameter.
- **
- ** After the calling function has finished using the result, it should
- ** pass the pointer to the result table to sqlite3_free_table() in order to
- ** release the memory that was malloc-ed. 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()].
- **
- ** INVARIANTS:
- **
- ** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then
- ** it frees the result table under construction, aborts the
- ** query in process, skips any subsequent queries, sets the
- ** *resultp output pointer to NULL and returns [SQLITE_NOMEM].
- **
- ** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL
- ** then [sqlite3_get_table()] write the number of columns in the
- ** result set of the query into *ncolumn if the query is
- ** successful (if the function returns SQLITE_OK).
- **
- ** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL
- ** then [sqlite3_get_table()] write the number of rows in the
- ** result set of the query into *nrow if the query is
- ** successful (if the function returns SQLITE_OK).
- **
- ** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value
- ** to the number of columns in the result set of the query in the
- ** sql parameter, or to zero if the query in sql has an empty
- ** result set.
- */
- int sqlite3_get_table(
- sqlite3*, /* An open database */
- const char *sql, /* SQL to be evaluated */
- char ***pResult, /* Results of the query */
- int *nrow, /* Number of result rows written here */
- int *ncolumn, /* Number of result columns written here */
- char **errmsg /* Error msg written here */
- );
- void sqlite3_free_table(char **result);
- /*
- ** CAPI3REF: Formatted String Printing Functions {F17400}
- **
- ** These routines are workalikes of the "printf()" family of functions
- ** from the standard C library.
- **
- ** 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.
- **
- ** In 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.
- **
- ** 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", and "%z" options.
- **
- ** The %q option works like %s in that it substitutes a null-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, so some string variable contains text as follows:
- **
- ** <blockquote><pre>
- ** char *zText = "It's a happy day!";
- ** </pre></blockquote>
- **
- ** One can use this text in an SQL statement as follows:
- **
- ** <blockquote><pre>
- ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
- ** sqlite3_exec(db, zSQL, 0, 0, 0);
- ** sqlite3_free(zSQL);
- ** </pre></blockquote>
- **
- ** Because the %q format string is used, the ''' character in zText
- ** is escaped and the SQL generated is as follows:
- **
- ** <blockquote><pre>
- ** INSERT INTO table1 VALUES('It''s a happy day!')
- ** </pre></blockquote>
- **
- ** This is correct. Had we used %s instead of %q, the generated SQL
- ** would have looked like this:
- **
- ** <blockquote><pre>
- ** INSERT INTO table1 VALUES('It's a happy day!');
- ** </pre></blockquote>
- **
- ** 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. Or if the parameter in the argument
- ** list is a NULL pointer, %Q substitutes the text "NULL" (without single
- ** quotes) in place of the %Q option. {END} So, for example, one could say:
- **
- ** <blockquote><pre>
- ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
- ** sqlite3_exec(db, zSQL, 0, 0, 0);
- ** sqlite3_free(zSQL);
- ** </pre></blockquote>
- **
- ** The code above will render a correct SQL statement in the zSQL
- ** variable even if the zText variable is a NULL pointer.
- **
- ** The "%z" formatting option works exactly like "%s" with the
- ** addition that after the string has been read and copied into
- ** the result, [sqlite3_free()] is called on the input string. {END}
- **
- ** INVARIANTS:
- **
- ** {F17403} The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces
- ** return either pointers to zero-terminated UTF-8 strings held in
- ** memory obtained from [sqlite3_malloc()] or NULL pointers if
- ** a call to [sqlite3_malloc()] fails.
- **
- ** {F17406} The [sqlite3_snprintf()] interface writes a zero-terminated
- ** UTF-8 string into the buffer pointed to by the second parameter
- ** provided that the first parameter is greater than zero.
- **
- ** {F17407} The [sqlite3_snprintf()] interface does not writes slots of
- ** its output buffer (the second parameter) outside the range
- ** of 0 through N-1 (where N is the first parameter)
- ** regardless of the length of the string
- ** requested by the format specification.
- **
- */
- char *sqlite3_mprintf(const char*,...);
- char *sqlite3_vmprintf(const char*, va_list);
- char *sqlite3_snprintf(int,char*,const char*, ...);
- /*
- ** CAPI3REF: Memory Allocation Subsystem {F17300}
- **
- ** 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
- ** windows VFS uses native malloc and free for some operations.
- **
- ** 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.
- **
- ** 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_free().
- **
- ** The sqlite3_realloc() interface attempts to resize a
- ** prior memory allocation to be at least N bytes, where N is the
- ** second parameter. The memory allocation to be resized is the first
- ** parameter. If the first parameter to sqlite3_realloc()
- ** is a NULL pointer then its behavior is identical to calling
- ** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
- ** If the second parameter to sqlite3_realloc() is zero or
- ** negative then the behavior is exactly the same as calling
- ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
- ** Sqlite3_realloc() returns a pointer to a memory allocation
- ** of at least N bytes in size or NULL if sufficient memory is unavailable.
- ** 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() and the prior allocation is freed.
- ** If sqlite3_realloc() returns NULL, then the prior allocation
- ** is not freed.
- **
- ** The memory returned by sqlite3_malloc() and sqlite3_realloc()
- ** is always aligned to at least an 8 byte boundary. {END}
- **
- ** The default implementation
- ** of the memory allocation subsystem uses the malloc(), realloc()
- ** and free() provided by the standard C library. {F17382} However, if
- ** SQLite is compiled with the following C preprocessor macro
- **
- ** <blockquote> SQLITE_MEMORY_SIZE=<i>NNN</i> </blockquote>
- **
- ** where <i>NNN</i> is an integer, then SQLite create a static
- ** array of at least <i>NNN</i> bytes in size and use that array
- ** for all of its dynamic memory allocation needs. {END} Additional
- ** memory allocator options may be added in future releases.
- **
- ** 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 windows OS interface layer calls
- ** the system malloc() and free() directly when converting
- ** filenames between the UTF-8 encoding used by SQLite
- ** and whatever filename encoding is used by the particular windows
- ** installation. Memory allocation errors are detected, but
- ** they are reported back as [SQLITE_CANTOPEN] or
- ** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
- **
- ** INVARIANTS:
- **
- ** {F17303} The [sqlite3_malloc(N)] interface returns either a pointer to
- ** newly checked-out block of at least N bytes of memory
- ** that is 8-byte aligned,
- ** or it returns NULL if it is unable to fulfill the request.
- **
- ** {F17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if
- ** N is less than or equal to zero.
- **
- ** {F17305} The [sqlite3_free(P)] interface releases memory previously
- ** returned from [sqlite3_malloc()] or [sqlite3_realloc()],
- ** making it available for reuse.
- **
- ** {F17306} A call to [sqlite3_free(NULL)] is a harmless no-op.
- **
- ** {F17310} A call to [sqlite3_realloc(0,N)] is equivalent to a call
- ** to [sqlite3_malloc(N)].
- **
- ** {F17312} A call to [sqlite3_realloc(P,0)] is equivalent to a call
- ** to [sqlite3_free(P)].
- **
- ** {F17315} The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()],
- ** and [sqlite3_free()] for all of its memory allocation and
- ** deallocation needs.
- **
- ** {F17318} The [sqlite3_realloc(P,N)] interface returns either a pointer
- ** to a block of checked-out memory of at least N bytes in size
- ** that is 8-byte aligned, or a NULL pointer.
- **
- ** {F17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
- ** copies the first K bytes of content from P into the newly allocated
- ** where K is the lessor of N and the size of the buffer P.
- **
- ** {F17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
- ** releases the buffer P.
- **
- ** {F17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is
- ** not modified or released.
- **
- ** LIMITATIONS:
- **
- ** {U17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
- ** must be either NULL or else a pointer obtained from a prior
- ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that has
- ** not been released.
- **
- ** {U17351} 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()].
- **
- */
- void *sqlite3_malloc(int);
- void *sqlite3_realloc(void*, int);
- void sqlite3_free(void*);
- /*
- ** CAPI3REF: Memory Allocator Statistics {F17370}
- **
- ** SQLite provides these two interfaces for reporting on the status
- ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
- ** the memory allocation subsystem included within the SQLite.
- **
- ** INVARIANTS:
- **
- ** {F17371} The [sqlite3_memory_used()] routine returns the
- ** number of bytes of memory currently outstanding
- ** (malloced but not freed).
- **
- ** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum
- ** value of [sqlite3_memory_used()]
- ** since the highwater mark was last reset.
- **
- ** {F17374} 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.
- **
- ** {F17375} The memory highwater 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 highwater mark
- ** prior to the reset.
- */
- sqlite3_int64 sqlite3_memory_used(void);
- sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
- /*
- ** CAPI3REF: Pseudo-Random Number Generator {F17390}
- **
- ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
- ** select random ROWIDs when inserting new records into a table that
- ** already uses the largest possible ROWID. The PRNG is also used for
- ** the build-in random() and randomblob() SQL functions. This interface allows
- ** appliations to access the same PRNG for other purposes.
- **
- ** A call to this routine stores N bytes of randomness into buffer P.
- **
- ** The first time this routine is invoked (either internally or by
- ** the application) the PRNG is seeded using randomness obtained
- ** from the xRandomness method of the default [sqlite3_vfs] object.
- ** On all subsequent invocations, the pseudo-randomness is generated
- ** internally and without recourse to the [sqlite3_vfs] xRandomness
- ** method.
- **
- ** INVARIANTS:
- **
- ** {F17392} The [sqlite3_randomness(N,P)] interface writes N bytes of
- ** high-quality pseudo-randomness into buffer P.
- */
- void sqlite3_randomness(int N, void *P);
- /*
- ** CAPI3REF: Compile-Time Authorization Callbacks {F12500}
- **
- ** This routine registers a authorizer callback with a particular
- ** [database connection], supplied in the first argument.
- ** The authorizer callback is invoked as SQL statements are being compiled
- ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
- ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various
- ** points during the compilation process, as logic is being created
- ** to perform various actions, the authorizer callback is invoked to
- ** see if those actions are allowed. The authorizer callback should
- ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
- ** specific action but allow the SQL statement to continue to be
- ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
- ** rejected with an error. If the authorizer callback returns
- ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
- ** then [sqlite3_prepare_v2()] or equivalent call that triggered
- ** the authorizer will fail with an error message.
- **
- ** When the callback returns [SQLITE_OK], that means the operation
- ** requested is ok. When the callback returns [SQLITE_DENY], the
- ** [sqlite3_prepare_v2()] or equivalent call that triggered the
- ** authorizer will fail with an error message explaining that
- ** access is denied. If the authorizer code is [SQLITE_READ]
- ** and the callback returns [SQLITE_IGNORE] then the
- ** [prepared statement] statement is constructed to substitute
- ** a NULL value in place of the table column that would have
- ** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
- ** return can be used to deny an untrusted user access to individual
- ** columns of a table.
- **
- ** The first parameter to the authorizer callback is a copy of
- ** the third parameter to the sqlite3_set_authorizer() interface.
- ** The second parameter to the callback is an integer
- ** [SQLITE_COPY | action code] that specifies the particular action
- ** to be authorized. The third through sixth
- ** parameters to the callback are zero-terminated strings that contain
- ** additional details about the action to be authorized.
- **
- ** An authorizer is used when [sqlite3_prepare | preparing]
- ** SQL statements from an untrusted
- ** source, to ensure that the SQL statements do not try to access data
- ** that they are not allowed to see, or that they do not try to
- ** execute malicious statements that damage the database. For
- ** example, an application may allow a user to enter arbitrary
- ** SQL queries for evaluation by a database. But the application does
- ** not want the user to be able to make arbitrary changes to the
- ** database. An authorizer could then be put in place while the
- ** user-entered SQL is being [sqlite3_prepare | prepared] that
- ** disallows everything except [SELECT] statements.
- **
- ** Applications that need to process SQL from untrusted sources
- ** might also consider lowering resource limits using [sqlite3_limit()]
- ** and limiting database size using the [max_page_count] [PRAGMA]
- ** in addition to using an authorizer.
- **
- ** Only a single authorizer can be in place on a database connection
- ** at a time. Each call to sqlite3_set_authorizer overrides the
- ** previous call. Disable the authorizer by installing a NULL callback.
- ** The authorizer is disabled by default.
- **
- ** Note that the authorizer callback is invoked only during
- ** [sqlite3_prepare()] or its variants. Authorization is not
- ** performed during statement evaluation in [sqlite3_step()].
- **
- ** INVARIANTS:
- **
- ** {F12501} The [sqlite3_set_authorizer(D,...)] interface registers a
- ** authorizer callback with database connection D.
- **
- ** {F12502} The authorizer callback is invoked as SQL statements are
- ** being compiled
- **
- ** {F12503} If the authorizer callback returns any value other than
- ** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] then
- ** the [sqlite3_prepare_v2()] or equivalent call that caused
- ** the authorizer callback to run shall fail with an
- ** [SQLITE_ERROR] error code and an appropriate error message.
- **
- ** {F12504} When the authorizer callback returns [SQLITE_OK], the operation
- ** described is coded normally.
- **
- ** {F12505} When the authorizer callback returns [SQLITE_DENY], the
- ** [sqlite3_prepare_v2()] or equivalent call that caused the
- ** authorizer callback to run shall fail
- ** with an [SQLITE_ERROR] error code and an error message
- ** explaining that access is denied.
- **
- ** {F12506} If the authorizer code (the 2nd parameter to the authorizer
- ** callback) is [SQLITE_READ] and the authorizer callback returns
- ** [SQLITE_IGNORE] then the prepared statement is constructed to
- ** insert a NULL value in place of the table column that would have
- ** been read if [SQLITE_OK] had been returned.
- **
- ** {F12507} If the authorizer code (the 2nd parameter to the authorizer
- ** callback) is anything other than [SQLITE_READ], then
- ** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY].
- **
- ** {F12510} The first parameter to the authorizer callback is a copy of
- ** the third parameter to the [sqlite3_set_authorizer()] interface.
- **
- ** {F12511} The second parameter to the callback is an integer
- ** [SQLITE_COPY | action code] that specifies the particular action
- ** to be authorized.
- **
- ** {F12512} The third through sixth parameters to the callback are
- ** zero-terminated strings that contain
- ** additional details about the action to be authorized.
- **
- ** {F12520} Each call to [sqlite3_set_authorizer()] overrides the
- ** any previously installed authorizer.
- **
- ** {F12521} A NULL authorizer means that no authorization
- ** callback is invoked.
- **
- ** {F12522} The default authorizer is NULL.
- */
- int sqlite3_set_authorizer(
- sqlite3*,
- int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
- void *pUserData
- );
- /*
- ** CAPI3REF: Authorizer Return Codes {F12590}
- **
- ** The [sqlite3_set_authorizer | authorizer callback function] must
- ** return either [SQLITE_OK] or one of these two constants in order
- ** to signal SQLite whether or not the action is permitted. See the
- ** [sqlite3_set_authorizer | authorizer documentation] for additional
- ** information.
- */
- #define SQLITE_DENY 1 /* Abort the SQL statement with an error */
- #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
- /*
- ** CAPI3REF: Authorizer Action Codes {F12550}
- **
- ** The [sqlite3_set_authorizer()] interface registers a callback function
- ** that is invoked to authorizer certain SQL statement actions. The
- ** second parameter to the callback is an integer code that specifies
- ** what action is being authorized. These are the integer action codes that
- ** the authorizer callback may be passed.
- **
- ** These action code values signify what kind of operation is to be
- ** authorized. The 3rd and 4th parameters to the authorization
- ** callback function will be parameters or NULL depending on which of these
- ** codes is used as the second parameter. The 5th parameter to the
- ** authorizer callback is the name of the database ("main", "temp",
- ** etc.) if applicable. The 6th parameter to the authorizer callback
- ** is the name of the inner-most trigger or view that is responsible for
- ** the access attempt or NULL if this access attempt is directly from
- ** top-level SQL code.
- **
- ** INVARIANTS:
- **
- ** {F12551} The second parameter to an
- ** [sqlite3_set_authorizer | authorizer callback is always an integer
- ** [SQLITE_COPY | authorizer code] that specifies what action
- ** is being authorized.
- **
- ** {F12552} The 3rd and 4th parameters to the
- ** [sqlite3_set_authorizer | authorization callback function]
- ** will be parameters or NULL depending on which
- ** [SQLITE_COPY | authorizer code] is used as the second parameter.
- **
- ** {F12553} The 5th parameter to the
- ** [sqlite3_set_authorizer | authorizer callback] is the name
- ** of the database (example: "main", "temp", etc.) if applicable.
- **
- ** {F12554} The 6th parameter to the
- ** [sqlite3_set_authorizer | authorizer callback] is the name
- ** of the inner-most trigger or view that is responsible for
- ** the access attempt or NULL if this access attempt is directly from
- ** top-level SQL code.
- */
- /******************************************* 3rd ************ 4th ***********/
- #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
- #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
- #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
- #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
- #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
- #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
- #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
- #define SQLITE_CREATE_VIEW 8 /* View Name NULL */
- #define SQLITE_DELETE 9 /* Table Name NULL */
- #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
- #define SQLITE_DROP_TABLE 11 /* Table Name NULL */
- #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
- #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
- #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
- #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
- #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
- #define SQLITE_DROP_VIEW 17 /* View Name NULL */
- #define SQLITE_INSERT 18 /* Table Name NULL */
- #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
- #define SQLITE_READ 20 /* Table Name Column Name */
- #define SQLITE_SELECT 21 /* NULL NULL */
- #define SQLITE_TRANSACTION 22 /* NULL NULL */
- #define SQLITE_UPDATE 23 /* Table Name Column Name */
- #define SQLITE_ATTACH 24 /* Filename NULL */
- #define SQLITE_DETACH 25 /* Database Name NULL */
- #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
- #define SQLITE_REINDEX 27 /* Index Name NULL */
- #define SQLITE_ANALYZE 28 /* Table Name NULL */
- #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
- #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
- #define SQLITE_FUNCTION 31 /* Function Name NULL */
- #define SQLITE_COPY 0 /* No longer used */
- /*
- ** CAPI3REF: Tracing And Profiling Functions {F12280}
- **
- ** These routines register callback functions that can be used for
- ** tracing and profiling the execution of SQL statements.
- **
- ** The callback function registered by sqlite3_trace() is invoked at
- ** various times when an SQL statement is being run by [sqlite3_step()].
- ** The callback returns a UTF-8 rendering of the SQL statement text
- ** as the statement first begins executing. Additional callbacks occur
- ** as each triggersubprogram is entered. The callbacks for triggers
- ** contain a UTF-8 SQL comment that identifies the trigger.
- **
- ** The callback function registered by sqlite3_profile() is invoked
- ** as each SQL statement finishes. The profile callback contains
- ** the original statement text and an estimate of wall-clock time
- ** of how long that statement took to run.
- **
- ** The sqlite3_profile() API is currently considered experimental and
- ** is subject to change or removal in a future release.
- **
- ** The trigger reporting feature of the trace callback is considered
- ** experimental and is subject to change or removal in future releases.
- ** Future versions of SQLite might also add new trace callback
- ** invocations.
- **
- ** INVARIANTS:
- **
- ** {F12281} The callback function registered by [sqlite3_trace()] is
- ** whenever an SQL statement first begins to execute and
- ** whenever a trigger subprogram first begins to run.
- **
- ** {F12282} Each call to [sqlite3_trace()] overrides the previously
- ** registered trace callback.
- **
- ** {F12283} A NULL trace callback disables tracing.
- **
- ** {F12284} The first argument to the trace callback is a copy of
- ** the pointer which was the 3rd argument to [sqlite3_trace()].
- **
- ** {F12285} The second argument to the trace callback is a
- ** zero-terminated UTF8 string containing the original text
- ** of the SQL statement as it was passed into [sqlite3_prepare_v2()]
- ** or the equivalent, or an SQL comment indicating the beginning
- ** of a trigger subprogram.
- **
- ** {F12287} The callback function registered by [sqlite3_profile()] is invoked
- ** as each SQL statement finishes.
- **
- ** {F12288} The first parameter to the profile callback is a copy of
- ** the 3rd parameter to [sqlite3_profile()].
- **
- ** {F12289} The second parameter to the profile callback is a
- ** zero-terminated UTF-8 string that contains the complete text of
- ** the SQL statement as it was processed by [sqlite3_prepare_v2()]
- ** or the equivalent.
- **
- ** {F12290} The third parameter to the profile callback is an estimate
- ** of the number of nanoseconds of wall-clock time required to
- ** run the SQL statement from start to finish.
- */
- void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
- void *sqlite3_profile(sqlite3*,
- void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
- /*
- ** CAPI3REF: Query Progress Callbacks {F12910}
- **
- ** This routine configures a callback function - the
- ** progress callback - that is invoked periodically during long
- ** running calls to [sqlite3_exec()], [sqlite3_step()] and
- ** [sqlite3_get_table()]. An example use for this
- ** interface is to keep a GUI updated during a large query.
- **
- ** If the progress callback returns non-zero, the opertion is
- ** interrupted. This feature can be used to implement a
- ** "Cancel" button on a GUI dialog box.
- **
- ** INVARIANTS:
- **
- ** {F12911} The callback function registered by [sqlite3_progress_handler()]
- ** is invoked periodically during long running calls to
- ** [sqlite3_step()].
- **
- ** {F12912} The progress callback is invoked once for every N virtual
- ** machine opcodes, where N is the second argument to
- ** the [sqlite3_progress_handler()] call that registered
- ** the callback. <todo>What if N is less than 1?</todo>
- **
- ** {F12913} The progress callback itself is identified by the third
- ** argument to [sqlite3_progress_handler()].
- **
- ** {F12914} The fourth argument [sqlite3_progress_handler()] is a
- *** void pointer passed to the progress callback
- ** function each time it is invoked.
- **
- ** {F12915} If a call to [sqlite3_step()] results in fewer than
- ** N opcodes being executed,
- ** then the progress callback is never invoked. {END}
- **
- ** {F12916} Every call to [sqlite3_progress_handler()]
- ** overwrites any previously registere progress handler.
- **
- ** {F12917} If the progress handler callback is NULL then no progress
- ** handler is invoked.
- **
- ** {F12918} If the progress callback returns a result other than 0, then
- ** the behavior is a if [sqlite3_interrupt()] had been called.
- */
- void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
- /*
- ** CAPI3REF: Opening A New Database Connection {F12700}
- **
- ** These routines open an SQLite database file whose name
- ** is given 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()].
- ** An [sqlite3*] handle is usually returned in *ppDb, even
- ** if an error occurs. The only exception is 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.
- **
- ** The default encoding for the database will be UTF-8 if
- ** [sqlite3_open()] or [sqlite3_open_v2()] is called and
- ** UTF-16 in the native byte order if [sqlite3_open16()] is used.
- **
- ** Whether or not an error occurs when it is opened, resources
- ** associated with the [sqlite3*] 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 acccepts two additional parameters for additional control
- ** over the new database connection. The flags parameter can be
- ** one of:
- **
- ** <ol>
- ** <li> [SQLITE_OPEN_READONLY]
- ** <li> [SQLITE_OPEN_READWRITE]
- ** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]
- ** </ol>
- **
- ** The first value opens the database read-only.
- ** If the database does not previously exist, an error is returned.
- ** The second option opens
- ** the database for reading and writing if possible, or reading only if
- ** if the file is write protected. In either case the database
- ** must already exist or an error is returned. The third option
- ** opens the database for reading and writing and creates it if it does
- ** not already exist.
- ** The third options is behavior that is always used for [sqlite3_open()]
- ** and [sqlite3_open16()].
- **
- ** If the 4th parameter to [sqlite3_open_v2()] is not one of the
- ** combinations shown above then the behavior is undefined.
- **
- ** If the filename is ":memory:", then an private
- ** in-memory database is created for the connection. This in-memory
- ** database will vanish when the database connection is closed. Future
- ** version of SQLite might make use of additional special filenames
- ** that begin with the ":" character. It is recommended that
- ** when a database filename really does begin with
- ** ":" that you prefix the filename with a pathname like "./" 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.
- **
- ** 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.
- **
- ** <b>Note to windows users:</b> The encoding used for the filename argument
- ** of [sqlite3_open()] and [sqlite3_open_v2()] must be UTF-8, not whatever
- ** codepage is currently defined. Filenames containing international
- ** characters must be converted to UTF-8 prior to passing them into
- ** [sqlite3_open()] or [sqlite3_open_v2()].
- **
- ** INVARIANTS:
- **
- ** {F12701} The [sqlite3_open()], [sqlite3_open16()], and
- ** [sqlite3_open_v2()] interfaces create a new
- ** [database connection] associated with
- ** the database file given in their first parameter.
- **
- ** {F12702} 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()].
- **
- ** {F12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()],
- ** or [sqlite3_open_v2()] writes a pointer to a new
- ** [database connection] into *ppDb.
- **
- ** {F12704} The [sqlite3_open()], [sqlite3_open16()], and
- ** [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success,
- ** or an appropriate [error code] on failure.
- **
- ** {F12706} The default text encoding for a new database created using
- ** [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8.
- **
- ** {F12707} The default text encoding for a new database created using
- ** [sqlite3_open16()] will be UTF-16.
- **
- ** {F12709} The [sqlite3_open(F,D)] interface is equivalent to
- ** [sqlite3_open_v2(F,D,G,0)] where the G parameter is
- ** [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE].
- **
- ** {F12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
- ** bit value [SQLITE_OPEN_READONLY] then the database is opened
- ** for reading only.
- **
- ** {F12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
- ** bit value [SQLITE_OPEN_READWRITE] then the database is opened
- ** reading and writing if possible, or for reading only if the
- ** file is write protected by the operating system.
- **
- ** {F12713} If the G parameter to [sqlite3_open(v2(F,D,G,V)] omits the
- ** bit value [SQLITE_OPEN_CREATE] and the database does not
- ** previously exist, an error is returned.
- **
- ** {F12714} If the G parameter to [sqlite3_open(v2(F,D,G,V)] contains the
- ** bit value [SQLITE_OPEN_CREATE] and the database does not
- ** previously exist, then an attempt is made to create and
- ** initialize the database.
- **
- ** {F12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()],
- ** or [sqlite3_open_v2()] is ":memory:", then an private,
- ** ephemeral, in-memory database is created for the connection.
- ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
- ** in sqlite3_open_v2()?</todo>
- **
- ** {F12719} If the filename is NULL or an empty string, then a private,
- ** ephermeral on-disk database will be created.
- ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
- ** in sqlite3_open_v2()?</todo>
- **
- ** {F12721} The [database connection] created by
- ** [sqlite3_open_v2(F,D,G,V)] will use the
- ** [sqlite3_vfs] object identified by the V parameter, or
- ** the default [sqlite3_vfs] object is V is a NULL pointer.
- */
- int sqlite3_open(
- const char *filename, /* Database filename (UTF-8) */
- sqlite3 **ppDb /* OUT: SQLite db handle */
- );
- int sqlite3_open16(
- const void *filename, /* Database filename (UTF-16) */
- sqlite3 **ppDb /* OUT: SQLite db handle */
- );
- 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: Error Codes And Messages {F12800}
- **
- ** The sqlite3_errcode() interface returns the numeric
- ** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code]
- ** for the most recent failed sqlite3_* API call associated
- ** with [sqlite3] handle 'db'. If a prior API call failed but the
- ** most recent API call succeeded, the return value from sqlite3_errcode()
- ** is undefined.
- **
- ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
- ** text that describes the error, as either UTF8 or UTF16 respectively.
- ** Memory to hold the error message string is managed internally.
- ** The application does not need to worry with freeing the result.
- ** However, the error string might be overwritten or deallocated by
- ** subsequent calls to other SQLite interface functions.
- **
- ** INVARIANTS:
- **
- ** {F12801} The [sqlite3_errcode(D)] interface returns the numeric
- ** [SQLITE_OK | result code] or
- ** [SQLITE_IOERR_READ | extended result code]
- ** for the most recently failed interface call associated
- ** with [database connection] D.
- **
- ** {F12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)]
- ** interfaces return English-language text that describes
- ** the error in the mostly recently failed interface call,
- ** encoded as either UTF8 or UTF16 respectively.
- **
- ** {F12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]
- ** are valid until the next SQLite interface call.
- **
- ** {F12808} Calls to API routines that do not return an error code
- ** (example: [sqlite3_data_count()]) do not
- ** change the error code or message returned by
- ** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
- **
- ** {F12809} Interfaces that are not associated with a specific
- ** [database connection] (examples:
- ** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()]
- ** do not change the values returned by
- ** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
- */
- int sqlite3_errcode(sqlite3 *db);
- const char *sqlite3_errmsg(sqlite3*);
- const void *sqlite3_errmsg16(sqlite3*);
- /*
- ** CAPI3REF: SQL Statement Object {F13000}
- ** KEYWORDS: {prepared statement} {prepared statements}
- **
- ** An instance of this object represent single SQL statements. This
- ** object is variously known as a "prepared statement" or a
- ** "compiled SQL statement" or simply as a "statement".
- **
- ** The life of a statement object goes something like this:
- **
- ** <ol>
- ** <li> Create the object using [sqlite3_prepare_v2()] or a related
- ** function.
- ** <li> Bind values to host parameters using
- ** [sqlite3_bind_blob | sqlite3_bind_* interfaces].
- ** <li> Run the SQL by calling [sqlite3_step()] one or more times.
- ** <li> Reset the statement using [sqlite3_reset()] then go back
- ** to step 2. Do this zero or more times.
- ** <li> Destroy the object using [sqlite3_finalize()].
- ** </ol>
- **
- ** Refer to documentation on individual methods above for additional
- ** information.
- */
- typedef struct sqlite3_stmt sqlite3_stmt;
- /*
- ** CAPI3REF: Run-time Limits {F12760}
- **
- ** 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. The function returns the old limit.
- **
- ** If the new limit is a negative number, the limit is unchanged.
- ** For the limit category of SQLITE_LIMIT_XYZ there is a hard upper
- ** bound set by a compile-time C-preprocess macro named SQLITE_MAX_XYZ.
- ** (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 limit.
- **
- ** 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
- ** webbrowser 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
- ** attach. Developers might also want to use the [sqlite3_set_authorizer()]
- ** interface to further control untrusted SQL. The size of the database
- ** created by an untrusted script can be contained using the
- ** [max_page_count] [PRAGMA].
- **
- ** This interface is currently considered experimental and is subject
- ** to change or removal without prior notice.
- **
- ** INVARIANTS:
- **
- ** {F12762} A successful call to [sqlite3_limit(D,C,V)] where V is
- ** positive changes the
- ** limit on the size of construct C in [database connection] D
- ** to the lessor of V and the hard upper bound on the size
- ** of C that is set at compile-time.
- **
- ** {F12764} A successful call to [sqlite3_limit(D,C,V)] where V is zero
- ** changes the limit on the size of construct C in
- ** [database connection] D to be the hard upper bound on the size
- ** of C that is set at compile-time.
- **
- ** {F12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative
- ** leaves the state of [database connection] D unchanged.
- **
- ** {F12769} A successful call to [sqlite3_limit(D,C,V)] returns the
- ** value of the limit on the size of construct C in
- ** in [database connection] D as it was prior to the call.
- */
- int sqlite3_limit(sqlite3*, int id, int newVal);
- /*
- ** CAPI3REF: Run-Time Limit Categories {F12790}
- ** KEYWORDS: {limit category} {limit categories}
- **
- ** These constants define various aspects of a [database connection]
- ** that can be limited in size by calls to [sqlite3_limit()].
- ** The meanings of the various limits are as follows:
- **
- ** <dl>
- ** <dt>SQLITE_LIMIT_LENGTH</dt>
- ** <dd>The maximum size of any
- ** string or blob or table row.<dd>
- **
- ** <dt>SQLITE_LIMIT_SQL_LENGTH</dt>
- ** <dd>The maximum length of an SQL statement.</dd>
- **
- ** <dt>SQLITE_LIMIT_COLUMN</dt>
- ** <dd>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.</dd>
- **
- ** <dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
- ** <dd>The maximum depth of the parse tree on any expression.</dd>
- **
- ** <dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
- ** <dd>The maximum number of terms in a compound SELECT statement.</dd>
- **
- ** <dt>SQLITE_LIMIT_VDBE_OP</dt>
- ** <dd>The maximum number of instructions in a virtual machine program
- ** used to implement an SQL statement.</dd>
- **
- ** <dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
- ** <dd>The maximum number of arguments on a function.</dd>
- **
- ** <dt>SQLITE_LIMIT_ATTACHED</dt>
- ** <dd>The maximum number of attached databases.</dd>
- **
- ** <dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
- ** <dd>The maximum length of the pattern argument to the LIKE or
- ** GLOB operators.</dd>
- **
- ** <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
- ** <dd>The maximum number of variables in an SQL statement that can
- ** be bound.</dd>
- ** </dl>
- */
- #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_VARIABLE_NUMBER 9
- /*
- ** CAPI3REF: Compiling An SQL Statement {F13010}
- **
- ** 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 an [database connection]
- ** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()]
- ** or [sqlite3_open16()].
- ** 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 uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2()
- ** use UTF-16. {END}
- **
- ** If the nByte argument is less
- ** than zero, then zSql is read up to the first zero terminator.
- ** If nByte is non-negative, then it is the maximum number of
- ** bytes read from zSql. When nByte is non-negative, the
- ** zSql string ends at either the first ' 00' or 'u0000' character or
- ** the nByte-th byte, whichever comes first. If the caller knows
- ** that the supplied string is nul-terminated, then there is a small
- ** performance advantage to be had by passing an nByte parameter that
- ** is equal to the number of bytes in the input string <i>including</i>
- ** the nul-terminator bytes.{END}
- **
- ** *pzTail is made to point to the first byte past the end of the
- ** first SQL statement in zSql. These routines only compiles 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()]. Or if there is an error, *ppStmt is
- ** set to NULL. If the input text contains no SQL (if the input
- ** is and empty string or a comment) then *ppStmt is set to NULL.
- ** {U13018} The calling procedure is responsible for deleting the
- ** compiled SQL statement
- ** using [sqlite3_finalize()] after it has finished with it.
- **
- ** On success, [SQLITE_OK] is returned. Otherwise an
- ** [error code] is returned.
- **
- ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
- ** 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. {END} This causes the [sqlite3_step()] interface to
- ** behave a differently in two ways:
- **
- ** <ol>
- ** <li>
- ** 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. If the schema has changed in
- ** a way that makes the statement no longer valid, [sqlite3_step()] will still
- ** return [SQLITE_SCHEMA]. But unlike the legacy behavior,
- ** [SQLITE_SCHEMA] is now a fatal error. Calling
- ** [sqlite3_prepare_v2()] again will not make the
- ** error go away. Note: use [sqlite3_errmsg()] to find the text
- ** of the parsing error that results in an [SQLITE_SCHEMA] return. {END}
- ** </li>
- **
- ** <li>
- ** 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 you 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.
- ** </li>
- ** </ol>
- **
- ** INVARIANTS:
- **
- ** {F13011} The [sqlite3_prepare(db,zSql,...)] and
- ** [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the
- ** text in their zSql parameter as UTF-8.
- **
- ** {F13012} The [sqlite3_prepare16(db,zSql,...)] and
- ** [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the
- ** text in their zSql parameter as UTF-16 in the native byte order.
- **
- ** {F13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
- ** and its variants is less than zero, then SQL text is
- ** read from zSql is read up to the first zero terminator.
- **
- ** {F13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
- ** and its variants is non-negative, then at most nBytes bytes
- ** SQL text is read from zSql.
- **
- ** {F13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants
- ** if the zSql input text contains more than one SQL statement
- ** and pzTail is not NULL, then *pzTail is made to point to the
- ** first byte past the end of the first SQL statement in zSql.
- ** <todo>What does *pzTail point to if there is one statement?</todo>
- **
- ** {F13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)]
- ** or one of its variants writes into *ppStmt a pointer to a new
- ** [prepared statement] or a pointer to NULL
- ** if zSql contains nothing other than whitespace or comments.
- **
- ** {F13019} The [sqlite3_prepare_v2()] interface and its variants return
- ** [SQLITE_OK] or an appropriate [error code] upon failure.
- **
- ** {F13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its
- ** variants returns an error (any value other than [SQLITE_OK])
- ** it first sets *ppStmt to NULL.
- */
- 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 */
- );
- 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 */
- );
- int sqlite3_prepare16(
- sqlite3 *db, /* Database handle */
- const void *zSql, /* SQL statement, UTF-16 encoded */
- int nByte, /* Maximum length of zSql in bytes. */
- sqlite3_stmt **ppStmt, /* OUT: Statement handle */
- const void **pzTail /* OUT: Pointer to unused portion of zSql */
- );
- int sqlite3_prepare16_v2(
- sqlite3 *db, /* Database handle */
- const void *zSql, /* SQL statement, UTF-16 encoded */
- int nByte, /* Maximum length of zSql in bytes. */
- sqlite3_stmt **ppStmt, /* OUT: Statement handle */
- const void **pzTail /* OUT: Pointer to unused portion of zSql */
- );
- /*
- ** CAPIREF: Retrieving Statement SQL {F13100}
- **
- ** This intereface can be used to retrieve a saved copy of the original
- ** SQL text used to create a [prepared statement].
- **
- ** INVARIANTS:
- **
- ** {F13101} If the [prepared statement] passed as
- ** the an argument to [sqlite3_sql()] was compiled
- ** compiled using either [sqlite3_prepare_v2()] or
- ** [sqlite3_prepare16_v2()],
- ** then [sqlite3_sql()] function returns a pointer to a
- ** zero-terminated string containing a UTF-8 rendering
- ** of the original SQL statement.
- **
- ** {F13102} If the [prepared statement] passed as
- ** the an argument to [sqlite3_sql()] was compiled
- ** compiled using either [sqlite3_prepare()] or
- ** [sqlite3_prepare16()],
- ** then [sqlite3_sql()] function returns a NULL pointer.
- **
- ** {F13103} The string returned by [sqlite3_sql(S)] is valid until the
- ** [prepared statement] S is deleted using [sqlite3_finalize(S)].
- */
- const char *sqlite3_sql(sqlite3_stmt *pStmt);
- /*
- ** CAPI3REF: Dynamically Typed Value Object {F15000}
- ** 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
- ** 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 terms "protected" and "unprotected" refer to whether or not
- ** a mutex is held. A 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)
- ** then there is no distinction between
- ** protected and unprotected sqlite3_value objects and they can be
- ** used interchangable. However, for maximum code portability it
- ** is recommended that applications make the distinction between
- ** between protected and unprotected sqlite3_value objects even if
- ** they are single threaded.
- **
- ** 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()]. All other
- ** interfaces that use sqlite3_value require protected sqlite3_value objects.
- */
- typedef struct Mem sqlite3_value;
- /*
- ** CAPI3REF: SQL Function Context Object {F16001}
- **
- ** 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.
- */
- typedef struct sqlite3_context sqlite3_context;
- /*
- ** CAPI3REF: Binding Values To Prepared Statements {F13500}
- **
- ** In the SQL strings input to [sqlite3_prepare_v2()] and its
- ** variants, literals may be replace by a parameter in one
- ** of these forms:
- **
- ** <ul>
- ** <li> ?
- ** <li> ?NNN
- ** <li> :VVV
- ** <li> @VVV
- ** <li> $VVV
- ** </ul>
- **
- ** In the parameter forms shown above NNN is an integer literal,
- ** VVV alpha-numeric parameter name.
- ** 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 always
- ** is a pointer to the [sqlite3_stmt] object returned from
- ** [sqlite3_prepare_v2()] or its variants. The second
- ** argument is the index of the parameter to be set. The
- ** first parameter has an index of 1. When the same named
- ** 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_name()] API if desired. The index
- ** for "?NNN" parameters is the value of NNN.
- ** The NNN value must be between 1 and the compile-time
- ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999).
- **
- ** The third argument is the value to bind to the parameter.
- **
- ** 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 <u>bytes</u>
- ** in the value, not the number of characters.
- ** If the fourth parameter is negative, the length of the string is
- ** number of bytes up to the first zero terminator.
- **
- ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
- ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
- ** string after SQLite has finished with it. 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 sqlite3_bind_zeroblob() routine binds a BLOB of length N that
- ** is filled with zeros. A zeroblob uses a fixed amount of memory
- ** (just an integer to hold it size) while it is being processed.
- ** Zeroblobs are intended to serve as place-holders for BLOBs whose
- ** content is later written using
- ** [sqlite3_blob_open | increment BLOB I/O] routines. A negative
- ** value for the zeroblob results in a zero-length BLOB.
- **
- ** The sqlite3_bind_*() routines must be called after
- ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
- ** before [sqlite3_step()].
- ** Bindings are not cleared by the [sqlite3_reset()] routine.
- ** Unbound parameters are interpreted as NULL.
- **
- ** These routines return [SQLITE_OK] on success or an error code if
- ** anything goes wrong. [SQLITE_RANGE] is returned if the parameter
- ** index is out of range. [SQLITE_NOMEM] is returned if malloc fails.
- ** [SQLITE_MISUSE] might be returned if these routines are called on a
- ** virtual machine that is the wrong state or which has already been finalized.
- ** Detection of misuse is unreliable. Applications should not depend
- ** on SQLITE_MISUSE returns. SQLITE_MISUSE is intended to indicate a
- ** a logic error in the application. Future versions of SQLite might
- ** panic rather than return SQLITE_MISUSE.
- **
- ** See also: [sqlite3_bind_parameter_count()],
- ** [sqlite3_bind_parameter_name()], and
- ** [sqlite3_bind_parameter_index()].
- **
- ** INVARIANTS:
- **
- ** {F13506} The [sqlite3_prepare | SQL statement compiler] recognizes
- ** tokens of the forms "?", "?NNN", "$VVV", ":VVV", and "@VVV"
- ** as SQL parameters, where NNN is any sequence of one or more
- ** digits and where VVV is any sequence of one or more
- ** alphanumeric characters or "::" optionally followed by
- ** a string containing no spaces and contained within parentheses.
- **
- ** {F13509} The initial value of an SQL parameter is NULL.
- **
- ** {F13512} The index of an "?" SQL parameter is one larger than the
- ** largest index of SQL parameter to the left, or 1 if
- ** the "?" is the leftmost SQL parameter.
- **
- ** {F13515} The index of an "?NNN" SQL parameter is the integer NNN.
- **
- ** {F13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is
- ** the same as the index of leftmost occurances of the same
- ** parameter, or one more than the largest index over all
- ** parameters to the left if this is the first occurrance
- ** of this parameter, or 1 if this is the leftmost parameter.
- **
- ** {F13521} The [sqlite3_prepare | SQL statement compiler] fail with
- ** an [SQLITE_RANGE] error if the index of an SQL parameter
- ** is less than 1 or greater than SQLITE_MAX_VARIABLE_NUMBER.
- **
- ** {F13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)]
- ** associate the value V with all SQL parameters having an
- ** index of N in the [prepared statement] S.
- **
- ** {F13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)]
- ** override prior calls with the same values of S and N.
- **
- ** {F13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)]
- ** persist across calls to [sqlite3_reset(S)].
- **
- ** {F13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
- ** [sqlite3_bind_text(S,N,V,L,D)], or
- ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L
- ** bytes of the blob or string pointed to by V, when L
- ** is non-negative.
- **
- ** {F13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or
- ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters
- ** from V through the first zero character when L is negative.
- **
- ** {F13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
- ** [sqlite3_bind_text(S,N,V,L,D)], or
- ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
- ** constant [SQLITE_STATIC], SQLite assumes that the value V
- ** is held in static unmanaged space that will not change
- ** during the lifetime of the binding.
- **
- ** {F13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
- ** [sqlite3_bind_text(S,N,V,L,D)], or
- ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
- ** constant [SQLITE_TRANSIENT], the routine makes a
- ** private copy of V value before it returns.
- **
- ** {F13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
- ** [sqlite3_bind_text(S,N,V,L,D)], or
- ** [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to
- ** a function, SQLite invokes that function to destroy the
- ** V value after it has finished using the V value.
- **
- ** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound
- ** is a blob of L bytes, or a zero-length blob if L is negative.
- **
- ** {F13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may
- ** be either a [protected sqlite3_value] object or an
- ** [unprotected sqlite3_value] object.
- */
- int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
- int sqlite3_bind_double(sqlite3_stmt*, int, double);
- int sqlite3_bind_int(sqlite3_stmt*, int, int);
- int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
- int sqlite3_bind_null(sqlite3_stmt*, int);
- int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
- int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
- int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
- int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
- /*
- ** CAPI3REF: Number Of SQL Parameters {F13600}
- **
- ** 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
- ** place-holders for values that are [sqlite3_bind_blob | bound]
- ** to the parameters at a later time.
- **
- ** This routine actually returns the index of the largest parameter.
- ** For all forms except ?NNN, this will correspond to the number of
- ** unique parameters. If parameters of the ?NNN 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()].
- **
- ** INVARIANTS:
- **
- ** {F13601} The [sqlite3_bind_parameter_count(S)] interface returns
- ** the largest index of all SQL parameters in the
- ** [prepared statement] S, or 0 if S
- ** contains no SQL parameters.
- */
- int sqlite3_bind_parameter_count(sqlite3_stmt*);
- /*
- ** CAPI3REF: Name Of A Host Parameter {F13620}
- **
- ** This routine returns a pointer to the name of the n-th
- ** SQL parameter in a [prepared statement].
- ** SQL parameters of the form ":AAA" or "@AAA" or "$AAA" have a name
- ** which is the string ":AAA" or "@AAA" or "$VVV".
- ** In other words, the initial ":" or "$" or "@"
- ** is included as part of the name.
- ** Parameters of the form "?" or "?NNN" have no name.
- **
- ** 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 the UTF-8 encoding even if the named parameter was
- ** originally specified as UTF-16 in [sqlite3_prepare16()] or
- ** [sqlite3_prepare16_v2()].
- **
- ** See also: [sqlite3_bind_blob|sqlite3_bind()],
- ** [sqlite3_bind_parameter_count()], and
- ** [sqlite3_bind_parameter_index()].
- **
- ** INVARIANTS:
- **
- ** {F13621} The [sqlite3_bind_parameter_name(S,N)] interface returns
- ** a UTF-8 rendering of the name of the SQL parameter in
- ** [prepared statement] S having index N, or
- ** NULL if there is no SQL parameter with index N or if the
- ** parameter with index N is an anonymous parameter "?" or
- ** a numbered parameter "?NNN".
- */
- const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
- /*
- ** CAPI3REF: Index Of A Parameter With A Given Name {F13640}
- **
- ** 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 even if the original statement
- ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
- **
- ** See also: [sqlite3_bind_blob|sqlite3_bind()],
- ** [sqlite3_bind_parameter_count()], and
- ** [sqlite3_bind_parameter_index()].
- **
- ** INVARIANTS:
- **
- ** {F13641} The [sqlite3_bind_parameter_index(S,N)] interface returns
- ** the index of SQL parameter in [prepared statement]
- ** S whose name matches the UTF-8 string N, or 0 if there is
- ** no match.
- */
- int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
- /*
- ** CAPI3REF: Reset All Bindings On A Prepared Statement {F13660}
- **
- ** 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.
- **
- ** INVARIANTS:
- **
- ** {F13661} The [sqlite3_clear_bindings(S)] interface resets all
- ** SQL parameter bindings in [prepared statement] S
- ** back to NULL.
- */
- int sqlite3_clear_bindings(sqlite3_stmt*);
- /*
- ** CAPI3REF: Number Of Columns In A Result Set {F13710}
- **
- ** Return the number of columns in the result set returned by the
- ** [prepared statement]. This routine returns 0
- ** if pStmt is an SQL statement that does not return data (for
- ** example an UPDATE).
- **
- ** INVARIANTS:
- **
- ** {F13711} The [sqlite3_column_count(S)] interface returns the number of
- ** columns in the result set generated by the
- ** [prepared statement] S, or 0 if S does not generate
- ** a result set.
- */
- int sqlite3_column_count(sqlite3_stmt *pStmt);
- /*
- ** CAPI3REF: Column Names In A Result Set {F13720}
- **
- ** 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 UTF8 string
- ** and sqlite3_column_name16() returns a pointer to a zero-terminated
- ** UTF16 string. The first parameter is the
- ** [prepared statement] that implements the SELECT statement.
- ** The second parameter is the column number. The left-most column is
- ** number 0.
- **
- ** The returned string pointer is valid until either the
- ** [prepared statement] is destroyed by [sqlite3_finalize()]
- ** or until the next call 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.
- **
- ** INVARIANTS:
- **
- ** {F13721} A successful invocation of the [sqlite3_column_name(S,N)]
- ** interface returns the name
- ** of the Nth column (where 0 is the left-most column) for the
- ** result set of [prepared statement] S as a
- ** zero-terminated UTF-8 string.
- **
- ** {F13723} A successful invocation of the [sqlite3_column_name16(S,N)]
- ** interface returns the name
- ** of the Nth column (where 0 is the left-most column) for the
- ** result set of [prepared statement] S as a
- ** zero-terminated UTF-16 string in the native byte order.
- **
- ** {F13724} The [sqlite3_column_name()] and [sqlite3_column_name16()]
- ** interfaces return a NULL pointer if they are unable to
- ** allocate memory memory to hold there normal return strings.
- **
- ** {F13725} If the N parameter to [sqlite3_column_name(S,N)] or
- ** [sqlite3_column_name16(S,N)] is out of range, then the
- ** interfaces returns a NULL pointer.
- **
- ** {F13726} The strings returned by [sqlite3_column_name(S,N)] and
- ** [sqlite3_column_name16(S,N)] are valid until the next
- ** call to either routine with the same S and N parameters