1.1 --- a/extensions/sqlite/sqlite-source/sqlite3.h Sun Oct 28 05:06:12 2007 +0000
1.2 +++ b/extensions/sqlite/sqlite-source/sqlite3.h Sun Oct 28 05:48:06 2007 +0000
1.3 @@ -43,6 +43,14 @@
1.4 extern "C" {
1.5 #endif
1.6
1.7 +
1.8 +/*
1.9 +** Add the ability to override 'extern'
1.10 +*/
1.11 +#ifndef SQLITE_EXTERN
1.12 +# define SQLITE_EXTERN extern
1.13 +#endif
1.14 +
1.15 /*
1.16 ** Make sure these symbols where not defined by some previous header
1.17 ** file.
1.18 @@ -81,8 +89,8 @@
1.19 **
1.20 ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
1.21 */
1.22 -#define SQLITE_VERSION "3.4.1"
1.23 -#define SQLITE_VERSION_NUMBER 3004001
1.24 +#define SQLITE_VERSION "3.5.1"
1.25 +#define SQLITE_VERSION_NUMBER 3005001
1.26
1.27 /*
1.28 ** CAPI3REF: Run-Time Library Version Numbers
1.29 @@ -100,19 +108,44 @@
1.30 ** is provided for DLL users who can only access functions and not
1.31 ** constants within the DLL.
1.32 */
1.33 -extern const char sqlite3_version[];
1.34 +SQLITE_EXTERN const char sqlite3_version[];
1.35 const char *sqlite3_libversion(void);
1.36 int sqlite3_libversion_number(void);
1.37
1.38 /*
1.39 +** CAPI3REF: Test To See If The Library Is Threadsafe
1.40 +**
1.41 +** This routine returns TRUE (nonzero) if SQLite was compiled with
1.42 +** all of its mutexes enabled and is thus threadsafe. It returns
1.43 +** zero if the particular build is for single-threaded operation
1.44 +** only.
1.45 +**
1.46 +** Really all this routine does is return true if SQLite was compiled
1.47 +** with the -DSQLITE_THREADSAFE=1 option and false if
1.48 +** compiled with -DSQLITE_THREADSAFE=0. If SQLite uses an
1.49 +** application-defined mutex subsystem, malloc subsystem, collating
1.50 +** sequence, VFS, SQL function, progress callback, commit hook,
1.51 +** extension, or other accessories and these add-ons are not
1.52 +** threadsafe, then clearly the combination will not be threadsafe
1.53 +** either. Hence, this routine never reports that the library
1.54 +** is guaranteed to be threadsafe, only when it is guaranteed not
1.55 +** to be.
1.56 +**
1.57 +** This is an experimental API and may go away or change in future
1.58 +** releases.
1.59 +*/
1.60 +int sqlite3_threadsafe(void);
1.61 +
1.62 +/*
1.63 ** CAPI3REF: Database Connection Handle
1.64 **
1.65 ** Each open SQLite database is represented by pointer to an instance of the
1.66 ** opaque structure named "sqlite3". It is useful to think of an sqlite3
1.67 -** pointer as an object. The [sqlite3_open] interface is its constructor
1.68 -** and [sqlite3_close] is its destructor. There are many other interfaces
1.69 -** (such as [sqlite3_prepare_v2], [sqlite3_create_function], and
1.70 -** [sqlite3_busy_timeout] to name but three) that are methods on this
1.71 +** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
1.72 +** [sqlite3_open_v2()] interfaces are its constructors
1.73 +** and [sqlite3_close()] is its destructor. There are many other interfaces
1.74 +** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and
1.75 +** [sqlite3_busy_timeout()] to name but three) that are methods on this
1.76 ** object.
1.77 */
1.78 typedef struct sqlite3 sqlite3;
1.79 @@ -137,26 +170,35 @@
1.80 typedef long long int sqlite_int64;
1.81 typedef unsigned long long int sqlite_uint64;
1.82 #endif
1.83 +typedef sqlite_int64 sqlite3_int64;
1.84 +typedef sqlite_uint64 sqlite3_uint64;
1.85
1.86 /*
1.87 ** If compiling for a processor that lacks floating point support,
1.88 ** substitute integer for floating-point
1.89 */
1.90 #ifdef SQLITE_OMIT_FLOATING_POINT
1.91 -# define double sqlite_int64
1.92 +# define double sqlite3_int64
1.93 #endif
1.94
1.95 /*
1.96 ** CAPI3REF: Closing A Database Connection
1.97 **
1.98 ** Call this function with a pointer to a structure that was previously
1.99 -** returned from [sqlite3_open()] and the corresponding database will by
1.100 +** returned from [sqlite3_open()], [sqlite3_open16()], or
1.101 +** [sqlite3_open_v2()] and the corresponding database will by
1.102 ** closed.
1.103 **
1.104 ** All SQL statements prepared using [sqlite3_prepare_v2()] or
1.105 ** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()]
1.106 ** before this routine is called. Otherwise, SQLITE_BUSY is returned and the
1.107 ** database connection remains open.
1.108 +**
1.109 +** Passing this routine a database connection that has already been
1.110 +** closed results in undefined behavior. If other interfaces that
1.111 +** reference the same database connection are pending (either in the
1.112 +** same thread or in different threads) when this routine is called,
1.113 +** then the behavior is undefined and is almost certainly undesirable.
1.114 */
1.115 int sqlite3_close(sqlite3 *);
1.116
1.117 @@ -181,7 +223,7 @@
1.118 ** invoked once for each row of the query result. This callback
1.119 ** should normally return 0. If the callback returns a non-zero
1.120 ** value then the query is aborted, all subsequent SQL statements
1.121 -** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT.
1.122 +** are skipped and the sqlite3_exec() function returns the [SQLITE_ABORT].
1.123 **
1.124 ** The 4th parameter to this interface is an arbitrary pointer that is
1.125 ** passed through to the callback function as its first parameter.
1.126 @@ -202,9 +244,8 @@
1.127 ** not while executing the callback) then an appropriate error
1.128 ** message is written into memory obtained from [sqlite3_malloc()] and
1.129 ** *errmsg is made to point to that message. The calling function
1.130 -** is responsible for freeing the memory that holds the error
1.131 -** message. Use [sqlite3_free()] for this. If errmsg==NULL,
1.132 -** then no error message is ever written.
1.133 +** is responsible for freeing the memory using [sqlite3_free()].
1.134 +** If errmsg==NULL, then no error message is ever written.
1.135 **
1.136 ** The return value is is SQLITE_OK if there are no errors and
1.137 ** some other [SQLITE_OK | return code] if there is an error.
1.138 @@ -254,7 +295,7 @@
1.139 #define SQLITE_EMPTY 16 /* Database is empty */
1.140 #define SQLITE_SCHEMA 17 /* The database schema changed */
1.141 #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
1.142 -#define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
1.143 +#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
1.144 #define SQLITE_MISMATCH 20 /* Data type mismatch */
1.145 #define SQLITE_MISUSE 21 /* Library used incorrectly */
1.146 #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
1.147 @@ -304,6 +345,382 @@
1.148 #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
1.149 #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
1.150 #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
1.151 +#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
1.152 +
1.153 +/*
1.154 +** CAPI3REF: Flags For File Open Operations
1.155 +**
1.156 +** Combination of the following bit values are used as the
1.157 +** third argument to the [sqlite3_open_v2()] interface and
1.158 +** as fourth argument to the xOpen method of the
1.159 +** [sqlite3_vfs] object.
1.160 +**
1.161 +*/
1.162 +#define SQLITE_OPEN_READONLY 0x00000001
1.163 +#define SQLITE_OPEN_READWRITE 0x00000002
1.164 +#define SQLITE_OPEN_CREATE 0x00000004
1.165 +#define SQLITE_OPEN_DELETEONCLOSE 0x00000008
1.166 +#define SQLITE_OPEN_EXCLUSIVE 0x00000010
1.167 +#define SQLITE_OPEN_MAIN_DB 0x00000100
1.168 +#define SQLITE_OPEN_TEMP_DB 0x00000200
1.169 +#define SQLITE_OPEN_TRANSIENT_DB 0x00000400
1.170 +#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800
1.171 +#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000
1.172 +#define SQLITE_OPEN_SUBJOURNAL 0x00002000
1.173 +#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000
1.174 +
1.175 +/*
1.176 +** CAPI3REF: Device Characteristics
1.177 +**
1.178 +** The xDeviceCapabilities method of the [sqlite3_io_methods]
1.179 +** object returns an integer which is a vector of the following
1.180 +** bit values expressing I/O characteristics of the mass storage
1.181 +** device that holds the file that the [sqlite3_io_methods]
1.182 +** refers to.
1.183 +**
1.184 +** The SQLITE_IOCAP_ATOMIC property means that all writes of
1.185 +** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
1.186 +** mean that writes of blocks that are nnn bytes in size and
1.187 +** are aligned to an address which is an integer multiple of
1.188 +** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
1.189 +** that when data is appended to a file, the data is appended
1.190 +** first then the size of the file is extended, never the other
1.191 +** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
1.192 +** information is written to disk in the same order as calls
1.193 +** to xWrite().
1.194 +*/
1.195 +#define SQLITE_IOCAP_ATOMIC 0x00000001
1.196 +#define SQLITE_IOCAP_ATOMIC512 0x00000002
1.197 +#define SQLITE_IOCAP_ATOMIC1K 0x00000004
1.198 +#define SQLITE_IOCAP_ATOMIC2K 0x00000008
1.199 +#define SQLITE_IOCAP_ATOMIC4K 0x00000010
1.200 +#define SQLITE_IOCAP_ATOMIC8K 0x00000020
1.201 +#define SQLITE_IOCAP_ATOMIC16K 0x00000040
1.202 +#define SQLITE_IOCAP_ATOMIC32K 0x00000080
1.203 +#define SQLITE_IOCAP_ATOMIC64K 0x00000100
1.204 +#define SQLITE_IOCAP_SAFE_APPEND 0x00000200
1.205 +#define SQLITE_IOCAP_SEQUENTIAL 0x00000400
1.206 +
1.207 +/*
1.208 +** CAPI3REF: File Locking Levels
1.209 +**
1.210 +** SQLite uses one of the following integer values as the second
1.211 +** argument to calls it makes to the xLock() and xUnlock() methods
1.212 +** of an [sqlite3_io_methods] object.
1.213 +*/
1.214 +#define SQLITE_LOCK_NONE 0
1.215 +#define SQLITE_LOCK_SHARED 1
1.216 +#define SQLITE_LOCK_RESERVED 2
1.217 +#define SQLITE_LOCK_PENDING 3
1.218 +#define SQLITE_LOCK_EXCLUSIVE 4
1.219 +
1.220 +/*
1.221 +** CAPI3REF: Synchronization Type Flags
1.222 +**
1.223 +** When SQLite invokes the xSync() method of an [sqlite3_io_methods]
1.224 +** object it uses a combination of the following integer values as
1.225 +** the second argument.
1.226 +**
1.227 +** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
1.228 +** sync operation only needs to flush data to mass storage. Inode
1.229 +** information need not be flushed. The SQLITE_SYNC_NORMAL means
1.230 +** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means
1.231 +** to use Mac OS-X style fullsync instead of fsync().
1.232 +*/
1.233 +#define SQLITE_SYNC_NORMAL 0x00002
1.234 +#define SQLITE_SYNC_FULL 0x00003
1.235 +#define SQLITE_SYNC_DATAONLY 0x00010
1.236 +
1.237 +
1.238 +/*
1.239 +** CAPI3REF: OS Interface Open File Handle
1.240 +**
1.241 +** An [sqlite3_file] object represents an open file in the OS
1.242 +** interface layer. Individual OS interface implementations will
1.243 +** want to subclass this object by appending additional fields
1.244 +** for their own use. The pMethods entry is a pointer to an
1.245 +** [sqlite3_io_methods] object that defines methods for performing
1.246 +** I/O operations on the open file.
1.247 +*/
1.248 +typedef struct sqlite3_file sqlite3_file;
1.249 +struct sqlite3_file {
1.250 + const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
1.251 +};
1.252 +
1.253 +/*
1.254 +** CAPI3REF: OS Interface File Virtual Methods Object
1.255 +**
1.256 +** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to
1.257 +** an instance of the this object. This object defines the
1.258 +** methods used to perform various operations against the open file.
1.259 +**
1.260 +** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
1.261 +** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
1.262 +* The second choice is an
1.263 +** OS-X style fullsync. The SQLITE_SYNC_DATA flag may be ORed in to
1.264 +** indicate that only the data of the file and not its inode needs to be
1.265 +** synced.
1.266 +**
1.267 +** The integer values to xLock() and xUnlock() are one of
1.268 +** <ul>
1.269 +** <li> [SQLITE_LOCK_NONE],
1.270 +** <li> [SQLITE_LOCK_SHARED],
1.271 +** <li> [SQLITE_LOCK_RESERVED],
1.272 +** <li> [SQLITE_LOCK_PENDING], or
1.273 +** <li> [SQLITE_LOCK_EXCLUSIVE].
1.274 +** </ul>
1.275 +** xLock() increases the lock. xUnlock() decreases the lock.
1.276 +** The xCheckReservedLock() method looks
1.277 +** to see if any database connection, either in this
1.278 +** process or in some other process, is holding an RESERVED,
1.279 +** PENDING, or EXCLUSIVE lock on the file. It returns true
1.280 +** if such a lock exists and false if not.
1.281 +**
1.282 +** The xFileControl() method is a generic interface that allows custom
1.283 +** VFS implementations to directly control an open file using the
1.284 +** [sqlite3_file_control()] interface. The second "op" argument
1.285 +** is an integer opcode. The third
1.286 +** argument is a generic pointer which is intended to be a pointer
1.287 +** to a structure that may contain arguments or space in which to
1.288 +** write return values. Potential uses for xFileControl() might be
1.289 +** functions to enable blocking locks with timeouts, to change the
1.290 +** locking strategy (for example to use dot-file locks), to inquire
1.291 +** about the status of a lock, or to break stale locks. The SQLite
1.292 +** core reserves opcodes less than 100 for its own use.
1.293 +** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
1.294 +** Applications that define a custom xFileControl method should use opcodes
1.295 +** greater than 100 to avoid conflicts.
1.296 +**
1.297 +** The xSectorSize() method returns the sector size of the
1.298 +** device that underlies the file. The sector size is the
1.299 +** minimum write that can be performed without disturbing
1.300 +** other bytes in the file. The xDeviceCharacteristics()
1.301 +** method returns a bit vector describing behaviors of the
1.302 +** underlying device:
1.303 +**
1.304 +** <ul>
1.305 +** <li> [SQLITE_IOCAP_ATOMIC]
1.306 +** <li> [SQLITE_IOCAP_ATOMIC512]
1.307 +** <li> [SQLITE_IOCAP_ATOMIC1K]
1.308 +** <li> [SQLITE_IOCAP_ATOMIC2K]
1.309 +** <li> [SQLITE_IOCAP_ATOMIC4K]
1.310 +** <li> [SQLITE_IOCAP_ATOMIC8K]
1.311 +** <li> [SQLITE_IOCAP_ATOMIC16K]
1.312 +** <li> [SQLITE_IOCAP_ATOMIC32K]
1.313 +** <li> [SQLITE_IOCAP_ATOMIC64K]
1.314 +** <li> [SQLITE_IOCAP_SAFE_APPEND]
1.315 +** <li> [SQLITE_IOCAP_SEQUENTIAL]
1.316 +** </ul>
1.317 +**
1.318 +** The SQLITE_IOCAP_ATOMIC property means that all writes of
1.319 +** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
1.320 +** mean that writes of blocks that are nnn bytes in size and
1.321 +** are aligned to an address which is an integer multiple of
1.322 +** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
1.323 +** that when data is appended to a file, the data is appended
1.324 +** first then the size of the file is extended, never the other
1.325 +** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
1.326 +** information is written to disk in the same order as calls
1.327 +** to xWrite().
1.328 +*/
1.329 +typedef struct sqlite3_io_methods sqlite3_io_methods;
1.330 +struct sqlite3_io_methods {
1.331 + int iVersion;
1.332 + int (*xClose)(sqlite3_file*);
1.333 + int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
1.334 + int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
1.335 + int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
1.336 + int (*xSync)(sqlite3_file*, int flags);
1.337 + int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
1.338 + int (*xLock)(sqlite3_file*, int);
1.339 + int (*xUnlock)(sqlite3_file*, int);
1.340 + int (*xCheckReservedLock)(sqlite3_file*);
1.341 + int (*xFileControl)(sqlite3_file*, int op, void *pArg);
1.342 + int (*xSectorSize)(sqlite3_file*);
1.343 + int (*xDeviceCharacteristics)(sqlite3_file*);
1.344 + /* Additional methods may be added in future releases */
1.345 +};
1.346 +
1.347 +/*
1.348 +** CAPI3REF: Standard File Control Opcodes
1.349 +**
1.350 +** These integer constants are opcodes for the xFileControl method
1.351 +** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()]
1.352 +** interface.
1.353 +**
1.354 +** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
1.355 +** opcode cases the xFileControl method to write the current state of
1.356 +** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
1.357 +** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
1.358 +** into an integer that the pArg argument points to. This capability
1.359 +** is used during testing and only needs to be supported when SQLITE_TEST
1.360 +** is defined.
1.361 +*/
1.362 +#define SQLITE_FCNTL_LOCKSTATE 1
1.363 +
1.364 +/*
1.365 +** CAPI3REF: Mutex Handle
1.366 +**
1.367 +** The mutex module within SQLite defines [sqlite3_mutex] to be an
1.368 +** abstract type for a mutex object. The SQLite core never looks
1.369 +** at the internal representation of an [sqlite3_mutex]. It only
1.370 +** deals with pointers to the [sqlite3_mutex] object.
1.371 +**
1.372 +** Mutexes are created using [sqlite3_mutex_alloc()].
1.373 +*/
1.374 +typedef struct sqlite3_mutex sqlite3_mutex;
1.375 +
1.376 +/*
1.377 +** CAPI3REF: OS Interface Object
1.378 +**
1.379 +** An instance of this object defines the interface between the
1.380 +** SQLite core and the underlying operating system. The "vfs"
1.381 +** in the name of the object stands for "virtual file system".
1.382 +**
1.383 +** The iVersion field is initially 1 but may be larger for future
1.384 +** versions of SQLite. Additional fields may be appended to this
1.385 +** object when the iVersion value is increased.
1.386 +**
1.387 +** The szOsFile field is the size of the subclassed [sqlite3_file]
1.388 +** structure used by this VFS. mxPathname is the maximum length of
1.389 +** a pathname in this VFS.
1.390 +**
1.391 +** Registered vfs modules are kept on a linked list formed by
1.392 +** the pNext pointer. The [sqlite3_vfs_register()]
1.393 +** and [sqlite3_vfs_unregister()] interfaces manage this list
1.394 +** in a thread-safe way. The [sqlite3_vfs_find()] interface
1.395 +** searches the list.
1.396 +**
1.397 +** The pNext field is the only fields in the sqlite3_vfs
1.398 +** structure that SQLite will ever modify. SQLite will only access
1.399 +** or modify this field while holding a particular static mutex.
1.400 +** The application should never modify anything within the sqlite3_vfs
1.401 +** object once the object has been registered.
1.402 +**
1.403 +** The zName field holds the name of the VFS module. The name must
1.404 +** be unique across all VFS modules.
1.405 +**
1.406 +** SQLite will guarantee that the zFilename string passed to
1.407 +** xOpen() is a full pathname as generated by xFullPathname() and
1.408 +** that the string will be valid and unchanged until xClose() is
1.409 +** called. So the [sqlite3_file] can store a pointer to the
1.410 +** filename if it needs to remember the filename for some reason.
1.411 +**
1.412 +** The flags argument to xOpen() is a copy of the flags argument
1.413 +** to [sqlite3_open_v2()]. If [sqlite3_open()] or [sqlite3_open16()]
1.414 +** is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
1.415 +** If xOpen() opens a file read-only then it sets *pOutFlags to
1.416 +** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be
1.417 +** set.
1.418 +**
1.419 +** SQLite will also add one of the following flags to the xOpen()
1.420 +** call, depending on the object being opened:
1.421 +**
1.422 +** <ul>
1.423 +** <li> [SQLITE_OPEN_MAIN_DB]
1.424 +** <li> [SQLITE_OPEN_MAIN_JOURNAL]
1.425 +** <li> [SQLITE_OPEN_TEMP_DB]
1.426 +** <li> [SQLITE_OPEN_TEMP_JOURNAL]
1.427 +** <li> [SQLITE_OPEN_TRANSIENT_DB]
1.428 +** <li> [SQLITE_OPEN_SUBJOURNAL]
1.429 +** <li> [SQLITE_OPEN_MASTER_JOURNAL]
1.430 +** </ul>
1.431 +**
1.432 +** The file I/O implementation can use the object type flags to
1.433 +** changes the way it deals with files. For example, an application
1.434 +** that does not care about crash recovery or rollback, might make
1.435 +** the open of a journal file a no-op. Writes to this journal are
1.436 +** also a no-op. Any attempt to read the journal return SQLITE_IOERR.
1.437 +** Or the implementation might recognize the a database file will
1.438 +** be doing page-aligned sector reads and writes in a random order
1.439 +** and set up its I/O subsystem accordingly.
1.440 +**
1.441 +** SQLite might also add one of the following flags to the xOpen
1.442 +** method:
1.443 +**
1.444 +** <ul>
1.445 +** <li> [SQLITE_OPEN_DELETEONCLOSE]
1.446 +** <li> [SQLITE_OPEN_EXCLUSIVE]
1.447 +** </ul>
1.448 +**
1.449 +** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
1.450 +** deleted when it is closed. This will always be set for TEMP
1.451 +** databases and journals and for subjournals. The
1.452 +** [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
1.453 +** for exclusive access. This flag is set for all files except
1.454 +** for the main database file.
1.455 +**
1.456 +** Space to hold the [sqlite3_file] structure passed as the third
1.457 +** argument to xOpen is allocated by caller (the SQLite core).
1.458 +** szOsFile bytes are allocated for this object. The xOpen method
1.459 +** fills in the allocated space.
1.460 +**
1.461 +** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
1.462 +** to test for the existance of a file,
1.463 +** or [SQLITE_ACCESS_READWRITE] to test to see
1.464 +** if a file is readable and writable, or [SQLITE_ACCESS_READ]
1.465 +** to test to see if a file is at least readable. The file can be a
1.466 +** directory.
1.467 +**
1.468 +** SQLite will always allocate at least mxPathname+1 byte for
1.469 +** the output buffers for xGetTempname and xFullPathname. The exact
1.470 +** size of the output buffer is also passed as a parameter to both
1.471 +** methods. If the output buffer is not large enough, SQLITE_CANTOPEN
1.472 +** should be returned. As this is handled as a fatal error by SQLite,
1.473 +** vfs implementations should endevour to prevent this by setting
1.474 +** mxPathname to a sufficiently large value.
1.475 +**
1.476 +** The xRandomness(), xSleep(), and xCurrentTime() interfaces
1.477 +** are not strictly a part of the filesystem, but they are
1.478 +** included in the VFS structure for completeness.
1.479 +** The xRandomness() function attempts to return nBytes bytes
1.480 +** of good-quality randomness into zOut. The return value is
1.481 +** the actual number of bytes of randomness obtained. The
1.482 +** xSleep() method cause the calling thread to sleep for at
1.483 +** least the number of microseconds given. The xCurrentTime()
1.484 +** method returns a Julian Day Number for the current date and
1.485 +** time.
1.486 +*/
1.487 +typedef struct sqlite3_vfs sqlite3_vfs;
1.488 +struct sqlite3_vfs {
1.489 + int iVersion; /* Structure version number */
1.490 + int szOsFile; /* Size of subclassed sqlite3_file */
1.491 + int mxPathname; /* Maximum file pathname length */
1.492 + sqlite3_vfs *pNext; /* Next registered VFS */
1.493 + const char *zName; /* Name of this virtual file system */
1.494 + void *pAppData; /* Pointer to application-specific data */
1.495 + int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
1.496 + int flags, int *pOutFlags);
1.497 + int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
1.498 + int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
1.499 + int (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut);
1.500 + int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
1.501 + void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
1.502 + void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
1.503 + void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
1.504 + void (*xDlClose)(sqlite3_vfs*, void*);
1.505 + int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
1.506 + int (*xSleep)(sqlite3_vfs*, int microseconds);
1.507 + int (*xCurrentTime)(sqlite3_vfs*, double*);
1.508 + /* New fields may be appended in figure versions. The iVersion
1.509 + ** value will increment whenever this happens. */
1.510 +};
1.511 +
1.512 +/*
1.513 +** CAPI3REF: Flags for the xAccess VFS method
1.514 +**
1.515 +** These integer constants can be used as the third parameter to
1.516 +** the xAccess method of an [sqlite3_vfs] object. They determine
1.517 +** the kind of what kind of permissions the xAccess method is
1.518 +** looking for. With SQLITE_ACCESS_EXISTS, the xAccess method
1.519 +** simply checks to see if the file exists. With SQLITE_ACCESS_READWRITE,
1.520 +** the xAccess method checks to see if the file is both readable
1.521 +** and writable. With SQLITE_ACCESS_READ the xAccess method
1.522 +** checks to see if the file is readable.
1.523 +*/
1.524 +#define SQLITE_ACCESS_EXISTS 0
1.525 +#define SQLITE_ACCESS_READWRITE 1
1.526 +#define SQLITE_ACCESS_READ 2
1.527
1.528 /*
1.529 ** CAPI3REF: Enable Or Disable Extended Result Codes
1.530 @@ -341,8 +758,12 @@
1.531 ** is running. But once the trigger terminates, the value returned
1.532 ** by this routine reverts to the last value inserted before the
1.533 ** trigger fired.
1.534 +**
1.535 +** If another thread does a new insert on the same database connection
1.536 +** while this routine is running and thus changes the last insert rowid,
1.537 +** then the return value of this routine is undefined.
1.538 */
1.539 -sqlite_int64 sqlite3_last_insert_rowid(sqlite3*);
1.540 +sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
1.541
1.542 /*
1.543 ** CAPI3REF: Count The Number Of Rows Modified
1.544 @@ -374,6 +795,10 @@
1.545 ** zero regardless of the number of elements that were originally in the
1.546 ** table. To get an accurate count of the number of rows deleted, use
1.547 ** "DELETE FROM table WHERE 1" instead.
1.548 +**
1.549 +** If another thread makes changes on the same database connection
1.550 +** while this routine is running then the return value of this routine
1.551 +** is undefined.
1.552 */
1.553 int sqlite3_changes(sqlite3*);
1.554
1.555 @@ -385,7 +810,7 @@
1.556 ** was opened. This includes UPDATE, INSERT and DELETE statements executed
1.557 ** as part of trigger programs. All changes are counted as soon as the
1.558 ** statement that makes them is completed (when the statement handle is
1.559 -** passed to [sqlite3_reset()] or [sqlite_finalise()]).
1.560 +** passed to [sqlite3_reset()] or [sqlite3_finalize()]).
1.561 **
1.562 ** See also the [sqlite3_change()] interface.
1.563 **
1.564 @@ -396,6 +821,10 @@
1.565 ** zero regardless of the number of elements that were originally in the
1.566 ** table. To get an accurate count of the number of rows deleted, use
1.567 ** "DELETE FROM table WHERE 1" instead.
1.568 +**
1.569 +** If another thread makes changes on the same database connection
1.570 +** while this routine is running then the return value of this routine
1.571 +** is undefined.
1.572 */
1.573 int sqlite3_total_changes(sqlite3*);
1.574
1.575 @@ -409,7 +838,9 @@
1.576 ** immediately.
1.577 **
1.578 ** It is safe to call this routine from a thread different from the
1.579 -** thread that is currently running the database operation.
1.580 +** thread that is currently running the database operation. But it
1.581 +** is not safe to call this routine with a database connection that
1.582 +** is closed or might close before sqlite3_interrupt() returns.
1.583 **
1.584 ** The SQL operation that is interrupted will return [SQLITE_INTERRUPT].
1.585 ** If an interrupted operation was an update that is inside an
1.586 @@ -502,6 +933,13 @@
1.587 ** connection. Setting a new busy handler clears any previous one.
1.588 ** Note that calling [sqlite3_busy_timeout()] will also set or clear
1.589 ** the busy handler.
1.590 +**
1.591 +** When operating in [sqlite3_enable_shared_cache | shared cache mode],
1.592 +** only a single busy handler can be defined for each database file.
1.593 +** So if two database connections share a single cache, then changing
1.594 +** the busy handler on one connection will also change the busy
1.595 +** handler in the other connection. The busy handler is invoked
1.596 +** in the thread that was running when the SQLITE_BUSY was hit.
1.597 */
1.598 int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
1.599
1.600 @@ -535,27 +973,27 @@
1.601 **
1.602 ** As an example, suppose the query result where this table:
1.603 **
1.604 -** <pre>
1.605 +** <blockquote><pre>
1.606 ** Name | Age
1.607 ** -----------------------
1.608 ** Alice | 43
1.609 ** Bob | 28
1.610 ** Cindy | 21
1.611 -** </pre>
1.612 +** </pre></blockquote>
1.613 **
1.614 ** If the 3rd argument were &azResult then after the function returns
1.615 ** azResult will contain the following data:
1.616 **
1.617 -** <pre>
1.618 -** azResult[0] = "Name";
1.619 -** azResult[1] = "Age";
1.620 -** azResult[2] = "Alice";
1.621 -** azResult[3] = "43";
1.622 -** azResult[4] = "Bob";
1.623 -** azResult[5] = "28";
1.624 -** azResult[6] = "Cindy";
1.625 -** azResult[7] = "21";
1.626 -** </pre>
1.627 +** <blockquote><pre>
1.628 +** azResult[0] = "Name";
1.629 +** azResult[1] = "Age";
1.630 +** azResult[2] = "Alice";
1.631 +** azResult[3] = "43";
1.632 +** azResult[4] = "Bob";
1.633 +** azResult[5] = "28";
1.634 +** azResult[6] = "Cindy";
1.635 +** azResult[7] = "21";
1.636 +** </pre></blockquote>
1.637 **
1.638 ** Notice that there is an extra row of data containing the column
1.639 ** headers. But the *nrow return value is still 3. *ncolumn is
1.640 @@ -588,7 +1026,7 @@
1.641 ** from the standard C library.
1.642 **
1.643 ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
1.644 -** results into memory obtained from [sqlite_malloc()].
1.645 +** results into memory obtained from [sqlite3_malloc()].
1.646 ** The strings returned by these two routines should be
1.647 ** released by [sqlite3_free()]. Both routines return a
1.648 ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
1.649 @@ -616,7 +1054,7 @@
1.650 ** These routines all implement some additional formatting
1.651 ** options that are useful for constructing SQL statements.
1.652 ** All of the usual printf formatting options apply. In addition, there
1.653 -** is are "%q" and "%Q" options.
1.654 +** is are "%q", "%Q", and "%z" options.
1.655 **
1.656 ** The %q option works like %s in that it substitutes a null-terminated
1.657 ** string from the argument list. But %q also doubles every '\'' character.
1.658 @@ -669,25 +1107,119 @@
1.659 **
1.660 ** The code above will render a correct SQL statement in the zSQL
1.661 ** variable even if the zText variable is a NULL pointer.
1.662 +**
1.663 +** The "%z" formatting option works exactly like "%s" with the
1.664 +** addition that after the string has been read and copied into
1.665 +** the result, [sqlite3_free()] is called on the input string.
1.666 */
1.667 char *sqlite3_mprintf(const char*,...);
1.668 char *sqlite3_vmprintf(const char*, va_list);
1.669 char *sqlite3_snprintf(int,char*,const char*, ...);
1.670
1.671 /*
1.672 -** CAPI3REF: Memory Allocation Functions
1.673 -**
1.674 -** SQLite uses its own memory allocator. On some installations, this
1.675 -** memory allocator is identical to the standard malloc()/realloc()/free()
1.676 -** and can be used interchangable. On others, the implementations are
1.677 -** different. For maximum portability, it is best not to mix calls
1.678 -** to the standard malloc/realloc/free with the sqlite versions.
1.679 +** CAPI3REF: Memory Allocation Subsystem
1.680 +**
1.681 +** The SQLite core uses these three routines for all of its own
1.682 +** internal memory allocation needs. (See the exception below.)
1.683 +** The default implementation
1.684 +** of the memory allocation subsystem uses the malloc(), realloc()
1.685 +** and free() provided by the standard C library. However, if
1.686 +** SQLite is compiled with the following C preprocessor macro
1.687 +**
1.688 +** <blockquote> SQLITE_OMIT_MEMORY_ALLOCATION </blockquote>
1.689 +**
1.690 +** then no implementation is provided for these routines by
1.691 +** SQLite. The application that links against SQLite is
1.692 +** expected to provide its own implementation. If the application
1.693 +** does provide its own implementation for these routines, then
1.694 +** it must also provide an implementations for
1.695 +** [sqlite3_memory_alarm()], [sqlite3_memory_used()], and
1.696 +** [sqlite3_memory_highwater()]. The alternative implementations
1.697 +** for these last three routines need not actually work, but
1.698 +** stub functions at least are needed to statisfy the linker.
1.699 +** SQLite never calls [sqlite3_memory_highwater()] itself, but
1.700 +** the symbol is included in a table as part of the
1.701 +** [sqlite3_load_extension()] interface. The
1.702 +** [sqlite3_memory_alarm()] and [sqlite3_memory_used()] interfaces
1.703 +** are called by [sqlite3_soft_heap_limit()] and working implementations
1.704 +** of both routines must be provided if [sqlite3_soft_heap_limit()]
1.705 +** is to operate correctly.
1.706 +**
1.707 +** <b>Exception:</b> The windows OS interface layer calls
1.708 +** the system malloc() and free() directly when converting
1.709 +** filenames between the UTF-8 encoding used by SQLite
1.710 +** and whatever filename encoding is used by the particular windows
1.711 +** installation. Memory allocation errors are detected, but
1.712 +** they are reported back as [SQLITE_CANTOPEN] or
1.713 +** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
1.714 */
1.715 void *sqlite3_malloc(int);
1.716 void *sqlite3_realloc(void*, int);
1.717 void sqlite3_free(void*);
1.718
1.719 /*
1.720 +** CAPI3REF: Memory Allocator Statistics
1.721 +**
1.722 +** In addition to the basic three allocation routines
1.723 +** [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()],
1.724 +** the memory allocation subsystem included with the SQLite
1.725 +** sources provides the interfaces shown below.
1.726 +**
1.727 +** The first of these two routines returns the amount of memory
1.728 +** currently outstanding (malloced but not freed). The second
1.729 +** returns the largest instantaneous amount of outstanding
1.730 +** memory. The highwater mark is reset if the argument is
1.731 +** true.
1.732 +**
1.733 +** The implementation of these routines in the SQLite core
1.734 +** is omitted if the application is compiled with the
1.735 +** SQLITE_OMIT_MEMORY_ALLOCATION macro defined. In that case,
1.736 +** the application that links SQLite must provide its own
1.737 +** alternative implementation. See the documentation on
1.738 +** [sqlite3_malloc()] for additional information.
1.739 +*/
1.740 +sqlite3_int64 sqlite3_memory_used(void);
1.741 +sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
1.742 +
1.743 +/*
1.744 +** CAPI3REF: Memory Allocation Alarms
1.745 +**
1.746 +** The [sqlite3_memory_alarm] routine is used to register
1.747 +** a callback on memory allocation events.
1.748 +**
1.749 +** This routine registers or clears a callbacks that fires when
1.750 +** the amount of memory allocated exceeds iThreshold. Only
1.751 +** a single callback can be registered at a time. Each call
1.752 +** to [sqlite3_memory_alarm()] overwrites the previous callback.
1.753 +** The callback is disabled by setting xCallback to a NULL
1.754 +** pointer.
1.755 +**
1.756 +** The parameters to the callback are the pArg value, the
1.757 +** amount of memory currently in use, and the size of the
1.758 +** allocation that provoked the callback. The callback will
1.759 +** presumably invoke [sqlite3_free()] to free up memory space.
1.760 +** The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()]
1.761 +** but if it does, no additional callbacks will be invoked by
1.762 +** the recursive calls.
1.763 +**
1.764 +** The [sqlite3_soft_heap_limit()] interface works by registering
1.765 +** a memory alarm at the soft heap limit and invoking
1.766 +** [sqlite3_release_memory()] in the alarm callback. Application
1.767 +** programs should not attempt to use the [sqlite3_memory_alarm()]
1.768 +** interface because doing so will interfere with the
1.769 +** [sqlite3_soft_heap_limit()] module. This interface is exposed
1.770 +** only so that applications can provide their own
1.771 +** alternative implementation when the SQLite core is
1.772 +** compiled with SQLITE_OMIT_MEMORY_ALLOCATION.
1.773 +*/
1.774 +int sqlite3_memory_alarm(
1.775 + void(*xCallback)(void *pArg, sqlite3_int64 used, int N),
1.776 + void *pArg,
1.777 + sqlite3_int64 iThreshold
1.778 +);
1.779 +
1.780 +
1.781 +/*
1.782 ** CAPI3REF: Compile-Time Authorization Callbacks
1.783 ***
1.784 ** This routine registers a authorizer callback with the SQLite library.
1.785 @@ -827,7 +1359,7 @@
1.786 */
1.787 void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
1.788 void *sqlite3_profile(sqlite3*,
1.789 - void(*xProfile)(void*,const char*,sqlite_uint64), void*);
1.790 + void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
1.791
1.792 /*
1.793 ** CAPI3REF: Query Progress Callbacks
1.794 @@ -866,25 +1398,65 @@
1.795 ** CAPI3REF: Opening A New Database Connection
1.796 **
1.797 ** Open the sqlite database file "filename". The "filename" is UTF-8
1.798 -** encoded for sqlite3_open() and UTF-16 encoded in the native byte order
1.799 -** for sqlite3_open16(). An [sqlite3*] handle is returned in *ppDb, even
1.800 +** encoded for [sqlite3_open()] and [sqlite3_open_v2()] and UTF-16 encoded
1.801 +** in the native byte order for [sqlite3_open16()].
1.802 +** An [sqlite3*] handle is returned in *ppDb, even
1.803 ** if an error occurs. If the database is opened (or created) successfully,
1.804 -** then SQLITE_OK is returned. Otherwise an error code is returned. The
1.805 -** sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain
1.806 +** then [SQLITE_OK] is returned. Otherwise an error code is returned. The
1.807 +** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
1.808 ** an English language description of the error.
1.809 **
1.810 -** If the database file does not exist, then a new database will be created
1.811 -** as needed. The default encoding for the database will be UTF-8 if
1.812 -** sqlite3_open() is called and UTF-16 if sqlite3_open16 is used.
1.813 +** The default encoding for the database will be UTF-8 if
1.814 +** [sqlite3_open()] or [sqlite3_open_v2()] is called and
1.815 +** UTF-16 if [sqlite3_open16()] is used.
1.816 **
1.817 ** Whether or not an error occurs when it is opened, resources associated
1.818 ** with the [sqlite3*] handle should be released by passing it to
1.819 -** sqlite3_close() when it is no longer required.
1.820 -**
1.821 -** Note to windows users: The encoding used for the filename argument
1.822 -** of sqlite3_open() must be UTF-8, not whatever codepage is currently
1.823 -** defined. Filenames containing international characters must be converted
1.824 -** to UTF-8 prior to passing them into sqlite3_open().
1.825 +** [sqlite3_close()] when it is no longer required.
1.826 +**
1.827 +** The [sqlite3_open_v2()] interface works like [sqlite3_open()] except that
1.828 +** provides two additional parameters for additional control over the
1.829 +** new database connection. The flags parameter can be one of:
1.830 +**
1.831 +** <ol>
1.832 +** <li> [SQLITE_OPEN_READONLY]
1.833 +** <li> [SQLITE_OPEN_READWRITE]
1.834 +** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]
1.835 +** </ol>
1.836 +**
1.837 +** The first value opens the database read-only. If the database does
1.838 +** not previously exist, an error is returned. The second option opens
1.839 +** the database for reading and writing if possible, or reading only if
1.840 +** if the file is write protected. In either case the database must already
1.841 +** exist or an error is returned. The third option opens the database
1.842 +** for reading and writing and creates it if it does not already exist.
1.843 +** The third options is behavior that is always used for [sqlite3_open()]
1.844 +** and [sqlite3_open16()].
1.845 +**
1.846 +** If the filename is ":memory:", then an private
1.847 +** in-memory database is created for the connection. This in-memory
1.848 +** database will vanish when the database connection is closed. Future
1.849 +** version of SQLite might make use of additional special filenames
1.850 +** that begin with the ":" character. It is recommended that
1.851 +** when a database filename really does begin with
1.852 +** ":" that you prefix the filename with a pathname like "./" to
1.853 +** avoid ambiguity.
1.854 +**
1.855 +** If the filename is an empty string, then a private temporary
1.856 +** on-disk database will be created. This private database will be
1.857 +** automatically deleted as soon as the database connection is closed.
1.858 +**
1.859 +** The fourth parameter to sqlite3_open_v2() is the name of the
1.860 +** [sqlite3_vfs] object that defines the operating system
1.861 +** interface that the new database connection should use. If the
1.862 +** fourth parameter is a NULL pointer then the default [sqlite3_vfs]
1.863 +** object is used.
1.864 +**
1.865 +** <b>Note to windows users:</b> The encoding used for the filename argument
1.866 +** of [sqlite3_open()] and [sqlite3_open_v2()] must be UTF-8, not whatever
1.867 +** codepage is currently defined. Filenames containing international
1.868 +** characters must be converted to UTF-8 prior to passing them into
1.869 +** [sqlite3_open()] or [sqlite3_open_v2()].
1.870 */
1.871 int sqlite3_open(
1.872 const char *filename, /* Database filename (UTF-8) */
1.873 @@ -894,6 +1466,12 @@
1.874 const void *filename, /* Database filename (UTF-16) */
1.875 sqlite3 **ppDb /* OUT: SQLite db handle */
1.876 );
1.877 +int sqlite3_open_v2(
1.878 + const char *filename, /* Database filename (UTF-8) */
1.879 + sqlite3 **ppDb, /* OUT: SQLite db handle */
1.880 + int flags, /* Flags */
1.881 + const char *zVfs /* Name of VFS module to use */
1.882 +);
1.883
1.884 /*
1.885 ** CAPI3REF: Error Codes And Messages
1.886 @@ -905,7 +1483,7 @@
1.887 ** most recent API call succeeded, the return value from sqlite3_errcode()
1.888 ** is undefined.
1.889 **
1.890 -** The sqlite3_errmsg() and sqlite3_errmsg16() return English-langauge
1.891 +** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
1.892 ** text that describes the error, as either UTF8 or UTF16 respectively.
1.893 ** Memory to hold the error message string is managed internally. The
1.894 ** string may be overwritten or deallocated by subsequent calls to SQLite
1.895 @@ -916,8 +1494,11 @@
1.896 ** (overwriting the previous values). Note that calls to [sqlite3_errcode()],
1.897 ** [sqlite3_errmsg()], and [sqlite3_errmsg16()] themselves do not affect the
1.898 ** results of future invocations. Calls to API routines that do not return
1.899 -** an error code (examples: [sqlite3_data_count()] or [sqlite3_mprintf()]) do
1.900 -** not change the error code returned by this routine.
1.901 +** an error code (example: [sqlite3_data_count()]) do not
1.902 +** change the error code returned by this routine. Interfaces that are
1.903 +** not associated with a specific database connection (examples:
1.904 +** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()] do not change
1.905 +** the return code.
1.906 **
1.907 ** Assuming no other intervening sqlite3_* API calls are made, the error
1.908 ** code returned by this function is associated with the same error as
1.909 @@ -959,7 +1540,8 @@
1.910 ** program using one of these routines.
1.911 **
1.912 ** The first argument "db" is an [sqlite3 | SQLite database handle]
1.913 -** obtained from a prior call to [sqlite3_open()] or [sqlite3_open16()].
1.914 +** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()]
1.915 +** or [sqlite3_open16()].
1.916 ** The second argument "zSql" is the statement to be compiled, encoded
1.917 ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()
1.918 ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2()
1.919 @@ -1127,7 +1709,8 @@
1.920 ** (just an integer to hold it size) while it is being processed.
1.921 ** Zeroblobs are intended to serve as place-holders for BLOBs whose
1.922 ** content is later written using
1.923 -** [sqlite3_blob_open | increment BLOB I/O] routines.
1.924 +** [sqlite3_blob_open | increment BLOB I/O] routines. A negative
1.925 +** value for the zeroblob results in a zero-length BLOB.
1.926 **
1.927 ** The sqlite3_bind_*() routines must be called after
1.928 ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
1.929 @@ -1144,7 +1727,7 @@
1.930 int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
1.931 int sqlite3_bind_double(sqlite3_stmt*, int, double);
1.932 int sqlite3_bind_int(sqlite3_stmt*, int, int);
1.933 -int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite_int64);
1.934 +int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
1.935 int sqlite3_bind_null(sqlite3_stmt*, int);
1.936 int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
1.937 int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
1.938 @@ -1164,6 +1747,10 @@
1.939 ** are used (where NNN is an integer) then there might be gaps in the
1.940 ** numbering and the value returned by this interface is the index of the
1.941 ** host parameter with the largest index value.
1.942 +**
1.943 +** The prepared statement must not be [sqlite3_finalize | finalized]
1.944 +** prior to this routine returnning. Otherwise the results are undefined
1.945 +** and probably undesirable.
1.946 */
1.947 int sqlite3_bind_parameter_count(sqlite3_stmt*);
1.948
1.949 @@ -1223,14 +1810,18 @@
1.950 ** in the result set of a SELECT statement. The sqlite3_column_name()
1.951 ** interface returns a pointer to a UTF8 string and sqlite3_column_name16()
1.952 ** returns a pointer to a UTF16 string. The first parameter is the
1.953 -** [sqlite_stmt | prepared statement] that implements the SELECT statement.
1.954 +** [sqlite3_stmt | prepared statement] that implements the SELECT statement.
1.955 ** The second parameter is the column number. The left-most column is
1.956 ** number 0.
1.957 **
1.958 ** The returned string pointer is valid until either the
1.959 -** [sqlite_stmt | prepared statement] is destroyed by [sqlite3_finalize()]
1.960 +** [sqlite3_stmt | prepared statement] is destroyed by [sqlite3_finalize()]
1.961 ** or until the next call sqlite3_column_name() or sqlite3_column_name16()
1.962 ** on the same column.
1.963 +**
1.964 +** If sqlite3_malloc() fails during the processing of either routine
1.965 +** (for example during a conversion from UTF-8 to UTF-16) then a
1.966 +** NULL pointer is returned.
1.967 */
1.968 const char *sqlite3_column_name(sqlite3_stmt*, int N);
1.969 const void *sqlite3_column_name16(sqlite3_stmt*, int N);
1.970 @@ -1268,6 +1859,10 @@
1.971 **
1.972 ** These APIs are only available if the library was compiled with the
1.973 ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
1.974 +**
1.975 +** If two or more threads call one or more of these routines against the same
1.976 +** prepared statement and column at the same time then the results are
1.977 +** undefined.
1.978 */
1.979 const char *sqlite3_column_database_name(sqlite3_stmt*,int);
1.980 const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
1.981 @@ -1354,11 +1949,11 @@
1.982 ** With the legacy interface, a more specific error code (example:
1.983 ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
1.984 ** can be obtained by calling [sqlite3_reset()] on the
1.985 -** [sqlite_stmt | prepared statement]. In the "v2" interface,
1.986 +** [sqlite3_stmt | prepared statement]. In the "v2" interface,
1.987 ** the more specific error code is returned directly by sqlite3_step().
1.988 **
1.989 ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
1.990 -** Perhaps it was called on a [sqlite_stmt | prepared statement] that has
1.991 +** Perhaps it was called on a [sqlite3_stmt | prepared statement] that has
1.992 ** already been [sqlite3_finalize | finalized] or on one that had
1.993 ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
1.994 ** be the case that the same database connection is being used by two or
1.995 @@ -1389,7 +1984,7 @@
1.996 ** will return the same value as the [sqlite3_column_count()] function.
1.997 ** After [sqlite3_step()] has returned an [SQLITE_DONE], [SQLITE_BUSY], or
1.998 ** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been
1.999 -** called on the [sqlite_stmt | prepared statement] for the first time,
1.1000 +** called on the [sqlite3_stmt | prepared statement] for the first time,
1.1001 ** this routine returns zero.
1.1002 */
1.1003 int sqlite3_data_count(sqlite3_stmt *pStmt);
1.1004 @@ -1428,17 +2023,27 @@
1.1005 /*
1.1006 ** CAPI3REF: Results Values From A Query
1.1007 **
1.1008 -** These routines return information about the information
1.1009 -** in a single column of the current result row of a query. In every
1.1010 +** These routines return information about
1.1011 +** a single column of the current result row of a query. In every
1.1012 ** case the first argument is a pointer to the
1.1013 ** [sqlite3_stmt | SQL statement] that is being
1.1014 -** evaluate (the [sqlite_stmt*] that was returned from
1.1015 +** evaluated (the [sqlite3_stmt*] that was returned from
1.1016 ** [sqlite3_prepare_v2()] or one of its variants) and
1.1017 ** the second argument is the index of the column for which information
1.1018 -** should be returned. The left-most column has an index of 0.
1.1019 +** should be returned. The left-most column of the result set
1.1020 +** has an index of 0.
1.1021 **
1.1022 ** If the SQL statement is not currently point to a valid row, or if the
1.1023 -** the column index is out of range, the result is undefined.
1.1024 +** the column index is out of range, the result is undefined.
1.1025 +** These routines may only be called when the most recent call to
1.1026 +** [sqlite3_step()] has returned [SQLITE_ROW] and neither
1.1027 +** [sqlite3_reset()] nor [sqlite3_finalize()] has been call subsequently.
1.1028 +** If any of these routines are called after [sqlite3_reset()] or
1.1029 +** [sqlite3_finalize()] or after [sqlite3_step()] has returned
1.1030 +** something other than [SQLITE_ROW], the results are undefined.
1.1031 +** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
1.1032 +** are called from a different thread while any of these routines
1.1033 +** are pending, then the results are undefined.
1.1034 **
1.1035 ** The sqlite3_column_type() routine returns
1.1036 ** [SQLITE_INTEGER | datatype code] for the initial data type
1.1037 @@ -1461,6 +2066,11 @@
1.1038 ** of the string. For clarity: the value returned is the number of
1.1039 ** bytes in the string, not the number of characters.
1.1040 **
1.1041 +** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
1.1042 +** even zero-length strings, are always zero terminated. The return
1.1043 +** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
1.1044 +** pointer, possibly even a NULL pointer.
1.1045 +**
1.1046 ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
1.1047 ** but leaves the result in UTF-16 instead of UTF-8.
1.1048 ** The zero terminator is not included in this count.
1.1049 @@ -1473,8 +2083,7 @@
1.1050 **
1.1051 ** <blockquote>
1.1052 ** <table border="1">
1.1053 -** <tr><th> Internal <th> Requested <th>
1.1054 -** <tr><th> Type <th> Type <th> Conversion
1.1055 +** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion
1.1056 **
1.1057 ** <tr><td> NULL <td> INTEGER <td> Result is 0
1.1058 ** <tr><td> NULL <td> FLOAT <td> Result is 0.0
1.1059 @@ -1542,13 +2151,26 @@
1.1060 ** find the size of the result. Do not mix call to sqlite3_column_text() or
1.1061 ** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not
1.1062 ** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
1.1063 +**
1.1064 +** The pointers returned are valid until a type conversion occurs as
1.1065 +** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
1.1066 +** [sqlite3_finalize()] is called. The memory space used to hold strings
1.1067 +** and blobs is freed automatically. Do <b>not</b> pass the pointers returned
1.1068 +** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
1.1069 +** [sqlite3_free()].
1.1070 +**
1.1071 +** If a memory allocation error occurs during the evaluation of any
1.1072 +** of these routines, a default value is returned. The default value
1.1073 +** is either the integer 0, the floating point number 0.0, or a NULL
1.1074 +** pointer. Subsequent calls to [sqlite3_errcode()] will return
1.1075 +** [SQLITE_NOMEM].
1.1076 */
1.1077 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
1.1078 int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
1.1079 int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
1.1080 double sqlite3_column_double(sqlite3_stmt*, int iCol);
1.1081 int sqlite3_column_int(sqlite3_stmt*, int iCol);
1.1082 -sqlite_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
1.1083 +sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
1.1084 const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
1.1085 const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
1.1086 int sqlite3_column_type(sqlite3_stmt*, int iCol);
1.1087 @@ -1578,7 +2200,7 @@
1.1088 ** CAPI3REF: Reset A Prepared Statement Object
1.1089 **
1.1090 ** The sqlite3_reset() function is called to reset a
1.1091 -** [sqlite_stmt | compiled SQL statement] object.
1.1092 +** [sqlite3_stmt | compiled SQL statement] object.
1.1093 ** back to it's initial state, ready to be re-executed.
1.1094 ** Any SQL statement variables that had values bound to them using
1.1095 ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
1.1096 @@ -1617,7 +2239,7 @@
1.1097 ** its parameters. Any SQL function implementation should be able to work
1.1098 ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
1.1099 ** more efficient with one encoding than another. It is allowed to
1.1100 -** invoke sqlite_create_function() or sqlite3_create_function16() multiple
1.1101 +** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
1.1102 ** times with the same function but with different values of eTextRep.
1.1103 ** When multiple implementations of the same function are available, SQLite
1.1104 ** will pick the one that involves the least amount of data conversion.
1.1105 @@ -1627,7 +2249,7 @@
1.1106 **
1.1107 ** The fifth parameter is an arbitrary pointer. The implementation
1.1108 ** of the function can gain access to this pointer using
1.1109 -** [sqlite_user_data()].
1.1110 +** [sqlite3_user_data()].
1.1111 **
1.1112 ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
1.1113 ** pointers to C-language functions that implement the SQL
1.1114 @@ -1691,7 +2313,7 @@
1.1115 int sqlite3_expired(sqlite3_stmt*);
1.1116 int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
1.1117 int sqlite3_global_recover(void);
1.1118 -
1.1119 +void sqlite3_thread_cleanup(void);
1.1120
1.1121 /*
1.1122 ** CAPI3REF: Obtaining SQL Function Parameter Values
1.1123 @@ -1729,15 +2351,21 @@
1.1124 ** Please pay particular attention to the fact that the pointer that
1.1125 ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or
1.1126 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
1.1127 -** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite_value_text()],
1.1128 +** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
1.1129 ** or [sqlite3_value_text16()].
1.1130 +**
1.1131 +** These routines must be called from the same thread as
1.1132 +** the SQL function that supplied the sqlite3_value* parameters.
1.1133 +** Or, if the sqlite3_value* argument comes from the [sqlite3_column_value()]
1.1134 +** interface, then these routines should be called from the same thread
1.1135 +** that ran [sqlite3_column_value()].
1.1136 */
1.1137 const void *sqlite3_value_blob(sqlite3_value*);
1.1138 int sqlite3_value_bytes(sqlite3_value*);
1.1139 int sqlite3_value_bytes16(sqlite3_value*);
1.1140 double sqlite3_value_double(sqlite3_value*);
1.1141 int sqlite3_value_int(sqlite3_value*);
1.1142 -sqlite_int64 sqlite3_value_int64(sqlite3_value*);
1.1143 +sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
1.1144 const unsigned char *sqlite3_value_text(sqlite3_value*);
1.1145 const void *sqlite3_value_text16(sqlite3_value*);
1.1146 const void *sqlite3_value_text16le(sqlite3_value*);
1.1147 @@ -1762,6 +2390,9 @@
1.1148 ** [sqlite3_context | SQL function context] that is the first
1.1149 ** parameter to the callback routine that implements the aggregate
1.1150 ** function.
1.1151 +**
1.1152 +** This routine must be called from the same thread in which
1.1153 +** the aggregate SQL function is running.
1.1154 */
1.1155 void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
1.1156
1.1157 @@ -1772,6 +2403,9 @@
1.1158 ** and [sqlite3_create_function16()] routines
1.1159 ** used to register user functions is available to
1.1160 ** the implementation of the function using this call.
1.1161 +**
1.1162 +** This routine must be called from the same thread in which
1.1163 +** the SQL function is running.
1.1164 */
1.1165 void *sqlite3_user_data(sqlite3_context*);
1.1166
1.1167 @@ -1804,6 +2438,9 @@
1.1168 ** In practice, meta-data is preserved between function calls for
1.1169 ** expressions that are constant at compile time. This includes literal
1.1170 ** values and SQL variables.
1.1171 +**
1.1172 +** These routines must be called from the same thread in which
1.1173 +** the SQL function is running.
1.1174 */
1.1175 void *sqlite3_get_auxdata(sqlite3_context*, int);
1.1176 void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
1.1177 @@ -1850,14 +2487,18 @@
1.1178 ** The sqlite3_result_toobig() cause the function implementation
1.1179 ** to throw and error indicating that a string or BLOB is to long
1.1180 ** to represent.
1.1181 +**
1.1182 +** These routines must be called from within the same thread as
1.1183 +** the SQL function associated with the [sqlite3_context] pointer.
1.1184 */
1.1185 void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
1.1186 void sqlite3_result_double(sqlite3_context*, double);
1.1187 void sqlite3_result_error(sqlite3_context*, const char*, int);
1.1188 void sqlite3_result_error16(sqlite3_context*, const void*, int);
1.1189 void sqlite3_result_error_toobig(sqlite3_context*);
1.1190 +void sqlite3_result_error_nomem(sqlite3_context*);
1.1191 void sqlite3_result_int(sqlite3_context*, int);
1.1192 -void sqlite3_result_int64(sqlite3_context*, sqlite_int64);
1.1193 +void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
1.1194 void sqlite3_result_null(sqlite3_context*);
1.1195 void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
1.1196 void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
1.1197 @@ -2003,6 +2644,9 @@
1.1198 ** millisecond time resolution, then the time will be rounded up to
1.1199 ** the nearest second. The number of milliseconds of sleep actually
1.1200 ** requested from the operating system is returned.
1.1201 +**
1.1202 +** SQLite implements this interface by calling the xSleep()
1.1203 +** method of the default [sqlite3_vfs] object.
1.1204 */
1.1205 int sqlite3_sleep(int);
1.1206
1.1207 @@ -2015,20 +2659,31 @@
1.1208 ** is NULL pointer, then SQLite does a search for an appropriate temporary
1.1209 ** file directory.
1.1210 **
1.1211 -** Once [sqlite3_open()] has been called, changing this variable will
1.1212 -** invalidate the current temporary database, if any. Generally speaking,
1.1213 -** it is not safe to invoke this routine after [sqlite3_open()] has
1.1214 -** been called.
1.1215 +** It is not safe to modify this variable once a database connection
1.1216 +** has been opened. It is intended that this variable be set once
1.1217 +** as part of process initialization and before any SQLite interface
1.1218 +** routines have been call and remain unchanged thereafter.
1.1219 */
1.1220 -extern char *sqlite3_temp_directory;
1.1221 +SQLITE_EXTERN char *sqlite3_temp_directory;
1.1222
1.1223 /*
1.1224 -** CAPI3REF: Test To See If The Databse Is In Auto-Commit Mode
1.1225 +** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode
1.1226 **
1.1227 ** Test to see whether or not the database connection is in autocommit
1.1228 ** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on
1.1229 ** by default. Autocommit is disabled by a BEGIN statement and reenabled
1.1230 ** by the next COMMIT or ROLLBACK.
1.1231 +**
1.1232 +** If certain kinds of errors occur on a statement within a multi-statement
1.1233 +** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR],
1.1234 +** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
1.1235 +** transaction might be rolled back automatically. The only way to
1.1236 +** find out if SQLite automatically rolled back the transaction after
1.1237 +** an error is to use this function.
1.1238 +**
1.1239 +** If another thread changes the autocommit status of the database
1.1240 +** connection while this routine is running, then the return value
1.1241 +** is undefined.
1.1242 */
1.1243 int sqlite3_get_autocommit(sqlite3*);
1.1244
1.1245 @@ -2095,7 +2750,7 @@
1.1246 */
1.1247 void *sqlite3_update_hook(
1.1248 sqlite3*,
1.1249 - void(*)(void *,int ,char const *,char const *,sqlite_int64),
1.1250 + void(*)(void *,int ,char const *,char const *,sqlite3_int64),
1.1251 void*
1.1252 );
1.1253
1.1254 @@ -2107,38 +2762,26 @@
1.1255 ** Sharing is enabled if the argument is true and disabled if the argument
1.1256 ** is false.
1.1257 **
1.1258 -** Cache sharing is enabled and disabled on a thread-by-thread basis.
1.1259 -** Each call to this routine enables or disables cache sharing only for
1.1260 -** connections created in the same thread in which this routine is called.
1.1261 -** There is no mechanism for sharing cache between database connections
1.1262 -** running in different threads.
1.1263 -**
1.1264 -** Sharing must be disabled prior to shutting down a thread or else
1.1265 -** the thread will leak memory. Call this routine with an argument of
1.1266 -** 0 to turn off sharing. Or use the sqlite3_thread_cleanup() API.
1.1267 -**
1.1268 -** This routine must not be called when any database connections
1.1269 -** are active in the current thread. Enabling or disabling shared
1.1270 -** cache while there are active database connections will result
1.1271 -** in memory corruption.
1.1272 -**
1.1273 -** When the shared cache is enabled, the
1.1274 -** following routines must always be called from the same thread:
1.1275 -** [sqlite3_open()], [sqlite3_prepare_v2()], [sqlite3_step()],
1.1276 -** [sqlite3_reset()], [sqlite3_finalize()], and [sqlite3_close()].
1.1277 -** This is due to the fact that the shared cache makes use of
1.1278 -** thread-specific storage so that it will be available for sharing
1.1279 -** with other connections.
1.1280 +** Beginning in SQLite version 3.5.0, cache sharing is enabled and disabled
1.1281 +** for an entire process. In prior versions of SQLite, sharing was
1.1282 +** enabled or disabled for each thread separately.
1.1283 +**
1.1284 +** The cache sharing mode set by this interface effects all subsequent
1.1285 +** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
1.1286 +** Existing database connections continue use the sharing mode that was
1.1287 +** in effect at the time they were opened.
1.1288 **
1.1289 ** Virtual tables cannot be used with a shared cache. When shared
1.1290 -** cache is enabled, the sqlite3_create_module() API used to register
1.1291 +** cache is enabled, the [sqlite3_create_module()] API used to register
1.1292 ** virtual tables will always return an error.
1.1293 **
1.1294 ** This routine returns [SQLITE_OK] if shared cache was
1.1295 ** enabled or disabled successfully. An [SQLITE_ERROR | error code]
1.1296 ** is returned otherwise.
1.1297 **
1.1298 -** Shared cache is disabled by default for backward compatibility.
1.1299 +** Shared cache is disabled by default. But this might change in
1.1300 +** future releases of SQLite. Applications that care about shared
1.1301 +** cache setting should set it explicitly.
1.1302 */
1.1303 int sqlite3_enable_shared_cache(int);
1.1304
1.1305 @@ -2148,30 +2791,24 @@
1.1306 ** Attempt to free N bytes of heap memory by deallocating non-essential
1.1307 ** memory allocations held by the database library (example: memory
1.1308 ** used to cache database pages to improve performance).
1.1309 -**
1.1310 -** This function is not a part of standard builds. It is only created
1.1311 -** if SQLite is compiled with the SQLITE_ENABLE_MEMORY_MANAGEMENT macro.
1.1312 */
1.1313 int sqlite3_release_memory(int);
1.1314
1.1315 /*
1.1316 ** CAPI3REF: Impose A Limit On Heap Size
1.1317 **
1.1318 -** Place a "soft" limit on the amount of heap memory that may be allocated by
1.1319 -** SQLite within the current thread. If an internal allocation is requested
1.1320 -** that would exceed the specified limit, [sqlite3_release_memory()] is invoked
1.1321 -** one or more times to free up some space before the allocation is made.
1.1322 -**
1.1323 -** The limit is called "soft", because if [sqlite3_release_memory()] cannot free
1.1324 -** sufficient memory to prevent the limit from being exceeded, the memory is
1.1325 -** allocated anyway and the current operation proceeds.
1.1326 -**
1.1327 -** Prior to shutting down a thread sqlite3_soft_heap_limit() must be set to
1.1328 -** zero (the default) or else the thread will leak memory. Alternatively, use
1.1329 -** the [sqlite3_thread_cleanup()] API.
1.1330 +** Place a "soft" limit on the amount of heap memory that may be allocated
1.1331 +** by SQLite. If an internal allocation is requested
1.1332 +** that would exceed the specified limit, [sqlite3_release_memory()] is
1.1333 +** invoked one or more times to free up some space before the allocation
1.1334 +** is made.
1.1335 +**
1.1336 +** The limit is called "soft", because if [sqlite3_release_memory()] cannot
1.1337 +** free sufficient memory to prevent the limit from being exceeded,
1.1338 +** the memory is allocated anyway and the current operation proceeds.
1.1339 **
1.1340 ** A negative or zero value for N means that there is no soft heap limit and
1.1341 -** [sqlite3_release_memory()] will only be called when memory is exhaused.
1.1342 +** [sqlite3_release_memory()] will only be called when memory is exhausted.
1.1343 ** The default value for the soft heap limit is zero.
1.1344 **
1.1345 ** SQLite makes a best effort to honor the soft heap limit. But if it
1.1346 @@ -2179,28 +2816,23 @@
1.1347 ** continue without error or notification. This is why the limit is
1.1348 ** called a "soft" limit. It is advisory only.
1.1349 **
1.1350 -** This function is only available if the library was compiled with the
1.1351 -** SQLITE_ENABLE_MEMORY_MANAGEMENT option set.
1.1352 -** memory-management has been enabled.
1.1353 +** The soft heap limit is implemented using the [sqlite3_memory_alarm()]
1.1354 +** interface. Only a single memory alarm is available in the default
1.1355 +** implementation. This means that if the application also uses the
1.1356 +** memory alarm interface it will interfere with the operation of the
1.1357 +** soft heap limit and undefined behavior will result.
1.1358 +**
1.1359 +** Prior to SQLite version 3.5.0, this routine only constrained the memory
1.1360 +** allocated by a single thread - the same thread in which this routine
1.1361 +** runs. Beginning with SQLite version 3.5.0, the soft heap limit is
1.1362 +** applied to all threads. The value specified for the soft heap limit
1.1363 +** is an upper bound on the total memory allocation for all threads. In
1.1364 +** version 3.5.0 there is no mechanism for limiting the heap usage for
1.1365 +** individual threads.
1.1366 */
1.1367 void sqlite3_soft_heap_limit(int);
1.1368
1.1369 /*
1.1370 -** CAPI3REF: Clean Up Thread Local Storage
1.1371 -**
1.1372 -** This routine makes sure that all thread-local storage has been
1.1373 -** deallocated for the current thread.
1.1374 -**
1.1375 -** This routine is not technically necessary. All thread-local storage
1.1376 -** will be automatically deallocated once memory-management and
1.1377 -** shared-cache are disabled and the soft heap limit has been set
1.1378 -** to zero. This routine is provided as a convenience for users who
1.1379 -** want to make absolutely sure they have not forgotten something
1.1380 -** prior to killing off a thread.
1.1381 -*/
1.1382 -void sqlite3_thread_cleanup(void);
1.1383 -
1.1384 -/*
1.1385 ** CAPI3REF: Extract Metadata About A Column Of A Table
1.1386 **
1.1387 ** This routine
1.1388 @@ -2273,7 +2905,7 @@
1.1389 char const **pzCollSeq, /* OUTPUT: Collation sequence name */
1.1390 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
1.1391 int *pPrimaryKey, /* OUTPUT: True if column part of PK */
1.1392 - int *pAutoinc /* OUTPUT: True if colums is auto-increment */
1.1393 + int *pAutoinc /* OUTPUT: True if column is auto-increment */
1.1394 );
1.1395
1.1396 /*
1.1397 @@ -2318,7 +2950,7 @@
1.1398 **
1.1399 ** Register an extension entry point that is automatically invoked
1.1400 ** whenever a new database connection is opened using
1.1401 -** [sqlite3_open()] or [sqlite3_open16()].
1.1402 +** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()].
1.1403 **
1.1404 ** This API can be invoked at program startup in order to register
1.1405 ** one or more statically linked extensions that will be available
1.1406 @@ -2398,8 +3030,8 @@
1.1407 int (*xNext)(sqlite3_vtab_cursor*);
1.1408 int (*xEof)(sqlite3_vtab_cursor*);
1.1409 int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
1.1410 - int (*xRowid)(sqlite3_vtab_cursor*, sqlite_int64 *pRowid);
1.1411 - int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite_int64 *);
1.1412 + int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
1.1413 + int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
1.1414 int (*xBegin)(sqlite3_vtab *pVTab);
1.1415 int (*xSync)(sqlite3_vtab *pVTab);
1.1416 int (*xCommit)(sqlite3_vtab *pVTab);
1.1417 @@ -2430,7 +3062,7 @@
1.1418 ** is usable) and false if it cannot.
1.1419 **
1.1420 ** The optimizer automatically inverts terms of the form "expr OP column"
1.1421 -** and makes other simplificatinos to the WHERE clause in an attempt to
1.1422 +** and makes other simplifications to the WHERE clause in an attempt to
1.1423 ** get as many WHERE clause terms into the form shown above as possible.
1.1424 ** The aConstraint[] array only reports WHERE clause terms in the correct
1.1425 ** form that refer to the particular virtual table being queried.
1.1426 @@ -2459,24 +3091,24 @@
1.1427 */
1.1428 struct sqlite3_index_info {
1.1429 /* Inputs */
1.1430 - const int nConstraint; /* Number of entries in aConstraint */
1.1431 - const struct sqlite3_index_constraint {
1.1432 + int nConstraint; /* Number of entries in aConstraint */
1.1433 + struct sqlite3_index_constraint {
1.1434 int iColumn; /* Column on left-hand side of constraint */
1.1435 unsigned char op; /* Constraint operator */
1.1436 unsigned char usable; /* True if this constraint is usable */
1.1437 int iTermOffset; /* Used internally - xBestIndex should ignore */
1.1438 - } *const aConstraint; /* Table of WHERE clause constraints */
1.1439 - const int nOrderBy; /* Number of terms in the ORDER BY clause */
1.1440 - const struct sqlite3_index_orderby {
1.1441 + } *aConstraint; /* Table of WHERE clause constraints */
1.1442 + int nOrderBy; /* Number of terms in the ORDER BY clause */
1.1443 + struct sqlite3_index_orderby {
1.1444 int iColumn; /* Column number */
1.1445 unsigned char desc; /* True for DESC. False for ASC. */
1.1446 - } *const aOrderBy; /* The ORDER BY clause */
1.1447 + } *aOrderBy; /* The ORDER BY clause */
1.1448
1.1449 /* Outputs */
1.1450 struct sqlite3_index_constraint_usage {
1.1451 int argvIndex; /* if >0, constraint is part of argv to xFilter */
1.1452 unsigned char omit; /* Do not code a test for this constraint */
1.1453 - } *const aConstraintUsage;
1.1454 + } *aConstraintUsage;
1.1455 int idxNum; /* Number used to identify the index */
1.1456 char *idxStr; /* String, possibly obtained from sqlite3_malloc */
1.1457 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
1.1458 @@ -2519,7 +3151,7 @@
1.1459 /*
1.1460 ** Every module implementation uses a subclass of the following structure
1.1461 ** to describe a particular instance of the module. Each subclass will
1.1462 -** be taylored to the specific needs of the module implementation. The
1.1463 +** be tailored to the specific needs of the module implementation. The
1.1464 ** purpose of this superclass is to define certain fields that are common
1.1465 ** to all module implementations.
1.1466 **
1.1467 @@ -2585,7 +3217,7 @@
1.1468 ** to be experimental. The interface might change in incompatible ways.
1.1469 ** If this is a problem for you, do not use the interface at this time.
1.1470 **
1.1471 -** When the virtual-table mechanism stablizes, we will declare the
1.1472 +** When the virtual-table mechanism stabilizes, we will declare the
1.1473 ** interface fixed, support it indefinitely, and remove this comment.
1.1474 **
1.1475 ****** EXPERIMENTAL - subject to change without notice **************
1.1476 @@ -2599,7 +3231,7 @@
1.1477 ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()].
1.1478 ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
1.1479 ** can be used to read or write small subsections of the blob.
1.1480 -** The [sqltie3_blob_size()] interface returns the size of the
1.1481 +** The [sqlite3_blob_bytes()] interface returns the size of the
1.1482 ** blob in bytes.
1.1483 */
1.1484 typedef struct sqlite3_blob sqlite3_blob;
1.1485 @@ -2631,7 +3263,7 @@
1.1486 const char *zDb,
1.1487 const char *zTable,
1.1488 const char *zColumn,
1.1489 - sqlite_int64 iRow,
1.1490 + sqlite3_int64 iRow,
1.1491 int flags,
1.1492 sqlite3_blob **ppBlob
1.1493 );
1.1494 @@ -2689,6 +3321,224 @@
1.1495 int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
1.1496
1.1497 /*
1.1498 +** CAPI3REF: Virtual File System Objects
1.1499 +**
1.1500 +** A virtual filesystem (VFS) is an [sqlite3_vfs] object
1.1501 +** that SQLite uses to interact
1.1502 +** with the underlying operating system. Most builds come with a
1.1503 +** single default VFS that is appropriate for the host computer.
1.1504 +** New VFSes can be registered and existing VFSes can be unregistered.
1.1505 +** The following interfaces are provided.
1.1506 +**
1.1507 +** The sqlite3_vfs_find() interface returns a pointer to a VFS given its
1.1508 +** name. Names are case sensitive. If there is no match, a NULL
1.1509 +** pointer is returned. If zVfsName is NULL then the default
1.1510 +** VFS is returned.
1.1511 +**
1.1512 +** New VFSes are registered with sqlite3_vfs_register(). Each
1.1513 +** new VFS becomes the default VFS if the makeDflt flag is set.
1.1514 +** The same VFS can be registered multiple times without injury.
1.1515 +** To make an existing VFS into the default VFS, register it again
1.1516 +** with the makeDflt flag set. If two different VFSes with the
1.1517 +** same name are registered, the behavior is undefined. If a
1.1518 +** VFS is registered with a name that is NULL or an empty string,
1.1519 +** then the behavior is undefined.
1.1520 +**
1.1521 +** Unregister a VFS with the sqlite3_vfs_unregister() interface.
1.1522 +** If the default VFS is unregistered, another VFS is chosen as
1.1523 +** the default. The choice for the new VFS is arbitrary.
1.1524 +*/
1.1525 +sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
1.1526 +int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
1.1527 +int sqlite3_vfs_unregister(sqlite3_vfs*);
1.1528 +
1.1529 +/*
1.1530 +** CAPI3REF: Mutexes
1.1531 +**
1.1532 +** The SQLite core uses these routines for thread
1.1533 +** synchronization. Though they are intended for internal
1.1534 +** use by SQLite, code that links against SQLite is
1.1535 +** permitted to use any of these routines.
1.1536 +**
1.1537 +** The SQLite source code contains multiple implementations
1.1538 +** of these mutex routines. An appropriate implementation
1.1539 +** is selected automatically at compile-time. The following
1.1540 +** implementations are available in the SQLite core:
1.1541 +**
1.1542 +** <ul>
1.1543 +** <li> SQLITE_MUTEX_OS2
1.1544 +** <li> SQLITE_MUTEX_PTHREAD
1.1545 +** <li> SQLITE_MUTEX_W32
1.1546 +** <li> SQLITE_MUTEX_NOOP
1.1547 +** </ul>
1.1548 +**
1.1549 +** The SQLITE_MUTEX_NOOP implementation is a set of routines
1.1550 +** that does no real locking and is appropriate for use in
1.1551 +** a single-threaded application. The SQLITE_MUTEX_OS2,
1.1552 +** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations
1.1553 +** are appropriate for use on os/2, unix, and windows.
1.1554 +**
1.1555 +** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
1.1556 +** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
1.1557 +** implementation is included with the library. The
1.1558 +** mutex interface routines defined here become external
1.1559 +** references in the SQLite library for which implementations
1.1560 +** must be provided by the application. This facility allows an
1.1561 +** application that links against SQLite to provide its own mutex
1.1562 +** implementation without having to modify the SQLite core.
1.1563 +**
1.1564 +** The sqlite3_mutex_alloc() routine allocates a new
1.1565 +** mutex and returns a pointer to it. If it returns NULL
1.1566 +** that means that a mutex could not be allocated. SQLite
1.1567 +** will unwind its stack and return an error. The argument
1.1568 +** to sqlite3_mutex_alloc() is one of these integer constants:
1.1569 +**
1.1570 +** <ul>
1.1571 +** <li> SQLITE_MUTEX_FAST
1.1572 +** <li> SQLITE_MUTEX_RECURSIVE
1.1573 +** <li> SQLITE_MUTEX_STATIC_MASTER
1.1574 +** <li> SQLITE_MUTEX_STATIC_MEM
1.1575 +** <li> SQLITE_MUTEX_STATIC_MEM2
1.1576 +** <li> SQLITE_MUTEX_STATIC_PRNG
1.1577 +** <li> SQLITE_MUTEX_STATIC_LRU
1.1578 +** </ul>
1.1579 +**
1.1580 +** The first two constants cause sqlite3_mutex_alloc() to create
1.1581 +** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
1.1582 +** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
1.1583 +** The mutex implementation does not need to make a distinction
1.1584 +** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
1.1585 +** not want to. But SQLite will only request a recursive mutex in
1.1586 +** cases where it really needs one. If a faster non-recursive mutex
1.1587 +** implementation is available on the host platform, the mutex subsystem
1.1588 +** might return such a mutex in response to SQLITE_MUTEX_FAST.
1.1589 +**
1.1590 +** The other allowed parameters to sqlite3_mutex_alloc() each return
1.1591 +** a pointer to a static preexisting mutex. Four static mutexes are
1.1592 +** used by the current version of SQLite. Future versions of SQLite
1.1593 +** may add additional static mutexes. Static mutexes are for internal
1.1594 +** use by SQLite only. Applications that use SQLite mutexes should
1.1595 +** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
1.1596 +** SQLITE_MUTEX_RECURSIVE.
1.1597 +**
1.1598 +** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
1.1599 +** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
1.1600 +** returns a different mutex on every call. But for the static
1.1601 +** mutex types, the same mutex is returned on every call that has
1.1602 +** the same type number.
1.1603 +**
1.1604 +** The sqlite3_mutex_free() routine deallocates a previously
1.1605 +** allocated dynamic mutex. SQLite is careful to deallocate every
1.1606 +** dynamic mutex that it allocates. The dynamic mutexes must not be in
1.1607 +** use when they are deallocated. Attempting to deallocate a static
1.1608 +** mutex results in undefined behavior. SQLite never deallocates
1.1609 +** a static mutex.
1.1610 +**
1.1611 +** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
1.1612 +** to enter a mutex. If another thread is already within the mutex,
1.1613 +** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
1.1614 +** SQLITE_BUSY. The sqlite3_mutex_try() interface returns SQLITE_OK
1.1615 +** upon successful entry. Mutexes created using SQLITE_MUTEX_RECURSIVE can
1.1616 +** be entered multiple times by the same thread. In such cases the,
1.1617 +** mutex must be exited an equal number of times before another thread
1.1618 +** can enter. If the same thread tries to enter any other kind of mutex
1.1619 +** more than once, the behavior is undefined. SQLite will never exhibit
1.1620 +** such behavior in its own use of mutexes.
1.1621 +**
1.1622 +** Some systems (ex: windows95) do not the operation implemented by
1.1623 +** sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() will
1.1624 +** always return SQLITE_BUSY. The SQLite core only ever uses
1.1625 +** sqlite3_mutex_try() as an optimization so this is acceptable behavior.
1.1626 +**
1.1627 +** The sqlite3_mutex_leave() routine exits a mutex that was
1.1628 +** previously entered by the same thread. The behavior
1.1629 +** is undefined if the mutex is not currently entered by the
1.1630 +** calling thread or is not currently allocated. SQLite will
1.1631 +** never do either.
1.1632 +**
1.1633 +** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
1.1634 +*/
1.1635 +sqlite3_mutex *sqlite3_mutex_alloc(int);
1.1636 +void sqlite3_mutex_free(sqlite3_mutex*);
1.1637 +void sqlite3_mutex_enter(sqlite3_mutex*);
1.1638 +int sqlite3_mutex_try(sqlite3_mutex*);
1.1639 +void sqlite3_mutex_leave(sqlite3_mutex*);
1.1640 +
1.1641 +/*
1.1642 +** CAPI3REF: Mutex Verifcation Routines
1.1643 +**
1.1644 +** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
1.1645 +** are intended for use inside assert() statements. The SQLite core
1.1646 +** never uses these routines except inside an assert() and applications
1.1647 +** are advised to follow the lead of the core. The core only
1.1648 +** provides implementations for these routines when it is compiled
1.1649 +** with the SQLITE_DEBUG flag. External mutex implementations
1.1650 +** are only required to provide these routines if SQLITE_DEBUG is
1.1651 +** defined and if NDEBUG is not defined.
1.1652 +**
1.1653 +** These routines should return true if the mutex in their argument
1.1654 +** is held or not held, respectively, by the calling thread.
1.1655 +**
1.1656 +** The implementation is not required to provided versions of these
1.1657 +** routines that actually work.
1.1658 +** If the implementation does not provide working
1.1659 +** versions of these routines, it should at least provide stubs
1.1660 +** that always return true so that one does not get spurious
1.1661 +** assertion failures.
1.1662 +**
1.1663 +** If the argument to sqlite3_mutex_held() is a NULL pointer then
1.1664 +** the routine should return 1. This seems counter-intuitive since
1.1665 +** clearly the mutex cannot be held if it does not exist. But the
1.1666 +** the reason the mutex does not exist is because the build is not
1.1667 +** using mutexes. And we do not want the assert() containing the
1.1668 +** call to sqlite3_mutex_held() to fail, so a non-zero return is
1.1669 +** the appropriate thing to do. The sqlite3_mutex_notheld()
1.1670 +** interface should also return 1 when given a NULL pointer.
1.1671 +*/
1.1672 +int sqlite3_mutex_held(sqlite3_mutex*);
1.1673 +int sqlite3_mutex_notheld(sqlite3_mutex*);
1.1674 +
1.1675 +/*
1.1676 +** CAPI3REF: Mutex Types
1.1677 +**
1.1678 +** The [sqlite3_mutex_alloc()] interface takes a single argument
1.1679 +** which is one of these integer constants.
1.1680 +*/
1.1681 +#define SQLITE_MUTEX_FAST 0
1.1682 +#define SQLITE_MUTEX_RECURSIVE 1
1.1683 +#define SQLITE_MUTEX_STATIC_MASTER 2
1.1684 +#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
1.1685 +#define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */
1.1686 +#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */
1.1687 +#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
1.1688 +
1.1689 +/*
1.1690 +** CAPI3REF: Low-Level Control Of Database Files
1.1691 +**
1.1692 +** The [sqlite3_file_control()] interface makes a direct call to the
1.1693 +** xFileControl method for the [sqlite3_io_methods] object associated
1.1694 +** with a particular database identified by the second argument. The
1.1695 +** name of the database is the name assigned to the database by the
1.1696 +** <a href="lang_attach.html">ATTACH</a> SQL command that opened the
1.1697 +** database. To control the main database file, use the name "main"
1.1698 +** or a NULL pointer. The third and fourth parameters to this routine
1.1699 +** are passed directly through to the second and third parameters of
1.1700 +** the xFileControl method. The return value of the xFileControl
1.1701 +** method becomes the return value of this routine.
1.1702 +**
1.1703 +** If the second parameter (zDbName) does not match the name of any
1.1704 +** open database file, then SQLITE_ERROR is returned. This error
1.1705 +** code is not remembered and will not be recalled by [sqlite3_errcode()]
1.1706 +** or [sqlite3_errmsg()]. The underlying xFileControl method might
1.1707 +** also return SQLITE_ERROR. There is no way to distinguish between
1.1708 +** an incorrect zDbName and an SQLITE_ERROR return from the underlying
1.1709 +** xFileControl method.
1.1710 +**
1.1711 +** See also: [SQLITE_FCNTL_LOCKSTATE]
1.1712 +*/
1.1713 +int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
1.1714 +
1.1715 +/*
1.1716 ** Undo the hack that converts floating point types to integer for
1.1717 ** builds on processors without floating point support.
1.1718 */
