|
This document is a work in progress.
The goal of this document is to provide an precise and exact definition of what SQLite does, how it works, and what to expect from SQLite for any given input. When completed, this document will become the authoritative reference for using SQLite.
F10010 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
#define SQLITE_VERSION "3.5.3" #define SQLITE_VERSION_NUMBER 3005003 |
F10011 | The #define in the sqlite3.h header file named SQLITE_VERSION resolves to a string literal that identifies the version of the SQLite library in the format "X.Y.Z", where X is the major version number, Y is the minor version number and Z is the release number. The X.Y.Z might be followed by "alpha" or "beta". |
F10014 | The SQLITE_VERSION_NUMBER #define resolves to an integer with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are as with SQLITE_VERSION. |
F10020 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
SQLITE_EXTERN const char sqlite3_version[]; const char *sqlite3_libversion(void); int sqlite3_libversion_number(void); |
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. |
F10100 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_threadsafe(void); |
F10101 | The sqlite3_threadsafe() routine returns nonzero if SQLite was compiled with its mutexes enabled or zero if SQLite was compiled with mutexes disabled. |
F10200 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
#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; |
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. |
F10210 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
#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 */ |
F10211 | The result codes shown here are the only ones returned by SQLite in its default configuration. |
F10212 | However, the sqlite3_extended_result_codes() API can be used to set a database connectoin to return more detailed result codes. |
F10220 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
#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)) |
F10221 | The extended result codes are enabled or disabled for each database connection using the sqlite3_extended_result_codes() API. |
F10223 | The symbolic name for an extended result code always contains a related primary result code as a prefix. |
F10224 | Primary result codes contain a single "_" character. |
F10225 | Extended result codes contain two or more "_" characters. |
F10226 | The numeric value of an extended result code can be converted to its corresponding primary result code by masking off the lower 8 bytes. |
F10230 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
#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 |
F10231 | Some combination of the these bit values are used as the third argument to the sqlite3_open_v2() interface and as fourth argument to the xOpen method of the sqlite3_vfs object. |
F10240 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
#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 |
F10241 | 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. |
F10242 | The SQLITE_IOCAP_ATOMIC property means that all writes of any size are atomic. |
F10243 | 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. |
F10244 | 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. |
F10245 | The SQLITE_IOCAP_SEQUENTIAL property means that information is written to disk in the same order as calls to xWrite(). |
F10250 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
#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 |
F10251 | SQLite uses one of the following integer values as the second argument to calls it makes to the xLock() and xUnlock() methods of an sqlite3_io_methods object. |
F10260 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
#define SQLITE_SYNC_NORMAL 0x00002 #define SQLITE_SYNC_FULL 0x00003 #define SQLITE_SYNC_DATAONLY 0x00010 |
F10261 | When SQLite invokes the xSync() method of an sqlite3_io_methods object it uses a combination of the these integer values as the second argument. |
F10262 | 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. |
F10263 | The SQLITE_SYNC_NORMAL means to use normal fsync() semantics. |
F10264 | The SQLITE_SYNC_FULL flag means to use Mac OS-X style fullsync instead of fsync(). |
F10265 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
#define SQLITE_INTEGER 1 #define SQLITE_FLOAT 2 #define SQLITE_BLOB 4 #define SQLITE_NULL 5 #ifdef SQLITE_TEXT # undef SQLITE_TEXT #else # define SQLITE_TEXT 3 #endif #define SQLITE3_TEXT 3 |
F10266 | Every value in SQLite has one of five fundamental datatypes:
|
F10267 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
#define SQLITE_UTF8 1 #define SQLITE_UTF16LE 2 #define SQLITE_UTF16BE 3 #define SQLITE_UTF16 4 /* Use native byte order */ #define SQLITE_ANY 5 /* sqlite3_create_function only */ #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ |
F10280 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
typedef void (*sqlite3_destructor_type)(void*); #define SQLITE_STATIC ((sqlite3_destructor_type)0) #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) |
F10310 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
SQLITE_EXTERN char *sqlite3_temp_directory; |
F10330 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_enable_shared_cache(int); |
F10331 | This routine enables or disables the sharing of the database cache and schema data structures between connections to the same database. |
F10332 | Sharing is enabled if the argument is true and disabled if the argument is false. |
F10333 | Cache sharing is enabled and disabled for an entire process. |
F10334 | The cache sharing mode set by this interface effects all subsequent calls to sqlite3_open(), sqlite3_open_v2(), and sqlite3_open16(). |
F10335 | Existing database connections continue use the sharing mode that was in effect at the time they were opened. |
F10336 | When shared cache is enabled, the sqlite3_create_module() API used to register virtual tables will always return an error. |
F10337 | This routine returns SQLITE_OK if shared cache was enabled or disabled successfully. |
F10338 | An error code is returned otherwise. |
F10339 | Shared cache is disabled by default. |
U10422 | Software that uses extended result codes should expect to see new result codes in future releases of SQLite. |
F10510 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
int sqlite3_complete(const char *sql); int sqlite3_complete16(const void *sql); |
F10511 | These functions return true if the given input string ends with a semicolon optionally followed by whitespace or comments. |
F10512 | For sqlite3_complete(), the parameter must be a zero-terminated UTF-8 string. |
F10513 | For sqlite3_complete16(), a zero-terminated machine byte order UTF-16 string is required. |
F10514 | These routines return false if the terminal semicolon is within a comment, a string literal or a quoted identifier (in other words if the final semicolon is not really a separate token but part of a larger token) or if the final semicolon is in between the BEGIN and END keywords of a CREATE TRIGGER statement. |
F10530 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_sleep(int); |
F10531 | The sqlite3_sleep() function causes the current thread to suspend execution for at least a number of milliseconds specified in its parameter. |
F10532 | If the operating system does not support sleep requests with millisecond time resolution, then the time will be rounded up to the nearest second. |
F10533 | The number of milliseconds of sleep actually requested from the operating system is returned. |
F10534 | SQLite implements this interface by calling the xSleep() method of the default sqlite3_vfs object. |
F11110 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
typedef struct sqlite3_file sqlite3_file; struct sqlite3_file { const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ }; |
F11120 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
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 */ }; |
F11140 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
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. */ }; |
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. |
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. |
F11143 | SQLite will also add one of the following flags to the xOpen()
call, depending on the object being opened:
|
F11144 | SQLite might also add one of the following flags to the xOpen
method:
|
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. |
F11148 | At least szOsFile bytes of memory is allocated by SQLite to hold the sqlite3_file structure passed as the third argument to xOpen. |
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. |
F11150 | SQLite will always allocate at least mxPathname+1 byte 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. |
F11190 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
#define SQLITE_ACCESS_EXISTS 0 #define SQLITE_ACCESS_READWRITE 1 #define SQLITE_ACCESS_READ 2 |
F11191 | These integer constants can be used as the third parameter to the xAccess method of an sqlite3_vfs object. |
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. |
F11200 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); int sqlite3_vfs_unregister(sqlite3_vfs*); |
F11201 | The sqlite3_vfs_find() interface returns a pointer to a VFS given its name. |
F11202 | Names are case sensitive. |
F11203 | Names are zero-terminated UTF-8 strings. |
F11204 | If there is no match, a NULL pointer is returned. |
F11205 | If zVfsName is NULL then the default VFS is returned. |
F11210 | New VFSes are registered with sqlite3_vfs_register(). |
F11211 | Each new VFS becomes the default VFS if the makeDflt flag is set. |
F11212 | The same VFS can be registered multiple times without injury. |
F11213 | To make an existing VFS into the default VFS, register it again with the makeDflt flag set. |
U11214 | If two different VFSes with the same name are registered, the behavior is undefined. |
U11215 | If a VFS is registered with a name that is NULL or an empty string, then the behavior is undefined. |
F11220 | Unregister a VFS with the sqlite3_vfs_unregister() interface. |
F11221 | If the default VFS is unregistered, another VFS is chosen as the default. The choice for the new VFS is arbitrary. |
F11300 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); |
F11301 | The sqlite3_file_control() interface makes a direct call to the xFileControl method for the sqlite3_io_methods object associated with a particular database identified by the second argument. |
F11302 | The name of the database is the name assigned to the database by the ATTACH SQL command that opened the database. |
F11303 | To control the main database file, use the name "main" or a NULL pointer. |
F11304 | The third and fourth parameters to this routine are passed directly through to the second and third parameters of the xFileControl method. |
F11305 | The return value of the xFileControl method becomes the return value of this routine. |
F11306 | If the second parameter (zDbName) does not match the name of any open database file, then SQLITE_ERROR is returned. |
F11307 | This error code is not remembered and will not be recalled by sqlite3_errcode() or sqlite3_errmsg(). |
U11308 | The underlying xFileControl method might also return SQLITE_ERROR. |
U11309 | There is no way to distinguish between an incorrect zDbName and an SQLITE_ERROR return from the underlying xFileControl method. |
F11310 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
#define SQLITE_FCNTL_LOCKSTATE 1 |
F11311 | The SQLITE_FCNTL_LOCKSTATE opcode is used for debugging. This opcode cases 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. |
F11312 | This capability is used during testing and only needs to be supported when SQLITE_TEST is defined. |
F12000 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
typedef struct sqlite3 sqlite3; |
F12010 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_close(sqlite3 *); |
F12011 | The sqlite3_close() interfaces destroys an sqlite3 object allocated by a prior call to sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2(). |
F12012 | Sqlite3_close() 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. |
U12015 | Passing this routine a database connection that has already been closed results in undefined behavior. |
U12016 | If other interfaces that reference the same database connection are pending (either in the same thread or in different threads) when this routine is called, then the behavior is undefined and is almost certainly undesirable. |
F12023 | If the schema has changed in a way that makes the statement no longer valid, sqlite3_step() will still return SQLITE_SCHEMA. |
F12024 | Calling sqlite3_prepare_v2() again will not make the error go away. |
F12025 | Note: use sqlite3_errmsg() to find the text of the parsing error that results in an SQLITE_SCHEMA return. |
F12100 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
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 */ ); |
F12101 | The sqlite3_exec() interface evaluates zero or more UTF-8 encoded, semicolon-separated SQL statements in the zero-terminated string of its second argument. |
F12102 | The SQL statements are evaluated in the context of the database connection specified by in the first argument. |
F12103 | SQL statements are prepared one by one using sqlite3_prepare() or the equivalent, evaluated using one or more calls to sqlite3_step(), then destroyed using sqlite3_finalize(). |
F12104 | The return value of sqlite3_exec() is SQLITE_OK if all SQL statement run successfully. |
F12105 | If one or more of the SQL statements handed to sqlite3_exec() are queries, then the callback function specified by the 3rd parameter is invoked once for each row of the query result. |
F12106 | If the callback returns a non-zero value then the query is aborted, all subsequent SQL statements are skipped and the sqlite3_exec() function returns the SQLITE_ABORT. |
F12107 | The 4th parameter to sqlite3_exec() is an arbitrary pointer that is passed through to the callback function as its first parameter. |
F12108 | The 2nd parameter to the callback function is the number of columns in the query result. |
F12109 | The 3rd parameter to the callback is an array of pointers to strings holding the values for each column as extracted using sqlite3_column_text(). NULL values in the result set result in a NULL pointer. All other value are in their UTF-8 string representation. |
F12110 | The callback function may be NULL, even for queries. A NULL callback is not an error. It just means that no callback will be invoked. |
F12112 | If an error occurs while parsing or evaluating the SQL then an appropriate error message is written into memory obtained from sqlite3_malloc() and *errmsg is made to point to that message assuming errmsg is not NULL. |
U12113 | The calling function is responsible for freeing the memory using sqlite3_free(). |
F12114 | If errmsg is NULL then no attempt is made to generate an error message. (TODO: Is the return code SQLITE_NOMEM or the original error code?) (TODO: What happens if there are multiple errors? Do we get code for the first error, or is the choice of reported error arbitrary?) |
F12115 | The return value is is SQLITE_OK if there are no errors and some other return code if there is an error. The particular return value depends on the type of error. |
F12116 | If sqlite3_malloc() fails while attempting to generate the error message, *errmsg is set to NULL. |
F12117 | The 4th parameter to the callback is an array of strings obtained using sqlite3_column_name() and holding the names of each column, also in UTF-8. |
F12200 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_extended_result_codes(sqlite3*, int onoff); |
F12201 | The sqlite3_extended_result_codes() routine enables or disables the extended result codes feature on a database connection if its 2nd parameter is non-zero or zero, respectively. |
F12202 | By default, SQLite API routines return one of only 26 integer result codes. |
F12203 | When extended result codes are enabled by this routine, the repetoire of result codes can be much larger and can (hopefully) provide more detailed information about the cause of an error. |
F12204 | The second argument is a boolean value that turns extended result codes on and off. |
F12205 | Extended result codes are off by default for backwards compatibility with older versions of SQLite. |
F12220 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); |
F12221 | Each entry in an SQLite table has a unique 64-bit signed integer key called the "rowid". |
F12222 | 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. |
F12223 | If the table has a column of type INTEGER PRIMARY KEY then that column is another an alias for the rowid. |
F12224 | This routine returns the rowid of the most recent successful INSERT into the database from the database connection shown in the first argument. |
F12225 | If no successful inserts have ever occurred on this database connection, zero is returned. |
F12226 | 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. |
F12227 | But once the trigger terminates, the value returned by this routine reverts to the last value inserted before the trigger fired. |
F12228 | An INSERT that fails due to a constraint violation is not a successful insert and does not change the value returned by this routine. |
F12229 | 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. |
F12231 | 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. |
UF12232 | If another thread does a new insert on the same database connection while this routine is running and thus changes the last insert rowid, then the return value of this routine is undefined. |
F12240 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_changes(sqlite3*); |
F12241 | 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. |
F12242 | Only changes that are directly specified by the INSERT, UPDATE, or DELETE statement are counted. Auxiliary changes caused by triggers are not counted. |
F12243 | Use the sqlite3_total_changes() function to find the total number of changes including changes caused by triggers. |
F12244 | 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. |
F12245 | All changes are counted, even if they are later undone by a ROLLBACK or ABORT. |
F12246 | Except, changes associated with creating and dropping tables are not counted. |
F12247 | If a callback invokes sqlite3_exec() or sqlite3_step() recursively, then the changes in the inner, recursive call are counted together with the changes in the outer call. |
F12248 | 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. |
F12251 | To get an accurate count of the number of rows deleted, use "DELETE FROM table WHERE 1" instead. |
UF12252 | If another thread makes changes on the same database connection while this routine is running then the return value of this routine is undefined. |
F12260 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_total_changes(sqlite3*); |
F12261 | This function returns the number of database rows that have been modified by INSERT, UPDATE or DELETE statements since the database handle was opened. |
F12262 | The count includes UPDATE, INSERT and DELETE statements executed as part of trigger programs. |
F12263 | All 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()). |
U12264 | If another thread makes changes on the same database connection while this routine is running then the return value of this routine is undefined. |
F12265 | 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 form 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. |
F12270 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
void sqlite3_interrupt(sqlite3*); |
F12271 | This function causes any pending database operation to abort and return at its earliest opportunity. |
F12272 | It is safe to call this routine from a thread different from the thread that is currently running the database operation. |
U12273 | 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. |
F12274 | The SQL operation that is interrupted will return SQLITE_INTERRUPT. |
F12275 | 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. |
F12276 | A call to sqlite3_interrupt() has no effect on SQL statements that are started after sqlite3_interrupt() returns. |
F12280 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); void *sqlite3_profile(sqlite3*, void(*xProfile)(void*,const char*,sqlite3_uint64), void*); |
F12281 | The callback function registered by sqlite3_trace() is invoked at the first sqlite3_step() for the evaluation of an SQL statement. |
F12282 | Only a single trace callback can be registered at a time. Each call to sqlite3_trace() overrides the previous. |
F12283 | A NULL callback for sqlite3_trace() 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. |
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. |
F12310 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); |
F12311 | 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. |
F12312 | If the busy callback is NULL, then SQLITE_BUSY or SQLITE_IOERR_BLOCKED is returned immediately upon encountering the lock. |
F12313 | If the busy callback is not NULL, then the callback will be invoked with two arguments. |
F12314 | The first argument to the handler is a copy of the void* pointer which is the third argument to this routine. |
F12315 | The second argument to the handler is the number of times that the busy handler has been invoked for this locking event. |
F12316 | 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. |
F12317 | 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. |
F12319 | 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. |
F12321 | The default busy callback is NULL. |
F12322 | 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. |
F12323 | 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. |
F12324 | 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. |
F12325 | This error code promotion forces an automatic rollback of the changes. |
F12326 | Sqlite is re-entrant, so the busy handler may start a new query. |
U12327 | But the busy handler may not close the database. Closing the database from a busy handler will delete data structures out from under the executing query and will probably result in a segmentation fault or other runtime error. |
F12328 | There can only be a single busy handler defined for each database connection. Setting a new busy handler clears any previous one. |
F12329 | Note that calling sqlite3_busy_timeout() will also set or clear the busy handler. |
F12331 | When operating in shared cache mode, only a single busy handler can be defined for each database file. So if two database connections share a single cache, then changing the busy handler on one connection will also change the busy handler in the other connection. |
F12332 | The busy handler is invoked in the thread that was running when the lock contention occurs. |
F12340 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_busy_timeout(sqlite3*, int ms); |
F12341 | This routine sets a busy handler that sleeps for a while when a table is locked. |
F12342 | 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. |
F12344 | Calling this routine with an argument less than or equal to zero turns off all busy handlers. |
F12345 | 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. |
F12370 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
int sqlite3_get_table( sqlite3*, /* An open database */ const char *sql, /* SQL to be executed */ char ***resultp, /* Result written to a char *[] that this points to */ 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); |
F12371 | Instead of invoking a user-supplied callback for each row of the result, this routine remembers each row of the result in memory obtained from sqlite3_malloc(), then returns all of the result after the query has finished. |
F12372 | As an example, suppose the query result where this table:
If the 3rd argument were &azResult then after the function returns azResult will contain the following data:Name | Age ----------------------- Alice | 43 Bob | 28 Cindy | 21 Notice that there is an extra row of data containing the column headers. But the *nrow return value is still 3. *ncolumn is set to 2. In general, the number of values inserted into azResult will be ((*nrow) + 1)*(*ncolumn).azResult[0] = "Name"; azResult[1] = "Age"; azResult[2] = "Alice"; azResult[3] = "43"; azResult[4] = "Bob"; azResult[5] = "28"; azResult[6] = "Cindy"; azResult[7] = "21"; |
F12373 | The return value of this routine is the same as from sqlite3_exec(). |
U12374 | After the calling function has finished using the result, it should pass the result data pointer to sqlite3_free_table() in order to release the memory that was malloc-ed. Because of the way the sqlite3_malloc() happens, the calling function must not try to call sqlite3_free() directly. Only sqlite3_free_table() is able to release the memory properly and safely. |
F12500 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_set_authorizer( sqlite3*, int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), void *pUserData ); |
F12501 | This routine registers a authorizer callback with a particular database connection, supplied in the first argument. |
F12502 | 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(). |
F12503 | 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. |
F12504 | 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 shall fail with an SQLITE_ERROR error code and an appropriate error message. |
F12505 | When the callback returns SQLITE_DENY, the sqlite3_prepare_v2() or equivalent call that triggered the authorizer 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 anything other than SQLITE_READ, then a return of SQLITE_IGNORE has the same effect as SQLITE_DENY. If the authorizer code is SQLITE_READ and the 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. |
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 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 | 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. |
F12521 | A NULL authorizer means that no authorization callback is invoked. |
F12522 | The default authorizer is NULL. |
F12523 | Authorization is not performed during statement evaluation in sqlite3_step(). |
F12550 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
/******************************************* 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 */ |
F12551 | 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. |
F12552 | 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. |
F12553 | The 5th parameter to the authorizer callback is the name of the database ("main", "temp", etc.) if applicable. |
F12554 | 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. |
F12590 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
#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 */ |
F12600 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_load_extension( sqlite3 *db, /* Load the extension into this database connection */ const char *zFile, /* Name of the shared library containing extension */ const char *zProc, /* Entry point. Derived from zFile if 0 */ char **pzErrMsg /* Put error message here if not 0 */ ); |
F12601 | The sqlite3_load_extension() interface attempts to load an SQLite extension library contained in the file zFile. |
F12602 | The entry point is zProc. |
F12603 | zProc may be 0 in which case the name of the entry point defaults to "sqlite3_extension_init". |
F12604 | The sqlite3_load_extension() interface shall return SQLITE_OK on success and SQLITE_ERROR if something goes wrong. |
F12605 | If an error occurs and pzErrMsg is not 0, then the sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with error message text stored in memory obtained from sqlite3_malloc(). |
F12606 | Extension loading must be enabled using sqlite3_enable_load_extension() prior to calling this API or an error will be returned. |
F12620 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_enable_load_extension(sqlite3 *db, int onoff); |
F12621 | Call the sqlite3_enable_load_extension() routine with onoff==1 to turn extension loading on and call it with onoff==0 to turn it back off again. |
F12622 | It is off by default. |
F12640 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_auto_extension(void *xEntryPoint); |
F12641 | This function registers an extension entry point that is automatically invoked whenever a new database connection is opened using sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2(). |
F12642 | Duplicate extensions are detected so calling this routine multiple times with the same extension is harmless. |
F12643 | This routine stores a pointer to the extension in an array that is obtained from sqlite_malloc(). |
F12644 | Automatic extensions apply across all threads. |
F12660 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
void sqlite3_reset_auto_extension(void); |
F12661 | This function disables all previously registered automatic extensions. |
F12662 | This call disabled automatic extensions in all threads. |
F12700 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
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 */ ); |
F12701 | These routines open an SQLite database file whose name is given by the filename argument. |
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 | An sqlite3* handle is returned in *ppDb, even if an error occurs. |
F12704 | If the database is opened (and/or created) successfully, then SQLITE_OK is returned. |
F12705 | Otherwise an error code is returned. |
F12706 | The sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain an English language description of the error. |
F12707 | 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. |
F12708 | 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. |
F12709 | The sqlite3_open_v2() interface works like sqlite3_open() except that it acccepts two additional parameters for additional control over the new database connection. |
F12710 | The flags parameter can be
one of:
|
F12711 | The first value opens the database read-only. |
F12712 | If the database does not previously exist, an error is returned. |
F12713 | The second option opens the database for reading and writing if possible, or reading only if if the file is write protected. |
F12714 | In either case the database must already exist or an error is returned. |
F12715 | The third option opens the database for reading and writing and creates it if it does not already exist. |
F12716 | The third options is behavior that is always used for sqlite3_open() and sqlite3_open16(). |
F12717 | If the filename is ":memory:", then an private in-memory database is created for the connection. |
F12718 | This in-memory database will vanish when the database connection is closed. |
F12719 | If the filename is an empty string, then a private temporary on-disk database will be created. |
F12720 | This private database will be automatically deleted as soon as the database connection is closed. |
F12721 | 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. |
F12722 | If the fourth parameter is a NULL pointer then the default sqlite3_vfs object is used. |
F12723 | (Exception: 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.) |
F12800 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
int sqlite3_errcode(sqlite3 *db); const char *sqlite3_errmsg(sqlite3*); const void *sqlite3_errmsg16(sqlite3*); |
F12801 | The sqlite3_errcode() interface returns the numeric result code or extended result code for the most recent failed sqlite3_* API call associated with sqlite3 handle 'db'. |
U12802 | If a prior API call failed but the most recent API call succeeded, the return value from sqlite3_errcode() is undefined. |
F12803 | The sqlite3_errmsg() and sqlite3_errmsg16() return English-language text that describes the error, as either UTF8 or UTF16 respectively. |
F12804 | Memory to hold the error message string is managed internally. |
U12805 | The string may be overwritten or deallocated by subsequent calls to SQLite interface functions. |
F12806 | Calls to many sqlite3_* functions set the error code and string returned by sqlite3_errcode(), sqlite3_errmsg(), and sqlite3_errmsg16() overwriting the previous values. |
F12807 | Except, calls to sqlite3_errcode(), sqlite3_errmsg(), and sqlite3_errmsg16() themselves do not affect the results of future invocations. |
F12808 | Calls to API routines that do not return an error code (example: sqlite3_data_count()) do not change the error code returned by this routine. |
F12809 | Interfaces that are not associated with a specific database connection (examples: sqlite3_mprintf() or sqlite3_enable_shared_cache() do not change the return code. |
F12810 | Assuming no other intervening sqlite3_* API calls are made, the error code returned by this function is associated with the same error as the strings returned by sqlite3_errmsg() and sqlite3_errmsg16(). |
F12850 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_table_column_metadata( sqlite3 *db, /* Connection handle */ const char *zDbName, /* Database name or NULL */ const char *zTableName, /* Table name */ const char *zColumnName, /* Column name */ char const **pzDataType, /* OUTPUT: Declared data type */ char const **pzCollSeq, /* OUTPUT: Collation sequence name */ int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ int *pPrimaryKey, /* OUTPUT: True if column part of PK */ int *pAutoinc /* OUTPUT: True if column is auto-increment */ ); |
F12910 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); |
F12911 | 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(). |
F12912 | The progress callback is invoked once for every N virtual machine opcodes, where N is the second argument to this function. |
F12913 | The progress callback itself is identified by the third argument to this function. |
F12914 | The fourth argument to this function is a void pointer passed to the progress callback function each time it is invoked. |
F12915 | If a call to sqlite3_exec(), sqlite3_step(), or sqlite3_get_table() results in fewer than N opcodes being executed, then the progress callback is never invoked. |
F12916 | Only a single progress callback function may be registered for each open database connection. Every call to sqlite3_progress_handler() overwrites the results of the previous call. |
F12917 | To remove the progress callback altogether, pass NULL as the third argument to this function. |
F12918 | If the progress callback returns a result other than 0, then the current query is immediately terminated and any database changes rolled back. |
F12919 | The containing sqlite3_exec(), sqlite3_step(), or sqlite3_get_table() call returns SQLITE_INTERRUPT. |
F12930 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_get_autocommit(sqlite3*); |
F12931 | The sqlite3_get_autocommit() interfaces returns non-zero or zero if the given database connection is or is not in autocommit mode, respectively. |
F12932 | Autocommit mode is on by default. |
F12933 | Autocommit mode is disabled by a BEGIN statement. |
F12934 | Autocommit mode is reenabled by a COMMIT or ROLLBACK. |
F12935 | The only way to find out if SQLite automatically rolled back the transaction after an error is to use this function. |
U12936 | If another thread changes the autocommit status of the database connection while this routine is running, then the return value is undefined. |
F12950 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); |
F12951 | The sqlite3_commit_hook() interface registers a callback function to be invoked whenever a transaction is committed. |
F12952 | Any callback set by a previous call to sqlite3_commit_hook() for the same database connection is overridden. |
F12953 | The sqlite3_rollback_hook() interface registers a callback function to be invoked whenever a transaction is committed. |
F12954 | Any callback set by a previous call to sqlite3_commit_hook() for the same database connection is overridden. |
F12956 | The pArg argument is passed through to the callback. |
F12957 | If the callback on a commit hook function returns non-zero, then the commit is converted into a rollback. |
F12958 | If another function was previously registered, its pArg value is returned. Otherwise NULL is returned. |
F12959 | Registering a NULL function disables the callback. |
F12961 | For the purposes of this API, a transaction is said to have been rolled back if an explicit "ROLLBACK" statement is executed, or an error or constraint causes an implicit rollback to occur. |
F12962 | The rollback callback is not invoked if a transaction is automatically rolled back because the database connection is closed. |
F12964 | The rollback callback is not invoked if a transaction is rolled back because a commit callback returned non-zero. (TODO: Check on this ) |
F12970 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
void *sqlite3_update_hook( sqlite3*, void(*)(void *,int ,char const *,char const *,sqlite3_int64), void* ); |
F12971 | The sqlite3_update_hook() interface registers a callback function with the database connection identified by the first argument to be invoked whenever a row is updated, inserted or deleted. |
F12972 | Any callback set by a previous call to this function for the same database connection is overridden. |
F12974 | The second argument is a pointer to the function to invoke when a row is updated, inserted or deleted. |
F12976 | The first argument to the callback is a copy of the third argument to sqlite3_update_hook(). |
F12977 | The second callback argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending on the operation that caused the callback to be invoked. |
F12978 | The third and fourth arguments to the callback contain pointers to the database and table name containing the affected row. |
F12979 | The final callback parameter is the rowid of the row. |
F12981 | In the case of an update, this is the rowid after the update takes place. |
F12983 | The update hook is not invoked when internal system tables are modified (i.e. sqlite_master and sqlite_sequence). |
F12984 | If another function was previously registered, its pArg value is returned. |
F12985 | Otherwise NULL is returned. |
F13000 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
typedef struct sqlite3_stmt sqlite3_stmt; |
F13010 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
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 */ ); |
F13011 | The first argument "db" is an SQLite database handle obtained from a prior call to sqlite3_open(), sqlite3_open_v2() or sqlite3_open16(). |
F13012 | 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. |
F13013 | If the nByte argument is less than zero, then zSql is read up to the first zero terminator. |
F13014 | 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 '\000' or '\u0000' character or until the nByte-th byte, whichever comes first. |
F13015 | *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. |
F13016 | *ppStmt is left pointing to a compiled SQL statement structure that can be executed using sqlite3_step(). Or if there is an error, *ppStmt may be set to NULL. |
F13017 | 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. |
F13019 | On success, SQLITE_OK is returned. Otherwise an error code is returned. |
F13020 | In the "v2" interfaces, the prepared statement that is returned (the sqlite3_stmt object) contains a copy of the original SQL text. |
F13022 | 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. |
F13030 | When an error occurs, sqlite3_step() will return one of the detailed result codes or extended result codes. |
F13031 | 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. |
F13032 | With the "v2" prepare interfaces, the underlying reason for the error is returned immediately. |
F13120 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
sqlite3 *sqlite3_db_handle(sqlite3_stmt*); |
F13121 | The sqlite3_db_handle interface returns the sqlite3* database handle to which a prepared statement belongs. |
F13122 | the database handle returned by sqlite3_db_handle is the same database handle that was the first argument to the sqlite3_prepare_v2() or its variants that was used to create the statement in the first place. |
F13200 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_step(sqlite3_stmt*); |
F13300 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_finalize(sqlite3_stmt *pStmt); |
F13330 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_reset(sqlite3_stmt *pStmt); |
F13500 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
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); |
F13501 | In the SQL strings input to sqlite3_prepare_v2() and its
variants, literals may be replace by a parameter in one
of these forms:
|
F13502 | 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. |
F13503 | The second argument is the index of the parameter to be set. |
F13504 | The first parameter has an index of 1. |
F13505 | When the same named parameter is used more than once, second and subsequent occurrences have the same index as the first occurrence. |
F13506 | The index for named parameters can be looked up using the sqlite3_bind_parameter_name() API if desired. |
F13507 | The index for "?NNN" parameters is the value of NNN. |
F13508 | The NNN value must be between 1 and the compile-time parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). |
F13509 | The third argument is the value to bind to the parameter. |
F13510 | In those routines that have a fourth argument, its value is the number of bytes in the parameter. To be clear: the value is the number of bytes in the string, not the number of characters. |
F13511 | The number of bytes does not include the zero-terminator at the end of strings. |
F13512 | If the fourth parameter is negative, the length of the string is number of bytes up to the first zero terminator. |
F13513 | The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and sqlite3_bind_text16() is a destructor used to dispose of the BLOB or text after SQLite has finished with it. |
F13514 | If the fifth argument is the special value SQLITE_STATIC, then the library assumes that the information is in static, unmanaged space and does not need to be freed. |
F13515 | 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. |
F13520 | The sqlite3_bind_zeroblob() routine binds a BLOB of length N that is filled with zeros. |
F13521 | A zeroblob uses a fixed amount of memory (just an integer to hold it size) while it is being processed. |
F13522 | A negative value for the zeroblob results in a zero-length BLOB. |
F13530 | The sqlite3_bind_*() routines must be called after sqlite3_prepare_v2() (and its variants) or sqlite3_reset() and before sqlite3_step(). |
F13531 | Bindings are not cleared by the sqlite3_reset() routine. |
F13532 | Unbound parameters are interpreted as NULL. |
F13540 | These routines return SQLITE_OK on success or an error code if anything goes wrong. |
F13541 | SQLITE_RANGE is returned if the parameter index is out of range. |
F13542 | SQLITE_NOMEM is returned if malloc fails. |
F13543 | SQLITE_MISUSE is returned if these routines are called on a virtual machine that is the wrong state or which has already been finalized. |
F13600 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_bind_parameter_count(sqlite3_stmt*); |
F13601 | Return the largest host parameter index in the precompiled statement given as the argument. |
F13602 | When the host parameters are of the forms like ":AAA", "$VVV", "@AAA", or "?", then they are assigned sequential increasing numbers beginning with one, so the value returned is the number of parameters. |
F13603 | However if the same host parameter name is used multiple times, each occurrance is given the same number, so the value returned in that case is the number of unique host parameter names. |
F13604 | If host parameters of the form "?NNN" are used (where NNN is an integer) then there might be gaps in the numbering and the value returned by this interface is the index of the host parameter with the largest index value. |
U13605 | The prepared statement must not be finalized prior to this routine returning. Otherwise the results are undefined and probably undesirable. |
F13620 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); |
F13621 | This routine returns a pointer to the name of the n-th parameter in a prepared statement. |
F13622 | Host parameters of the form ":AAA" or "@AAA" or "$VVV" 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. |
F13623 | The first host parameter has an index of 1, not 0. |
F13624 | If the value n is out of range or if the n-th parameter is nameless, then NULL is returned. |
F13625 | 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(). |
F13626 | Parameters of the form "?" or "?NNN" have no name. |
F13640 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); |
F13641 | This routine returns the index of a host parameter with the given name. |
F13642 | The name must match exactly. |
F13643 | If no parameter with the given name is found, return 0. |
F13644 | Parameter names must be UTF8. |
F13660 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_clear_bindings(sqlite3_stmt*); |
F13661 | Contrary to the intuition of many, sqlite3_reset() does not reset the bindings on a prepared statement. |
F13662 | Use this routine to reset all host parameters to NULL. |
F13710 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_column_count(sqlite3_stmt *pStmt); |
F13711 | Return the number of columns in the result set returned by the compiled SQL statement. |
F13712 | This routine returns 0 if pStmt is an SQL statement that does not return data (for example an UPDATE). |
F13720 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
const char *sqlite3_column_name(sqlite3_stmt*, int N); const void *sqlite3_column_name16(sqlite3_stmt*, int N); |
F13721 | These routines return the name assigned to a particular column in the result set of a SELECT statement. |
F13722 | 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. |
F13723 | 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. |
F13724 | 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. |
F13725 | 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. |
F13740 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
const char *sqlite3_column_database_name(sqlite3_stmt*,int); const void *sqlite3_column_database_name16(sqlite3_stmt*,int); const char *sqlite3_column_table_name(sqlite3_stmt*,int); const void *sqlite3_column_table_name16(sqlite3_stmt*,int); const char *sqlite3_column_origin_name(sqlite3_stmt*,int); const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); |
F13741 | These routines provide a means to determine what column of what table in which database a result of a SELECT statement comes from. |
F13742 | The name of the database or table or column can be returned as either a UTF8 or UTF16 string. |
F13743 | The _database_ routines return the database name, the _table_ routines return the table name, and the origin_ routines return the column name. |
F13744 | The returned string is valid until the prepared statement is destroyed using sqlite3_finalize() or until the same information is requested again in a different encoding. |
F13745 | The names returned are the original un-aliased names of the database, table, and column. |
F13746 | The first argument to the following calls is a compiled SQL statement. |
F13747 | These functions return information about the Nth column returned by the statement, where N is the second function argument. |
F13748 | If the Nth column returned by the statement is an expression or subquery and is not a column value, then all of these functions return NULL. |
F13749 | Otherwise, they return the name of the attached database, table and column that query result column was extracted from. |
F13750 | As with all other SQLite APIs, those postfixed with "16" return UTF-16 encoded strings, the other functions return UTF-8. |
U13751 | If two or more threads call one or more of these routines against the same prepared statement and column at the same time then the results are undefined. |
F13760 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
const char *sqlite3_column_decltype(sqlite3_stmt *, int i); const void *sqlite3_column_decltype16(sqlite3_stmt*,int); |
F13761 | If this statement is a SELECT statement and the Nth column of the returned result set of that SELECT is a table column (not an expression or subquery) then the declared type of the table column is returned. |
F13762 | If the Nth column of the result set is an expression or subquery, then a NULL pointer is returned. |
F13763 | The returned string is always UTF-8 encoded. |
F13770 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_data_count(sqlite3_stmt *pStmt); |
F13771 | After a call to sqlite3_step() that returns SQLITE_ROW, this routine will return the same value as the sqlite3_column_count() function. |
F13772 | After sqlite3_step() has returned an SQLITE_DONE, SQLITE_BUSY, or a error code, or before sqlite3_step() has been called on the prepared statement for the first time, this routine returns zero. |
F13800 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); int sqlite3_column_bytes(sqlite3_stmt*, int iCol); int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); double sqlite3_column_double(sqlite3_stmt*, int iCol); int sqlite3_column_int(sqlite3_stmt*, int iCol); sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); int sqlite3_column_type(sqlite3_stmt*, int iCol); sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); |
F15000 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
typedef struct Mem sqlite3_value; |
F15001 | SQLite uses the sqlite3_value object to represent all values that are or can be stored in a database table. |
F15002 | Values stored in sqlite3_value objects can be be integers, floating point values, strings, BLOBs, or NULL. |
F15100 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
const void *sqlite3_value_blob(sqlite3_value*); int sqlite3_value_bytes(sqlite3_value*); int sqlite3_value_bytes16(sqlite3_value*); double sqlite3_value_double(sqlite3_value*); int sqlite3_value_int(sqlite3_value*); sqlite3_int64 sqlite3_value_int64(sqlite3_value*); const unsigned char *sqlite3_value_text(sqlite3_value*); const void *sqlite3_value_text16(sqlite3_value*); const void *sqlite3_value_text16le(sqlite3_value*); const void *sqlite3_value_text16be(sqlite3_value*); int sqlite3_value_type(sqlite3_value*); int sqlite3_value_numeric_type(sqlite3_value*); |
F16001 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
typedef struct sqlite3_context sqlite3_context; |
F16002 | A pointer to an sqlite3_context object is always first parameter to application-defined SQL functions. |
F16100 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
int sqlite3_create_function( sqlite3 *, const char *zFunctionName, int nArg, int eTextRep, void*, void (*xFunc)(sqlite3_context*,int,sqlite3_value**), void (*xStep)(sqlite3_context*,int,sqlite3_value**), void (*xFinal)(sqlite3_context*) ); int sqlite3_create_function16( sqlite3*, const void *zFunctionName, int nArg, int eTextRep, void*, void (*xFunc)(sqlite3_context*,int,sqlite3_value**), void (*xStep)(sqlite3_context*,int,sqlite3_value**), void (*xFinal)(sqlite3_context*) ); |
F16210 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); |
F16211 | The first time the sqlite3_aggregate_context() routine is is called for a particular aggregate, SQLite allocates nBytes of memory zeros that memory, and returns a pointer to it. |
F16212 | On second and subsequent calls to sqlite3_aggregate_context() for the same aggregate function index, the same buffer is returned. |
F16213 | SQLite automatically frees the allocated buffer when the aggregate query concludes. |
F16240 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
void *sqlite3_user_data(sqlite3_context*); |
F16241 | The sqlite3_user_data() interface returns a copy of the pointer that was the pUserData parameter (the 5th parameter) of the the sqlite3_create_function() and sqlite3_create_function16() routines that originally registered the application defined function. |
U16243 | This routine must be called from the same thread in which the application-defined function is running. |
F16270 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
void *sqlite3_get_auxdata(sqlite3_context*, int N); void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*)); |
F16271 | The sqlite3_get_auxdata() interface returns a pointer to the meta-data associated by the sqlite3_set_auxdata() function with the Nth argument value to the application-defined function. |
F16272 | If no meta-data has been ever been set for the Nth argument of the function, or if the cooresponding function parameter has changed since the meta-data was set, then sqlite3_get_auxdata() returns a NULL pointer. |
F16275 | The sqlite3_set_auxdata() interface saves the meta-data pointed to by its 3rd parameter as the meta-data for the N-th argument of the application-defined function. |
F16277 | If it is not NULL, SQLite will invoke the destructor function given by the 4th parameter to sqlite3_set_auxdata() on the meta-data when the corresponding function parameter changes or when the SQL statement completes, whichever comes first. |
F16342 | sqlite3_release_memory() returns the number of bytes actually freed, which might be more or less than the amount requested. |
F16351 | The sqlite3_soft_heap_limit() interface places a "soft" limit on the amount of heap memory that may be allocated by SQLite. |
F16352 | If an internal allocation is requested that would exceed the soft heap limit, sqlite3_release_memory() is invoked one or more times to free up some space before the allocation is made. |
F16353 | The limit is called "soft", because if sqlite3_release_memory() cannot free sufficient memory to prevent the limit from being exceeded, the memory is allocated anyway and the current operation proceeds. |
F16354 | A negative or zero value for N means that there is no soft heap limit and sqlite3_release_memory() will only be called when memory is exhausted. |
F16355 | The default value for the soft heap limit is zero. SQLite makes a best effort to honor the soft heap limit. |
F16356 | But if the soft heap limit cannot honored, execution will continue without error or notification. |
F16357 | The value specified for the soft heap limit is an upper bound on the total memory allocation for all threads. |
F16400 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); void sqlite3_result_double(sqlite3_context*, double); void sqlite3_result_error(sqlite3_context*, const char*, int); void sqlite3_result_error16(sqlite3_context*, const void*, int); void sqlite3_result_error_toobig(sqlite3_context*); void sqlite3_result_error_nomem(sqlite3_context*); void sqlite3_result_int(sqlite3_context*, int); void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); void sqlite3_result_null(sqlite3_context*); void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); void sqlite3_result_value(sqlite3_context*, sqlite3_value*); void sqlite3_result_zeroblob(sqlite3_context*, int n); |
F16402 | The sqlite3_result_blob() interface sets the result from an application defined function to be the BLOB whose content is pointed to by the second parameter and which is N bytes long where N is the third parameter. |
F16403 | The sqlite3_result_zeroblob() inerfaces set the result of the application defined function to be a BLOB containing all zero bytes and N bytes in size, where N is the value of the 2nd parameter. |
F16407 | The sqlite3_result_double() interface sets the result from an application defined function to be a floating point value specified by its 2nd argument. |
F16409 | The sqlite3_result_error() and sqlite3_result_error16() functions cause the implemented SQL function to throw an exception. |
F16411 | SQLite uses the string pointed to by the 2nd parameter of sqlite3_result_error() or sqlite3_result_error16() as the text of an error message. |
F16412 | SQLite interprets the error message string from sqlite3_result_error() as UTF8. |
F16413 | SQLite interprets the string from sqlite3_result_error16() as UTF16 in native byte order. |
F16414 | If the third parameter to sqlite3_result_error() or sqlite3_result_error16() is negative then SQLite takes as the error message all text up through the first zero character. |
F16415 | If the third parameter to sqlite3_result_error() or sqlite3_result_error16() is non-negative then SQLite takes that many bytes (not characters) from the 2nd parameter as the error message. |
F16417 | The sqlite3_result_error() and sqlite3_result_error16() routines make a copy private copy of the error message text before they return. |
F16421 | The sqlite3_result_toobig() interface causes SQLite to throw an error indicating that a string or BLOB is to long to represent. |
F16422 | The sqlite3_result_nomem() interface causes SQLite to throw an exception indicating that the a memory allocation failed. |
F16431 | The sqlite3_result_int() interface sets the return value of the application-defined function to be the 32-bit signed integer value given in the 2nd argument. |
F16432 | The sqlite3_result_int64() interface sets the return value of the application-defined function to be the 64-bit signed integer value given in the 2nd argument. |
F16437 | The sqlite3_result_null() interface sets the return value of the application-defined function to be NULL. |
F16441 | The sqlite3_result_text(), sqlite3_result_text16(), sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces set the return value of the application-defined function to be a text string which is represented as UTF-8, UTF-16 native byte order, UTF-16 little endian, or UTF-16 big endian, respectively. |
F16442 | SQLite takes the text result from the application from the 2nd parameter of the sqlite3_result_text* interfaces. |
F16444 | If the 3rd parameter to the sqlite3_result_text* interfaces is negative, then SQLite takes result text from the 2nd parameter through the first zero character. |
F16447 | If the 3rd parameter to the sqlite3_result_text* interfaces is non-negative, then as many bytes (not characters) of the text pointed to by the 2nd parameter are taken as the application-defined function result. |
F16451 | If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that function as the destructor on the text or blob result when it has finished using that result. |
F16453 | If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite assumes that the text or blob result is constant space and does not copy the space or call a destructor when it has finished using that result. |
F16454 | If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob is the special constant SQLITE_TRANSIENT then SQLite makes a copy of the result into space obtained from from sqlite3_malloc() before it returns. |
F16461 | The sqlite3_result_value() interface sets the result of the application-defined function to be a copy the sqlite3_value object specified by the 2nd parameter. |
F16463 | The sqlite3_result_value() interface makes a copy of the sqlite3_value so that sqlite3_value specified in the parameter may change or be deallocated after sqlite3_result_value() returns without harm. |
U16491 | These routines are called from within the different thread than the one containing the application-defined function that recieved the sqlite3_context pointer, the results are undefined. |
F16600 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
int sqlite3_create_collation( sqlite3*, const char *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*) ); int sqlite3_create_collation_v2( sqlite3*, const char *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*), void(*xDestroy)(void*) ); int sqlite3_create_collation16( sqlite3*, const char *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*) ); |
F16601 | These functions are used to add new collation sequences to the sqlite3* handle specified as the first argument. |
F16602 | The name of the new collation sequence is specified as a UTF-8 string for sqlite3_create_collation() and sqlite3_create_collation_v2() and a UTF-16 string for sqlite3_create_collation16(). |
F16603 | In all cases the name is passed as the second function argument. |
F16604 | The third argument may be one of the constants SQLITE_UTF8, SQLITE_UTF16LE or SQLITE_UTF16BE, indicating that the user-supplied routine expects to be passed pointers to strings encoded using UTF-8, UTF-16 little-endian or UTF-16 big-endian respectively. |
F16605 | The third argument might also be SQLITE_UTF16_ALIGNED to indicate that the routine expects pointers to 16-bit word aligned strings of UTF16 in the native byte order of the host computer. |
F16607 | A pointer to the user supplied routine must be passed as the fifth argument. |
F16609 | If it is NULL, this is the same as deleting the collation sequence (so that SQLite cannot call it anymore). |
F16611 | Each time the application supplied function is invoked, it is passed a copy of the void* passed as the fourth argument to sqlite3_create_collation() or sqlite3_create_collation16() as its first parameter. |
F16612 | The remaining arguments to the application-supplied routine are two strings, each represented by a length, data pair and encoded in the encoding that was passed as the third argument when the collation sequence was registered. |
F16615 | The sqlite3_create_collation_v2() works like sqlite3_create_collation() excapt that it takes an extra argument which is a destructor for the collation. |
F16617 | The destructor is called when the collation is destroyed and is passed a copy of the fourth parameter void* pointer of the sqlite3_create_collation_v2(). |
F16618 | Collations are destroyed when they are overridden by later calls to the collation creation functions or when the sqlite3* database handle is closed using sqlite3_close(). |
F16700 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
int sqlite3_collation_needed( sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const char*) ); int sqlite3_collation_needed16( sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const void*) ); |
F16701 | To avoid having to register all collation sequences before a database can be used, a single callback function may be registered with the database handle to be called whenever an undefined collation sequence is required. |
F16702 | If the function is registered using the sqlite3_collation_needed() API, then it is passed the names of undefined collation sequences as strings encoded in UTF-8. |
F16703 | If sqlite3_collation_needed16() is used, the names are passed as UTF-16 in machine native byte order. |
F16704 | A call to either function replaces any existing callback. |
F16705 | When the callback is invoked, the first argument passed is a copy of the second argument to sqlite3_collation_needed() or sqlite3_collation_needed16(). |
F16706 | The second argument is the database handle. |
F16707 | The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE, or SQLITE_UTF16LE, indicating the most desirable form of the collation sequence function required. |
F16708 | The fourth parameter is the name of the required collation sequence. |
F16806 | Return the size in bytes of the blob accessible via the open blob-handle passed as an argument. |
F17000 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
sqlite3_mutex *sqlite3_mutex_alloc(int); void sqlite3_mutex_free(sqlite3_mutex*); void sqlite3_mutex_enter(sqlite3_mutex*); int sqlite3_mutex_try(sqlite3_mutex*); void sqlite3_mutex_leave(sqlite3_mutex*); |
F17001 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
#define SQLITE_MUTEX_FAST 0 #define SQLITE_MUTEX_RECURSIVE 1 #define SQLITE_MUTEX_STATIC_MASTER 2 #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ #define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */ #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ |
F17002 | The sqlite3_mutex_alloc() interface takes a single argument which is one of these integer constants. |
F17011 | The sqlite3_mutex_alloc() routine allocates a new mutex and returns a pointer to it. |
F17012 | If it returns NULL that means that a mutex could not be allocated. |
F17013 | SQLite will unwind its stack and return an error. |
F17014 | The argument
to sqlite3_mutex_alloc() is one of these integer constants:
|
F17015 | The first two constants cause sqlite3_mutex_alloc() to create a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE is used but not necessarily so when SQLITE_MUTEX_FAST is used. |
F17016 | But SQLite will only request a recursive mutex in cases where it really needs one. |
F17017 | The other allowed parameters to sqlite3_mutex_alloc() each return a pointer to a static preexisting mutex. |
F17018 | Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() returns a different mutex on every call. |
F17019 | The sqlite3_mutex_free() routine deallocates a previously allocated dynamic mutex. |
F17020 | SQLite is careful to deallocate every dynamic mutex that it allocates. |
U17021 | The dynamic mutexes must not be in use when they are deallocated. |
U17022 | Attempting to deallocate a static mutex results in undefined behavior. |
F17023 | SQLite never deallocates a static mutex. |
F17024 | If another thread is already within the mutex, sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return SQLITE_BUSY. |
F17025 | The sqlite3_mutex_try() interface returns SQLITE_OK upon successful entry. |
F17026 | Mutexes created using SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. |
F17027 | In such cases the, mutex must be exited an equal number of times before another thread can enter. |
U17028 | If the same thread tries to enter any other kind of mutex more than once, the behavior is undefined. |
F17029 | SQLite will never exhibit such behavior in its own use of mutexes. |
F17030 | The SQLite core only ever uses sqlite3_mutex_try() as an optimization so this is acceptable behavior. |
F17031 | The sqlite3_mutex_leave() routine exits a mutex that was previously entered by the same thread. |
U17032 | The behavior is undefined if the mutex is not currently entered by the calling thread or is not currently allocated. |
F17033 | SQLite will never do either. |
F17034 | But for the static mutex types, the same mutex is returned on every call that has the same type number. |
F17080 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
int sqlite3_mutex_held(sqlite3_mutex*); int sqlite3_mutex_notheld(sqlite3_mutex*); |
F17081 | The SQLite core never uses these routines except inside an assert() and applications are advised to follow the lead of the core. |
F17082 | The core only provides implementations for these routines when it is compiled with the SQLITE_DEBUG flag. |
F17083 | These routines should return true if the mutex in their argument is held or not held, respectively, by the calling thread. |
X17084 | The implementation is not required to provided versions of these routines that actually work. If the implementation does not provide working versions of these routines, it should at least provide stubs that always return true so that one does not get spurious assertion failures. |
F17085 | If the argument to sqlite3_mutex_held() is a NULL pointer then the routine should return 1. |
F17086 | The sqlite3_mutex_notheld() interface should also return 1 when given a NULL pointer. |
U17087 | External mutex implementations are only required to provide these routines if SQLITE_DEBUG is defined and if NDEBUG is not defined. |
F17110 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
typedef struct sqlite3_mutex sqlite3_mutex; |
F17111 | The SQLite core never looks at the internal representation of an sqlite3_mutex. |
F17300 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
void *sqlite3_malloc(int); void *sqlite3_realloc(void*, int); void sqlite3_free(void*); |
F17301 | The SQLite core uses these three routines for all of its own internal memory allocation needs. |
F17302 | The sqlite3_malloc() routine returns a pointer to a block of memory at least N bytes in length, where N is the parameter. |
F17303 | If sqlite3_malloc() is unable to obtain sufficient free memory, it returns a NULL pointer. |
F17304 | If the parameter N to sqlite3_malloc() is zero or negative then sqlite3_malloc() returns a NULL pointer. |
F17305 | Calling sqlite3_free() with a pointer previously returned by sqlite3_malloc() or sqlite3_realloc() releases that memory so that it might be reused. |
F17306 | The sqlite3_free() routine is a no-op if is called with a NULL pointer. Passing a NULL pointer to sqlite3_free() is harmless. |
U17307 | 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. |
U17309 | 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(). |
F17310 | 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. |
F17311 | 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(). |
F17312 | 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(). |
F17313 | Sqlite3_realloc() returns a pointer to a memory allocation of at least N bytes in size or NULL if sufficient memory is unavailable. |
F17314 | 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. |
F17315 | If sqlite3_realloc() returns NULL, then the prior allocation is not freed. |
F17316 | The memory returned by sqlite3_malloc() and sqlite3_realloc() is always aligned to at least an 8 byte boundary. |
F17340 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_release_memory(int); |
F17341 | The sqlite3_release_memory() interface attempts to free N bytes of heap memory by deallocating non-essential memory allocations held by the database labrary. |
F17350 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
void sqlite3_soft_heap_limit(int); |
F17370 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
sqlite3_int64 sqlite3_memory_used(void); sqlite3_int64 sqlite3_memory_highwater(int resetFlag); |
F17371 | The sqlite3_memory_used() routine returns the number of bytes of memory currently outstanding (malloced but not freed). |
F17372 | The value returned by sqlite3_memory_used() includes any overhead added by SQLite, but not overhead added by the library malloc() that backs the sqlite3_malloc() implementation. |
F17373 | The sqlite3_memory_highwater() routines returns the maximum number of bytes that have been outstanding at any time since the highwater mark was last reset. |
F17374 | The byte count returned by sqlite3_memory_highwater() uses the same byte counting rules as sqlite3_memory_used(). |
F17375 | If the parameter to sqlite3_memory_highwater() is true, then the highwater mark is reset to the current value of sqlite3_memory_used() and the prior highwater mark (before the reset) is returned. |
F17376 | If the parameter to sqlite3_memory_highwater() is zero, then the highwater mark is unchanged. |
F17381 | 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
SQLITE_MEMORY_SIZE=NNNwhere NNN is an integer, then SQLite create a static array of at least NNN bytes in size and use that array for all of its dynamic memory allocation needs. |
F17400 | The "sqlite3.h" header file shall contain declarations equivalent to the following:
char *sqlite3_mprintf(const char*,...); char *sqlite3_vmprintf(const char*, va_list); char *sqlite3_snprintf(int,char*,const char*, ...); |
F17401 | The sqlite3_mprintf() and sqlite3_vmprintf() routines write their results into memory obtained from sqlite3_malloc(). |
U17402 | The strings returned by these two routines should be released by sqlite3_free(). |
F17403 | Both routines return a NULL pointer if sqlite3_malloc() is unable to allocate enough memory to hold the resulting string. |
F17404 | 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. |
F17405 | Note also that sqlite3_snprintf() returns a pointer to its buffer instead of the number of characters actually written into the buffer. |
F17406 | As long as the buffer size is greater than zero, sqlite3_snprintf() guarantees that the buffer is always zero-terminated. |
F17407 | The first parameter "n" is the total size of the buffer, including space for the zero terminator. |
F17410 | 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. |
F17411 | 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. |
F17412 | 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. |
F17800 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
typedef struct sqlite3_blob sqlite3_blob; |
F17805 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_blob_bytes(sqlite3_blob *); |
F17810 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_blob_open( sqlite3*, const char *zDb, const char *zTable, const char *zColumn, sqlite3_int64 iRow, int flags, sqlite3_blob **ppBlob ); |
F17811 | This interfaces opens a handle to the blob located
in row iRow,, column zColumn, table zTable in database zDb;
in other words, the same blob that would be selected by:
SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; |
F17812 | If the flags parameter is non-zero, the blob is opened for read and write access. If it is zero, the blob is opened for read access. |
F17813 | On success, SQLITE_OK is returned and the new blob handle is written to *ppBlob. |
F17814 | Otherwise an error code is returned and any value written to *ppBlob should not be used by the caller. |
F17815 | This function sets the database-handle error code and message accessible via sqlite3_errcode() and sqlite3_errmsg(). (TODO: We should go through and mark all interfaces that behave this way with a similar statement) |
F17830 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_blob_close(sqlite3_blob *); |
F17831 | Closing a BLOB shall cause the current transaction to commit if there are no other BLOBs, no pending prepared statements, and the database connection is in autocommit mode. |
F17832 | If any writes were made to the BLOB, they might be held in cache until the close operation if they will fit. |
F17833 | Any errors that occur during closing are reported as a non-zero return value. |
F17839 | The BLOB is closed unconditionally. Even if this routine returns an error code, the BLOB is still closed. |
F17850 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_blob_read(sqlite3_blob *, void *z, int n, int iOffset); |
F17851 | n bytes of data are copied into buffer z from the open blob, starting at offset iOffset. |
F17852 | If offset iOffset is less than n bytes from the end of the blob, SQLITE_ERROR is returned and no data is read. |
F17853 | If n is less than zero SQLITE_ERROR is returned and no data is read. |
F17854 | On success, SQLITE_OK is returned. Otherwise, an SQLite error code or an extended error code is returned. |
F17870 | The "sqlite3.h" header file shall contain a declaration equivalent to the following:
int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); |
F17871 | n bytes of data are copied from the buffer pointed to by z into the open blob, starting at offset iOffset. |
F17872 | If the blob-handle passed as the first argument was not opened for writing (the flags parameter to sqlite3_blob_open() was zero), this function returns SQLITE_READONLY. |
F17873 | This function may only modify the contents of the blob; it is not possible to increase the size of a blob using this API. |
F17874 | If offset iOffset is less than n bytes from the end of the blob, SQLITE_ERROR is returned and no data is written. |
F17875 | If n is less than zero SQLITE_ERROR is returned and no data is written. |
F17876 | On success, SQLITE_OK is returned. Otherwise, an SQLite error code or an extended error code is returned. |