Small. Fast. Reliable.
Choose any three.

SQLite Requirements

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.

The C/C++ Interface

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:
  • 64-bit signed integer
  • 64-bit IEEE floating point number
  • string
  • BLOB
  • NULL
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:
  • SQLITE_OPEN_MAIN_DB
  • SQLITE_OPEN_MAIN_JOURNAL
  • SQLITE_OPEN_TEMP_DB
  • SQLITE_OPEN_TEMP_JOURNAL
  • SQLITE_OPEN_TRANSIENT_DB
  • SQLITE_OPEN_SUBJOURNAL
  • SQLITE_OPEN_MASTER_JOURNAL
F11144 SQLite might also add one of the following flags to the xOpen method:
  • SQLITE_OPEN_DELETEONCLOSE
  • SQLITE_OPEN_EXCLUSIVE
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:
Name        | Age
-----------------------
Alice       | 43
Bob         | 28
Cindy       | 21
If the 3rd argument were &azResult then after the function returns azResult will contain the following data:
azResult[0] = "Name";
azResult[1] = "Age";
azResult[2] = "Alice";
azResult[3] = "43";
azResult[4] = "Bob";
azResult[5] = "28";
azResult[6] = "Cindy";
azResult[7] = "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).
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:
  1. SQLITE_OPEN_READONLY
  2. SQLITE_OPEN_READWRITE
  3. SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
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:
  • ?
  • ?NNN
  • :AAA
  • @AAA
  • $VVV
In the parameter forms shown above NNN is an integer literal, AAA is an alphanumeric identifier and VVV is a variable name according to the syntax rules of the TCL programming language.
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:
  • SQLITE_MUTEX_FAST
  • SQLITE_MUTEX_RECURSIVE
  • SQLITE_MUTEX_STATIC_MASTER
  • SQLITE_MUTEX_STATIC_MEM
  • SQLITE_MUTEX_STATIC_MEM2
  • SQLITE_MUTEX_STATIC_PRNG
  • SQLITE_MUTEX_STATIC_LRU
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=NNN
where 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.

This page last modified 2007/12/05 23:48:55 UTC