4
** The author disclaims copyright to this source code. In place of
5
** a legal notice, here is a blessing:
7
** May you do good and not evil.
8
** May you find forgiveness for yourself and forgive others.
9
** May you share freely, never taking more than you give.
11
*************************************************************************
12
** This header file defines the interface that the SQLite library
13
** presents to client programs. If a C-function, structure, datatype,
14
** or constant definition does not appear in this file, then it is
15
** not a published API of SQLite, is subject to change without
16
** notice, and should not be referenced by programs that use SQLite.
18
** Some of the definitions that are in this file are marked as
19
** "experimental". Experimental interfaces are normally new
20
** features recently added to SQLite. We do not anticipate changes
21
** to experimental interfaces but reserve the right to make minor changes
22
** if experience from use "in the wild" suggest such changes are prudent.
24
** The official C-language API documentation for SQLite is derived
25
** from comments in this file. This file is the authoritative source
26
** on how SQLite interfaces are suppose to operate.
28
** The name of this file under configuration management is "sqlite.h.in".
29
** The makefile makes some minor changes to this file (such as inserting
30
** the version number) and changes its name to "sqlite3.h" as
31
** part of the build process.
35
#include <stdarg.h> /* Needed for the definition of va_list */
38
** Make sure we can call this stuff from C++.
46
** Add the ability to override 'extern'
49
# define SQLITE_EXTERN extern
58
** These no-op macros are used in front of interfaces to mark those
59
** interfaces as either deprecated or experimental. New applications
60
** should not use deprecated interfaces - they are support for backwards
61
** compatibility only. Application writers should be aware that
62
** experimental interfaces are subject to change in point releases.
64
** These macros used to resolve to various kinds of compiler magic that
65
** would generate warning messages when they were used. But that
66
** compiler magic ended up generating such a flurry of bug reports
67
** that we have taken it all out and gone back to using simple
70
#define SQLITE_DEPRECATED
71
#define SQLITE_EXPERIMENTAL
74
** Ensure these symbols were not defined by some previous header file.
77
# undef SQLITE_VERSION
79
#ifdef SQLITE_VERSION_NUMBER
80
# undef SQLITE_VERSION_NUMBER
84
** CAPI3REF: Compile-Time Library Version Numbers
86
** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
87
** evaluates to a string literal that is the SQLite version in the
88
** format "X.Y.Z" where X is the major version number (always 3 for
89
** SQLite3) and Y is the minor version number and Z is the release number.)^
90
** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
91
** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
92
** numbers used in [SQLITE_VERSION].)^
93
** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
94
** be larger than the release from which it is derived. Either Y will
95
** be held constant and Z will be incremented or else Y will be incremented
96
** and Z will be reset to zero.
98
** Since version 3.6.18, SQLite source code has been stored in the
99
** <a href="http://www.fossil-scm.org/">Fossil configuration management
100
** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to
101
** a string which identifies a particular check-in of SQLite
102
** within its configuration management system. ^The SQLITE_SOURCE_ID
103
** string contains the date and time of the check-in (UTC) and an SHA1
104
** hash of the entire source tree.
106
** See also: [sqlite3_libversion()],
107
** [sqlite3_libversion_number()], [sqlite3_sourceid()],
108
** [sqlite_version()] and [sqlite_source_id()].
110
#define SQLITE_VERSION "3.7.6.2"
111
#define SQLITE_VERSION_NUMBER 3007006
112
#define SQLITE_SOURCE_ID "2011-04-17 17:25:17 154ddbc17120be2915eb03edc52af1225eb7cb5e"
115
** CAPI3REF: Run-Time Library Version Numbers
116
** KEYWORDS: sqlite3_version, sqlite3_sourceid
118
** These interfaces provide the same information as the [SQLITE_VERSION],
119
** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
120
** but are associated with the library instead of the header file. ^(Cautious
121
** programmers might include assert() statements in their application to
122
** verify that values returned by these interfaces match the macros in
123
** the header, and thus insure that the application is
124
** compiled with matching library and header files.
127
** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
128
** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
129
** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
130
** </pre></blockquote>)^
132
** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
133
** macro. ^The sqlite3_libversion() function returns a pointer to the
134
** to the sqlite3_version[] string constant. The sqlite3_libversion()
135
** function is provided for use in DLLs since DLL users usually do not have
136
** direct access to string constants within the DLL. ^The
137
** sqlite3_libversion_number() function returns an integer equal to
138
** [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns
139
** a pointer to a string constant whose value is the same as the
140
** [SQLITE_SOURCE_ID] C preprocessor macro.
142
** See also: [sqlite_version()] and [sqlite_source_id()].
144
SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
145
SQLITE_API const char *sqlite3_libversion(void);
146
SQLITE_API const char *sqlite3_sourceid(void);
147
SQLITE_API int sqlite3_libversion_number(void);
150
** CAPI3REF: Run-Time Library Compilation Options Diagnostics
152
** ^The sqlite3_compileoption_used() function returns 0 or 1
153
** indicating whether the specified option was defined at
154
** compile time. ^The SQLITE_ prefix may be omitted from the
155
** option name passed to sqlite3_compileoption_used().
157
** ^The sqlite3_compileoption_get() function allows iterating
158
** over the list of options that were defined at compile time by
159
** returning the N-th compile time option string. ^If N is out of range,
160
** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_
161
** prefix is omitted from any strings returned by
162
** sqlite3_compileoption_get().
164
** ^Support for the diagnostic functions sqlite3_compileoption_used()
165
** and sqlite3_compileoption_get() may be omitted by specifying the
166
** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
168
** See also: SQL functions [sqlite_compileoption_used()] and
169
** [sqlite_compileoption_get()] and the [compile_options pragma].
171
#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
172
SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
173
SQLITE_API const char *sqlite3_compileoption_get(int N);
177
** CAPI3REF: Test To See If The Library Is Threadsafe
179
** ^The sqlite3_threadsafe() function returns zero if and only if
180
** SQLite was compiled mutexing code omitted due to the
181
** [SQLITE_THREADSAFE] compile-time option being set to 0.
183
** SQLite can be compiled with or without mutexes. When
184
** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
185
** are enabled and SQLite is threadsafe. When the
186
** [SQLITE_THREADSAFE] macro is 0,
187
** the mutexes are omitted. Without the mutexes, it is not safe
188
** to use SQLite concurrently from more than one thread.
190
** Enabling mutexes incurs a measurable performance penalty.
191
** So if speed is of utmost importance, it makes sense to disable
192
** the mutexes. But for maximum safety, mutexes should be enabled.
193
** ^The default behavior is for mutexes to be enabled.
195
** This interface can be used by an application to make sure that the
196
** version of SQLite that it is linking against was compiled with
197
** the desired setting of the [SQLITE_THREADSAFE] macro.
199
** This interface only reports on the compile-time mutex setting
200
** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
201
** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
202
** can be fully or partially disabled using a call to [sqlite3_config()]
203
** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
204
** or [SQLITE_CONFIG_MUTEX]. ^(The return value of the
205
** sqlite3_threadsafe() function shows only the compile-time setting of
206
** thread safety, not any run-time changes to that setting made by
207
** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
208
** is unchanged by calls to sqlite3_config().)^
210
** See the [threading mode] documentation for additional information.
212
SQLITE_API int sqlite3_threadsafe(void);
215
** CAPI3REF: Database Connection Handle
216
** KEYWORDS: {database connection} {database connections}
218
** Each open SQLite database is represented by a pointer to an instance of
219
** the opaque structure named "sqlite3". It is useful to think of an sqlite3
220
** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
221
** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
222
** is its destructor. There are many other interfaces (such as
223
** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
224
** [sqlite3_busy_timeout()] to name but three) that are methods on an
227
typedef struct sqlite3 sqlite3;
230
** CAPI3REF: 64-Bit Integer Types
231
** KEYWORDS: sqlite_int64 sqlite_uint64
233
** Because there is no cross-platform way to specify 64-bit integer types
234
** SQLite includes typedefs for 64-bit signed and unsigned integers.
236
** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
237
** The sqlite_int64 and sqlite_uint64 types are supported for backwards
238
** compatibility only.
240
** ^The sqlite3_int64 and sqlite_int64 types can store integer values
241
** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
242
** sqlite3_uint64 and sqlite_uint64 types can store integer values
243
** between 0 and +18446744073709551615 inclusive.
245
#ifdef SQLITE_INT64_TYPE
246
typedef SQLITE_INT64_TYPE sqlite_int64;
247
typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
248
#elif defined(_MSC_VER) || defined(__BORLANDC__)
249
typedef __int64 sqlite_int64;
250
typedef unsigned __int64 sqlite_uint64;
252
typedef long long int sqlite_int64;
253
typedef unsigned long long int sqlite_uint64;
255
typedef sqlite_int64 sqlite3_int64;
256
typedef sqlite_uint64 sqlite3_uint64;
259
** If compiling for a processor that lacks floating point support,
260
** substitute integer for floating-point.
262
#ifdef SQLITE_OMIT_FLOATING_POINT
263
# define double sqlite3_int64
267
** CAPI3REF: Closing A Database Connection
269
** ^The sqlite3_close() routine is the destructor for the [sqlite3] object.
270
** ^Calls to sqlite3_close() return SQLITE_OK if the [sqlite3] object is
271
** successfully destroyed and all associated resources are deallocated.
273
** Applications must [sqlite3_finalize | finalize] all [prepared statements]
274
** and [sqlite3_blob_close | close] all [BLOB handles] associated with
275
** the [sqlite3] object prior to attempting to close the object. ^If
276
** sqlite3_close() is called on a [database connection] that still has
277
** outstanding [prepared statements] or [BLOB handles], then it returns
280
** ^If [sqlite3_close()] is invoked while a transaction is open,
281
** the transaction is automatically rolled back.
283
** The C parameter to [sqlite3_close(C)] must be either a NULL
284
** pointer or an [sqlite3] object pointer obtained
285
** from [sqlite3_open()], [sqlite3_open16()], or
286
** [sqlite3_open_v2()], and not previously closed.
287
** ^Calling sqlite3_close() with a NULL pointer argument is a
290
SQLITE_API int sqlite3_close(sqlite3 *);
293
** The type for a callback function.
294
** This is legacy and deprecated. It is included for historical
295
** compatibility and is not documented.
297
typedef int (*sqlite3_callback)(void*,int,char**, char**);
300
** CAPI3REF: One-Step Query Execution Interface
302
** The sqlite3_exec() interface is a convenience wrapper around
303
** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
304
** that allows an application to run multiple statements of SQL
305
** without having to use a lot of C code.
307
** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
308
** semicolon-separate SQL statements passed into its 2nd argument,
309
** in the context of the [database connection] passed in as its 1st
310
** argument. ^If the callback function of the 3rd argument to
311
** sqlite3_exec() is not NULL, then it is invoked for each result row
312
** coming out of the evaluated SQL statements. ^The 4th argument to
313
** to sqlite3_exec() is relayed through to the 1st argument of each
314
** callback invocation. ^If the callback pointer to sqlite3_exec()
315
** is NULL, then no callback is ever invoked and result rows are
318
** ^If an error occurs while evaluating the SQL statements passed into
319
** sqlite3_exec(), then execution of the current statement stops and
320
** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec()
321
** is not NULL then any error message is written into memory obtained
322
** from [sqlite3_malloc()] and passed back through the 5th parameter.
323
** To avoid memory leaks, the application should invoke [sqlite3_free()]
324
** on error message strings returned through the 5th parameter of
325
** of sqlite3_exec() after the error message string is no longer needed.
326
** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
327
** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
328
** NULL before returning.
330
** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
331
** routine returns SQLITE_ABORT without invoking the callback again and
332
** without running any subsequent SQL statements.
334
** ^The 2nd argument to the sqlite3_exec() callback function is the
335
** number of columns in the result. ^The 3rd argument to the sqlite3_exec()
336
** callback is an array of pointers to strings obtained as if from
337
** [sqlite3_column_text()], one for each column. ^If an element of a
338
** result row is NULL then the corresponding string pointer for the
339
** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
340
** sqlite3_exec() callback is an array of pointers to strings where each
341
** entry represents the name of corresponding result column as obtained
342
** from [sqlite3_column_name()].
344
** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
345
** to an empty string, or a pointer that contains only whitespace and/or
346
** SQL comments, then no SQL statements are evaluated and the database
352
** <li> The application must insure that the 1st parameter to sqlite3_exec()
353
** is a valid and open [database connection].
354
** <li> The application must not close [database connection] specified by
355
** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
356
** <li> The application must not modify the SQL statement text passed into
357
** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
360
SQLITE_API int sqlite3_exec(
361
sqlite3*, /* An open database */
362
const char *sql, /* SQL to be evaluated */
363
int (*callback)(void*,int,char**,char**), /* Callback function */
364
void *, /* 1st argument to callback */
365
char **errmsg /* Error msg written here */
369
** CAPI3REF: Result Codes
370
** KEYWORDS: SQLITE_OK {error code} {error codes}
371
** KEYWORDS: {result code} {result codes}
373
** Many SQLite functions return an integer result code from the set shown
374
** here in order to indicates success or failure.
376
** New error codes may be added in future versions of SQLite.
378
** See also: [SQLITE_IOERR_READ | extended result codes]
380
#define SQLITE_OK 0 /* Successful result */
381
/* beginning-of-error-codes */
382
#define SQLITE_ERROR 1 /* SQL error or missing database */
383
#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
384
#define SQLITE_PERM 3 /* Access permission denied */
385
#define SQLITE_ABORT 4 /* Callback routine requested an abort */
386
#define SQLITE_BUSY 5 /* The database file is locked */
387
#define SQLITE_LOCKED 6 /* A table in the database is locked */
388
#define SQLITE_NOMEM 7 /* A malloc() failed */
389
#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
390
#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
391
#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
392
#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
393
#define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */
394
#define SQLITE_FULL 13 /* Insertion failed because database is full */
395
#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
396
#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
397
#define SQLITE_EMPTY 16 /* Database is empty */
398
#define SQLITE_SCHEMA 17 /* The database schema changed */
399
#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
400
#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
401
#define SQLITE_MISMATCH 20 /* Data type mismatch */
402
#define SQLITE_MISUSE 21 /* Library used incorrectly */
403
#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
404
#define SQLITE_AUTH 23 /* Authorization denied */
405
#define SQLITE_FORMAT 24 /* Auxiliary database format error */
406
#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
407
#define SQLITE_NOTADB 26 /* File opened that is not a database file */
408
#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
409
#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
410
/* end-of-error-codes */
413
** CAPI3REF: Extended Result Codes
414
** KEYWORDS: {extended error code} {extended error codes}
415
** KEYWORDS: {extended result code} {extended result codes}
417
** In its default configuration, SQLite API routines return one of 26 integer
418
** [SQLITE_OK | result codes]. However, experience has shown that many of
419
** these result codes are too coarse-grained. They do not provide as
420
** much information about problems as programmers might like. In an effort to
421
** address this, newer versions of SQLite (version 3.3.8 and later) include
422
** support for additional result codes that provide more detailed information
423
** about errors. The extended result codes are enabled or disabled
424
** on a per database connection basis using the
425
** [sqlite3_extended_result_codes()] API.
427
** Some of the available extended result codes are listed here.
428
** One may expect the number of extended result codes will be expand
429
** over time. Software that uses extended result codes should expect
430
** to see new result codes in future releases of SQLite.
432
** The SQLITE_OK result code will never be extended. It will always
435
#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
436
#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
437
#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
438
#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))
439
#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))
440
#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))
441
#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))
442
#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))
443
#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
444
#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
445
#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
446
#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
447
#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8))
448
#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
449
#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8))
450
#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8))
451
#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8))
452
#define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8))
453
#define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8))
454
#define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8))
455
#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
456
#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
457
#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8))
460
** CAPI3REF: Flags For File Open Operations
462
** These bit values are intended for use in the
463
** 3rd parameter to the [sqlite3_open_v2()] interface and
464
** in the 4th parameter to the xOpen method of the
465
** [sqlite3_vfs] object.
467
#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
468
#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
469
#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */
470
#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */
471
#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */
472
#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */
473
#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */
474
#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */
475
#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */
476
#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */
477
#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */
478
#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */
479
#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */
480
#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
481
#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
482
#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */
483
#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
484
#define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
486
/* Reserved: 0x00F00000 */
489
** CAPI3REF: Device Characteristics
491
** The xDeviceCharacteristics method of the [sqlite3_io_methods]
492
** object returns an integer which is a vector of the these
493
** bit values expressing I/O characteristics of the mass storage
494
** device that holds the file that the [sqlite3_io_methods]
497
** The SQLITE_IOCAP_ATOMIC property means that all writes of
498
** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
499
** mean that writes of blocks that are nnn bytes in size and
500
** are aligned to an address which is an integer multiple of
501
** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
502
** that when data is appended to a file, the data is appended
503
** first then the size of the file is extended, never the other
504
** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
505
** information is written to disk in the same order as calls
508
#define SQLITE_IOCAP_ATOMIC 0x00000001
509
#define SQLITE_IOCAP_ATOMIC512 0x00000002
510
#define SQLITE_IOCAP_ATOMIC1K 0x00000004
511
#define SQLITE_IOCAP_ATOMIC2K 0x00000008
512
#define SQLITE_IOCAP_ATOMIC4K 0x00000010
513
#define SQLITE_IOCAP_ATOMIC8K 0x00000020
514
#define SQLITE_IOCAP_ATOMIC16K 0x00000040
515
#define SQLITE_IOCAP_ATOMIC32K 0x00000080
516
#define SQLITE_IOCAP_ATOMIC64K 0x00000100
517
#define SQLITE_IOCAP_SAFE_APPEND 0x00000200
518
#define SQLITE_IOCAP_SEQUENTIAL 0x00000400
519
#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
522
** CAPI3REF: File Locking Levels
524
** SQLite uses one of these integer values as the second
525
** argument to calls it makes to the xLock() and xUnlock() methods
526
** of an [sqlite3_io_methods] object.
528
#define SQLITE_LOCK_NONE 0
529
#define SQLITE_LOCK_SHARED 1
530
#define SQLITE_LOCK_RESERVED 2
531
#define SQLITE_LOCK_PENDING 3
532
#define SQLITE_LOCK_EXCLUSIVE 4
535
** CAPI3REF: Synchronization Type Flags
537
** When SQLite invokes the xSync() method of an
538
** [sqlite3_io_methods] object it uses a combination of
539
** these integer values as the second argument.
541
** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
542
** sync operation only needs to flush data to mass storage. Inode
543
** information need not be flushed. If the lower four bits of the flag
544
** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
545
** If the lower four bits equal SQLITE_SYNC_FULL, that means
546
** to use Mac OS X style fullsync instead of fsync().
548
** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
549
** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
550
** settings. The [synchronous pragma] determines when calls to the
551
** xSync VFS method occur and applies uniformly across all platforms.
552
** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
553
** energetic or rigorous or forceful the sync operations are and
554
** only make a difference on Mac OSX for the default SQLite code.
555
** (Third-party VFS implementations might also make the distinction
556
** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
557
** operating systems natively supported by SQLite, only Mac OSX
558
** cares about the difference.)
560
#define SQLITE_SYNC_NORMAL 0x00002
561
#define SQLITE_SYNC_FULL 0x00003
562
#define SQLITE_SYNC_DATAONLY 0x00010
565
** CAPI3REF: OS Interface Open File Handle
567
** An [sqlite3_file] object represents an open file in the
568
** [sqlite3_vfs | OS interface layer]. Individual OS interface
569
** implementations will
570
** want to subclass this object by appending additional fields
571
** for their own use. The pMethods entry is a pointer to an
572
** [sqlite3_io_methods] object that defines methods for performing
573
** I/O operations on the open file.
575
typedef struct sqlite3_file sqlite3_file;
576
struct sqlite3_file {
577
const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
581
** CAPI3REF: OS Interface File Virtual Methods Object
583
** Every file opened by the [sqlite3_vfs] xOpen method populates an
584
** [sqlite3_file] object (or, more commonly, a subclass of the
585
** [sqlite3_file] object) with a pointer to an instance of this object.
586
** This object defines the methods used to perform various operations
587
** against the open file represented by the [sqlite3_file] object.
589
** If the xOpen method sets the sqlite3_file.pMethods element
590
** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
591
** may be invoked even if the xOpen reported that it failed. The
592
** only way to prevent a call to xClose following a failed xOpen
593
** is for the xOpen to set the sqlite3_file.pMethods element to NULL.
595
** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
596
** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
597
** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
598
** flag may be ORed in to indicate that only the data of the file
599
** and not its inode needs to be synced.
601
** The integer values to xLock() and xUnlock() are one of
603
** <li> [SQLITE_LOCK_NONE],
604
** <li> [SQLITE_LOCK_SHARED],
605
** <li> [SQLITE_LOCK_RESERVED],
606
** <li> [SQLITE_LOCK_PENDING], or
607
** <li> [SQLITE_LOCK_EXCLUSIVE].
609
** xLock() increases the lock. xUnlock() decreases the lock.
610
** The xCheckReservedLock() method checks whether any database connection,
611
** either in this process or in some other process, is holding a RESERVED,
612
** PENDING, or EXCLUSIVE lock on the file. It returns true
613
** if such a lock exists and false otherwise.
615
** The xFileControl() method is a generic interface that allows custom
616
** VFS implementations to directly control an open file using the
617
** [sqlite3_file_control()] interface. The second "op" argument is an
618
** integer opcode. The third argument is a generic pointer intended to
619
** point to a structure that may contain arguments or space in which to
620
** write return values. Potential uses for xFileControl() might be
621
** functions to enable blocking locks with timeouts, to change the
622
** locking strategy (for example to use dot-file locks), to inquire
623
** about the status of a lock, or to break stale locks. The SQLite
624
** core reserves all opcodes less than 100 for its own use.
625
** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
626
** Applications that define a custom xFileControl method should use opcodes
627
** greater than 100 to avoid conflicts. VFS implementations should
628
** return [SQLITE_NOTFOUND] for file control opcodes that they do not
631
** The xSectorSize() method returns the sector size of the
632
** device that underlies the file. The sector size is the
633
** minimum write that can be performed without disturbing
634
** other bytes in the file. The xDeviceCharacteristics()
635
** method returns a bit vector describing behaviors of the
636
** underlying device:
639
** <li> [SQLITE_IOCAP_ATOMIC]
640
** <li> [SQLITE_IOCAP_ATOMIC512]
641
** <li> [SQLITE_IOCAP_ATOMIC1K]
642
** <li> [SQLITE_IOCAP_ATOMIC2K]
643
** <li> [SQLITE_IOCAP_ATOMIC4K]
644
** <li> [SQLITE_IOCAP_ATOMIC8K]
645
** <li> [SQLITE_IOCAP_ATOMIC16K]
646
** <li> [SQLITE_IOCAP_ATOMIC32K]
647
** <li> [SQLITE_IOCAP_ATOMIC64K]
648
** <li> [SQLITE_IOCAP_SAFE_APPEND]
649
** <li> [SQLITE_IOCAP_SEQUENTIAL]
652
** The SQLITE_IOCAP_ATOMIC property means that all writes of
653
** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
654
** mean that writes of blocks that are nnn bytes in size and
655
** are aligned to an address which is an integer multiple of
656
** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
657
** that when data is appended to a file, the data is appended
658
** first then the size of the file is extended, never the other
659
** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
660
** information is written to disk in the same order as calls
663
** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
664
** in the unread portions of the buffer with zeros. A VFS that
665
** fails to zero-fill short reads might seem to work. However,
666
** failure to zero-fill short reads will eventually lead to
667
** database corruption.
669
typedef struct sqlite3_io_methods sqlite3_io_methods;
670
struct sqlite3_io_methods {
672
int (*xClose)(sqlite3_file*);
673
int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
674
int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
675
int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
676
int (*xSync)(sqlite3_file*, int flags);
677
int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
678
int (*xLock)(sqlite3_file*, int);
679
int (*xUnlock)(sqlite3_file*, int);
680
int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
681
int (*xFileControl)(sqlite3_file*, int op, void *pArg);
682
int (*xSectorSize)(sqlite3_file*);
683
int (*xDeviceCharacteristics)(sqlite3_file*);
684
/* Methods above are valid for version 1 */
685
int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
686
int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
687
void (*xShmBarrier)(sqlite3_file*);
688
int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
689
/* Methods above are valid for version 2 */
690
/* Additional methods may be added in future releases */
694
** CAPI3REF: Standard File Control Opcodes
696
** These integer constants are opcodes for the xFileControl method
697
** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
700
** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
701
** opcode causes the xFileControl method to write the current state of
702
** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
703
** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
704
** into an integer that the pArg argument points to. This capability
705
** is used during testing and only needs to be supported when SQLITE_TEST
708
** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
709
** layer a hint of how large the database file will grow to be during the
710
** current transaction. This hint is not guaranteed to be accurate but it
711
** is often close. The underlying VFS might choose to preallocate database
712
** file space based on this hint in order to help writes to the database
715
** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
716
** extends and truncates the database file in chunks of a size specified
717
** by the user. The fourth argument to [sqlite3_file_control()] should
718
** point to an integer (type int) containing the new chunk-size to use
719
** for the nominated database. Allocating database file space in large
720
** chunks (say 1MB at a time), may reduce file-system fragmentation and
721
** improve performance on some systems.
723
** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
724
** to the [sqlite3_file] object associated with a particular database
725
** connection. See the [sqlite3_file_control()] documentation for
726
** additional information.
728
** ^(The [SQLITE_FCNTL_SYNC_OMITTED] opcode is generated internally by
729
** SQLite and sent to all VFSes in place of a call to the xSync method
730
** when the database connection has [PRAGMA synchronous] set to OFF.)^
731
** Some specialized VFSes need this signal in order to operate correctly
732
** when [PRAGMA synchronous | PRAGMA synchronous=OFF] is set, but most
733
** VFSes do not need this signal and should silently ignore this opcode.
734
** Applications should not call [sqlite3_file_control()] with this
735
** opcode as doing so may disrupt the operation of the specialized VFSes
736
** that do require it.
738
#define SQLITE_FCNTL_LOCKSTATE 1
739
#define SQLITE_GET_LOCKPROXYFILE 2
740
#define SQLITE_SET_LOCKPROXYFILE 3
741
#define SQLITE_LAST_ERRNO 4
742
#define SQLITE_FCNTL_SIZE_HINT 5
743
#define SQLITE_FCNTL_CHUNK_SIZE 6
744
#define SQLITE_FCNTL_FILE_POINTER 7
745
#define SQLITE_FCNTL_SYNC_OMITTED 8
749
** CAPI3REF: Mutex Handle
751
** The mutex module within SQLite defines [sqlite3_mutex] to be an
752
** abstract type for a mutex object. The SQLite core never looks
753
** at the internal representation of an [sqlite3_mutex]. It only
754
** deals with pointers to the [sqlite3_mutex] object.
756
** Mutexes are created using [sqlite3_mutex_alloc()].
758
typedef struct sqlite3_mutex sqlite3_mutex;
761
** CAPI3REF: OS Interface Object
763
** An instance of the sqlite3_vfs object defines the interface between
764
** the SQLite core and the underlying operating system. The "vfs"
765
** in the name of the object stands for "virtual file system".
767
** The value of the iVersion field is initially 1 but may be larger in
768
** future versions of SQLite. Additional fields may be appended to this
769
** object when the iVersion value is increased. Note that the structure
770
** of the sqlite3_vfs object changes in the transaction between
771
** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
774
** The szOsFile field is the size of the subclassed [sqlite3_file]
775
** structure used by this VFS. mxPathname is the maximum length of
776
** a pathname in this VFS.
778
** Registered sqlite3_vfs objects are kept on a linked list formed by
779
** the pNext pointer. The [sqlite3_vfs_register()]
780
** and [sqlite3_vfs_unregister()] interfaces manage this list
781
** in a thread-safe way. The [sqlite3_vfs_find()] interface
782
** searches the list. Neither the application code nor the VFS
783
** implementation should use the pNext pointer.
785
** The pNext field is the only field in the sqlite3_vfs
786
** structure that SQLite will ever modify. SQLite will only access
787
** or modify this field while holding a particular static mutex.
788
** The application should never modify anything within the sqlite3_vfs
789
** object once the object has been registered.
791
** The zName field holds the name of the VFS module. The name must
792
** be unique across all VFS modules.
794
** ^SQLite guarantees that the zFilename parameter to xOpen
795
** is either a NULL pointer or string obtained
796
** from xFullPathname() with an optional suffix added.
797
** ^If a suffix is added to the zFilename parameter, it will
798
** consist of a single "-" character followed by no more than
799
** 10 alphanumeric and/or "-" characters.
800
** ^SQLite further guarantees that
801
** the string will be valid and unchanged until xClose() is
802
** called. Because of the previous sentence,
803
** the [sqlite3_file] can safely store a pointer to the
804
** filename if it needs to remember the filename for some reason.
805
** If the zFilename parameter to xOpen is a NULL pointer then xOpen
806
** must invent its own temporary name for the file. ^Whenever the
807
** xFilename parameter is NULL it will also be the case that the
808
** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
810
** The flags argument to xOpen() includes all bits set in
811
** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
812
** or [sqlite3_open16()] is used, then flags includes at least
813
** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
814
** If xOpen() opens a file read-only then it sets *pOutFlags to
815
** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set.
817
** ^(SQLite will also add one of the following flags to the xOpen()
818
** call, depending on the object being opened:
821
** <li> [SQLITE_OPEN_MAIN_DB]
822
** <li> [SQLITE_OPEN_MAIN_JOURNAL]
823
** <li> [SQLITE_OPEN_TEMP_DB]
824
** <li> [SQLITE_OPEN_TEMP_JOURNAL]
825
** <li> [SQLITE_OPEN_TRANSIENT_DB]
826
** <li> [SQLITE_OPEN_SUBJOURNAL]
827
** <li> [SQLITE_OPEN_MASTER_JOURNAL]
828
** <li> [SQLITE_OPEN_WAL]
831
** The file I/O implementation can use the object type flags to
832
** change the way it deals with files. For example, an application
833
** that does not care about crash recovery or rollback might make
834
** the open of a journal file a no-op. Writes to this journal would
835
** also be no-ops, and any attempt to read the journal would return
836
** SQLITE_IOERR. Or the implementation might recognize that a database
837
** file will be doing page-aligned sector reads and writes in a random
838
** order and set up its I/O subsystem accordingly.
840
** SQLite might also add one of the following flags to the xOpen method:
843
** <li> [SQLITE_OPEN_DELETEONCLOSE]
844
** <li> [SQLITE_OPEN_EXCLUSIVE]
847
** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
848
** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE]
849
** will be set for TEMP databases and their journals, transient
850
** databases, and subjournals.
852
** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
853
** with the [SQLITE_OPEN_CREATE] flag, which are both directly
854
** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
855
** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
856
** SQLITE_OPEN_CREATE, is used to indicate that file should always
857
** be created, and that it is an error if it already exists.
858
** It is <i>not</i> used to indicate the file should be opened
859
** for exclusive access.
861
** ^At least szOsFile bytes of memory are allocated by SQLite
862
** to hold the [sqlite3_file] structure passed as the third
863
** argument to xOpen. The xOpen method does not have to
864
** allocate the structure; it should just fill it in. Note that
865
** the xOpen method must set the sqlite3_file.pMethods to either
866
** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
867
** this even if the open fails. SQLite expects that the sqlite3_file.pMethods
868
** element will be valid after xOpen returns regardless of the success
869
** or failure of the xOpen call.
871
** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
872
** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
873
** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
874
** to test whether a file is at least readable. The file can be a
877
** ^SQLite will always allocate at least mxPathname+1 bytes for the
878
** output buffer xFullPathname. The exact size of the output buffer
879
** is also passed as a parameter to both methods. If the output buffer
880
** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
881
** handled as a fatal error by SQLite, vfs implementations should endeavor
882
** to prevent this by setting mxPathname to a sufficiently large value.
884
** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
885
** interfaces are not strictly a part of the filesystem, but they are
886
** included in the VFS structure for completeness.
887
** The xRandomness() function attempts to return nBytes bytes
888
** of good-quality randomness into zOut. The return value is
889
** the actual number of bytes of randomness obtained.
890
** The xSleep() method causes the calling thread to sleep for at
891
** least the number of microseconds given. ^The xCurrentTime()
892
** method returns a Julian Day Number for the current date and time as
893
** a floating point value.
894
** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
895
** Day Number multipled by 86400000 (the number of milliseconds in
897
** ^SQLite will use the xCurrentTimeInt64() method to get the current
898
** date and time if that method is available (if iVersion is 2 or
899
** greater and the function pointer is not NULL) and will fall back
900
** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
902
** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
903
** are not used by the SQLite core. These optional interfaces are provided
904
** by some VFSes to facilitate testing of the VFS code. By overriding
905
** system calls with functions under its control, a test program can
906
** simulate faults and error conditions that would otherwise be difficult
907
** or impossible to induce. The set of system calls that can be overridden
908
** varies from one VFS to another, and from one version of the same VFS to the
909
** next. Applications that use these interfaces must be prepared for any
910
** or all of these interfaces to be NULL or for their behavior to change
911
** from one release to the next. Applications must not attempt to access
912
** any of these methods if the iVersion of the VFS is less than 3.
914
typedef struct sqlite3_vfs sqlite3_vfs;
915
typedef void (*sqlite3_syscall_ptr)(void);
917
int iVersion; /* Structure version number (currently 3) */
918
int szOsFile; /* Size of subclassed sqlite3_file */
919
int mxPathname; /* Maximum file pathname length */
920
sqlite3_vfs *pNext; /* Next registered VFS */
921
const char *zName; /* Name of this virtual file system */
922
void *pAppData; /* Pointer to application-specific data */
923
int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
924
int flags, int *pOutFlags);
925
int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
926
int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
927
int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
928
void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
929
void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
930
void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
931
void (*xDlClose)(sqlite3_vfs*, void*);
932
int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
933
int (*xSleep)(sqlite3_vfs*, int microseconds);
934
int (*xCurrentTime)(sqlite3_vfs*, double*);
935
int (*xGetLastError)(sqlite3_vfs*, int, char *);
937
** The methods above are in version 1 of the sqlite_vfs object
938
** definition. Those that follow are added in version 2 or later
940
int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
942
** The methods above are in versions 1 and 2 of the sqlite_vfs object.
943
** Those below are for version 3 and greater.
945
int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
946
sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
947
const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
949
** The methods above are in versions 1 through 3 of the sqlite_vfs object.
950
** New fields may be appended in figure versions. The iVersion
951
** value will increment whenever this happens.
956
** CAPI3REF: Flags for the xAccess VFS method
958
** These integer constants can be used as the third parameter to
959
** the xAccess method of an [sqlite3_vfs] object. They determine
960
** what kind of permissions the xAccess method is looking for.
961
** With SQLITE_ACCESS_EXISTS, the xAccess method
962
** simply checks whether the file exists.
963
** With SQLITE_ACCESS_READWRITE, the xAccess method
964
** checks whether the named directory is both readable and writable
965
** (in other words, if files can be added, removed, and renamed within
967
** The SQLITE_ACCESS_READWRITE constant is currently used only by the
968
** [temp_store_directory pragma], though this could change in a future
969
** release of SQLite.
970
** With SQLITE_ACCESS_READ, the xAccess method
971
** checks whether the file is readable. The SQLITE_ACCESS_READ constant is
972
** currently unused, though it might be used in a future release of
975
#define SQLITE_ACCESS_EXISTS 0
976
#define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */
977
#define SQLITE_ACCESS_READ 2 /* Unused */
980
** CAPI3REF: Flags for the xShmLock VFS method
982
** These integer constants define the various locking operations
983
** allowed by the xShmLock method of [sqlite3_io_methods]. The
984
** following are the only legal combinations of flags to the
988
** <li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
989
** <li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
990
** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
991
** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
994
** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
995
** was given no the corresponding lock.
997
** The xShmLock method can transition between unlocked and SHARED or
998
** between unlocked and EXCLUSIVE. It cannot transition between SHARED
1001
#define SQLITE_SHM_UNLOCK 1
1002
#define SQLITE_SHM_LOCK 2
1003
#define SQLITE_SHM_SHARED 4
1004
#define SQLITE_SHM_EXCLUSIVE 8
1007
** CAPI3REF: Maximum xShmLock index
1009
** The xShmLock method on [sqlite3_io_methods] may use values
1010
** between 0 and this upper bound as its "offset" argument.
1011
** The SQLite core will never attempt to acquire or release a
1012
** lock outside of this range
1014
#define SQLITE_SHM_NLOCK 8
1018
** CAPI3REF: Initialize The SQLite Library
1020
** ^The sqlite3_initialize() routine initializes the
1021
** SQLite library. ^The sqlite3_shutdown() routine
1022
** deallocates any resources that were allocated by sqlite3_initialize().
1023
** These routines are designed to aid in process initialization and
1024
** shutdown on embedded systems. Workstation applications using
1025
** SQLite normally do not need to invoke either of these routines.
1027
** A call to sqlite3_initialize() is an "effective" call if it is
1028
** the first time sqlite3_initialize() is invoked during the lifetime of
1029
** the process, or if it is the first time sqlite3_initialize() is invoked
1030
** following a call to sqlite3_shutdown(). ^(Only an effective call
1031
** of sqlite3_initialize() does any initialization. All other calls
1032
** are harmless no-ops.)^
1034
** A call to sqlite3_shutdown() is an "effective" call if it is the first
1035
** call to sqlite3_shutdown() since the last sqlite3_initialize(). ^(Only
1036
** an effective call to sqlite3_shutdown() does any deinitialization.
1037
** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
1039
** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
1040
** is not. The sqlite3_shutdown() interface must only be called from a
1041
** single thread. All open [database connections] must be closed and all
1042
** other SQLite resources must be deallocated prior to invoking
1043
** sqlite3_shutdown().
1045
** Among other things, ^sqlite3_initialize() will invoke
1046
** sqlite3_os_init(). Similarly, ^sqlite3_shutdown()
1047
** will invoke sqlite3_os_end().
1049
** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
1050
** ^If for some reason, sqlite3_initialize() is unable to initialize
1051
** the library (perhaps it is unable to allocate a needed resource such
1052
** as a mutex) it returns an [error code] other than [SQLITE_OK].
1054
** ^The sqlite3_initialize() routine is called internally by many other
1055
** SQLite interfaces so that an application usually does not need to
1056
** invoke sqlite3_initialize() directly. For example, [sqlite3_open()]
1057
** calls sqlite3_initialize() so the SQLite library will be automatically
1058
** initialized when [sqlite3_open()] is called if it has not be initialized
1059
** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
1060
** compile-time option, then the automatic calls to sqlite3_initialize()
1061
** are omitted and the application must call sqlite3_initialize() directly
1062
** prior to using any other SQLite interface. For maximum portability,
1063
** it is recommended that applications always invoke sqlite3_initialize()
1064
** directly prior to using any other SQLite interface. Future releases
1065
** of SQLite may require this. In other words, the behavior exhibited
1066
** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
1067
** default behavior in some future release of SQLite.
1069
** The sqlite3_os_init() routine does operating-system specific
1070
** initialization of the SQLite library. The sqlite3_os_end()
1071
** routine undoes the effect of sqlite3_os_init(). Typical tasks
1072
** performed by these routines include allocation or deallocation
1073
** of static resources, initialization of global variables,
1074
** setting up a default [sqlite3_vfs] module, or setting up
1075
** a default configuration using [sqlite3_config()].
1077
** The application should never invoke either sqlite3_os_init()
1078
** or sqlite3_os_end() directly. The application should only invoke
1079
** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()
1080
** interface is called automatically by sqlite3_initialize() and
1081
** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
1082
** implementations for sqlite3_os_init() and sqlite3_os_end()
1083
** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
1084
** When [custom builds | built for other platforms]
1085
** (using the [SQLITE_OS_OTHER=1] compile-time
1086
** option) the application must supply a suitable implementation for
1087
** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
1088
** implementation of sqlite3_os_init() or sqlite3_os_end()
1089
** must return [SQLITE_OK] on success and some other [error code] upon
1092
SQLITE_API int sqlite3_initialize(void);
1093
SQLITE_API int sqlite3_shutdown(void);
1094
SQLITE_API int sqlite3_os_init(void);
1095
SQLITE_API int sqlite3_os_end(void);
1098
** CAPI3REF: Configuring The SQLite Library
1100
** The sqlite3_config() interface is used to make global configuration
1101
** changes to SQLite in order to tune SQLite to the specific needs of
1102
** the application. The default configuration is recommended for most
1103
** applications and so this routine is usually not necessary. It is
1104
** provided to support rare applications with unusual needs.
1106
** The sqlite3_config() interface is not threadsafe. The application
1107
** must insure that no other SQLite interfaces are invoked by other
1108
** threads while sqlite3_config() is running. Furthermore, sqlite3_config()
1109
** may only be invoked prior to library initialization using
1110
** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
1111
** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
1112
** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
1113
** Note, however, that ^sqlite3_config() can be called as part of the
1114
** implementation of an application-defined [sqlite3_os_init()].
1116
** The first argument to sqlite3_config() is an integer
1117
** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines
1118
** what property of SQLite is to be configured. Subsequent arguments
1119
** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option]
1120
** in the first argument.
1122
** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
1123
** ^If the option is unknown or SQLite is unable to set the option
1124
** then this routine returns a non-zero [error code].
1126
SQLITE_API int sqlite3_config(int, ...);
1129
** CAPI3REF: Configure database connections
1131
** The sqlite3_db_config() interface is used to make configuration
1132
** changes to a [database connection]. The interface is similar to
1133
** [sqlite3_config()] except that the changes apply to a single
1134
** [database connection] (specified in the first argument).
1136
** The second argument to sqlite3_db_config(D,V,...) is the
1137
** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code
1138
** that indicates what aspect of the [database connection] is being configured.
1139
** Subsequent arguments vary depending on the configuration verb.
1141
** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
1142
** the call is considered successful.
1144
SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
1147
** CAPI3REF: Memory Allocation Routines
1149
** An instance of this object defines the interface between SQLite
1150
** and low-level memory allocation routines.
1152
** This object is used in only one place in the SQLite interface.
1153
** A pointer to an instance of this object is the argument to
1154
** [sqlite3_config()] when the configuration option is
1155
** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
1156
** By creating an instance of this object
1157
** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
1158
** during configuration, an application can specify an alternative
1159
** memory allocation subsystem for SQLite to use for all of its
1160
** dynamic memory needs.
1162
** Note that SQLite comes with several [built-in memory allocators]
1163
** that are perfectly adequate for the overwhelming majority of applications
1164
** and that this object is only useful to a tiny minority of applications
1165
** with specialized memory allocation requirements. This object is
1166
** also used during testing of SQLite in order to specify an alternative
1167
** memory allocator that simulates memory out-of-memory conditions in
1168
** order to verify that SQLite recovers gracefully from such
1171
** The xMalloc and xFree methods must work like the
1172
** malloc() and free() functions from the standard C library.
1173
** The xRealloc method must work like realloc() from the standard C library
1174
** with the exception that if the second argument to xRealloc is zero,
1175
** xRealloc must be a no-op - it must not perform any allocation or
1176
** deallocation. ^SQLite guarantees that the second argument to
1177
** xRealloc is always a value returned by a prior call to xRoundup.
1178
** And so in cases where xRoundup always returns a positive number,
1179
** xRealloc can perform exactly as the standard library realloc() and
1180
** still be in compliance with this specification.
1182
** xSize should return the allocated size of a memory allocation
1183
** previously obtained from xMalloc or xRealloc. The allocated size
1184
** is always at least as big as the requested size but may be larger.
1186
** The xRoundup method returns what would be the allocated size of
1187
** a memory allocation given a particular requested size. Most memory
1188
** allocators round up memory allocations at least to the next multiple
1189
** of 8. Some allocators round up to a larger multiple or to a power of 2.
1190
** Every memory allocation request coming in through [sqlite3_malloc()]
1191
** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
1192
** that causes the corresponding memory allocation to fail.
1194
** The xInit method initializes the memory allocator. (For example,
1195
** it might allocate any require mutexes or initialize internal data
1196
** structures. The xShutdown method is invoked (indirectly) by
1197
** [sqlite3_shutdown()] and should deallocate any resources acquired
1198
** by xInit. The pAppData pointer is used as the only parameter to
1199
** xInit and xShutdown.
1201
** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
1202
** the xInit method, so the xInit method need not be threadsafe. The
1203
** xShutdown method is only called from [sqlite3_shutdown()] so it does
1204
** not need to be threadsafe either. For all other methods, SQLite
1205
** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
1206
** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
1207
** it is by default) and so the methods are automatically serialized.
1208
** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
1209
** methods must be threadsafe or else make their own arrangements for
1212
** SQLite will never invoke xInit() more than once without an intervening
1213
** call to xShutdown().
1215
typedef struct sqlite3_mem_methods sqlite3_mem_methods;
1216
struct sqlite3_mem_methods {
1217
void *(*xMalloc)(int); /* Memory allocation function */
1218
void (*xFree)(void*); /* Free a prior allocation */
1219
void *(*xRealloc)(void*,int); /* Resize an allocation */
1220
int (*xSize)(void*); /* Return the size of an allocation */
1221
int (*xRoundup)(int); /* Round up request size to allocation size */
1222
int (*xInit)(void*); /* Initialize the memory allocator */
1223
void (*xShutdown)(void*); /* Deinitialize the memory allocator */
1224
void *pAppData; /* Argument to xInit() and xShutdown() */
1228
** CAPI3REF: Configuration Options
1230
** These constants are the available integer configuration options that
1231
** can be passed as the first argument to the [sqlite3_config()] interface.
1233
** New configuration options may be added in future releases of SQLite.
1234
** Existing configuration options might be discontinued. Applications
1235
** should check the return code from [sqlite3_config()] to make sure that
1236
** the call worked. The [sqlite3_config()] interface will return a
1237
** non-zero [error code] if a discontinued or unsupported configuration option
1241
** <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
1242
** <dd>There are no arguments to this option. ^This option sets the
1243
** [threading mode] to Single-thread. In other words, it disables
1244
** all mutexing and puts SQLite into a mode where it can only be used
1245
** by a single thread. ^If SQLite is compiled with
1246
** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1247
** it is not possible to change the [threading mode] from its default
1248
** value of Single-thread and so [sqlite3_config()] will return
1249
** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
1250
** configuration option.</dd>
1252
** <dt>SQLITE_CONFIG_MULTITHREAD</dt>
1253
** <dd>There are no arguments to this option. ^This option sets the
1254
** [threading mode] to Multi-thread. In other words, it disables
1255
** mutexing on [database connection] and [prepared statement] objects.
1256
** The application is responsible for serializing access to
1257
** [database connections] and [prepared statements]. But other mutexes
1258
** are enabled so that SQLite will be safe to use in a multi-threaded
1259
** environment as long as no two threads attempt to use the same
1260
** [database connection] at the same time. ^If SQLite is compiled with
1261
** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1262
** it is not possible to set the Multi-thread [threading mode] and
1263
** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1264
** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
1266
** <dt>SQLITE_CONFIG_SERIALIZED</dt>
1267
** <dd>There are no arguments to this option. ^This option sets the
1268
** [threading mode] to Serialized. In other words, this option enables
1269
** all mutexes including the recursive
1270
** mutexes on [database connection] and [prepared statement] objects.
1271
** In this mode (which is the default when SQLite is compiled with
1272
** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
1273
** to [database connections] and [prepared statements] so that the
1274
** application is free to use the same [database connection] or the
1275
** same [prepared statement] in different threads at the same time.
1276
** ^If SQLite is compiled with
1277
** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1278
** it is not possible to set the Serialized [threading mode] and
1279
** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1280
** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
1282
** <dt>SQLITE_CONFIG_MALLOC</dt>
1283
** <dd> ^(This option takes a single argument which is a pointer to an
1284
** instance of the [sqlite3_mem_methods] structure. The argument specifies
1285
** alternative low-level memory allocation routines to be used in place of
1286
** the memory allocation routines built into SQLite.)^ ^SQLite makes
1287
** its own private copy of the content of the [sqlite3_mem_methods] structure
1288
** before the [sqlite3_config()] call returns.</dd>
1290
** <dt>SQLITE_CONFIG_GETMALLOC</dt>
1291
** <dd> ^(This option takes a single argument which is a pointer to an
1292
** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods]
1293
** structure is filled with the currently defined memory allocation routines.)^
1294
** This option can be used to overload the default memory allocation
1295
** routines with a wrapper that simulations memory allocation failure or
1296
** tracks memory usage, for example. </dd>
1298
** <dt>SQLITE_CONFIG_MEMSTATUS</dt>
1299
** <dd> ^This option takes single argument of type int, interpreted as a
1300
** boolean, which enables or disables the collection of memory allocation
1301
** statistics. ^(When memory allocation statistics are disabled, the
1302
** following SQLite interfaces become non-operational:
1304
** <li> [sqlite3_memory_used()]
1305
** <li> [sqlite3_memory_highwater()]
1306
** <li> [sqlite3_soft_heap_limit64()]
1307
** <li> [sqlite3_status()]
1309
** ^Memory allocation statistics are enabled by default unless SQLite is
1310
** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
1311
** allocation statistics are disabled by default.
1314
** <dt>SQLITE_CONFIG_SCRATCH</dt>
1315
** <dd> ^This option specifies a static memory buffer that SQLite can use for
1316
** scratch memory. There are three arguments: A pointer an 8-byte
1317
** aligned memory buffer from which the scratch allocations will be
1318
** drawn, the size of each scratch allocation (sz),
1319
** and the maximum number of scratch allocations (N). The sz
1320
** argument must be a multiple of 16.
1321
** The first argument must be a pointer to an 8-byte aligned buffer
1322
** of at least sz*N bytes of memory.
1323
** ^SQLite will use no more than two scratch buffers per thread. So
1324
** N should be set to twice the expected maximum number of threads.
1325
** ^SQLite will never require a scratch buffer that is more than 6
1326
** times the database page size. ^If SQLite needs needs additional
1327
** scratch memory beyond what is provided by this configuration option, then
1328
** [sqlite3_malloc()] will be used to obtain the memory needed.</dd>
1330
** <dt>SQLITE_CONFIG_PAGECACHE</dt>
1331
** <dd> ^This option specifies a static memory buffer that SQLite can use for
1332
** the database page cache with the default page cache implemenation.
1333
** This configuration should not be used if an application-define page
1334
** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option.
1335
** There are three arguments to this option: A pointer to 8-byte aligned
1336
** memory, the size of each page buffer (sz), and the number of pages (N).
1337
** The sz argument should be the size of the largest database page
1338
** (a power of two between 512 and 32768) plus a little extra for each
1339
** page header. ^The page header size is 20 to 40 bytes depending on
1340
** the host architecture. ^It is harmless, apart from the wasted memory,
1341
** to make sz a little too large. The first
1342
** argument should point to an allocation of at least sz*N bytes of memory.
1343
** ^SQLite will use the memory provided by the first argument to satisfy its
1344
** memory needs for the first N pages that it adds to cache. ^If additional
1345
** page cache memory is needed beyond what is provided by this option, then
1346
** SQLite goes to [sqlite3_malloc()] for the additional storage space.
1347
** The pointer in the first argument must
1348
** be aligned to an 8-byte boundary or subsequent behavior of SQLite
1349
** will be undefined.</dd>
1351
** <dt>SQLITE_CONFIG_HEAP</dt>
1352
** <dd> ^This option specifies a static memory buffer that SQLite will use
1353
** for all of its dynamic memory allocation needs beyond those provided
1354
** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
1355
** There are three arguments: An 8-byte aligned pointer to the memory,
1356
** the number of bytes in the memory buffer, and the minimum allocation size.
1357
** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
1358
** to using its default memory allocator (the system malloc() implementation),
1359
** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the
1360
** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
1361
** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory
1362
** allocator is engaged to handle all of SQLites memory allocation needs.
1363
** The first pointer (the memory pointer) must be aligned to an 8-byte
1364
** boundary or subsequent behavior of SQLite will be undefined.
1365
** The minimum allocation size is capped at 2^12. Reasonable values
1366
** for the minimum allocation size are 2^5 through 2^8.</dd>
1368
** <dt>SQLITE_CONFIG_MUTEX</dt>
1369
** <dd> ^(This option takes a single argument which is a pointer to an
1370
** instance of the [sqlite3_mutex_methods] structure. The argument specifies
1371
** alternative low-level mutex routines to be used in place
1372
** the mutex routines built into SQLite.)^ ^SQLite makes a copy of the
1373
** content of the [sqlite3_mutex_methods] structure before the call to
1374
** [sqlite3_config()] returns. ^If SQLite is compiled with
1375
** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1376
** the entire mutexing subsystem is omitted from the build and hence calls to
1377
** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
1378
** return [SQLITE_ERROR].</dd>
1380
** <dt>SQLITE_CONFIG_GETMUTEX</dt>
1381
** <dd> ^(This option takes a single argument which is a pointer to an
1382
** instance of the [sqlite3_mutex_methods] structure. The
1383
** [sqlite3_mutex_methods]
1384
** structure is filled with the currently defined mutex routines.)^
1385
** This option can be used to overload the default mutex allocation
1386
** routines with a wrapper used to track mutex usage for performance
1387
** profiling or testing, for example. ^If SQLite is compiled with
1388
** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1389
** the entire mutexing subsystem is omitted from the build and hence calls to
1390
** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
1391
** return [SQLITE_ERROR].</dd>
1393
** <dt>SQLITE_CONFIG_LOOKASIDE</dt>
1394
** <dd> ^(This option takes two arguments that determine the default
1395
** memory allocation for the lookaside memory allocator on each
1396
** [database connection]. The first argument is the
1397
** size of each lookaside buffer slot and the second is the number of
1398
** slots allocated to each database connection.)^ ^(This option sets the
1399
** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
1400
** verb to [sqlite3_db_config()] can be used to change the lookaside
1401
** configuration on individual connections.)^ </dd>
1403
** <dt>SQLITE_CONFIG_PCACHE</dt>
1404
** <dd> ^(This option takes a single argument which is a pointer to
1405
** an [sqlite3_pcache_methods] object. This object specifies the interface
1406
** to a custom page cache implementation.)^ ^SQLite makes a copy of the
1407
** object and uses it for page cache memory allocations.</dd>
1409
** <dt>SQLITE_CONFIG_GETPCACHE</dt>
1410
** <dd> ^(This option takes a single argument which is a pointer to an
1411
** [sqlite3_pcache_methods] object. SQLite copies of the current
1412
** page cache implementation into that object.)^ </dd>
1414
** <dt>SQLITE_CONFIG_LOG</dt>
1415
** <dd> ^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
1416
** function with a call signature of void(*)(void*,int,const char*),
1417
** and a pointer to void. ^If the function pointer is not NULL, it is
1418
** invoked by [sqlite3_log()] to process each logging event. ^If the
1419
** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
1420
** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
1421
** passed through as the first parameter to the application-defined logger
1422
** function whenever that function is invoked. ^The second parameter to
1423
** the logger function is a copy of the first parameter to the corresponding
1424
** [sqlite3_log()] call and is intended to be a [result code] or an
1425
** [extended result code]. ^The third parameter passed to the logger is
1426
** log message after formatting via [sqlite3_snprintf()].
1427
** The SQLite logging interface is not reentrant; the logger function
1428
** supplied by the application must not invoke any SQLite interface.
1429
** In a multi-threaded application, the application-defined logger
1430
** function must be threadsafe. </dd>
1434
#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
1435
#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
1436
#define SQLITE_CONFIG_SERIALIZED 3 /* nil */
1437
#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
1438
#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
1439
#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */
1440
#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
1441
#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
1442
#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
1443
#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
1444
#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
1445
/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
1446
#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
1447
#define SQLITE_CONFIG_PCACHE 14 /* sqlite3_pcache_methods* */
1448
#define SQLITE_CONFIG_GETPCACHE 15 /* sqlite3_pcache_methods* */
1449
#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
1452
** CAPI3REF: Database Connection Configuration Options
1454
** These constants are the available integer configuration options that
1455
** can be passed as the second argument to the [sqlite3_db_config()] interface.
1457
** New configuration options may be added in future releases of SQLite.
1458
** Existing configuration options might be discontinued. Applications
1459
** should check the return code from [sqlite3_db_config()] to make sure that
1460
** the call worked. ^The [sqlite3_db_config()] interface will return a
1461
** non-zero [error code] if a discontinued or unsupported configuration option
1465
** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
1466
** <dd> ^This option takes three additional arguments that determine the
1467
** [lookaside memory allocator] configuration for the [database connection].
1468
** ^The first argument (the third parameter to [sqlite3_db_config()] is a
1469
** pointer to a memory buffer to use for lookaside memory.
1470
** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
1471
** may be NULL in which case SQLite will allocate the
1472
** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
1473
** size of each lookaside buffer slot. ^The third argument is the number of
1474
** slots. The size of the buffer in the first argument must be greater than
1475
** or equal to the product of the second and third arguments. The buffer
1476
** must be aligned to an 8-byte boundary. ^If the second argument to
1477
** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
1478
** rounded down to the next smaller multiple of 8. ^(The lookaside memory
1479
** configuration for a database connection can only be changed when that
1480
** connection is not currently using lookaside memory, or in other words
1481
** when the "current value" returned by
1482
** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
1483
** Any attempt to change the lookaside memory configuration when lookaside
1484
** memory is in use leaves the configuration unchanged and returns
1485
** [SQLITE_BUSY].)^</dd>
1487
** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
1488
** <dd> ^This option is used to enable or disable the enforcement of
1489
** [foreign key constraints]. There should be two additional arguments.
1490
** The first argument is an integer which is 0 to disable FK enforcement,
1491
** positive to enable FK enforcement or negative to leave FK enforcement
1492
** unchanged. The second parameter is a pointer to an integer into which
1493
** is written 0 or 1 to indicate whether FK enforcement is off or on
1494
** following this call. The second parameter may be a NULL pointer, in
1495
** which case the FK enforcement setting is not reported back. </dd>
1497
** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
1498
** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
1499
** There should be two additional arguments.
1500
** The first argument is an integer which is 0 to disable triggers,
1501
** positive to enable triggers or negative to leave the setting unchanged.
1502
** The second parameter is a pointer to an integer into which
1503
** is written 0 or 1 to indicate whether triggers are disabled or enabled
1504
** following this call. The second parameter may be a NULL pointer, in
1505
** which case the trigger setting is not reported back. </dd>
1509
#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
1510
#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
1511
#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
1515
** CAPI3REF: Enable Or Disable Extended Result Codes
1517
** ^The sqlite3_extended_result_codes() routine enables or disables the
1518
** [extended result codes] feature of SQLite. ^The extended result
1519
** codes are disabled by default for historical compatibility.
1521
SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
1524
** CAPI3REF: Last Insert Rowid
1526
** ^Each entry in an SQLite table has a unique 64-bit signed
1527
** integer key called the [ROWID | "rowid"]. ^The rowid is always available
1528
** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
1529
** names are not also used by explicitly declared columns. ^If
1530
** the table has a column of type [INTEGER PRIMARY KEY] then that column
1531
** is another alias for the rowid.
1533
** ^This routine returns the [rowid] of the most recent
1534
** successful [INSERT] into the database from the [database connection]
1535
** in the first argument. ^If no successful [INSERT]s
1536
** have ever occurred on that database connection, zero is returned.
1538
** ^(If an [INSERT] occurs within a trigger, then the [rowid] of the inserted
1539
** row is returned by this routine as long as the trigger is running.
1540
** But once the trigger terminates, the value returned by this routine
1541
** reverts to the last value inserted before the trigger fired.)^
1543
** ^An [INSERT] that fails due to a constraint violation is not a
1544
** successful [INSERT] and does not change the value returned by this
1545
** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
1546
** and INSERT OR ABORT make no changes to the return value of this
1547
** routine when their insertion fails. ^(When INSERT OR REPLACE
1548
** encounters a constraint violation, it does not fail. The
1549
** INSERT continues to completion after deleting rows that caused
1550
** the constraint problem so INSERT OR REPLACE will always change
1551
** the return value of this interface.)^
1553
** ^For the purposes of this routine, an [INSERT] is considered to
1554
** be successful even if it is subsequently rolled back.
1556
** This function is accessible to SQL statements via the
1557
** [last_insert_rowid() SQL function].
1559
** If a separate thread performs a new [INSERT] on the same
1560
** database connection while the [sqlite3_last_insert_rowid()]
1561
** function is running and thus changes the last insert [rowid],
1562
** then the value returned by [sqlite3_last_insert_rowid()] is
1563
** unpredictable and might not equal either the old or the new
1564
** last insert [rowid].
1566
SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
1569
** CAPI3REF: Count The Number Of Rows Modified
1571
** ^This function returns the number of database rows that were changed
1572
** or inserted or deleted by the most recently completed SQL statement
1573
** on the [database connection] specified by the first parameter.
1574
** ^(Only changes that are directly specified by the [INSERT], [UPDATE],
1575
** or [DELETE] statement are counted. Auxiliary changes caused by
1576
** triggers or [foreign key actions] are not counted.)^ Use the
1577
** [sqlite3_total_changes()] function to find the total number of changes
1578
** including changes caused by triggers and foreign key actions.
1580
** ^Changes to a view that are simulated by an [INSTEAD OF trigger]
1581
** are not counted. Only real table changes are counted.
1583
** ^(A "row change" is a change to a single row of a single table
1584
** caused by an INSERT, DELETE, or UPDATE statement. Rows that
1585
** are changed as side effects of [REPLACE] constraint resolution,
1586
** rollback, ABORT processing, [DROP TABLE], or by any other
1587
** mechanisms do not count as direct row changes.)^
1589
** A "trigger context" is a scope of execution that begins and
1590
** ends with the script of a [CREATE TRIGGER | trigger].
1591
** Most SQL statements are
1592
** evaluated outside of any trigger. This is the "top level"
1593
** trigger context. If a trigger fires from the top level, a
1594
** new trigger context is entered for the duration of that one
1595
** trigger. Subtriggers create subcontexts for their duration.
1597
** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
1598
** not create a new trigger context.
1600
** ^This function returns the number of direct row changes in the
1601
** most recent INSERT, UPDATE, or DELETE statement within the same
1604
** ^Thus, when called from the top level, this function returns the
1605
** number of changes in the most recent INSERT, UPDATE, or DELETE
1606
** that also occurred at the top level. ^(Within the body of a trigger,
1607
** the sqlite3_changes() interface can be called to find the number of
1608
** changes in the most recently completed INSERT, UPDATE, or DELETE
1609
** statement within the body of the same trigger.
1610
** However, the number returned does not include changes
1611
** caused by subtriggers since those have their own context.)^
1613
** See also the [sqlite3_total_changes()] interface, the
1614
** [count_changes pragma], and the [changes() SQL function].
1616
** If a separate thread makes changes on the same database connection
1617
** while [sqlite3_changes()] is running then the value returned
1618
** is unpredictable and not meaningful.
1620
SQLITE_API int sqlite3_changes(sqlite3*);
1623
** CAPI3REF: Total Number Of Rows Modified
1625
** ^This function returns the number of row changes caused by [INSERT],
1626
** [UPDATE] or [DELETE] statements since the [database connection] was opened.
1627
** ^(The count returned by sqlite3_total_changes() includes all changes
1628
** from all [CREATE TRIGGER | trigger] contexts and changes made by
1629
** [foreign key actions]. However,
1630
** the count does not include changes used to implement [REPLACE] constraints,
1631
** do rollbacks or ABORT processing, or [DROP TABLE] processing. The
1632
** count does not include rows of views that fire an [INSTEAD OF trigger],
1633
** though if the INSTEAD OF trigger makes changes of its own, those changes
1635
** ^The sqlite3_total_changes() function counts the changes as soon as
1636
** the statement that makes them is completed (when the statement handle
1637
** is passed to [sqlite3_reset()] or [sqlite3_finalize()]).
1639
** See also the [sqlite3_changes()] interface, the
1640
** [count_changes pragma], and the [total_changes() SQL function].
1642
** If a separate thread makes changes on the same database connection
1643
** while [sqlite3_total_changes()] is running then the value
1644
** returned is unpredictable and not meaningful.
1646
SQLITE_API int sqlite3_total_changes(sqlite3*);
1649
** CAPI3REF: Interrupt A Long-Running Query
1651
** ^This function causes any pending database operation to abort and
1652
** return at its earliest opportunity. This routine is typically
1653
** called in response to a user action such as pressing "Cancel"
1654
** or Ctrl-C where the user wants a long query operation to halt
1657
** ^It is safe to call this routine from a thread different from the
1658
** thread that is currently running the database operation. But it
1659
** is not safe to call this routine with a [database connection] that
1660
** is closed or might close before sqlite3_interrupt() returns.
1662
** ^If an SQL operation is very nearly finished at the time when
1663
** sqlite3_interrupt() is called, then it might not have an opportunity
1664
** to be interrupted and might continue to completion.
1666
** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
1667
** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
1668
** that is inside an explicit transaction, then the entire transaction
1669
** will be rolled back automatically.
1671
** ^The sqlite3_interrupt(D) call is in effect until all currently running
1672
** SQL statements on [database connection] D complete. ^Any new SQL statements
1673
** that are started after the sqlite3_interrupt() call and before the
1674
** running statements reaches zero are interrupted as if they had been
1675
** running prior to the sqlite3_interrupt() call. ^New SQL statements
1676
** that are started after the running statement count reaches zero are
1677
** not effected by the sqlite3_interrupt().
1678
** ^A call to sqlite3_interrupt(D) that occurs when there are no running
1679
** SQL statements is a no-op and has no effect on SQL statements
1680
** that are started after the sqlite3_interrupt() call returns.
1682
** If the database connection closes while [sqlite3_interrupt()]
1683
** is running then bad things will likely happen.
1685
SQLITE_API void sqlite3_interrupt(sqlite3*);
1688
** CAPI3REF: Determine If An SQL Statement Is Complete
1690
** These routines are useful during command-line input to determine if the
1691
** currently entered text seems to form a complete SQL statement or
1692
** if additional input is needed before sending the text into
1693
** SQLite for parsing. ^These routines return 1 if the input string
1694
** appears to be a complete SQL statement. ^A statement is judged to be
1695
** complete if it ends with a semicolon token and is not a prefix of a
1696
** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within
1697
** string literals or quoted identifier names or comments are not
1698
** independent tokens (they are part of the token in which they are
1699
** embedded) and thus do not count as a statement terminator. ^Whitespace
1700
** and comments that follow the final semicolon are ignored.
1702
** ^These routines return 0 if the statement is incomplete. ^If a
1703
** memory allocation fails, then SQLITE_NOMEM is returned.
1705
** ^These routines do not parse the SQL statements thus
1706
** will not detect syntactically incorrect SQL.
1708
** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior
1709
** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
1710
** automatically by sqlite3_complete16(). If that initialization fails,
1711
** then the return value from sqlite3_complete16() will be non-zero
1712
** regardless of whether or not the input SQL is complete.)^
1714
** The input to [sqlite3_complete()] must be a zero-terminated
1717
** The input to [sqlite3_complete16()] must be a zero-terminated
1718
** UTF-16 string in native byte order.
1720
SQLITE_API int sqlite3_complete(const char *sql);
1721
SQLITE_API int sqlite3_complete16(const void *sql);
1724
** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
1726
** ^This routine sets a callback function that might be invoked whenever
1727
** an attempt is made to open a database table that another thread
1728
** or process has locked.
1730
** ^If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]
1731
** is returned immediately upon encountering the lock. ^If the busy callback
1732
** is not NULL, then the callback might be invoked with two arguments.
1734
** ^The first argument to the busy handler is a copy of the void* pointer which
1735
** is the third argument to sqlite3_busy_handler(). ^The second argument to
1736
** the busy handler callback is the number of times that the busy handler has
1737
** been invoked for this locking event. ^If the
1738
** busy callback returns 0, then no additional attempts are made to
1739
** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
1740
** ^If the callback returns non-zero, then another attempt
1741
** is made to open the database for reading and the cycle repeats.
1743
** The presence of a busy handler does not guarantee that it will be invoked
1744
** when there is lock contention. ^If SQLite determines that invoking the busy
1745
** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
1746
** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler.
1747
** Consider a scenario where one process is holding a read lock that
1748
** it is trying to promote to a reserved lock and
1749
** a second process is holding a reserved lock that it is trying
1750
** to promote to an exclusive lock. The first process cannot proceed
1751
** because it is blocked by the second and the second process cannot
1752
** proceed because it is blocked by the first. If both processes
1753
** invoke the busy handlers, neither will make any progress. Therefore,
1754
** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
1755
** will induce the first process to release its read lock and allow
1756
** the second process to proceed.
1758
** ^The default busy callback is NULL.
1760
** ^The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
1761
** when SQLite is in the middle of a large transaction where all the
1762
** changes will not fit into the in-memory cache. SQLite will
1763
** already hold a RESERVED lock on the database file, but it needs
1764
** to promote this lock to EXCLUSIVE so that it can spill cache
1765
** pages into the database file without harm to concurrent
1766
** readers. ^If it is unable to promote the lock, then the in-memory
1767
** cache will be left in an inconsistent state and so the error
1768
** code is promoted from the relatively benign [SQLITE_BUSY] to
1769
** the more severe [SQLITE_IOERR_BLOCKED]. ^This error code promotion
1770
** forces an automatic rollback of the changes. See the
1771
** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">
1772
** CorruptionFollowingBusyError</a> wiki page for a discussion of why
1773
** this is important.
1775
** ^(There can only be a single busy handler defined for each
1776
** [database connection]. Setting a new busy handler clears any
1777
** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
1778
** will also set or clear the busy handler.
1780
** The busy callback should not take any actions which modify the
1781
** database connection that invoked the busy handler. Any such actions
1782
** result in undefined behavior.
1784
** A busy handler must not close the database connection
1785
** or [prepared statement] that invoked the busy handler.
1787
SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
1790
** CAPI3REF: Set A Busy Timeout
1792
** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
1793
** for a specified amount of time when a table is locked. ^The handler
1794
** will sleep multiple times until at least "ms" milliseconds of sleeping
1795
** have accumulated. ^After at least "ms" milliseconds of sleeping,
1796
** the handler returns 0 which causes [sqlite3_step()] to return
1797
** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
1799
** ^Calling this routine with an argument less than or equal to zero
1800
** turns off all busy handlers.
1802
** ^(There can only be a single busy handler for a particular
1803
** [database connection] any any given moment. If another busy handler
1804
** was defined (using [sqlite3_busy_handler()]) prior to calling
1805
** this routine, that other busy handler is cleared.)^
1807
SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
1810
** CAPI3REF: Convenience Routines For Running Queries
1812
** This is a legacy interface that is preserved for backwards compatibility.
1813
** Use of this interface is not recommended.
1815
** Definition: A <b>result table</b> is memory data structure created by the
1816
** [sqlite3_get_table()] interface. A result table records the
1817
** complete query results from one or more queries.
1819
** The table conceptually has a number of rows and columns. But
1820
** these numbers are not part of the result table itself. These
1821
** numbers are obtained separately. Let N be the number of rows
1822
** and M be the number of columns.
1824
** A result table is an array of pointers to zero-terminated UTF-8 strings.
1825
** There are (N+1)*M elements in the array. The first M pointers point
1826
** to zero-terminated strings that contain the names of the columns.
1827
** The remaining entries all point to query results. NULL values result
1828
** in NULL pointers. All other values are in their UTF-8 zero-terminated
1829
** string representation as returned by [sqlite3_column_text()].
1831
** A result table might consist of one or more memory allocations.
1832
** It is not safe to pass a result table directly to [sqlite3_free()].
1833
** A result table should be deallocated using [sqlite3_free_table()].
1835
** ^(As an example of the result table format, suppose a query result
1838
** <blockquote><pre>
1840
** -----------------------
1844
** </pre></blockquote>
1846
** There are two column (M==2) and three rows (N==3). Thus the
1847
** result table has 8 entries. Suppose the result table is stored
1848
** in an array names azResult. Then azResult holds this content:
1850
** <blockquote><pre>
1851
** azResult[0] = "Name";
1852
** azResult[1] = "Age";
1853
** azResult[2] = "Alice";
1854
** azResult[3] = "43";
1855
** azResult[4] = "Bob";
1856
** azResult[5] = "28";
1857
** azResult[6] = "Cindy";
1858
** azResult[7] = "21";
1859
** </pre></blockquote>)^
1861
** ^The sqlite3_get_table() function evaluates one or more
1862
** semicolon-separated SQL statements in the zero-terminated UTF-8
1863
** string of its 2nd parameter and returns a result table to the
1864
** pointer given in its 3rd parameter.
1866
** After the application has finished with the result from sqlite3_get_table(),
1867
** it must pass the result table pointer to sqlite3_free_table() in order to
1868
** release the memory that was malloced. Because of the way the
1869
** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
1870
** function must not try to call [sqlite3_free()] directly. Only
1871
** [sqlite3_free_table()] is able to release the memory properly and safely.
1873
** The sqlite3_get_table() interface is implemented as a wrapper around
1874
** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
1875
** to any internal data structures of SQLite. It uses only the public
1876
** interface defined here. As a consequence, errors that occur in the
1877
** wrapper layer outside of the internal [sqlite3_exec()] call are not
1878
** reflected in subsequent calls to [sqlite3_errcode()] or
1879
** [sqlite3_errmsg()].
1881
SQLITE_API int sqlite3_get_table(
1882
sqlite3 *db, /* An open database */
1883
const char *zSql, /* SQL to be evaluated */
1884
char ***pazResult, /* Results of the query */
1885
int *pnRow, /* Number of result rows written here */
1886
int *pnColumn, /* Number of result columns written here */
1887
char **pzErrmsg /* Error msg written here */
1889
SQLITE_API void sqlite3_free_table(char **result);
1892
** CAPI3REF: Formatted String Printing Functions
1894
** These routines are work-alikes of the "printf()" family of functions
1895
** from the standard C library.
1897
** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
1898
** results into memory obtained from [sqlite3_malloc()].
1899
** The strings returned by these two routines should be
1900
** released by [sqlite3_free()]. ^Both routines return a
1901
** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
1902
** memory to hold the resulting string.
1904
** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
1905
** the standard C library. The result is written into the
1906
** buffer supplied as the second parameter whose size is given by
1907
** the first parameter. Note that the order of the
1908
** first two parameters is reversed from snprintf().)^ This is an
1909
** historical accident that cannot be fixed without breaking
1910
** backwards compatibility. ^(Note also that sqlite3_snprintf()
1911
** returns a pointer to its buffer instead of the number of
1912
** characters actually written into the buffer.)^ We admit that
1913
** the number of characters written would be a more useful return
1914
** value but we cannot change the implementation of sqlite3_snprintf()
1915
** now without breaking compatibility.
1917
** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
1918
** guarantees that the buffer is always zero-terminated. ^The first
1919
** parameter "n" is the total size of the buffer, including space for
1920
** the zero terminator. So the longest string that can be completely
1921
** written will be n-1 characters.
1923
** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
1925
** These routines all implement some additional formatting
1926
** options that are useful for constructing SQL statements.
1927
** All of the usual printf() formatting options apply. In addition, there
1928
** is are "%q", "%Q", and "%z" options.
1930
** ^(The %q option works like %s in that it substitutes a null-terminated
1931
** string from the argument list. But %q also doubles every '\'' character.
1932
** %q is designed for use inside a string literal.)^ By doubling each '\''
1933
** character it escapes that character and allows it to be inserted into
1936
** For example, assume the string variable zText contains text as follows:
1938
** <blockquote><pre>
1939
** char *zText = "It's a happy day!";
1940
** </pre></blockquote>
1942
** One can use this text in an SQL statement as follows:
1944
** <blockquote><pre>
1945
** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
1946
** sqlite3_exec(db, zSQL, 0, 0, 0);
1947
** sqlite3_free(zSQL);
1948
** </pre></blockquote>
1950
** Because the %q format string is used, the '\'' character in zText
1951
** is escaped and the SQL generated is as follows:
1953
** <blockquote><pre>
1954
** INSERT INTO table1 VALUES('It''s a happy day!')
1955
** </pre></blockquote>
1957
** This is correct. Had we used %s instead of %q, the generated SQL
1958
** would have looked like this:
1960
** <blockquote><pre>
1961
** INSERT INTO table1 VALUES('It's a happy day!');
1962
** </pre></blockquote>
1964
** This second example is an SQL syntax error. As a general rule you should
1965
** always use %q instead of %s when inserting text into a string literal.
1967
** ^(The %Q option works like %q except it also adds single quotes around
1968
** the outside of the total string. Additionally, if the parameter in the
1969
** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
1970
** single quotes).)^ So, for example, one could say:
1972
** <blockquote><pre>
1973
** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
1974
** sqlite3_exec(db, zSQL, 0, 0, 0);
1975
** sqlite3_free(zSQL);
1976
** </pre></blockquote>
1978
** The code above will render a correct SQL statement in the zSQL
1979
** variable even if the zText variable is a NULL pointer.
1981
** ^(The "%z" formatting option works like "%s" but with the
1982
** addition that after the string has been read and copied into
1983
** the result, [sqlite3_free()] is called on the input string.)^
1985
SQLITE_API char *sqlite3_mprintf(const char*,...);
1986
SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
1987
SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
1988
SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
1991
** CAPI3REF: Memory Allocation Subsystem
1993
** The SQLite core uses these three routines for all of its own
1994
** internal memory allocation needs. "Core" in the previous sentence
1995
** does not include operating-system specific VFS implementation. The
1996
** Windows VFS uses native malloc() and free() for some operations.
1998
** ^The sqlite3_malloc() routine returns a pointer to a block
1999
** of memory at least N bytes in length, where N is the parameter.
2000
** ^If sqlite3_malloc() is unable to obtain sufficient free
2001
** memory, it returns a NULL pointer. ^If the parameter N to
2002
** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
2005
** ^Calling sqlite3_free() with a pointer previously returned
2006
** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
2007
** that it might be reused. ^The sqlite3_free() routine is
2008
** a no-op if is called with a NULL pointer. Passing a NULL pointer
2009
** to sqlite3_free() is harmless. After being freed, memory
2010
** should neither be read nor written. Even reading previously freed
2011
** memory might result in a segmentation fault or other severe error.
2012
** Memory corruption, a segmentation fault, or other severe error
2013
** might result if sqlite3_free() is called with a non-NULL pointer that
2014
** was not obtained from sqlite3_malloc() or sqlite3_realloc().
2016
** ^(The sqlite3_realloc() interface attempts to resize a
2017
** prior memory allocation to be at least N bytes, where N is the
2018
** second parameter. The memory allocation to be resized is the first
2019
** parameter.)^ ^ If the first parameter to sqlite3_realloc()
2020
** is a NULL pointer then its behavior is identical to calling
2021
** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
2022
** ^If the second parameter to sqlite3_realloc() is zero or
2023
** negative then the behavior is exactly the same as calling
2024
** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
2025
** ^sqlite3_realloc() returns a pointer to a memory allocation
2026
** of at least N bytes in size or NULL if sufficient memory is unavailable.
2027
** ^If M is the size of the prior allocation, then min(N,M) bytes
2028
** of the prior allocation are copied into the beginning of buffer returned
2029
** by sqlite3_realloc() and the prior allocation is freed.
2030
** ^If sqlite3_realloc() returns NULL, then the prior allocation
2033
** ^The memory returned by sqlite3_malloc() and sqlite3_realloc()
2034
** is always aligned to at least an 8 byte boundary, or to a
2035
** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
2038
** In SQLite version 3.5.0 and 3.5.1, it was possible to define
2039
** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
2040
** implementation of these routines to be omitted. That capability
2041
** is no longer provided. Only built-in memory allocators can be used.
2043
** The Windows OS interface layer calls
2044
** the system malloc() and free() directly when converting
2045
** filenames between the UTF-8 encoding used by SQLite
2046
** and whatever filename encoding is used by the particular Windows
2047
** installation. Memory allocation errors are detected, but
2048
** they are reported back as [SQLITE_CANTOPEN] or
2049
** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
2051
** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
2052
** must be either NULL or else pointers obtained from a prior
2053
** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
2054
** not yet been released.
2056
** The application must not read or write any part of
2057
** a block of memory after it has been released using
2058
** [sqlite3_free()] or [sqlite3_realloc()].
2060
SQLITE_API void *sqlite3_malloc(int);
2061
SQLITE_API void *sqlite3_realloc(void*, int);
2062
SQLITE_API void sqlite3_free(void*);
2065
** CAPI3REF: Memory Allocator Statistics
2067
** SQLite provides these two interfaces for reporting on the status
2068
** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
2069
** routines, which form the built-in memory allocation subsystem.
2071
** ^The [sqlite3_memory_used()] routine returns the number of bytes
2072
** of memory currently outstanding (malloced but not freed).
2073
** ^The [sqlite3_memory_highwater()] routine returns the maximum
2074
** value of [sqlite3_memory_used()] since the high-water mark
2075
** was last reset. ^The values returned by [sqlite3_memory_used()] and
2076
** [sqlite3_memory_highwater()] include any overhead
2077
** added by SQLite in its implementation of [sqlite3_malloc()],
2078
** but not overhead added by the any underlying system library
2079
** routines that [sqlite3_malloc()] may call.
2081
** ^The memory high-water mark is reset to the current value of
2082
** [sqlite3_memory_used()] if and only if the parameter to
2083
** [sqlite3_memory_highwater()] is true. ^The value returned
2084
** by [sqlite3_memory_highwater(1)] is the high-water mark
2085
** prior to the reset.
2087
SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
2088
SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
2091
** CAPI3REF: Pseudo-Random Number Generator
2093
** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
2094
** select random [ROWID | ROWIDs] when inserting new records into a table that
2095
** already uses the largest possible [ROWID]. The PRNG is also used for
2096
** the build-in random() and randomblob() SQL functions. This interface allows
2097
** applications to access the same PRNG for other purposes.
2099
** ^A call to this routine stores N bytes of randomness into buffer P.
2101
** ^The first time this routine is invoked (either internally or by
2102
** the application) the PRNG is seeded using randomness obtained
2103
** from the xRandomness method of the default [sqlite3_vfs] object.
2104
** ^On all subsequent invocations, the pseudo-randomness is generated
2105
** internally and without recourse to the [sqlite3_vfs] xRandomness
2108
SQLITE_API void sqlite3_randomness(int N, void *P);
2111
** CAPI3REF: Compile-Time Authorization Callbacks
2113
** ^This routine registers an authorizer callback with a particular
2114
** [database connection], supplied in the first argument.
2115
** ^The authorizer callback is invoked as SQL statements are being compiled
2116
** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
2117
** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. ^At various
2118
** points during the compilation process, as logic is being created
2119
** to perform various actions, the authorizer callback is invoked to
2120
** see if those actions are allowed. ^The authorizer callback should
2121
** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
2122
** specific action but allow the SQL statement to continue to be
2123
** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
2124
** rejected with an error. ^If the authorizer callback returns
2125
** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
2126
** then the [sqlite3_prepare_v2()] or equivalent call that triggered
2127
** the authorizer will fail with an error message.
2129
** When the callback returns [SQLITE_OK], that means the operation
2130
** requested is ok. ^When the callback returns [SQLITE_DENY], the
2131
** [sqlite3_prepare_v2()] or equivalent call that triggered the
2132
** authorizer will fail with an error message explaining that
2133
** access is denied.
2135
** ^The first parameter to the authorizer callback is a copy of the third
2136
** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
2137
** to the callback is an integer [SQLITE_COPY | action code] that specifies
2138
** the particular action to be authorized. ^The third through sixth parameters
2139
** to the callback are zero-terminated strings that contain additional
2140
** details about the action to be authorized.
2142
** ^If the action code is [SQLITE_READ]
2143
** and the callback returns [SQLITE_IGNORE] then the
2144
** [prepared statement] statement is constructed to substitute
2145
** a NULL value in place of the table column that would have
2146
** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
2147
** return can be used to deny an untrusted user access to individual
2148
** columns of a table.
2149
** ^If the action code is [SQLITE_DELETE] and the callback returns
2150
** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
2151
** [truncate optimization] is disabled and all rows are deleted individually.
2153
** An authorizer is used when [sqlite3_prepare | preparing]
2154
** SQL statements from an untrusted source, to ensure that the SQL statements
2155
** do not try to access data they are not allowed to see, or that they do not
2156
** try to execute malicious statements that damage the database. For
2157
** example, an application may allow a user to enter arbitrary
2158
** SQL queries for evaluation by a database. But the application does
2159
** not want the user to be able to make arbitrary changes to the
2160
** database. An authorizer could then be put in place while the
2161
** user-entered SQL is being [sqlite3_prepare | prepared] that
2162
** disallows everything except [SELECT] statements.
2164
** Applications that need to process SQL from untrusted sources
2165
** might also consider lowering resource limits using [sqlite3_limit()]
2166
** and limiting database size using the [max_page_count] [PRAGMA]
2167
** in addition to using an authorizer.
2169
** ^(Only a single authorizer can be in place on a database connection
2170
** at a time. Each call to sqlite3_set_authorizer overrides the
2171
** previous call.)^ ^Disable the authorizer by installing a NULL callback.
2172
** The authorizer is disabled by default.
2174
** The authorizer callback must not do anything that will modify
2175
** the database connection that invoked the authorizer callback.
2176
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
2177
** database connections for the meaning of "modify" in this paragraph.
2179
** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
2180
** statement might be re-prepared during [sqlite3_step()] due to a
2181
** schema change. Hence, the application should ensure that the
2182
** correct authorizer callback remains in place during the [sqlite3_step()].
2184
** ^Note that the authorizer callback is invoked only during
2185
** [sqlite3_prepare()] or its variants. Authorization is not
2186
** performed during statement evaluation in [sqlite3_step()], unless
2187
** as stated in the previous paragraph, sqlite3_step() invokes
2188
** sqlite3_prepare_v2() to reprepare a statement after a schema change.
2190
SQLITE_API int sqlite3_set_authorizer(
2192
int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
2197
** CAPI3REF: Authorizer Return Codes
2199
** The [sqlite3_set_authorizer | authorizer callback function] must
2200
** return either [SQLITE_OK] or one of these two constants in order
2201
** to signal SQLite whether or not the action is permitted. See the
2202
** [sqlite3_set_authorizer | authorizer documentation] for additional
2205
#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
2206
#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
2209
** CAPI3REF: Authorizer Action Codes
2211
** The [sqlite3_set_authorizer()] interface registers a callback function
2212
** that is invoked to authorize certain SQL statement actions. The
2213
** second parameter to the callback is an integer code that specifies
2214
** what action is being authorized. These are the integer action codes that
2215
** the authorizer callback may be passed.
2217
** These action code values signify what kind of operation is to be
2218
** authorized. The 3rd and 4th parameters to the authorization
2219
** callback function will be parameters or NULL depending on which of these
2220
** codes is used as the second parameter. ^(The 5th parameter to the
2221
** authorizer callback is the name of the database ("main", "temp",
2222
** etc.) if applicable.)^ ^The 6th parameter to the authorizer callback
2223
** is the name of the inner-most trigger or view that is responsible for
2224
** the access attempt or NULL if this access attempt is directly from
2225
** top-level SQL code.
2227
/******************************************* 3rd ************ 4th ***********/
2228
#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
2229
#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
2230
#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
2231
#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
2232
#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
2233
#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
2234
#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
2235
#define SQLITE_CREATE_VIEW 8 /* View Name NULL */
2236
#define SQLITE_DELETE 9 /* Table Name NULL */
2237
#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
2238
#define SQLITE_DROP_TABLE 11 /* Table Name NULL */
2239
#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
2240
#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
2241
#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
2242
#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
2243
#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
2244
#define SQLITE_DROP_VIEW 17 /* View Name NULL */
2245
#define SQLITE_INSERT 18 /* Table Name NULL */
2246
#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
2247
#define SQLITE_READ 20 /* Table Name Column Name */
2248
#define SQLITE_SELECT 21 /* NULL NULL */
2249
#define SQLITE_TRANSACTION 22 /* Operation NULL */
2250
#define SQLITE_UPDATE 23 /* Table Name Column Name */
2251
#define SQLITE_ATTACH 24 /* Filename NULL */
2252
#define SQLITE_DETACH 25 /* Database Name NULL */
2253
#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
2254
#define SQLITE_REINDEX 27 /* Index Name NULL */
2255
#define SQLITE_ANALYZE 28 /* Table Name NULL */
2256
#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
2257
#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
2258
#define SQLITE_FUNCTION 31 /* NULL Function Name */
2259
#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
2260
#define SQLITE_COPY 0 /* No longer used */
2263
** CAPI3REF: Tracing And Profiling Functions
2265
** These routines register callback functions that can be used for
2266
** tracing and profiling the execution of SQL statements.
2268
** ^The callback function registered by sqlite3_trace() is invoked at
2269
** various times when an SQL statement is being run by [sqlite3_step()].
2270
** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
2271
** SQL statement text as the statement first begins executing.
2272
** ^(Additional sqlite3_trace() callbacks might occur
2273
** as each triggered subprogram is entered. The callbacks for triggers
2274
** contain a UTF-8 SQL comment that identifies the trigger.)^
2276
** ^The callback function registered by sqlite3_profile() is invoked
2277
** as each SQL statement finishes. ^The profile callback contains
2278
** the original statement text and an estimate of wall-clock time
2279
** of how long that statement took to run. ^The profile callback
2280
** time is in units of nanoseconds, however the current implementation
2281
** is only capable of millisecond resolution so the six least significant
2282
** digits in the time are meaningless. Future versions of SQLite
2283
** might provide greater resolution on the profiler callback. The
2284
** sqlite3_profile() function is considered experimental and is
2285
** subject to change in future versions of SQLite.
2287
SQLITE_API void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
2288
SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
2289
void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
2292
** CAPI3REF: Query Progress Callbacks
2294
** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
2295
** function X to be invoked periodically during long running calls to
2296
** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
2297
** database connection D. An example use for this
2298
** interface is to keep a GUI updated during a large query.
2300
** ^The parameter P is passed through as the only parameter to the
2301
** callback function X. ^The parameter N is the number of
2302
** [virtual machine instructions] that are evaluated between successive
2303
** invocations of the callback X.
2305
** ^Only a single progress handler may be defined at one time per
2306
** [database connection]; setting a new progress handler cancels the
2307
** old one. ^Setting parameter X to NULL disables the progress handler.
2308
** ^The progress handler is also disabled by setting N to a value less
2311
** ^If the progress callback returns non-zero, the operation is
2312
** interrupted. This feature can be used to implement a
2313
** "Cancel" button on a GUI progress dialog box.
2315
** The progress handler callback must not do anything that will modify
2316
** the database connection that invoked the progress handler.
2317
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
2318
** database connections for the meaning of "modify" in this paragraph.
2321
SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
2324
** CAPI3REF: Opening A New Database Connection
2326
** ^These routines open an SQLite database file whose name is given by the
2327
** filename argument. ^The filename argument is interpreted as UTF-8 for
2328
** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
2329
** order for sqlite3_open16(). ^(A [database connection] handle is usually
2330
** returned in *ppDb, even if an error occurs. The only exception is that
2331
** if SQLite is unable to allocate memory to hold the [sqlite3] object,
2332
** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
2333
** object.)^ ^(If the database is opened (and/or created) successfully, then
2334
** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The
2335
** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
2336
** an English language description of the error following a failure of any
2337
** of the sqlite3_open() routines.
2339
** ^The default encoding for the database will be UTF-8 if
2340
** sqlite3_open() or sqlite3_open_v2() is called and
2341
** UTF-16 in the native byte order if sqlite3_open16() is used.
2343
** Whether or not an error occurs when it is opened, resources
2344
** associated with the [database connection] handle should be released by
2345
** passing it to [sqlite3_close()] when it is no longer required.
2347
** The sqlite3_open_v2() interface works like sqlite3_open()
2348
** except that it accepts two additional parameters for additional control
2349
** over the new database connection. ^(The flags parameter to
2350
** sqlite3_open_v2() can take one of
2351
** the following three values, optionally combined with the
2352
** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
2353
** and/or [SQLITE_OPEN_PRIVATECACHE] flags:)^
2356
** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
2357
** <dd>The database is opened in read-only mode. If the database does not
2358
** already exist, an error is returned.</dd>)^
2360
** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
2361
** <dd>The database is opened for reading and writing if possible, or reading
2362
** only if the file is write protected by the operating system. In either
2363
** case the database must already exist, otherwise an error is returned.</dd>)^
2365
** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
2366
** <dd>The database is opened for reading and writing, and is created if
2367
** it does not already exist. This is the behavior that is always used for
2368
** sqlite3_open() and sqlite3_open16().</dd>)^
2371
** If the 3rd parameter to sqlite3_open_v2() is not one of the
2372
** combinations shown above or one of the combinations shown above combined
2373
** with the [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX],
2374
** [SQLITE_OPEN_SHAREDCACHE] and/or [SQLITE_OPEN_PRIVATECACHE] flags,
2375
** then the behavior is undefined.
2377
** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
2378
** opens in the multi-thread [threading mode] as long as the single-thread
2379
** mode has not been set at compile-time or start-time. ^If the
2380
** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
2381
** in the serialized [threading mode] unless single-thread was
2382
** previously selected at compile-time or start-time.
2383
** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
2384
** eligible to use [shared cache mode], regardless of whether or not shared
2385
** cache is enabled using [sqlite3_enable_shared_cache()]. ^The
2386
** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
2387
** participate in [shared cache mode] even if it is enabled.
2389
** ^If the filename is ":memory:", then a private, temporary in-memory database
2390
** is created for the connection. ^This in-memory database will vanish when
2391
** the database connection is closed. Future versions of SQLite might
2392
** make use of additional special filenames that begin with the ":" character.
2393
** It is recommended that when a database filename actually does begin with
2394
** a ":" character you should prefix the filename with a pathname such as
2395
** "./" to avoid ambiguity.
2397
** ^If the filename is an empty string, then a private, temporary
2398
** on-disk database will be created. ^This private database will be
2399
** automatically deleted as soon as the database connection is closed.
2401
** ^The fourth parameter to sqlite3_open_v2() is the name of the
2402
** [sqlite3_vfs] object that defines the operating system interface that
2403
** the new database connection should use. ^If the fourth parameter is
2404
** a NULL pointer then the default [sqlite3_vfs] object is used.
2406
** <b>Note to Windows users:</b> The encoding used for the filename argument
2407
** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
2408
** codepage is currently defined. Filenames containing international
2409
** characters must be converted to UTF-8 prior to passing them into
2410
** sqlite3_open() or sqlite3_open_v2().
2412
SQLITE_API int sqlite3_open(
2413
const char *filename, /* Database filename (UTF-8) */
2414
sqlite3 **ppDb /* OUT: SQLite db handle */
2416
SQLITE_API int sqlite3_open16(
2417
const void *filename, /* Database filename (UTF-16) */
2418
sqlite3 **ppDb /* OUT: SQLite db handle */
2420
SQLITE_API int sqlite3_open_v2(
2421
const char *filename, /* Database filename (UTF-8) */
2422
sqlite3 **ppDb, /* OUT: SQLite db handle */
2423
int flags, /* Flags */
2424
const char *zVfs /* Name of VFS module to use */
2428
** CAPI3REF: Error Codes And Messages
2430
** ^The sqlite3_errcode() interface returns the numeric [result code] or
2431
** [extended result code] for the most recent failed sqlite3_* API call
2432
** associated with a [database connection]. If a prior API call failed
2433
** but the most recent API call succeeded, the return value from
2434
** sqlite3_errcode() is undefined. ^The sqlite3_extended_errcode()
2435
** interface is the same except that it always returns the
2436
** [extended result code] even when extended result codes are
2439
** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
2440
** text that describes the error, as either UTF-8 or UTF-16 respectively.
2441
** ^(Memory to hold the error message string is managed internally.
2442
** The application does not need to worry about freeing the result.
2443
** However, the error string might be overwritten or deallocated by
2444
** subsequent calls to other SQLite interface functions.)^
2446
** When the serialized [threading mode] is in use, it might be the
2447
** case that a second error occurs on a separate thread in between
2448
** the time of the first error and the call to these interfaces.
2449
** When that happens, the second error will be reported since these
2450
** interfaces always report the most recent result. To avoid
2451
** this, each thread can obtain exclusive use of the [database connection] D
2452
** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
2453
** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
2454
** all calls to the interfaces listed here are completed.
2456
** If an interface fails with SQLITE_MISUSE, that means the interface
2457
** was invoked incorrectly by the application. In that case, the
2458
** error code and message may or may not be set.
2460
SQLITE_API int sqlite3_errcode(sqlite3 *db);
2461
SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
2462
SQLITE_API const char *sqlite3_errmsg(sqlite3*);
2463
SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
2466
** CAPI3REF: SQL Statement Object
2467
** KEYWORDS: {prepared statement} {prepared statements}
2469
** An instance of this object represents a single SQL statement.
2470
** This object is variously known as a "prepared statement" or a
2471
** "compiled SQL statement" or simply as a "statement".
2473
** The life of a statement object goes something like this:
2476
** <li> Create the object using [sqlite3_prepare_v2()] or a related
2478
** <li> Bind values to [host parameters] using the sqlite3_bind_*()
2480
** <li> Run the SQL by calling [sqlite3_step()] one or more times.
2481
** <li> Reset the statement using [sqlite3_reset()] then go back
2482
** to step 2. Do this zero or more times.
2483
** <li> Destroy the object using [sqlite3_finalize()].
2486
** Refer to documentation on individual methods above for additional
2489
typedef struct sqlite3_stmt sqlite3_stmt;
2492
** CAPI3REF: Run-time Limits
2494
** ^(This interface allows the size of various constructs to be limited
2495
** on a connection by connection basis. The first parameter is the
2496
** [database connection] whose limit is to be set or queried. The
2497
** second parameter is one of the [limit categories] that define a
2498
** class of constructs to be size limited. The third parameter is the
2499
** new limit for that construct.)^
2501
** ^If the new limit is a negative number, the limit is unchanged.
2502
** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
2503
** [limits | hard upper bound]
2504
** set at compile-time by a C preprocessor macro called
2505
** [limits | SQLITE_MAX_<i>NAME</i>].
2506
** (The "_LIMIT_" in the name is changed to "_MAX_".))^
2507
** ^Attempts to increase a limit above its hard upper bound are
2508
** silently truncated to the hard upper bound.
2510
** ^Regardless of whether or not the limit was changed, the
2511
** [sqlite3_limit()] interface returns the prior value of the limit.
2512
** ^Hence, to find the current value of a limit without changing it,
2513
** simply invoke this interface with the third parameter set to -1.
2515
** Run-time limits are intended for use in applications that manage
2516
** both their own internal database and also databases that are controlled
2517
** by untrusted external sources. An example application might be a
2518
** web browser that has its own databases for storing history and
2519
** separate databases controlled by JavaScript applications downloaded
2520
** off the Internet. The internal databases can be given the
2521
** large, default limits. Databases managed by external sources can
2522
** be given much smaller limits designed to prevent a denial of service
2523
** attack. Developers might also want to use the [sqlite3_set_authorizer()]
2524
** interface to further control untrusted SQL. The size of the database
2525
** created by an untrusted script can be contained using the
2526
** [max_page_count] [PRAGMA].
2528
** New run-time limit categories may be added in future releases.
2530
SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
2533
** CAPI3REF: Run-Time Limit Categories
2534
** KEYWORDS: {limit category} {*limit categories}
2536
** These constants define various performance limits
2537
** that can be lowered at run-time using [sqlite3_limit()].
2538
** The synopsis of the meanings of the various limits is shown below.
2539
** Additional information is available at [limits | Limits in SQLite].
2542
** ^(<dt>SQLITE_LIMIT_LENGTH</dt>
2543
** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
2545
** ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
2546
** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
2548
** ^(<dt>SQLITE_LIMIT_COLUMN</dt>
2549
** <dd>The maximum number of columns in a table definition or in the
2550
** result set of a [SELECT] or the maximum number of columns in an index
2551
** or in an ORDER BY or GROUP BY clause.</dd>)^
2553
** ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
2554
** <dd>The maximum depth of the parse tree on any expression.</dd>)^
2556
** ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
2557
** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
2559
** ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
2560
** <dd>The maximum number of instructions in a virtual machine program
2561
** used to implement an SQL statement. This limit is not currently
2562
** enforced, though that might be added in some future release of
2565
** ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
2566
** <dd>The maximum number of arguments on a function.</dd>)^
2568
** ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
2569
** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
2571
** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
2572
** <dd>The maximum length of the pattern argument to the [LIKE] or
2573
** [GLOB] operators.</dd>)^
2575
** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
2576
** <dd>The maximum index number of any [parameter] in an SQL statement.)^
2578
** ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
2579
** <dd>The maximum depth of recursion for triggers.</dd>)^
2582
#define SQLITE_LIMIT_LENGTH 0
2583
#define SQLITE_LIMIT_SQL_LENGTH 1
2584
#define SQLITE_LIMIT_COLUMN 2
2585
#define SQLITE_LIMIT_EXPR_DEPTH 3
2586
#define SQLITE_LIMIT_COMPOUND_SELECT 4
2587
#define SQLITE_LIMIT_VDBE_OP 5
2588
#define SQLITE_LIMIT_FUNCTION_ARG 6
2589
#define SQLITE_LIMIT_ATTACHED 7
2590
#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8
2591
#define SQLITE_LIMIT_VARIABLE_NUMBER 9
2592
#define SQLITE_LIMIT_TRIGGER_DEPTH 10
2595
** CAPI3REF: Compiling An SQL Statement
2596
** KEYWORDS: {SQL statement compiler}
2598
** To execute an SQL query, it must first be compiled into a byte-code
2599
** program using one of these routines.
2601
** The first argument, "db", is a [database connection] obtained from a
2602
** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
2603
** [sqlite3_open16()]. The database connection must not have been closed.
2605
** The second argument, "zSql", is the statement to be compiled, encoded
2606
** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()
2607
** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
2610
** ^If the nByte argument is less than zero, then zSql is read up to the
2611
** first zero terminator. ^If nByte is non-negative, then it is the maximum
2612
** number of bytes read from zSql. ^When nByte is non-negative, the
2613
** zSql string ends at either the first '\000' or '\u0000' character or
2614
** the nByte-th byte, whichever comes first. If the caller knows
2615
** that the supplied string is nul-terminated, then there is a small
2616
** performance advantage to be gained by passing an nByte parameter that
2617
** is equal to the number of bytes in the input string <i>including</i>
2618
** the nul-terminator bytes.
2620
** ^If pzTail is not NULL then *pzTail is made to point to the first byte
2621
** past the end of the first SQL statement in zSql. These routines only
2622
** compile the first statement in zSql, so *pzTail is left pointing to
2623
** what remains uncompiled.
2625
** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
2626
** executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set
2627
** to NULL. ^If the input text contains no SQL (if the input is an empty
2628
** string or a comment) then *ppStmt is set to NULL.
2629
** The calling procedure is responsible for deleting the compiled
2630
** SQL statement using [sqlite3_finalize()] after it has finished with it.
2631
** ppStmt may not be NULL.
2633
** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
2634
** otherwise an [error code] is returned.
2636
** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
2637
** recommended for all new programs. The two older interfaces are retained
2638
** for backwards compatibility, but their use is discouraged.
2639
** ^In the "v2" interfaces, the prepared statement
2640
** that is returned (the [sqlite3_stmt] object) contains a copy of the
2641
** original SQL text. This causes the [sqlite3_step()] interface to
2642
** behave differently in three ways:
2646
** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
2647
** always used to do, [sqlite3_step()] will automatically recompile the SQL
2648
** statement and try to run it again.
2652
** ^When an error occurs, [sqlite3_step()] will return one of the detailed
2653
** [error codes] or [extended error codes]. ^The legacy behavior was that
2654
** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
2655
** and the application would have to make a second call to [sqlite3_reset()]
2656
** in order to find the underlying cause of the problem. With the "v2" prepare
2657
** interfaces, the underlying reason for the error is returned immediately.
2661
** ^If the specific value bound to [parameter | host parameter] in the
2662
** WHERE clause might influence the choice of query plan for a statement,
2663
** then the statement will be automatically recompiled, as if there had been
2664
** a schema change, on the first [sqlite3_step()] call following any change
2665
** to the [sqlite3_bind_text | bindings] of that [parameter].
2666
** ^The specific value of WHERE-clause [parameter] might influence the
2667
** choice of query plan if the parameter is the left-hand side of a [LIKE]
2668
** or [GLOB] operator or if the parameter is compared to an indexed column
2669
** and the [SQLITE_ENABLE_STAT2] compile-time option is enabled.
2674
SQLITE_API int sqlite3_prepare(
2675
sqlite3 *db, /* Database handle */
2676
const char *zSql, /* SQL statement, UTF-8 encoded */
2677
int nByte, /* Maximum length of zSql in bytes. */
2678
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
2679
const char **pzTail /* OUT: Pointer to unused portion of zSql */
2681
SQLITE_API int sqlite3_prepare_v2(
2682
sqlite3 *db, /* Database handle */
2683
const char *zSql, /* SQL statement, UTF-8 encoded */
2684
int nByte, /* Maximum length of zSql in bytes. */
2685
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
2686
const char **pzTail /* OUT: Pointer to unused portion of zSql */
2688
SQLITE_API int sqlite3_prepare16(
2689
sqlite3 *db, /* Database handle */
2690
const void *zSql, /* SQL statement, UTF-16 encoded */
2691
int nByte, /* Maximum length of zSql in bytes. */
2692
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
2693
const void **pzTail /* OUT: Pointer to unused portion of zSql */
2695
SQLITE_API int sqlite3_prepare16_v2(
2696
sqlite3 *db, /* Database handle */
2697
const void *zSql, /* SQL statement, UTF-16 encoded */
2698
int nByte, /* Maximum length of zSql in bytes. */
2699
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
2700
const void **pzTail /* OUT: Pointer to unused portion of zSql */
2704
** CAPI3REF: Retrieving Statement SQL
2706
** ^This interface can be used to retrieve a saved copy of the original
2707
** SQL text used to create a [prepared statement] if that statement was
2708
** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
2710
SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
2713
** CAPI3REF: Determine If An SQL Statement Writes The Database
2715
** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
2716
** and only if the [prepared statement] X makes no direct changes to
2717
** the content of the database file.
2719
** Note that [application-defined SQL functions] or
2720
** [virtual tables] might change the database indirectly as a side effect.
2721
** ^(For example, if an application defines a function "eval()" that
2722
** calls [sqlite3_exec()], then the following SQL statement would
2723
** change the database file through side-effects:
2725
** <blockquote><pre>
2726
** SELECT eval('DELETE FROM t1') FROM t2;
2727
** </pre></blockquote>
2729
** But because the [SELECT] statement does not change the database file
2730
** directly, sqlite3_stmt_readonly() would still return true.)^
2732
** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
2733
** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
2734
** since the statements themselves do not actually modify the database but
2735
** rather they control the timing of when other statements modify the
2736
** database. ^The [ATTACH] and [DETACH] statements also cause
2737
** sqlite3_stmt_readonly() to return true since, while those statements
2738
** change the configuration of a database connection, they do not make
2739
** changes to the content of the database files on disk.
2741
SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
2744
** CAPI3REF: Dynamically Typed Value Object
2745
** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
2747
** SQLite uses the sqlite3_value object to represent all values
2748
** that can be stored in a database table. SQLite uses dynamic typing
2749
** for the values it stores. ^Values stored in sqlite3_value objects
2750
** can be integers, floating point values, strings, BLOBs, or NULL.
2752
** An sqlite3_value object may be either "protected" or "unprotected".
2753
** Some interfaces require a protected sqlite3_value. Other interfaces
2754
** will accept either a protected or an unprotected sqlite3_value.
2755
** Every interface that accepts sqlite3_value arguments specifies
2756
** whether or not it requires a protected sqlite3_value.
2758
** The terms "protected" and "unprotected" refer to whether or not
2759
** a mutex is held. An internal mutex is held for a protected
2760
** sqlite3_value object but no mutex is held for an unprotected
2761
** sqlite3_value object. If SQLite is compiled to be single-threaded
2762
** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
2763
** or if SQLite is run in one of reduced mutex modes
2764
** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
2765
** then there is no distinction between protected and unprotected
2766
** sqlite3_value objects and they can be used interchangeably. However,
2767
** for maximum code portability it is recommended that applications
2768
** still make the distinction between protected and unprotected
2769
** sqlite3_value objects even when not strictly required.
2771
** ^The sqlite3_value objects that are passed as parameters into the
2772
** implementation of [application-defined SQL functions] are protected.
2773
** ^The sqlite3_value object returned by
2774
** [sqlite3_column_value()] is unprotected.
2775
** Unprotected sqlite3_value objects may only be used with
2776
** [sqlite3_result_value()] and [sqlite3_bind_value()].
2777
** The [sqlite3_value_blob | sqlite3_value_type()] family of
2778
** interfaces require protected sqlite3_value objects.
2780
typedef struct Mem sqlite3_value;
2783
** CAPI3REF: SQL Function Context Object
2785
** The context in which an SQL function executes is stored in an
2786
** sqlite3_context object. ^A pointer to an sqlite3_context object
2787
** is always first parameter to [application-defined SQL functions].
2788
** The application-defined SQL function implementation will pass this
2789
** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
2790
** [sqlite3_aggregate_context()], [sqlite3_user_data()],
2791
** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
2792
** and/or [sqlite3_set_auxdata()].
2794
typedef struct sqlite3_context sqlite3_context;
2797
** CAPI3REF: Binding Values To Prepared Statements
2798
** KEYWORDS: {host parameter} {host parameters} {host parameter name}
2799
** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
2801
** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
2802
** literals may be replaced by a [parameter] that matches one of following
2813
** In the templates above, NNN represents an integer literal,
2814
** and VVV represents an alphanumeric identifier.)^ ^The values of these
2815
** parameters (also called "host parameter names" or "SQL parameters")
2816
** can be set using the sqlite3_bind_*() routines defined here.
2818
** ^The first argument to the sqlite3_bind_*() routines is always
2819
** a pointer to the [sqlite3_stmt] object returned from
2820
** [sqlite3_prepare_v2()] or its variants.
2822
** ^The second argument is the index of the SQL parameter to be set.
2823
** ^The leftmost SQL parameter has an index of 1. ^When the same named
2824
** SQL parameter is used more than once, second and subsequent
2825
** occurrences have the same index as the first occurrence.
2826
** ^The index for named parameters can be looked up using the
2827
** [sqlite3_bind_parameter_index()] API if desired. ^The index
2828
** for "?NNN" parameters is the value of NNN.
2829
** ^The NNN value must be between 1 and the [sqlite3_limit()]
2830
** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
2832
** ^The third argument is the value to bind to the parameter.
2834
** ^(In those routines that have a fourth argument, its value is the
2835
** number of bytes in the parameter. To be clear: the value is the
2836
** number of <u>bytes</u> in the value, not the number of characters.)^
2837
** ^If the fourth parameter is negative, the length of the string is
2838
** the number of bytes up to the first zero terminator.
2840
** ^The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
2841
** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
2842
** string after SQLite has finished with it. ^The destructor is called
2843
** to dispose of the BLOB or string even if the call to sqlite3_bind_blob(),
2844
** sqlite3_bind_text(), or sqlite3_bind_text16() fails.
2845
** ^If the fifth argument is
2846
** the special value [SQLITE_STATIC], then SQLite assumes that the
2847
** information is in static, unmanaged space and does not need to be freed.
2848
** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
2849
** SQLite makes its own private copy of the data immediately, before
2850
** the sqlite3_bind_*() routine returns.
2852
** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
2853
** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
2854
** (just an integer to hold its size) while it is being processed.
2855
** Zeroblobs are intended to serve as placeholders for BLOBs whose
2856
** content is later written using
2857
** [sqlite3_blob_open | incremental BLOB I/O] routines.
2858
** ^A negative value for the zeroblob results in a zero-length BLOB.
2860
** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
2861
** for the [prepared statement] or with a prepared statement for which
2862
** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
2863
** then the call will return [SQLITE_MISUSE]. If any sqlite3_bind_()
2864
** routine is passed a [prepared statement] that has been finalized, the
2865
** result is undefined and probably harmful.
2867
** ^Bindings are not cleared by the [sqlite3_reset()] routine.
2868
** ^Unbound parameters are interpreted as NULL.
2870
** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
2871
** [error code] if anything goes wrong.
2872
** ^[SQLITE_RANGE] is returned if the parameter
2873
** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
2875
** See also: [sqlite3_bind_parameter_count()],
2876
** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
2878
SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
2879
SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
2880
SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
2881
SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
2882
SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
2883
SQLITE_API int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
2884
SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
2885
SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
2886
SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
2889
** CAPI3REF: Number Of SQL Parameters
2891
** ^This routine can be used to find the number of [SQL parameters]
2892
** in a [prepared statement]. SQL parameters are tokens of the
2893
** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
2894
** placeholders for values that are [sqlite3_bind_blob | bound]
2895
** to the parameters at a later time.
2897
** ^(This routine actually returns the index of the largest (rightmost)
2898
** parameter. For all forms except ?NNN, this will correspond to the
2899
** number of unique parameters. If parameters of the ?NNN form are used,
2900
** there may be gaps in the list.)^
2902
** See also: [sqlite3_bind_blob|sqlite3_bind()],
2903
** [sqlite3_bind_parameter_name()], and
2904
** [sqlite3_bind_parameter_index()].
2906
SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
2909
** CAPI3REF: Name Of A Host Parameter
2911
** ^The sqlite3_bind_parameter_name(P,N) interface returns
2912
** the name of the N-th [SQL parameter] in the [prepared statement] P.
2913
** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
2914
** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
2916
** In other words, the initial ":" or "$" or "@" or "?"
2917
** is included as part of the name.)^
2918
** ^Parameters of the form "?" without a following integer have no name
2919
** and are referred to as "nameless" or "anonymous parameters".
2921
** ^The first host parameter has an index of 1, not 0.
2923
** ^If the value N is out of range or if the N-th parameter is
2924
** nameless, then NULL is returned. ^The returned string is
2925
** always in UTF-8 encoding even if the named parameter was
2926
** originally specified as UTF-16 in [sqlite3_prepare16()] or
2927
** [sqlite3_prepare16_v2()].
2929
** See also: [sqlite3_bind_blob|sqlite3_bind()],
2930
** [sqlite3_bind_parameter_count()], and
2931
** [sqlite3_bind_parameter_index()].
2933
SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
2936
** CAPI3REF: Index Of A Parameter With A Given Name
2938
** ^Return the index of an SQL parameter given its name. ^The
2939
** index value returned is suitable for use as the second
2940
** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero
2941
** is returned if no matching parameter is found. ^The parameter
2942
** name must be given in UTF-8 even if the original statement
2943
** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
2945
** See also: [sqlite3_bind_blob|sqlite3_bind()],
2946
** [sqlite3_bind_parameter_count()], and
2947
** [sqlite3_bind_parameter_index()].
2949
SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
2952
** CAPI3REF: Reset All Bindings On A Prepared Statement
2954
** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
2955
** the [sqlite3_bind_blob | bindings] on a [prepared statement].
2956
** ^Use this routine to reset all host parameters to NULL.
2958
SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
2961
** CAPI3REF: Number Of Columns In A Result Set
2963
** ^Return the number of columns in the result set returned by the
2964
** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
2965
** statement that does not return data (for example an [UPDATE]).
2967
** See also: [sqlite3_data_count()]
2969
SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
2972
** CAPI3REF: Column Names In A Result Set
2974
** ^These routines return the name assigned to a particular column
2975
** in the result set of a [SELECT] statement. ^The sqlite3_column_name()
2976
** interface returns a pointer to a zero-terminated UTF-8 string
2977
** and sqlite3_column_name16() returns a pointer to a zero-terminated
2978
** UTF-16 string. ^The first parameter is the [prepared statement]
2979
** that implements the [SELECT] statement. ^The second parameter is the
2980
** column number. ^The leftmost column is number 0.
2982
** ^The returned string pointer is valid until either the [prepared statement]
2983
** is destroyed by [sqlite3_finalize()] or until the statement is automatically
2984
** reprepared by the first call to [sqlite3_step()] for a particular run
2985
** or until the next call to
2986
** sqlite3_column_name() or sqlite3_column_name16() on the same column.
2988
** ^If sqlite3_malloc() fails during the processing of either routine
2989
** (for example during a conversion from UTF-8 to UTF-16) then a
2990
** NULL pointer is returned.
2992
** ^The name of a result column is the value of the "AS" clause for
2993
** that column, if there is an AS clause. If there is no AS clause
2994
** then the name of the column is unspecified and may change from
2995
** one release of SQLite to the next.
2997
SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
2998
SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
3001
** CAPI3REF: Source Of Data In A Query Result
3003
** ^These routines provide a means to determine the database, table, and
3004
** table column that is the origin of a particular result column in
3005
** [SELECT] statement.
3006
** ^The name of the database or table or column can be returned as
3007
** either a UTF-8 or UTF-16 string. ^The _database_ routines return
3008
** the database name, the _table_ routines return the table name, and
3009
** the origin_ routines return the column name.
3010
** ^The returned string is valid until the [prepared statement] is destroyed
3011
** using [sqlite3_finalize()] or until the statement is automatically
3012
** reprepared by the first call to [sqlite3_step()] for a particular run
3013
** or until the same information is requested
3014
** again in a different encoding.
3016
** ^The names returned are the original un-aliased names of the
3017
** database, table, and column.
3019
** ^The first argument to these interfaces is a [prepared statement].
3020
** ^These functions return information about the Nth result column returned by
3021
** the statement, where N is the second function argument.
3022
** ^The left-most column is column 0 for these routines.
3024
** ^If the Nth column returned by the statement is an expression or
3025
** subquery and is not a column value, then all of these functions return
3026
** NULL. ^These routine might also return NULL if a memory allocation error
3027
** occurs. ^Otherwise, they return the name of the attached database, table,
3028
** or column that query result column was extracted from.
3030
** ^As with all other SQLite APIs, those whose names end with "16" return
3031
** UTF-16 encoded strings and the other functions return UTF-8.
3033
** ^These APIs are only available if the library was compiled with the
3034
** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
3036
** If two or more threads call one or more of these routines against the same
3037
** prepared statement and column at the same time then the results are
3040
** If two or more threads call one or more
3041
** [sqlite3_column_database_name | column metadata interfaces]
3042
** for the same [prepared statement] and result column
3043
** at the same time then the results are undefined.
3045
SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
3046
SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
3047
SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
3048
SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
3049
SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
3050
SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
3053
** CAPI3REF: Declared Datatype Of A Query Result
3055
** ^(The first parameter is a [prepared statement].
3056
** If this statement is a [SELECT] statement and the Nth column of the
3057
** returned result set of that [SELECT] is a table column (not an
3058
** expression or subquery) then the declared type of the table
3059
** column is returned.)^ ^If the Nth column of the result set is an
3060
** expression or subquery, then a NULL pointer is returned.
3061
** ^The returned string is always UTF-8 encoded.
3063
** ^(For example, given the database schema:
3065
** CREATE TABLE t1(c1 VARIANT);
3067
** and the following statement to be compiled:
3069
** SELECT c1 + 1, c1 FROM t1;
3071
** this routine would return the string "VARIANT" for the second result
3072
** column (i==1), and a NULL pointer for the first result column (i==0).)^
3074
** ^SQLite uses dynamic run-time typing. ^So just because a column
3075
** is declared to contain a particular type does not mean that the
3076
** data stored in that column is of the declared type. SQLite is
3077
** strongly typed, but the typing is dynamic not static. ^Type
3078
** is associated with individual values, not with the containers
3079
** used to hold those values.
3081
SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
3082
SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
3085
** CAPI3REF: Evaluate An SQL Statement
3087
** After a [prepared statement] has been prepared using either
3088
** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
3089
** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
3090
** must be called one or more times to evaluate the statement.
3092
** The details of the behavior of the sqlite3_step() interface depend
3093
** on whether the statement was prepared using the newer "v2" interface
3094
** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
3095
** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
3096
** new "v2" interface is recommended for new applications but the legacy
3097
** interface will continue to be supported.
3099
** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
3100
** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
3101
** ^With the "v2" interface, any of the other [result codes] or
3102
** [extended result codes] might be returned as well.
3104
** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
3105
** database locks it needs to do its job. ^If the statement is a [COMMIT]
3106
** or occurs outside of an explicit transaction, then you can retry the
3107
** statement. If the statement is not a [COMMIT] and occurs within a
3108
** explicit transaction then you should rollback the transaction before
3111
** ^[SQLITE_DONE] means that the statement has finished executing
3112
** successfully. sqlite3_step() should not be called again on this virtual
3113
** machine without first calling [sqlite3_reset()] to reset the virtual
3114
** machine back to its initial state.
3116
** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
3117
** is returned each time a new row of data is ready for processing by the
3118
** caller. The values may be accessed using the [column access functions].
3119
** sqlite3_step() is called again to retrieve the next row of data.
3121
** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
3122
** violation) has occurred. sqlite3_step() should not be called again on
3123
** the VM. More information may be found by calling [sqlite3_errmsg()].
3124
** ^With the legacy interface, a more specific error code (for example,
3125
** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
3126
** can be obtained by calling [sqlite3_reset()] on the
3127
** [prepared statement]. ^In the "v2" interface,
3128
** the more specific error code is returned directly by sqlite3_step().
3130
** [SQLITE_MISUSE] means that the this routine was called inappropriately.
3131
** Perhaps it was called on a [prepared statement] that has
3132
** already been [sqlite3_finalize | finalized] or on one that had
3133
** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
3134
** be the case that the same database connection is being used by two or
3135
** more threads at the same moment in time.
3137
** For all versions of SQLite up to and including 3.6.23.1, a call to
3138
** [sqlite3_reset()] was required after sqlite3_step() returned anything
3139
** other than [SQLITE_ROW] before any subsequent invocation of
3140
** sqlite3_step(). Failure to reset the prepared statement using
3141
** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
3142
** sqlite3_step(). But after version 3.6.23.1, sqlite3_step() began
3143
** calling [sqlite3_reset()] automatically in this circumstance rather
3144
** than returning [SQLITE_MISUSE]. This is not considered a compatibility
3145
** break because any application that ever receives an SQLITE_MISUSE error
3146
** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
3147
** can be used to restore the legacy behavior.
3149
** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
3150
** API always returns a generic error code, [SQLITE_ERROR], following any
3151
** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call
3152
** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
3153
** specific [error codes] that better describes the error.
3154
** We admit that this is a goofy design. The problem has been fixed
3155
** with the "v2" interface. If you prepare all of your SQL statements
3156
** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
3157
** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
3158
** then the more specific [error codes] are returned directly
3159
** by sqlite3_step(). The use of the "v2" interface is recommended.
3161
SQLITE_API int sqlite3_step(sqlite3_stmt*);
3164
** CAPI3REF: Number of columns in a result set
3166
** ^The sqlite3_data_count(P) interface returns the number of columns in the
3167
** current row of the result set of [prepared statement] P.
3168
** ^If prepared statement P does not have results ready to return
3169
** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of
3170
** interfaces) then sqlite3_data_count(P) returns 0.
3171
** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
3173
** See also: [sqlite3_column_count()]
3175
SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
3178
** CAPI3REF: Fundamental Datatypes
3179
** KEYWORDS: SQLITE_TEXT
3181
** ^(Every value in SQLite has one of five fundamental datatypes:
3184
** <li> 64-bit signed integer
3185
** <li> 64-bit IEEE floating point number
3191
** These constants are codes for each of those types.
3193
** Note that the SQLITE_TEXT constant was also used in SQLite version 2
3194
** for a completely different meaning. Software that links against both
3195
** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
3198
#define SQLITE_INTEGER 1
3199
#define SQLITE_FLOAT 2
3200
#define SQLITE_BLOB 4
3201
#define SQLITE_NULL 5
3205
# define SQLITE_TEXT 3
3207
#define SQLITE3_TEXT 3
3210
** CAPI3REF: Result Values From A Query
3211
** KEYWORDS: {column access functions}
3213
** These routines form the "result set" interface.
3215
** ^These routines return information about a single column of the current
3216
** result row of a query. ^In every case the first argument is a pointer
3217
** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
3218
** that was returned from [sqlite3_prepare_v2()] or one of its variants)
3219
** and the second argument is the index of the column for which information
3220
** should be returned. ^The leftmost column of the result set has the index 0.
3221
** ^The number of columns in the result can be determined using
3222
** [sqlite3_column_count()].
3224
** If the SQL statement does not currently point to a valid row, or if the
3225
** column index is out of range, the result is undefined.
3226
** These routines may only be called when the most recent call to
3227
** [sqlite3_step()] has returned [SQLITE_ROW] and neither
3228
** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
3229
** If any of these routines are called after [sqlite3_reset()] or
3230
** [sqlite3_finalize()] or after [sqlite3_step()] has returned
3231
** something other than [SQLITE_ROW], the results are undefined.
3232
** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
3233
** are called from a different thread while any of these routines
3234
** are pending, then the results are undefined.
3236
** ^The sqlite3_column_type() routine returns the
3237
** [SQLITE_INTEGER | datatype code] for the initial data type
3238
** of the result column. ^The returned value is one of [SQLITE_INTEGER],
3239
** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value
3240
** returned by sqlite3_column_type() is only meaningful if no type
3241
** conversions have occurred as described below. After a type conversion,
3242
** the value returned by sqlite3_column_type() is undefined. Future
3243
** versions of SQLite may change the behavior of sqlite3_column_type()
3244
** following a type conversion.
3246
** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
3247
** routine returns the number of bytes in that BLOB or string.
3248
** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
3249
** the string to UTF-8 and then returns the number of bytes.
3250
** ^If the result is a numeric value then sqlite3_column_bytes() uses
3251
** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
3252
** the number of bytes in that string.
3253
** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
3255
** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
3256
** routine returns the number of bytes in that BLOB or string.
3257
** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
3258
** the string to UTF-16 and then returns the number of bytes.
3259
** ^If the result is a numeric value then sqlite3_column_bytes16() uses
3260
** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
3261
** the number of bytes in that string.
3262
** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
3264
** ^The values returned by [sqlite3_column_bytes()] and
3265
** [sqlite3_column_bytes16()] do not include the zero terminators at the end
3266
** of the string. ^For clarity: the values returned by
3267
** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
3268
** bytes in the string, not the number of characters.
3270
** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
3271
** even empty strings, are always zero terminated. ^The return
3272
** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
3274
** ^The object returned by [sqlite3_column_value()] is an
3275
** [unprotected sqlite3_value] object. An unprotected sqlite3_value object
3276
** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
3277
** If the [unprotected sqlite3_value] object returned by
3278
** [sqlite3_column_value()] is used in any other way, including calls
3279
** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
3280
** or [sqlite3_value_bytes()], then the behavior is undefined.
3282
** These routines attempt to convert the value where appropriate. ^For
3283
** example, if the internal representation is FLOAT and a text result
3284
** is requested, [sqlite3_snprintf()] is used internally to perform the
3285
** conversion automatically. ^(The following table details the conversions
3286
** that are applied:
3289
** <table border="1">
3290
** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion
3292
** <tr><td> NULL <td> INTEGER <td> Result is 0
3293
** <tr><td> NULL <td> FLOAT <td> Result is 0.0
3294
** <tr><td> NULL <td> TEXT <td> Result is NULL pointer
3295
** <tr><td> NULL <td> BLOB <td> Result is NULL pointer
3296
** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
3297
** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
3298
** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
3299
** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer
3300
** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
3301
** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT
3302
** <tr><td> TEXT <td> INTEGER <td> Use atoi()
3303
** <tr><td> TEXT <td> FLOAT <td> Use atof()
3304
** <tr><td> TEXT <td> BLOB <td> No change
3305
** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi()
3306
** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof()
3307
** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
3311
** The table above makes reference to standard C library functions atoi()
3312
** and atof(). SQLite does not really use these functions. It has its
3313
** own equivalent internal routines. The atoi() and atof() names are
3314
** used in the table for brevity and because they are familiar to most
3317
** Note that when type conversions occur, pointers returned by prior
3318
** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
3319
** sqlite3_column_text16() may be invalidated.
3320
** Type conversions and pointer invalidations might occur
3321
** in the following cases:
3324
** <li> The initial content is a BLOB and sqlite3_column_text() or
3325
** sqlite3_column_text16() is called. A zero-terminator might
3326
** need to be added to the string.</li>
3327
** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
3328
** sqlite3_column_text16() is called. The content must be converted
3330
** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
3331
** sqlite3_column_text() is called. The content must be converted
3335
** ^Conversions between UTF-16be and UTF-16le are always done in place and do
3336
** not invalidate a prior pointer, though of course the content of the buffer
3337
** that the prior pointer references will have been modified. Other kinds
3338
** of conversion are done in place when it is possible, but sometimes they
3339
** are not possible and in those cases prior pointers are invalidated.
3341
** The safest and easiest to remember policy is to invoke these routines
3342
** in one of the following ways:
3345
** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
3346
** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
3347
** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
3350
** In other words, you should call sqlite3_column_text(),
3351
** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
3352
** into the desired format, then invoke sqlite3_column_bytes() or
3353
** sqlite3_column_bytes16() to find the size of the result. Do not mix calls
3354
** to sqlite3_column_text() or sqlite3_column_blob() with calls to
3355
** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
3356
** with calls to sqlite3_column_bytes().
3358
** ^The pointers returned are valid until a type conversion occurs as
3359
** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
3360
** [sqlite3_finalize()] is called. ^The memory space used to hold strings
3361
** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned
3362
** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
3363
** [sqlite3_free()].
3365
** ^(If a memory allocation error occurs during the evaluation of any
3366
** of these routines, a default value is returned. The default value
3367
** is either the integer 0, the floating point number 0.0, or a NULL
3368
** pointer. Subsequent calls to [sqlite3_errcode()] will return
3369
** [SQLITE_NOMEM].)^
3371
SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
3372
SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
3373
SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
3374
SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
3375
SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
3376
SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
3377
SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
3378
SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
3379
SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
3380
SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
3383
** CAPI3REF: Destroy A Prepared Statement Object
3385
** ^The sqlite3_finalize() function is called to delete a [prepared statement].
3386
** ^If the most recent evaluation of the statement encountered no errors or
3387
** or if the statement is never been evaluated, then sqlite3_finalize() returns
3388
** SQLITE_OK. ^If the most recent evaluation of statement S failed, then
3389
** sqlite3_finalize(S) returns the appropriate [error code] or
3390
** [extended error code].
3392
** ^The sqlite3_finalize(S) routine can be called at any point during
3393
** the life cycle of [prepared statement] S:
3394
** before statement S is ever evaluated, after
3395
** one or more calls to [sqlite3_reset()], or after any call
3396
** to [sqlite3_step()] regardless of whether or not the statement has
3397
** completed execution.
3399
** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
3401
** The application must finalize every [prepared statement] in order to avoid
3402
** resource leaks. It is a grievous error for the application to try to use
3403
** a prepared statement after it has been finalized. Any use of a prepared
3404
** statement after it has been finalized can result in undefined and
3405
** undesirable behavior such as segfaults and heap corruption.
3407
SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
3410
** CAPI3REF: Reset A Prepared Statement Object
3412
** The sqlite3_reset() function is called to reset a [prepared statement]
3413
** object back to its initial state, ready to be re-executed.
3414
** ^Any SQL statement variables that had values bound to them using
3415
** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
3416
** Use [sqlite3_clear_bindings()] to reset the bindings.
3418
** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
3419
** back to the beginning of its program.
3421
** ^If the most recent call to [sqlite3_step(S)] for the
3422
** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
3423
** or if [sqlite3_step(S)] has never before been called on S,
3424
** then [sqlite3_reset(S)] returns [SQLITE_OK].
3426
** ^If the most recent call to [sqlite3_step(S)] for the
3427
** [prepared statement] S indicated an error, then
3428
** [sqlite3_reset(S)] returns an appropriate [error code].
3430
** ^The [sqlite3_reset(S)] interface does not change the values
3431
** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
3433
SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
3436
** CAPI3REF: Create Or Redefine SQL Functions
3437
** KEYWORDS: {function creation routines}
3438
** KEYWORDS: {application-defined SQL function}
3439
** KEYWORDS: {application-defined SQL functions}
3441
** ^These functions (collectively known as "function creation routines")
3442
** are used to add SQL functions or aggregates or to redefine the behavior
3443
** of existing SQL functions or aggregates. The only differences between
3444
** these routines are the text encoding expected for
3445
** the second parameter (the name of the function being created)
3446
** and the presence or absence of a destructor callback for
3447
** the application data pointer.
3449
** ^The first parameter is the [database connection] to which the SQL
3450
** function is to be added. ^If an application uses more than one database
3451
** connection then application-defined SQL functions must be added
3452
** to each database connection separately.
3454
** ^The second parameter is the name of the SQL function to be created or
3455
** redefined. ^The length of the name is limited to 255 bytes in a UTF-8
3456
** representation, exclusive of the zero-terminator. ^Note that the name
3457
** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
3458
** ^Any attempt to create a function with a longer name
3459
** will result in [SQLITE_MISUSE] being returned.
3461
** ^The third parameter (nArg)
3462
** is the number of arguments that the SQL function or
3463
** aggregate takes. ^If this parameter is -1, then the SQL function or
3464
** aggregate may take any number of arguments between 0 and the limit
3465
** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third
3466
** parameter is less than -1 or greater than 127 then the behavior is
3469
** ^The fourth parameter, eTextRep, specifies what
3470
** [SQLITE_UTF8 | text encoding] this SQL function prefers for
3471
** its parameters. Every SQL function implementation must be able to work
3472
** with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
3473
** more efficient with one encoding than another. ^An application may
3474
** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
3475
** times with the same function but with different values of eTextRep.
3476
** ^When multiple implementations of the same function are available, SQLite
3477
** will pick the one that involves the least amount of data conversion.
3478
** If there is only a single implementation which does not care what text
3479
** encoding is used, then the fourth argument should be [SQLITE_ANY].
3481
** ^(The fifth parameter is an arbitrary pointer. The implementation of the
3482
** function can gain access to this pointer using [sqlite3_user_data()].)^
3484
** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are
3485
** pointers to C-language functions that implement the SQL function or
3486
** aggregate. ^A scalar SQL function requires an implementation of the xFunc
3487
** callback only; NULL pointers must be passed as the xStep and xFinal
3488
** parameters. ^An aggregate SQL function requires an implementation of xStep
3489
** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
3490
** SQL function or aggregate, pass NULL pointers for all three function
3493
** ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL,
3494
** then it is destructor for the application data pointer.
3495
** The destructor is invoked when the function is deleted, either by being
3496
** overloaded or when the database connection closes.)^
3497
** ^The destructor is also invoked if the call to
3498
** sqlite3_create_function_v2() fails.
3499
** ^When the destructor callback of the tenth parameter is invoked, it
3500
** is passed a single argument which is a copy of the application data
3501
** pointer which was the fifth parameter to sqlite3_create_function_v2().
3503
** ^It is permitted to register multiple implementations of the same
3504
** functions with the same name but with either differing numbers of
3505
** arguments or differing preferred text encodings. ^SQLite will use
3506
** the implementation that most closely matches the way in which the
3507
** SQL function is used. ^A function implementation with a non-negative
3508
** nArg parameter is a better match than a function implementation with
3509
** a negative nArg. ^A function where the preferred text encoding
3510
** matches the database encoding is a better
3511
** match than a function where the encoding is different.
3512
** ^A function where the encoding difference is between UTF16le and UTF16be
3513
** is a closer match than a function where the encoding difference is
3514
** between UTF8 and UTF16.
3516
** ^Built-in functions may be overloaded by new application-defined functions.
3518
** ^An application-defined function is permitted to call other
3519
** SQLite interfaces. However, such calls must not
3520
** close the database connection nor finalize or reset the prepared
3521
** statement in which the function is running.
3523
SQLITE_API int sqlite3_create_function(
3525
const char *zFunctionName,
3529
void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
3530
void (*xStep)(sqlite3_context*,int,sqlite3_value**),
3531
void (*xFinal)(sqlite3_context*)
3533
SQLITE_API int sqlite3_create_function16(
3535
const void *zFunctionName,
3539
void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
3540
void (*xStep)(sqlite3_context*,int,sqlite3_value**),
3541
void (*xFinal)(sqlite3_context*)
3543
SQLITE_API int sqlite3_create_function_v2(
3545
const char *zFunctionName,
3549
void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
3550
void (*xStep)(sqlite3_context*,int,sqlite3_value**),
3551
void (*xFinal)(sqlite3_context*),
3552
void(*xDestroy)(void*)
3556
** CAPI3REF: Text Encodings
3558
** These constant define integer codes that represent the various
3559
** text encodings supported by SQLite.
3561
#define SQLITE_UTF8 1
3562
#define SQLITE_UTF16LE 2
3563
#define SQLITE_UTF16BE 3
3564
#define SQLITE_UTF16 4 /* Use native byte order */
3565
#define SQLITE_ANY 5 /* sqlite3_create_function only */
3566
#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
3569
** CAPI3REF: Deprecated Functions
3572
** These functions are [deprecated]. In order to maintain
3573
** backwards compatibility with older code, these functions continue
3574
** to be supported. However, new applications should avoid
3575
** the use of these functions. To help encourage people to avoid
3576
** using these functions, we are not going to tell you what they do.
3578
#ifndef SQLITE_OMIT_DEPRECATED
3579
SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
3580
SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
3581
SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
3582
SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
3583
SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
3584
SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
3588
** CAPI3REF: Obtaining SQL Function Parameter Values
3590
** The C-language implementation of SQL functions and aggregates uses
3591
** this set of interface routines to access the parameter values on
3592
** the function or aggregate.
3594
** The xFunc (for scalar functions) or xStep (for aggregates) parameters
3595
** to [sqlite3_create_function()] and [sqlite3_create_function16()]
3596
** define callbacks that implement the SQL functions and aggregates.
3597
** The 3rd parameter to these callbacks is an array of pointers to
3598
** [protected sqlite3_value] objects. There is one [sqlite3_value] object for
3599
** each parameter to the SQL function. These routines are used to
3600
** extract values from the [sqlite3_value] objects.
3602
** These routines work only with [protected sqlite3_value] objects.
3603
** Any attempt to use these routines on an [unprotected sqlite3_value]
3604
** object results in undefined behavior.
3606
** ^These routines work just like the corresponding [column access functions]
3607
** except that these routines take a single [protected sqlite3_value] object
3608
** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
3610
** ^The sqlite3_value_text16() interface extracts a UTF-16 string
3611
** in the native byte-order of the host machine. ^The
3612
** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
3613
** extract UTF-16 strings as big-endian and little-endian respectively.
3615
** ^(The sqlite3_value_numeric_type() interface attempts to apply
3616
** numeric affinity to the value. This means that an attempt is
3617
** made to convert the value to an integer or floating point. If
3618
** such a conversion is possible without loss of information (in other
3619
** words, if the value is a string that looks like a number)
3620
** then the conversion is performed. Otherwise no conversion occurs.
3621
** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
3623
** Please pay particular attention to the fact that the pointer returned
3624
** from [sqlite3_value_blob()], [sqlite3_value_text()], or
3625
** [sqlite3_value_text16()] can be invalidated by a subsequent call to
3626
** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
3627
** or [sqlite3_value_text16()].
3629
** These routines must be called from the same thread as
3630
** the SQL function that supplied the [sqlite3_value*] parameters.
3632
SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
3633
SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
3634
SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
3635
SQLITE_API double sqlite3_value_double(sqlite3_value*);
3636
SQLITE_API int sqlite3_value_int(sqlite3_value*);
3637
SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
3638
SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
3639
SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
3640
SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
3641
SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
3642
SQLITE_API int sqlite3_value_type(sqlite3_value*);
3643
SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
3646
** CAPI3REF: Obtain Aggregate Function Context
3648
** Implementations of aggregate SQL functions use this
3649
** routine to allocate memory for storing their state.
3651
** ^The first time the sqlite3_aggregate_context(C,N) routine is called
3652
** for a particular aggregate function, SQLite
3653
** allocates N of memory, zeroes out that memory, and returns a pointer
3654
** to the new memory. ^On second and subsequent calls to
3655
** sqlite3_aggregate_context() for the same aggregate function instance,
3656
** the same buffer is returned. Sqlite3_aggregate_context() is normally
3657
** called once for each invocation of the xStep callback and then one
3658
** last time when the xFinal callback is invoked. ^(When no rows match
3659
** an aggregate query, the xStep() callback of the aggregate function
3660
** implementation is never called and xFinal() is called exactly once.
3661
** In those cases, sqlite3_aggregate_context() might be called for the
3662
** first time from within xFinal().)^
3664
** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer if N is
3665
** less than or equal to zero or if a memory allocate error occurs.
3667
** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
3668
** determined by the N parameter on first successful call. Changing the
3669
** value of N in subsequent call to sqlite3_aggregate_context() within
3670
** the same aggregate function instance will not resize the memory
3673
** ^SQLite automatically frees the memory allocated by
3674
** sqlite3_aggregate_context() when the aggregate query concludes.
3676
** The first parameter must be a copy of the
3677
** [sqlite3_context | SQL function context] that is the first parameter
3678
** to the xStep or xFinal callback routine that implements the aggregate
3681
** This routine must be called from the same thread in which
3682
** the aggregate SQL function is running.
3684
SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
3687
** CAPI3REF: User Data For Functions
3689
** ^The sqlite3_user_data() interface returns a copy of
3690
** the pointer that was the pUserData parameter (the 5th parameter)
3691
** of the [sqlite3_create_function()]
3692
** and [sqlite3_create_function16()] routines that originally
3693
** registered the application defined function.
3695
** This routine must be called from the same thread in which
3696
** the application-defined function is running.
3698
SQLITE_API void *sqlite3_user_data(sqlite3_context*);
3701
** CAPI3REF: Database Connection For Functions
3703
** ^The sqlite3_context_db_handle() interface returns a copy of
3704
** the pointer to the [database connection] (the 1st parameter)
3705
** of the [sqlite3_create_function()]
3706
** and [sqlite3_create_function16()] routines that originally
3707
** registered the application defined function.
3709
SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
3712
** CAPI3REF: Function Auxiliary Data
3714
** The following two functions may be used by scalar SQL functions to
3715
** associate metadata with argument values. If the same value is passed to
3716
** multiple invocations of the same SQL function during query execution, under
3717
** some circumstances the associated metadata may be preserved. This may
3718
** be used, for example, to add a regular-expression matching scalar
3719
** function. The compiled version of the regular expression is stored as
3720
** metadata associated with the SQL value passed as the regular expression
3721
** pattern. The compiled regular expression can be reused on multiple
3722
** invocations of the same function so that the original pattern string
3723
** does not need to be recompiled on each invocation.
3725
** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata
3726
** associated by the sqlite3_set_auxdata() function with the Nth argument
3727
** value to the application-defined function. ^If no metadata has been ever
3728
** been set for the Nth argument of the function, or if the corresponding
3729
** function parameter has changed since the meta-data was set,
3730
** then sqlite3_get_auxdata() returns a NULL pointer.
3732
** ^The sqlite3_set_auxdata() interface saves the metadata
3733
** pointed to by its 3rd parameter as the metadata for the N-th
3734
** argument of the application-defined function. Subsequent
3735
** calls to sqlite3_get_auxdata() might return this data, if it has
3736
** not been destroyed.
3737
** ^If it is not NULL, SQLite will invoke the destructor
3738
** function given by the 4th parameter to sqlite3_set_auxdata() on
3739
** the metadata when the corresponding function parameter changes
3740
** or when the SQL statement completes, whichever comes first.
3742
** SQLite is free to call the destructor and drop metadata on any
3743
** parameter of any function at any time. ^The only guarantee is that
3744
** the destructor will be called before the metadata is dropped.
3746
** ^(In practice, metadata is preserved between function calls for
3747
** expressions that are constant at compile time. This includes literal
3748
** values and [parameters].)^
3750
** These routines must be called from the same thread in which
3751
** the SQL function is running.
3753
SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
3754
SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
3758
** CAPI3REF: Constants Defining Special Destructor Behavior
3760
** These are special values for the destructor that is passed in as the
3761
** final argument to routines like [sqlite3_result_blob()]. ^If the destructor
3762
** argument is SQLITE_STATIC, it means that the content pointer is constant
3763
** and will never change. It does not need to be destroyed. ^The
3764
** SQLITE_TRANSIENT value means that the content will likely change in
3765
** the near future and that SQLite should make its own private copy of
3766
** the content before returning.
3768
** The typedef is necessary to work around problems in certain
3769
** C++ compilers. See ticket #2191.
3771
typedef void (*sqlite3_destructor_type)(void*);
3772
#define SQLITE_STATIC ((sqlite3_destructor_type)0)
3773
#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
3776
** CAPI3REF: Setting The Result Of An SQL Function
3778
** These routines are used by the xFunc or xFinal callbacks that
3779
** implement SQL functions and aggregates. See
3780
** [sqlite3_create_function()] and [sqlite3_create_function16()]
3781
** for additional information.
3783
** These functions work very much like the [parameter binding] family of
3784
** functions used to bind values to host parameters in prepared statements.
3785
** Refer to the [SQL parameter] documentation for additional information.
3787
** ^The sqlite3_result_blob() interface sets the result from
3788
** an application-defined function to be the BLOB whose content is pointed
3789
** to by the second parameter and which is N bytes long where N is the
3792
** ^The sqlite3_result_zeroblob() interfaces set the result of
3793
** the application-defined function to be a BLOB containing all zero
3794
** bytes and N bytes in size, where N is the value of the 2nd parameter.
3796
** ^The sqlite3_result_double() interface sets the result from
3797
** an application-defined function to be a floating point value specified
3798
** by its 2nd argument.
3800
** ^The sqlite3_result_error() and sqlite3_result_error16() functions
3801
** cause the implemented SQL function to throw an exception.
3802
** ^SQLite uses the string pointed to by the
3803
** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
3804
** as the text of an error message. ^SQLite interprets the error
3805
** message string from sqlite3_result_error() as UTF-8. ^SQLite
3806
** interprets the string from sqlite3_result_error16() as UTF-16 in native
3807
** byte order. ^If the third parameter to sqlite3_result_error()
3808
** or sqlite3_result_error16() is negative then SQLite takes as the error
3809
** message all text up through the first zero character.
3810
** ^If the third parameter to sqlite3_result_error() or
3811
** sqlite3_result_error16() is non-negative then SQLite takes that many
3812
** bytes (not characters) from the 2nd parameter as the error message.
3813
** ^The sqlite3_result_error() and sqlite3_result_error16()
3814
** routines make a private copy of the error message text before
3815
** they return. Hence, the calling function can deallocate or
3816
** modify the text after they return without harm.
3817
** ^The sqlite3_result_error_code() function changes the error code
3818
** returned by SQLite as a result of an error in a function. ^By default,
3819
** the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error()
3820
** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
3822
** ^The sqlite3_result_toobig() interface causes SQLite to throw an error
3823
** indicating that a string or BLOB is too long to represent.
3825
** ^The sqlite3_result_nomem() interface causes SQLite to throw an error
3826
** indicating that a memory allocation failed.
3828
** ^The sqlite3_result_int() interface sets the return value
3829
** of the application-defined function to be the 32-bit signed integer
3830
** value given in the 2nd argument.
3831
** ^The sqlite3_result_int64() interface sets the return value
3832
** of the application-defined function to be the 64-bit signed integer
3833
** value given in the 2nd argument.
3835
** ^The sqlite3_result_null() interface sets the return value
3836
** of the application-defined function to be NULL.
3838
** ^The sqlite3_result_text(), sqlite3_result_text16(),
3839
** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
3840
** set the return value of the application-defined function to be
3841
** a text string which is represented as UTF-8, UTF-16 native byte order,
3842
** UTF-16 little endian, or UTF-16 big endian, respectively.
3843
** ^SQLite takes the text result from the application from
3844
** the 2nd parameter of the sqlite3_result_text* interfaces.
3845
** ^If the 3rd parameter to the sqlite3_result_text* interfaces
3846
** is negative, then SQLite takes result text from the 2nd parameter
3847
** through the first zero character.
3848
** ^If the 3rd parameter to the sqlite3_result_text* interfaces
3849
** is non-negative, then as many bytes (not characters) of the text
3850
** pointed to by the 2nd parameter are taken as the application-defined
3852
** ^If the 4th parameter to the sqlite3_result_text* interfaces
3853
** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
3854
** function as the destructor on the text or BLOB result when it has
3855
** finished using that result.
3856
** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
3857
** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
3858
** assumes that the text or BLOB result is in constant space and does not
3859
** copy the content of the parameter nor call a destructor on the content
3860
** when it has finished using that result.
3861
** ^If the 4th parameter to the sqlite3_result_text* interfaces
3862
** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
3863
** then SQLite makes a copy of the result into space obtained from
3864
** from [sqlite3_malloc()] before it returns.
3866
** ^The sqlite3_result_value() interface sets the result of
3867
** the application-defined function to be a copy the
3868
** [unprotected sqlite3_value] object specified by the 2nd parameter. ^The
3869
** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
3870
** so that the [sqlite3_value] specified in the parameter may change or
3871
** be deallocated after sqlite3_result_value() returns without harm.
3872
** ^A [protected sqlite3_value] object may always be used where an
3873
** [unprotected sqlite3_value] object is required, so either
3874
** kind of [sqlite3_value] object can be used with this interface.
3876
** If these routines are called from within the different thread
3877
** than the one containing the application-defined function that received
3878
** the [sqlite3_context] pointer, the results are undefined.
3880
SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
3881
SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
3882
SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
3883
SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
3884
SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
3885
SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
3886
SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
3887
SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
3888
SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
3889
SQLITE_API void sqlite3_result_null(sqlite3_context*);
3890
SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
3891
SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
3892
SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
3893
SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
3894
SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
3895
SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
3898
** CAPI3REF: Define New Collating Sequences
3900
** ^These functions add, remove, or modify a [collation] associated
3901
** with the [database connection] specified as the first argument.
3903
** ^The name of the collation is a UTF-8 string
3904
** for sqlite3_create_collation() and sqlite3_create_collation_v2()
3905
** and a UTF-16 string in native byte order for sqlite3_create_collation16().
3906
** ^Collation names that compare equal according to [sqlite3_strnicmp()] are
3907
** considered to be the same name.
3909
** ^(The third argument (eTextRep) must be one of the constants:
3911
** <li> [SQLITE_UTF8],
3912
** <li> [SQLITE_UTF16LE],
3913
** <li> [SQLITE_UTF16BE],
3914
** <li> [SQLITE_UTF16], or
3915
** <li> [SQLITE_UTF16_ALIGNED].
3917
** ^The eTextRep argument determines the encoding of strings passed
3918
** to the collating function callback, xCallback.
3919
** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep
3920
** force strings to be UTF16 with native byte order.
3921
** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin
3922
** on an even byte address.
3924
** ^The fourth argument, pArg, is an application data pointer that is passed
3925
** through as the first argument to the collating function callback.
3927
** ^The fifth argument, xCallback, is a pointer to the collating function.
3928
** ^Multiple collating functions can be registered using the same name but
3929
** with different eTextRep parameters and SQLite will use whichever
3930
** function requires the least amount of data transformation.
3931
** ^If the xCallback argument is NULL then the collating function is
3932
** deleted. ^When all collating functions having the same name are deleted,
3933
** that collation is no longer usable.
3935
** ^The collating function callback is invoked with a copy of the pArg
3936
** application data pointer and with two strings in the encoding specified
3937
** by the eTextRep argument. The collating function must return an
3938
** integer that is negative, zero, or positive
3939
** if the first string is less than, equal to, or greater than the second,
3940
** respectively. A collating function must always return the same answer
3941
** given the same inputs. If two or more collating functions are registered
3942
** to the same collation name (using different eTextRep values) then all
3943
** must give an equivalent answer when invoked with equivalent strings.
3944
** The collating function must obey the following properties for all
3945
** strings A, B, and C:
3948
** <li> If A==B then B==A.
3949
** <li> If A==B and B==C then A==C.
3950
** <li> If A<B THEN B>A.
3951
** <li> If A<B and B<C then A<C.
3954
** If a collating function fails any of the above constraints and that
3955
** collating function is registered and used, then the behavior of SQLite
3958
** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
3959
** with the addition that the xDestroy callback is invoked on pArg when
3960
** the collating function is deleted.
3961
** ^Collating functions are deleted when they are overridden by later
3962
** calls to the collation creation functions or when the
3963
** [database connection] is closed using [sqlite3_close()].
3965
** ^The xDestroy callback is <u>not</u> called if the
3966
** sqlite3_create_collation_v2() function fails. Applications that invoke
3967
** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
3968
** check the return code and dispose of the application data pointer
3969
** themselves rather than expecting SQLite to deal with it for them.
3970
** This is different from every other SQLite interface. The inconsistency
3971
** is unfortunate but cannot be changed without breaking backwards
3974
** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
3976
SQLITE_API int sqlite3_create_collation(
3981
int(*xCompare)(void*,int,const void*,int,const void*)
3983
SQLITE_API int sqlite3_create_collation_v2(
3988
int(*xCompare)(void*,int,const void*,int,const void*),
3989
void(*xDestroy)(void*)
3991
SQLITE_API int sqlite3_create_collation16(
3996
int(*xCompare)(void*,int,const void*,int,const void*)
4000
** CAPI3REF: Collation Needed Callbacks
4002
** ^To avoid having to register all collation sequences before a database
4003
** can be used, a single callback function may be registered with the
4004
** [database connection] to be invoked whenever an undefined collation
4005
** sequence is required.
4007
** ^If the function is registered using the sqlite3_collation_needed() API,
4008
** then it is passed the names of undefined collation sequences as strings
4009
** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
4010
** the names are passed as UTF-16 in machine native byte order.
4011
** ^A call to either function replaces the existing collation-needed callback.
4013
** ^(When the callback is invoked, the first argument passed is a copy
4014
** of the second argument to sqlite3_collation_needed() or
4015
** sqlite3_collation_needed16(). The second argument is the database
4016
** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
4017
** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
4018
** sequence function required. The fourth parameter is the name of the
4019
** required collation sequence.)^
4021
** The callback function should register the desired collation using
4022
** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
4023
** [sqlite3_create_collation_v2()].
4025
SQLITE_API int sqlite3_collation_needed(
4028
void(*)(void*,sqlite3*,int eTextRep,const char*)
4030
SQLITE_API int sqlite3_collation_needed16(
4033
void(*)(void*,sqlite3*,int eTextRep,const void*)
4036
#ifdef SQLITE_HAS_CODEC
4038
** Specify the key for an encrypted database. This routine should be
4039
** called right after sqlite3_open().
4041
** The code to implement this API is not available in the public release
4044
SQLITE_API int sqlite3_key(
4045
sqlite3 *db, /* Database to be rekeyed */
4046
const void *pKey, int nKey /* The key */
4050
** Change the key on an open database. If the current database is not
4051
** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
4052
** database is decrypted.
4054
** The code to implement this API is not available in the public release
4057
SQLITE_API int sqlite3_rekey(
4058
sqlite3 *db, /* Database to be rekeyed */
4059
const void *pKey, int nKey /* The new key */
4063
** Specify the activation key for a SEE database. Unless
4064
** activated, none of the SEE routines will work.
4066
SQLITE_API void sqlite3_activate_see(
4067
const char *zPassPhrase /* Activation phrase */
4071
#ifdef SQLITE_ENABLE_CEROD
4073
** Specify the activation key for a CEROD database. Unless
4074
** activated, none of the CEROD routines will work.
4076
SQLITE_API void sqlite3_activate_cerod(
4077
const char *zPassPhrase /* Activation phrase */
4082
** CAPI3REF: Suspend Execution For A Short Time
4084
** The sqlite3_sleep() function causes the current thread to suspend execution
4085
** for at least a number of milliseconds specified in its parameter.
4087
** If the operating system does not support sleep requests with
4088
** millisecond time resolution, then the time will be rounded up to
4089
** the nearest second. The number of milliseconds of sleep actually
4090
** requested from the operating system is returned.
4092
** ^SQLite implements this interface by calling the xSleep()
4093
** method of the default [sqlite3_vfs] object. If the xSleep() method
4094
** of the default VFS is not implemented correctly, or not implemented at
4095
** all, then the behavior of sqlite3_sleep() may deviate from the description
4096
** in the previous paragraphs.
4098
SQLITE_API int sqlite3_sleep(int);
4101
** CAPI3REF: Name Of The Folder Holding Temporary Files
4103
** ^(If this global variable is made to point to a string which is
4104
** the name of a folder (a.k.a. directory), then all temporary files
4105
** created by SQLite when using a built-in [sqlite3_vfs | VFS]
4106
** will be placed in that directory.)^ ^If this variable
4107
** is a NULL pointer, then SQLite performs a search for an appropriate
4108
** temporary file directory.
4110
** It is not safe to read or modify this variable in more than one
4111
** thread at a time. It is not safe to read or modify this variable
4112
** if a [database connection] is being used at the same time in a separate
4114
** It is intended that this variable be set once
4115
** as part of process initialization and before any SQLite interface
4116
** routines have been called and that this variable remain unchanged
4119
** ^The [temp_store_directory pragma] may modify this variable and cause
4120
** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore,
4121
** the [temp_store_directory pragma] always assumes that any string
4122
** that this variable points to is held in memory obtained from
4123
** [sqlite3_malloc] and the pragma may attempt to free that memory
4124
** using [sqlite3_free].
4125
** Hence, if this variable is modified directly, either it should be
4126
** made NULL or made to point to memory obtained from [sqlite3_malloc]
4127
** or else the use of the [temp_store_directory pragma] should be avoided.
4129
SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;
4132
** CAPI3REF: Test For Auto-Commit Mode
4133
** KEYWORDS: {autocommit mode}
4135
** ^The sqlite3_get_autocommit() interface returns non-zero or
4136
** zero if the given database connection is or is not in autocommit mode,
4137
** respectively. ^Autocommit mode is on by default.
4138
** ^Autocommit mode is disabled by a [BEGIN] statement.
4139
** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
4141
** If certain kinds of errors occur on a statement within a multi-statement
4142
** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],
4143
** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
4144
** transaction might be rolled back automatically. The only way to
4145
** find out whether SQLite automatically rolled back the transaction after
4146
** an error is to use this function.
4148
** If another thread changes the autocommit status of the database
4149
** connection while this routine is running, then the return value
4152
SQLITE_API int sqlite3_get_autocommit(sqlite3*);
4155
** CAPI3REF: Find The Database Handle Of A Prepared Statement
4157
** ^The sqlite3_db_handle interface returns the [database connection] handle
4158
** to which a [prepared statement] belongs. ^The [database connection]
4159
** returned by sqlite3_db_handle is the same [database connection]
4160
** that was the first argument
4161
** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
4162
** create the statement in the first place.
4164
SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
4167
** CAPI3REF: Find the next prepared statement
4169
** ^This interface returns a pointer to the next [prepared statement] after
4170
** pStmt associated with the [database connection] pDb. ^If pStmt is NULL
4171
** then this interface returns a pointer to the first prepared statement
4172
** associated with the database connection pDb. ^If no prepared statement
4173
** satisfies the conditions of this routine, it returns NULL.
4175
** The [database connection] pointer D in a call to
4176
** [sqlite3_next_stmt(D,S)] must refer to an open database
4177
** connection and in particular must not be a NULL pointer.
4179
SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
4182
** CAPI3REF: Commit And Rollback Notification Callbacks
4184
** ^The sqlite3_commit_hook() interface registers a callback
4185
** function to be invoked whenever a transaction is [COMMIT | committed].
4186
** ^Any callback set by a previous call to sqlite3_commit_hook()
4187
** for the same database connection is overridden.
4188
** ^The sqlite3_rollback_hook() interface registers a callback
4189
** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
4190
** ^Any callback set by a previous call to sqlite3_rollback_hook()
4191
** for the same database connection is overridden.
4192
** ^The pArg argument is passed through to the callback.
4193
** ^If the callback on a commit hook function returns non-zero,
4194
** then the commit is converted into a rollback.
4196
** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
4197
** return the P argument from the previous call of the same function
4198
** on the same [database connection] D, or NULL for
4199
** the first call for each function on D.
4201
** The callback implementation must not do anything that will modify
4202
** the database connection that invoked the callback. Any actions
4203
** to modify the database connection must be deferred until after the
4204
** completion of the [sqlite3_step()] call that triggered the commit
4205
** or rollback hook in the first place.
4206
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
4207
** database connections for the meaning of "modify" in this paragraph.
4209
** ^Registering a NULL function disables the callback.
4211
** ^When the commit hook callback routine returns zero, the [COMMIT]
4212
** operation is allowed to continue normally. ^If the commit hook
4213
** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
4214
** ^The rollback hook is invoked on a rollback that results from a commit
4215
** hook returning non-zero, just as it would be with any other rollback.
4217
** ^For the purposes of this API, a transaction is said to have been
4218
** rolled back if an explicit "ROLLBACK" statement is executed, or
4219
** an error or constraint causes an implicit rollback to occur.
4220
** ^The rollback callback is not invoked if a transaction is
4221
** automatically rolled back because the database connection is closed.
4223
** See also the [sqlite3_update_hook()] interface.
4225
SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
4226
SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
4229
** CAPI3REF: Data Change Notification Callbacks
4231
** ^The sqlite3_update_hook() interface registers a callback function
4232
** with the [database connection] identified by the first argument
4233
** to be invoked whenever a row is updated, inserted or deleted.
4234
** ^Any callback set by a previous call to this function
4235
** for the same database connection is overridden.
4237
** ^The second argument is a pointer to the function to invoke when a
4238
** row is updated, inserted or deleted.
4239
** ^The first argument to the callback is a copy of the third argument
4240
** to sqlite3_update_hook().
4241
** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
4242
** or [SQLITE_UPDATE], depending on the operation that caused the callback
4244
** ^The third and fourth arguments to the callback contain pointers to the
4245
** database and table name containing the affected row.
4246
** ^The final callback parameter is the [rowid] of the row.
4247
** ^In the case of an update, this is the [rowid] after the update takes place.
4249
** ^(The update hook is not invoked when internal system tables are
4250
** modified (i.e. sqlite_master and sqlite_sequence).)^
4252
** ^In the current implementation, the update hook
4253
** is not invoked when duplication rows are deleted because of an
4254
** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook
4255
** invoked when rows are deleted using the [truncate optimization].
4256
** The exceptions defined in this paragraph might change in a future
4257
** release of SQLite.
4259
** The update hook implementation must not do anything that will modify
4260
** the database connection that invoked the update hook. Any actions
4261
** to modify the database connection must be deferred until after the
4262
** completion of the [sqlite3_step()] call that triggered the update hook.
4263
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
4264
** database connections for the meaning of "modify" in this paragraph.
4266
** ^The sqlite3_update_hook(D,C,P) function
4267
** returns the P argument from the previous call
4268
** on the same [database connection] D, or NULL for
4269
** the first call on D.
4271
** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()]
4274
SQLITE_API void *sqlite3_update_hook(
4276
void(*)(void *,int ,char const *,char const *,sqlite3_int64),
4281
** CAPI3REF: Enable Or Disable Shared Pager Cache
4282
** KEYWORDS: {shared cache}
4284
** ^(This routine enables or disables the sharing of the database cache
4285
** and schema data structures between [database connection | connections]
4286
** to the same database. Sharing is enabled if the argument is true
4287
** and disabled if the argument is false.)^
4289
** ^Cache sharing is enabled and disabled for an entire process.
4290
** This is a change as of SQLite version 3.5.0. In prior versions of SQLite,
4291
** sharing was enabled or disabled for each thread separately.
4293
** ^(The cache sharing mode set by this interface effects all subsequent
4294
** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
4295
** Existing database connections continue use the sharing mode
4296
** that was in effect at the time they were opened.)^
4298
** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled
4299
** successfully. An [error code] is returned otherwise.)^
4301
** ^Shared cache is disabled by default. But this might change in
4302
** future releases of SQLite. Applications that care about shared
4303
** cache setting should set it explicitly.
4305
** See Also: [SQLite Shared-Cache Mode]
4307
SQLITE_API int sqlite3_enable_shared_cache(int);
4310
** CAPI3REF: Attempt To Free Heap Memory
4312
** ^The sqlite3_release_memory() interface attempts to free N bytes
4313
** of heap memory by deallocating non-essential memory allocations
4314
** held by the database library. Memory used to cache database
4315
** pages to improve performance is an example of non-essential memory.
4316
** ^sqlite3_release_memory() returns the number of bytes actually freed,
4317
** which might be more or less than the amount requested.
4318
** ^The sqlite3_release_memory() routine is a no-op returning zero
4319
** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].
4321
SQLITE_API int sqlite3_release_memory(int);
4324
** CAPI3REF: Impose A Limit On Heap Size
4326
** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the
4327
** soft limit on the amount of heap memory that may be allocated by SQLite.
4328
** ^SQLite strives to keep heap memory utilization below the soft heap
4329
** limit by reducing the number of pages held in the page cache
4330
** as heap memory usages approaches the limit.
4331
** ^The soft heap limit is "soft" because even though SQLite strives to stay
4332
** below the limit, it will exceed the limit rather than generate
4333
** an [SQLITE_NOMEM] error. In other words, the soft heap limit
4334
** is advisory only.
4336
** ^The return value from sqlite3_soft_heap_limit64() is the size of
4337
** the soft heap limit prior to the call. ^If the argument N is negative
4338
** then no change is made to the soft heap limit. Hence, the current
4339
** size of the soft heap limit can be determined by invoking
4340
** sqlite3_soft_heap_limit64() with a negative argument.
4342
** ^If the argument N is zero then the soft heap limit is disabled.
4344
** ^(The soft heap limit is not enforced in the current implementation
4345
** if one or more of following conditions are true:
4348
** <li> The soft heap limit is set to zero.
4349
** <li> Memory accounting is disabled using a combination of the
4350
** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and
4351
** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.
4352
** <li> An alternative page cache implementation is specified using
4353
** [sqlite3_config]([SQLITE_CONFIG_PCACHE],...).
4354
** <li> The page cache allocates from its own memory pool supplied
4355
** by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than
4359
** Beginning with SQLite version 3.7.3, the soft heap limit is enforced
4360
** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT]
4361
** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT],
4362
** the soft heap limit is enforced on every memory allocation. Without
4363
** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced
4364
** when memory is allocated by the page cache. Testing suggests that because
4365
** the page cache is the predominate memory user in SQLite, most
4366
** applications will achieve adequate soft heap limit enforcement without
4367
** the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT].
4369
** The circumstances under which SQLite will enforce the soft heap limit may
4370
** changes in future releases of SQLite.
4372
SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
4375
** CAPI3REF: Deprecated Soft Heap Limit Interface
4378
** This is a deprecated version of the [sqlite3_soft_heap_limit64()]
4379
** interface. This routine is provided for historical compatibility
4380
** only. All new applications should use the
4381
** [sqlite3_soft_heap_limit64()] interface rather than this one.
4383
SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
4387
** CAPI3REF: Extract Metadata About A Column Of A Table
4389
** ^This routine returns metadata about a specific column of a specific
4390
** database table accessible using the [database connection] handle
4391
** passed as the first function argument.
4393
** ^The column is identified by the second, third and fourth parameters to
4394
** this function. ^The second parameter is either the name of the database
4395
** (i.e. "main", "temp", or an attached database) containing the specified
4396
** table or NULL. ^If it is NULL, then all attached databases are searched
4397
** for the table using the same algorithm used by the database engine to
4398
** resolve unqualified table references.
4400
** ^The third and fourth parameters to this function are the table and column
4401
** name of the desired column, respectively. Neither of these parameters
4404
** ^Metadata is returned by writing to the memory locations passed as the 5th
4405
** and subsequent parameters to this function. ^Any of these arguments may be
4406
** NULL, in which case the corresponding element of metadata is omitted.
4409
** <table border="1">
4410
** <tr><th> Parameter <th> Output<br>Type <th> Description
4412
** <tr><td> 5th <td> const char* <td> Data type
4413
** <tr><td> 6th <td> const char* <td> Name of default collation sequence
4414
** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint
4415
** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY
4416
** <tr><td> 9th <td> int <td> True if column is [AUTOINCREMENT]
4420
** ^The memory pointed to by the character pointers returned for the
4421
** declaration type and collation sequence is valid only until the next
4422
** call to any SQLite API function.
4424
** ^If the specified table is actually a view, an [error code] is returned.
4426
** ^If the specified column is "rowid", "oid" or "_rowid_" and an
4427
** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output
4428
** parameters are set for the explicitly declared column. ^(If there is no
4429
** explicitly declared [INTEGER PRIMARY KEY] column, then the output
4430
** parameters are set as follows:
4433
** data type: "INTEGER"
4434
** collation sequence: "BINARY"
4437
** auto increment: 0
4440
** ^(This function may load one or more schemas from database files. If an
4441
** error occurs during this process, or if the requested table or column
4442
** cannot be found, an [error code] is returned and an error message left
4443
** in the [database connection] (to be retrieved using sqlite3_errmsg()).)^
4445
** ^This API is only available if the library was compiled with the
4446
** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined.
4448
SQLITE_API int sqlite3_table_column_metadata(
4449
sqlite3 *db, /* Connection handle */
4450
const char *zDbName, /* Database name or NULL */
4451
const char *zTableName, /* Table name */
4452
const char *zColumnName, /* Column name */
4453
char const **pzDataType, /* OUTPUT: Declared data type */
4454
char const **pzCollSeq, /* OUTPUT: Collation sequence name */
4455
int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
4456
int *pPrimaryKey, /* OUTPUT: True if column part of PK */
4457
int *pAutoinc /* OUTPUT: True if column is auto-increment */
4461
** CAPI3REF: Load An Extension
4463
** ^This interface loads an SQLite extension library from the named file.
4465
** ^The sqlite3_load_extension() interface attempts to load an
4466
** SQLite extension library contained in the file zFile.
4468
** ^The entry point is zProc.
4469
** ^zProc may be 0, in which case the name of the entry point
4470
** defaults to "sqlite3_extension_init".
4471
** ^The sqlite3_load_extension() interface returns
4472
** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
4473
** ^If an error occurs and pzErrMsg is not 0, then the
4474
** [sqlite3_load_extension()] interface shall attempt to
4475
** fill *pzErrMsg with error message text stored in memory
4476
** obtained from [sqlite3_malloc()]. The calling function
4477
** should free this memory by calling [sqlite3_free()].
4479
** ^Extension loading must be enabled using
4480
** [sqlite3_enable_load_extension()] prior to calling this API,
4481
** otherwise an error will be returned.
4483
** See also the [load_extension() SQL function].
4485
SQLITE_API int sqlite3_load_extension(
4486
sqlite3 *db, /* Load the extension into this database connection */
4487
const char *zFile, /* Name of the shared library containing extension */
4488
const char *zProc, /* Entry point. Derived from zFile if 0 */
4489
char **pzErrMsg /* Put error message here if not 0 */
4493
** CAPI3REF: Enable Or Disable Extension Loading
4495
** ^So as not to open security holes in older applications that are
4496
** unprepared to deal with extension loading, and as a means of disabling
4497
** extension loading while evaluating user-entered SQL, the following API
4498
** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
4500
** ^Extension loading is off by default. See ticket #1863.
4501
** ^Call the sqlite3_enable_load_extension() routine with onoff==1
4502
** to turn extension loading on and call it with onoff==0 to turn
4503
** it back off again.
4505
SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
4508
** CAPI3REF: Automatically Load Statically Linked Extensions
4510
** ^This interface causes the xEntryPoint() function to be invoked for
4511
** each new [database connection] that is created. The idea here is that
4512
** xEntryPoint() is the entry point for a statically linked SQLite extension
4513
** that is to be automatically loaded into all new database connections.
4515
** ^(Even though the function prototype shows that xEntryPoint() takes
4516
** no arguments and returns void, SQLite invokes xEntryPoint() with three
4517
** arguments and expects and integer result as if the signature of the
4518
** entry point where as follows:
4520
** <blockquote><pre>
4521
** int xEntryPoint(
4522
** sqlite3 *db,
4523
** const char **pzErrMsg,
4524
** const struct sqlite3_api_routines *pThunk
4526
** </pre></blockquote>)^
4528
** If the xEntryPoint routine encounters an error, it should make *pzErrMsg
4529
** point to an appropriate error message (obtained from [sqlite3_mprintf()])
4530
** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg
4531
** is NULL before calling the xEntryPoint(). ^SQLite will invoke
4532
** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns. ^If any
4533
** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()],
4534
** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail.
4536
** ^Calling sqlite3_auto_extension(X) with an entry point X that is already
4537
** on the list of automatic extensions is a harmless no-op. ^No entry point
4538
** will be called more than once for each database connection that is opened.
4540
** See also: [sqlite3_reset_auto_extension()].
4542
SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void));
4545
** CAPI3REF: Reset Automatic Extension Loading
4547
** ^This interface disables all automatic extensions previously
4548
** registered using [sqlite3_auto_extension()].
4550
SQLITE_API void sqlite3_reset_auto_extension(void);
4553
** The interface to the virtual-table mechanism is currently considered
4554
** to be experimental. The interface might change in incompatible ways.
4555
** If this is a problem for you, do not use the interface at this time.
4557
** When the virtual-table mechanism stabilizes, we will declare the
4558
** interface fixed, support it indefinitely, and remove this comment.
4562
** Structures used by the virtual table interface
4564
typedef struct sqlite3_vtab sqlite3_vtab;
4565
typedef struct sqlite3_index_info sqlite3_index_info;
4566
typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
4567
typedef struct sqlite3_module sqlite3_module;
4570
** CAPI3REF: Virtual Table Object
4571
** KEYWORDS: sqlite3_module {virtual table module}
4573
** This structure, sometimes called a "virtual table module",
4574
** defines the implementation of a [virtual tables].
4575
** This structure consists mostly of methods for the module.
4577
** ^A virtual table module is created by filling in a persistent
4578
** instance of this structure and passing a pointer to that instance
4579
** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].
4580
** ^The registration remains valid until it is replaced by a different
4581
** module or until the [database connection] closes. The content
4582
** of this structure must not change while it is registered with
4583
** any database connection.
4585
struct sqlite3_module {
4587
int (*xCreate)(sqlite3*, void *pAux,
4588
int argc, const char *const*argv,
4589
sqlite3_vtab **ppVTab, char**);
4590
int (*xConnect)(sqlite3*, void *pAux,
4591
int argc, const char *const*argv,
4592
sqlite3_vtab **ppVTab, char**);
4593
int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
4594
int (*xDisconnect)(sqlite3_vtab *pVTab);
4595
int (*xDestroy)(sqlite3_vtab *pVTab);
4596
int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
4597
int (*xClose)(sqlite3_vtab_cursor*);
4598
int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
4599
int argc, sqlite3_value **argv);
4600
int (*xNext)(sqlite3_vtab_cursor*);
4601
int (*xEof)(sqlite3_vtab_cursor*);
4602
int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
4603
int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
4604
int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
4605
int (*xBegin)(sqlite3_vtab *pVTab);
4606
int (*xSync)(sqlite3_vtab *pVTab);
4607
int (*xCommit)(sqlite3_vtab *pVTab);
4608
int (*xRollback)(sqlite3_vtab *pVTab);
4609
int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
4610
void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
4612
int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
4616
** CAPI3REF: Virtual Table Indexing Information
4617
** KEYWORDS: sqlite3_index_info
4619
** The sqlite3_index_info structure and its substructures is used as part
4620
** of the [virtual table] interface to
4621
** pass information into and receive the reply from the [xBestIndex]
4622
** method of a [virtual table module]. The fields under **Inputs** are the
4623
** inputs to xBestIndex and are read-only. xBestIndex inserts its
4624
** results into the **Outputs** fields.
4626
** ^(The aConstraint[] array records WHERE clause constraints of the form:
4628
** <blockquote>column OP expr</blockquote>
4630
** where OP is =, <, <=, >, or >=.)^ ^(The particular operator is
4631
** stored in aConstraint[].op using one of the
4632
** [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^
4633
** ^(The index of the column is stored in
4634
** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the
4635
** expr on the right-hand side can be evaluated (and thus the constraint
4636
** is usable) and false if it cannot.)^
4638
** ^The optimizer automatically inverts terms of the form "expr OP column"
4639
** and makes other simplifications to the WHERE clause in an attempt to
4640
** get as many WHERE clause terms into the form shown above as possible.
4641
** ^The aConstraint[] array only reports WHERE clause terms that are
4642
** relevant to the particular virtual table being queried.
4644
** ^Information about the ORDER BY clause is stored in aOrderBy[].
4645
** ^Each term of aOrderBy records a column of the ORDER BY clause.
4647
** The [xBestIndex] method must fill aConstraintUsage[] with information
4648
** about what parameters to pass to xFilter. ^If argvIndex>0 then
4649
** the right-hand side of the corresponding aConstraint[] is evaluated
4650
** and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit
4651
** is true, then the constraint is assumed to be fully handled by the
4652
** virtual table and is not checked again by SQLite.)^
4654
** ^The idxNum and idxPtr values are recorded and passed into the
4655
** [xFilter] method.
4656
** ^[sqlite3_free()] is used to free idxPtr if and only if
4657
** needToFreeIdxPtr is true.
4659
** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in
4660
** the correct order to satisfy the ORDER BY clause so that no separate
4661
** sorting step is required.
4663
** ^The estimatedCost value is an estimate of the cost of doing the
4664
** particular lookup. A full scan of a table with N entries should have
4665
** a cost of N. A binary search of a table of N entries should have a
4666
** cost of approximately log(N).
4668
struct sqlite3_index_info {
4670
int nConstraint; /* Number of entries in aConstraint */
4671
struct sqlite3_index_constraint {
4672
int iColumn; /* Column on left-hand side of constraint */
4673
unsigned char op; /* Constraint operator */
4674
unsigned char usable; /* True if this constraint is usable */
4675
int iTermOffset; /* Used internally - xBestIndex should ignore */
4676
} *aConstraint; /* Table of WHERE clause constraints */
4677
int nOrderBy; /* Number of terms in the ORDER BY clause */
4678
struct sqlite3_index_orderby {
4679
int iColumn; /* Column number */
4680
unsigned char desc; /* True for DESC. False for ASC. */
4681
} *aOrderBy; /* The ORDER BY clause */
4683
struct sqlite3_index_constraint_usage {
4684
int argvIndex; /* if >0, constraint is part of argv to xFilter */
4685
unsigned char omit; /* Do not code a test for this constraint */
4686
} *aConstraintUsage;
4687
int idxNum; /* Number used to identify the index */
4688
char *idxStr; /* String, possibly obtained from sqlite3_malloc */
4689
int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
4690
int orderByConsumed; /* True if output is already ordered */
4691
double estimatedCost; /* Estimated cost of using this index */
4695
** CAPI3REF: Virtual Table Constraint Operator Codes
4697
** These macros defined the allowed values for the
4698
** [sqlite3_index_info].aConstraint[].op field. Each value represents
4699
** an operator that is part of a constraint term in the wHERE clause of
4700
** a query that uses a [virtual table].
4702
#define SQLITE_INDEX_CONSTRAINT_EQ 2
4703
#define SQLITE_INDEX_CONSTRAINT_GT 4
4704
#define SQLITE_INDEX_CONSTRAINT_LE 8
4705
#define SQLITE_INDEX_CONSTRAINT_LT 16
4706
#define SQLITE_INDEX_CONSTRAINT_GE 32
4707
#define SQLITE_INDEX_CONSTRAINT_MATCH 64
4710
** CAPI3REF: Register A Virtual Table Implementation
4712
** ^These routines are used to register a new [virtual table module] name.
4713
** ^Module names must be registered before
4714
** creating a new [virtual table] using the module and before using a
4715
** preexisting [virtual table] for the module.
4717
** ^The module name is registered on the [database connection] specified
4718
** by the first parameter. ^The name of the module is given by the
4719
** second parameter. ^The third parameter is a pointer to
4720
** the implementation of the [virtual table module]. ^The fourth
4721
** parameter is an arbitrary client data pointer that is passed through
4722
** into the [xCreate] and [xConnect] methods of the virtual table module
4723
** when a new virtual table is be being created or reinitialized.
4725
** ^The sqlite3_create_module_v2() interface has a fifth parameter which
4726
** is a pointer to a destructor for the pClientData. ^SQLite will
4727
** invoke the destructor function (if it is not NULL) when SQLite
4728
** no longer needs the pClientData pointer. ^The destructor will also
4729
** be invoked if the call to sqlite3_create_module_v2() fails.
4730
** ^The sqlite3_create_module()
4731
** interface is equivalent to sqlite3_create_module_v2() with a NULL
4734
SQLITE_API int sqlite3_create_module(
4735
sqlite3 *db, /* SQLite connection to register module with */
4736
const char *zName, /* Name of the module */
4737
const sqlite3_module *p, /* Methods for the module */
4738
void *pClientData /* Client data for xCreate/xConnect */
4740
SQLITE_API int sqlite3_create_module_v2(
4741
sqlite3 *db, /* SQLite connection to register module with */
4742
const char *zName, /* Name of the module */
4743
const sqlite3_module *p, /* Methods for the module */
4744
void *pClientData, /* Client data for xCreate/xConnect */
4745
void(*xDestroy)(void*) /* Module destructor function */
4749
** CAPI3REF: Virtual Table Instance Object
4750
** KEYWORDS: sqlite3_vtab
4752
** Every [virtual table module] implementation uses a subclass
4753
** of this object to describe a particular instance
4754
** of the [virtual table]. Each subclass will
4755
** be tailored to the specific needs of the module implementation.
4756
** The purpose of this superclass is to define certain fields that are
4757
** common to all module implementations.
4759
** ^Virtual tables methods can set an error message by assigning a
4760
** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should
4761
** take care that any prior string is freed by a call to [sqlite3_free()]
4762
** prior to assigning a new string to zErrMsg. ^After the error message
4763
** is delivered up to the client application, the string will be automatically
4764
** freed by sqlite3_free() and the zErrMsg field will be zeroed.
4766
struct sqlite3_vtab {
4767
const sqlite3_module *pModule; /* The module for this virtual table */
4768
int nRef; /* NO LONGER USED */
4769
char *zErrMsg; /* Error message from sqlite3_mprintf() */
4770
/* Virtual table implementations will typically add additional fields */
4774
** CAPI3REF: Virtual Table Cursor Object
4775
** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
4777
** Every [virtual table module] implementation uses a subclass of the
4778
** following structure to describe cursors that point into the
4779
** [virtual table] and are used
4780
** to loop through the virtual table. Cursors are created using the
4781
** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed
4782
** by the [sqlite3_module.xClose | xClose] method. Cursors are used
4783
** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods
4784
** of the module. Each module implementation will define
4785
** the content of a cursor structure to suit its own needs.
4787
** This superclass exists in order to define fields of the cursor that
4788
** are common to all implementations.
4790
struct sqlite3_vtab_cursor {
4791
sqlite3_vtab *pVtab; /* Virtual table of this cursor */
4792
/* Virtual table implementations will typically add additional fields */
4796
** CAPI3REF: Declare The Schema Of A Virtual Table
4798
** ^The [xCreate] and [xConnect] methods of a
4799
** [virtual table module] call this interface
4800
** to declare the format (the names and datatypes of the columns) of
4801
** the virtual tables they implement.
4803
SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
4806
** CAPI3REF: Overload A Function For A Virtual Table
4808
** ^(Virtual tables can provide alternative implementations of functions
4809
** using the [xFindFunction] method of the [virtual table module].
4810
** But global versions of those functions
4811
** must exist in order to be overloaded.)^
4813
** ^(This API makes sure a global version of a function with a particular
4814
** name and number of parameters exists. If no such function exists
4815
** before this API is called, a new function is created.)^ ^The implementation
4816
** of the new function always causes an exception to be thrown. So
4817
** the new function is not good for anything by itself. Its only
4818
** purpose is to be a placeholder function that can be overloaded
4819
** by a [virtual table].
4821
SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
4824
** The interface to the virtual-table mechanism defined above (back up
4825
** to a comment remarkably similar to this one) is currently considered
4826
** to be experimental. The interface might change in incompatible ways.
4827
** If this is a problem for you, do not use the interface at this time.
4829
** When the virtual-table mechanism stabilizes, we will declare the
4830
** interface fixed, support it indefinitely, and remove this comment.
4834
** CAPI3REF: A Handle To An Open BLOB
4835
** KEYWORDS: {BLOB handle} {BLOB handles}
4837
** An instance of this object represents an open BLOB on which
4838
** [sqlite3_blob_open | incremental BLOB I/O] can be performed.
4839
** ^Objects of this type are created by [sqlite3_blob_open()]
4840
** and destroyed by [sqlite3_blob_close()].
4841
** ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
4842
** can be used to read or write small subsections of the BLOB.
4843
** ^The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.
4845
typedef struct sqlite3_blob sqlite3_blob;
4848
** CAPI3REF: Open A BLOB For Incremental I/O
4850
** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located
4851
** in row iRow, column zColumn, table zTable in database zDb;
4852
** in other words, the same BLOB that would be selected by:
4855
** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
4858
** ^If the flags parameter is non-zero, then the BLOB is opened for read
4859
** and write access. ^If it is zero, the BLOB is opened for read access.
4860
** ^It is not possible to open a column that is part of an index or primary
4861
** key for writing. ^If [foreign key constraints] are enabled, it is
4862
** not possible to open a column that is part of a [child key] for writing.
4864
** ^Note that the database name is not the filename that contains
4865
** the database but rather the symbolic name of the database that
4866
** appears after the AS keyword when the database is connected using [ATTACH].
4867
** ^For the main database file, the database name is "main".
4868
** ^For TEMP tables, the database name is "temp".
4870
** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is written
4871
** to *ppBlob. Otherwise an [error code] is returned and *ppBlob is set
4872
** to be a null pointer.)^
4873
** ^This function sets the [database connection] error code and message
4874
** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()] and related
4875
** functions. ^Note that the *ppBlob variable is always initialized in a
4876
** way that makes it safe to invoke [sqlite3_blob_close()] on *ppBlob
4877
** regardless of the success or failure of this routine.
4879
** ^(If the row that a BLOB handle points to is modified by an
4880
** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
4881
** then the BLOB handle is marked as "expired".
4882
** This is true if any column of the row is changed, even a column
4883
** other than the one the BLOB handle is open on.)^
4884
** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
4885
** an expired BLOB handle fail with a return code of [SQLITE_ABORT].
4886
** ^(Changes written into a BLOB prior to the BLOB expiring are not
4887
** rolled back by the expiration of the BLOB. Such changes will eventually
4888
** commit if the transaction continues to completion.)^
4890
** ^Use the [sqlite3_blob_bytes()] interface to determine the size of
4891
** the opened blob. ^The size of a blob may not be changed by this
4892
** interface. Use the [UPDATE] SQL command to change the size of a
4895
** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
4896
** and the built-in [zeroblob] SQL function can be used, if desired,
4897
** to create an empty, zero-filled blob in which to read or write using
4900
** To avoid a resource leak, every open [BLOB handle] should eventually
4901
** be released by a call to [sqlite3_blob_close()].
4903
SQLITE_API int sqlite3_blob_open(
4907
const char *zColumn,
4910
sqlite3_blob **ppBlob
4914
** CAPI3REF: Move a BLOB Handle to a New Row
4916
** ^This function is used to move an existing blob handle so that it points
4917
** to a different row of the same database table. ^The new row is identified
4918
** by the rowid value passed as the second argument. Only the row can be
4919
** changed. ^The database, table and column on which the blob handle is open
4920
** remain the same. Moving an existing blob handle to a new row can be
4921
** faster than closing the existing handle and opening a new one.
4923
** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -
4924
** it must exist and there must be either a blob or text value stored in
4925
** the nominated column.)^ ^If the new row is not present in the table, or if
4926
** it does not contain a blob or text value, or if another error occurs, an
4927
** SQLite error code is returned and the blob handle is considered aborted.
4928
** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or
4929
** [sqlite3_blob_reopen()] on an aborted blob handle immediately return
4930
** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle
4931
** always returns zero.
4933
** ^This function sets the database handle error code and message.
4935
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
4938
** CAPI3REF: Close A BLOB Handle
4940
** ^Closes an open [BLOB handle].
4942
** ^Closing a BLOB shall cause the current transaction to commit
4943
** if there are no other BLOBs, no pending prepared statements, and the
4944
** database connection is in [autocommit mode].
4945
** ^If any writes were made to the BLOB, they might be held in cache
4946
** until the close operation if they will fit.
4948
** ^(Closing the BLOB often forces the changes
4949
** out to disk and so if any I/O errors occur, they will likely occur
4950
** at the time when the BLOB is closed. Any errors that occur during
4951
** closing are reported as a non-zero return value.)^
4953
** ^(The BLOB is closed unconditionally. Even if this routine returns
4954
** an error code, the BLOB is still closed.)^
4956
** ^Calling this routine with a null pointer (such as would be returned
4957
** by a failed call to [sqlite3_blob_open()]) is a harmless no-op.
4959
SQLITE_API int sqlite3_blob_close(sqlite3_blob *);
4962
** CAPI3REF: Return The Size Of An Open BLOB
4964
** ^Returns the size in bytes of the BLOB accessible via the
4965
** successfully opened [BLOB handle] in its only argument. ^The
4966
** incremental blob I/O routines can only read or overwriting existing
4967
** blob content; they cannot change the size of a blob.
4969
** This routine only works on a [BLOB handle] which has been created
4970
** by a prior successful call to [sqlite3_blob_open()] and which has not
4971
** been closed by [sqlite3_blob_close()]. Passing any other pointer in
4972
** to this routine results in undefined and probably undesirable behavior.
4974
SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *);
4977
** CAPI3REF: Read Data From A BLOB Incrementally
4979
** ^(This function is used to read data from an open [BLOB handle] into a
4980
** caller-supplied buffer. N bytes of data are copied into buffer Z
4981
** from the open BLOB, starting at offset iOffset.)^
4983
** ^If offset iOffset is less than N bytes from the end of the BLOB,
4984
** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is
4985
** less than zero, [SQLITE_ERROR] is returned and no data is read.
4986
** ^The size of the blob (and hence the maximum value of N+iOffset)
4987
** can be determined using the [sqlite3_blob_bytes()] interface.
4989
** ^An attempt to read from an expired [BLOB handle] fails with an
4990
** error code of [SQLITE_ABORT].
4992
** ^(On success, sqlite3_blob_read() returns SQLITE_OK.
4993
** Otherwise, an [error code] or an [extended error code] is returned.)^
4995
** This routine only works on a [BLOB handle] which has been created
4996
** by a prior successful call to [sqlite3_blob_open()] and which has not
4997
** been closed by [sqlite3_blob_close()]. Passing any other pointer in
4998
** to this routine results in undefined and probably undesirable behavior.
5000
** See also: [sqlite3_blob_write()].
5002
SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
5005
** CAPI3REF: Write Data Into A BLOB Incrementally
5007
** ^This function is used to write data into an open [BLOB handle] from a
5008
** caller-supplied buffer. ^N bytes of data are copied from the buffer Z
5009
** into the open BLOB, starting at offset iOffset.
5011
** ^If the [BLOB handle] passed as the first argument was not opened for
5012
** writing (the flags parameter to [sqlite3_blob_open()] was zero),
5013
** this function returns [SQLITE_READONLY].
5015
** ^This function may only modify the contents of the BLOB; it is
5016
** not possible to increase the size of a BLOB using this API.
5017
** ^If offset iOffset is less than N bytes from the end of the BLOB,
5018
** [SQLITE_ERROR] is returned and no data is written. ^If N is
5019
** less than zero [SQLITE_ERROR] is returned and no data is written.
5020
** The size of the BLOB (and hence the maximum value of N+iOffset)
5021
** can be determined using the [sqlite3_blob_bytes()] interface.
5023
** ^An attempt to write to an expired [BLOB handle] fails with an
5024
** error code of [SQLITE_ABORT]. ^Writes to the BLOB that occurred
5025
** before the [BLOB handle] expired are not rolled back by the
5026
** expiration of the handle, though of course those changes might
5027
** have been overwritten by the statement that expired the BLOB handle
5028
** or by other independent statements.
5030
** ^(On success, sqlite3_blob_write() returns SQLITE_OK.
5031
** Otherwise, an [error code] or an [extended error code] is returned.)^
5033
** This routine only works on a [BLOB handle] which has been created
5034
** by a prior successful call to [sqlite3_blob_open()] and which has not
5035
** been closed by [sqlite3_blob_close()]. Passing any other pointer in
5036
** to this routine results in undefined and probably undesirable behavior.
5038
** See also: [sqlite3_blob_read()].
5040
SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
5043
** CAPI3REF: Virtual File System Objects
5045
** A virtual filesystem (VFS) is an [sqlite3_vfs] object
5046
** that SQLite uses to interact
5047
** with the underlying operating system. Most SQLite builds come with a
5048
** single default VFS that is appropriate for the host computer.
5049
** New VFSes can be registered and existing VFSes can be unregistered.
5050
** The following interfaces are provided.
5052
** ^The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.
5053
** ^Names are case sensitive.
5054
** ^Names are zero-terminated UTF-8 strings.
5055
** ^If there is no match, a NULL pointer is returned.
5056
** ^If zVfsName is NULL then the default VFS is returned.
5058
** ^New VFSes are registered with sqlite3_vfs_register().
5059
** ^Each new VFS becomes the default VFS if the makeDflt flag is set.
5060
** ^The same VFS can be registered multiple times without injury.
5061
** ^To make an existing VFS into the default VFS, register it again
5062
** with the makeDflt flag set. If two different VFSes with the
5063
** same name are registered, the behavior is undefined. If a
5064
** VFS is registered with a name that is NULL or an empty string,
5065
** then the behavior is undefined.
5067
** ^Unregister a VFS with the sqlite3_vfs_unregister() interface.
5068
** ^(If the default VFS is unregistered, another VFS is chosen as
5069
** the default. The choice for the new VFS is arbitrary.)^
5071
SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
5072
SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
5073
SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
5076
** CAPI3REF: Mutexes
5078
** The SQLite core uses these routines for thread
5079
** synchronization. Though they are intended for internal
5080
** use by SQLite, code that links against SQLite is
5081
** permitted to use any of these routines.
5083
** The SQLite source code contains multiple implementations
5084
** of these mutex routines. An appropriate implementation
5085
** is selected automatically at compile-time. ^(The following
5086
** implementations are available in the SQLite core:
5089
** <li> SQLITE_MUTEX_OS2
5090
** <li> SQLITE_MUTEX_PTHREAD
5091
** <li> SQLITE_MUTEX_W32
5092
** <li> SQLITE_MUTEX_NOOP
5095
** ^The SQLITE_MUTEX_NOOP implementation is a set of routines
5096
** that does no real locking and is appropriate for use in
5097
** a single-threaded application. ^The SQLITE_MUTEX_OS2,
5098
** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations
5099
** are appropriate for use on OS/2, Unix, and Windows.
5101
** ^(If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
5102
** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
5103
** implementation is included with the library. In this case the
5104
** application must supply a custom mutex implementation using the
5105
** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function
5106
** before calling sqlite3_initialize() or any other public sqlite3_
5107
** function that calls sqlite3_initialize().)^
5109
** ^The sqlite3_mutex_alloc() routine allocates a new
5110
** mutex and returns a pointer to it. ^If it returns NULL
5111
** that means that a mutex could not be allocated. ^SQLite
5112
** will unwind its stack and return an error. ^(The argument
5113
** to sqlite3_mutex_alloc() is one of these integer constants:
5116
** <li> SQLITE_MUTEX_FAST
5117
** <li> SQLITE_MUTEX_RECURSIVE
5118
** <li> SQLITE_MUTEX_STATIC_MASTER
5119
** <li> SQLITE_MUTEX_STATIC_MEM
5120
** <li> SQLITE_MUTEX_STATIC_MEM2
5121
** <li> SQLITE_MUTEX_STATIC_PRNG
5122
** <li> SQLITE_MUTEX_STATIC_LRU
5123
** <li> SQLITE_MUTEX_STATIC_LRU2
5126
** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
5127
** cause sqlite3_mutex_alloc() to create
5128
** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
5129
** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
5130
** The mutex implementation does not need to make a distinction
5131
** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
5132
** not want to. ^SQLite will only request a recursive mutex in
5133
** cases where it really needs one. ^If a faster non-recursive mutex
5134
** implementation is available on the host platform, the mutex subsystem
5135
** might return such a mutex in response to SQLITE_MUTEX_FAST.
5137
** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other
5138
** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
5139
** a pointer to a static preexisting mutex. ^Six static mutexes are
5140
** used by the current version of SQLite. Future versions of SQLite
5141
** may add additional static mutexes. Static mutexes are for internal
5142
** use by SQLite only. Applications that use SQLite mutexes should
5143
** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
5144
** SQLITE_MUTEX_RECURSIVE.
5146
** ^Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
5147
** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
5148
** returns a different mutex on every call. ^But for the static
5149
** mutex types, the same mutex is returned on every call that has
5150
** the same type number.
5152
** ^The sqlite3_mutex_free() routine deallocates a previously
5153
** allocated dynamic mutex. ^SQLite is careful to deallocate every
5154
** dynamic mutex that it allocates. The dynamic mutexes must not be in
5155
** use when they are deallocated. Attempting to deallocate a static
5156
** mutex results in undefined behavior. ^SQLite never deallocates
5159
** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
5160
** to enter a mutex. ^If another thread is already within the mutex,
5161
** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
5162
** SQLITE_BUSY. ^The sqlite3_mutex_try() interface returns [SQLITE_OK]
5163
** upon successful entry. ^(Mutexes created using
5164
** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
5165
** In such cases the,
5166
** mutex must be exited an equal number of times before another thread
5167
** can enter.)^ ^(If the same thread tries to enter any other
5168
** kind of mutex more than once, the behavior is undefined.
5169
** SQLite will never exhibit
5170
** such behavior in its own use of mutexes.)^
5172
** ^(Some systems (for example, Windows 95) do not support the operation
5173
** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try()
5174
** will always return SQLITE_BUSY. The SQLite core only ever uses
5175
** sqlite3_mutex_try() as an optimization so this is acceptable behavior.)^
5177
** ^The sqlite3_mutex_leave() routine exits a mutex that was
5178
** previously entered by the same thread. ^(The behavior
5179
** is undefined if the mutex is not currently entered by the
5180
** calling thread or is not currently allocated. SQLite will
5181
** never do either.)^
5183
** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
5184
** sqlite3_mutex_leave() is a NULL pointer, then all three routines
5185
** behave as no-ops.
5187
** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
5189
SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);
5190
SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*);
5191
SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*);
5192
SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
5193
SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
5196
** CAPI3REF: Mutex Methods Object
5198
** An instance of this structure defines the low-level routines
5199
** used to allocate and use mutexes.
5201
** Usually, the default mutex implementations provided by SQLite are
5202
** sufficient, however the user has the option of substituting a custom
5203
** implementation for specialized deployments or systems for which SQLite
5204
** does not provide a suitable implementation. In this case, the user
5205
** creates and populates an instance of this structure to pass
5206
** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
5207
** Additionally, an instance of this structure can be used as an
5208
** output variable when querying the system for the current mutex
5209
** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.
5211
** ^The xMutexInit method defined by this structure is invoked as
5212
** part of system initialization by the sqlite3_initialize() function.
5213
** ^The xMutexInit routine is called by SQLite exactly once for each
5214
** effective call to [sqlite3_initialize()].
5216
** ^The xMutexEnd method defined by this structure is invoked as
5217
** part of system shutdown by the sqlite3_shutdown() function. The
5218
** implementation of this method is expected to release all outstanding
5219
** resources obtained by the mutex methods implementation, especially
5220
** those obtained by the xMutexInit method. ^The xMutexEnd()
5221
** interface is invoked exactly once for each call to [sqlite3_shutdown()].
5223
** ^(The remaining seven methods defined by this structure (xMutexAlloc,
5224
** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
5225
** xMutexNotheld) implement the following interfaces (respectively):
5228
** <li> [sqlite3_mutex_alloc()] </li>
5229
** <li> [sqlite3_mutex_free()] </li>
5230
** <li> [sqlite3_mutex_enter()] </li>
5231
** <li> [sqlite3_mutex_try()] </li>
5232
** <li> [sqlite3_mutex_leave()] </li>
5233
** <li> [sqlite3_mutex_held()] </li>
5234
** <li> [sqlite3_mutex_notheld()] </li>
5237
** The only difference is that the public sqlite3_XXX functions enumerated
5238
** above silently ignore any invocations that pass a NULL pointer instead
5239
** of a valid mutex handle. The implementations of the methods defined
5240
** by this structure are not required to handle this case, the results
5241
** of passing a NULL pointer instead of a valid mutex handle are undefined
5242
** (i.e. it is acceptable to provide an implementation that segfaults if
5243
** it is passed a NULL pointer).
5245
** The xMutexInit() method must be threadsafe. ^It must be harmless to
5246
** invoke xMutexInit() multiple times within the same process and without
5247
** intervening calls to xMutexEnd(). Second and subsequent calls to
5248
** xMutexInit() must be no-ops.
5250
** ^xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
5251
** and its associates). ^Similarly, xMutexAlloc() must not use SQLite memory
5252
** allocation for a static mutex. ^However xMutexAlloc() may use SQLite
5253
** memory allocation for a fast or recursive mutex.
5255
** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
5256
** called, but only if the prior call to xMutexInit returned SQLITE_OK.
5257
** If xMutexInit fails in any way, it is expected to clean up after itself
5258
** prior to returning.
5260
typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
5261
struct sqlite3_mutex_methods {
5262
int (*xMutexInit)(void);
5263
int (*xMutexEnd)(void);
5264
sqlite3_mutex *(*xMutexAlloc)(int);
5265
void (*xMutexFree)(sqlite3_mutex *);
5266
void (*xMutexEnter)(sqlite3_mutex *);
5267
int (*xMutexTry)(sqlite3_mutex *);
5268
void (*xMutexLeave)(sqlite3_mutex *);
5269
int (*xMutexHeld)(sqlite3_mutex *);
5270
int (*xMutexNotheld)(sqlite3_mutex *);
5274
** CAPI3REF: Mutex Verification Routines
5276
** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
5277
** are intended for use inside assert() statements. ^The SQLite core
5278
** never uses these routines except inside an assert() and applications
5279
** are advised to follow the lead of the core. ^The SQLite core only
5280
** provides implementations for these routines when it is compiled
5281
** with the SQLITE_DEBUG flag. ^External mutex implementations
5282
** are only required to provide these routines if SQLITE_DEBUG is
5283
** defined and if NDEBUG is not defined.
5285
** ^These routines should return true if the mutex in their argument
5286
** is held or not held, respectively, by the calling thread.
5288
** ^The implementation is not required to provided versions of these
5289
** routines that actually work. If the implementation does not provide working
5290
** versions of these routines, it should at least provide stubs that always
5291
** return true so that one does not get spurious assertion failures.
5293
** ^If the argument to sqlite3_mutex_held() is a NULL pointer then
5294
** the routine should return 1. This seems counter-intuitive since
5295
** clearly the mutex cannot be held if it does not exist. But the
5296
** the reason the mutex does not exist is because the build is not
5297
** using mutexes. And we do not want the assert() containing the
5298
** call to sqlite3_mutex_held() to fail, so a non-zero return is
5299
** the appropriate thing to do. ^The sqlite3_mutex_notheld()
5300
** interface should also return 1 when given a NULL pointer.
5303
SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);
5304
SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
5308
** CAPI3REF: Mutex Types
5310
** The [sqlite3_mutex_alloc()] interface takes a single argument
5311
** which is one of these integer constants.
5313
** The set of static mutexes may change from one SQLite release to the
5314
** next. Applications that override the built-in mutex logic must be
5315
** prepared to accommodate additional static mutexes.
5317
#define SQLITE_MUTEX_FAST 0
5318
#define SQLITE_MUTEX_RECURSIVE 1
5319
#define SQLITE_MUTEX_STATIC_MASTER 2
5320
#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
5321
#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */
5322
#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */
5323
#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */
5324
#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
5325
#define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */
5326
#define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */
5329
** CAPI3REF: Retrieve the mutex for a database connection
5331
** ^This interface returns a pointer the [sqlite3_mutex] object that
5332
** serializes access to the [database connection] given in the argument
5333
** when the [threading mode] is Serialized.
5334
** ^If the [threading mode] is Single-thread or Multi-thread then this
5335
** routine returns a NULL pointer.
5337
SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
5340
** CAPI3REF: Low-Level Control Of Database Files
5342
** ^The [sqlite3_file_control()] interface makes a direct call to the
5343
** xFileControl method for the [sqlite3_io_methods] object associated
5344
** with a particular database identified by the second argument. ^The
5345
** name of the database is "main" for the main database or "temp" for the
5346
** TEMP database, or the name that appears after the AS keyword for
5347
** databases that are added using the [ATTACH] SQL command.
5348
** ^A NULL pointer can be used in place of "main" to refer to the
5349
** main database file.
5350
** ^The third and fourth parameters to this routine
5351
** are passed directly through to the second and third parameters of
5352
** the xFileControl method. ^The return value of the xFileControl
5353
** method becomes the return value of this routine.
5355
** ^The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes
5356
** a pointer to the underlying [sqlite3_file] object to be written into
5357
** the space pointed to by the 4th parameter. ^The SQLITE_FCNTL_FILE_POINTER
5358
** case is a short-circuit path which does not actually invoke the
5359
** underlying sqlite3_io_methods.xFileControl method.
5361
** ^If the second parameter (zDbName) does not match the name of any
5362
** open database file, then SQLITE_ERROR is returned. ^This error
5363
** code is not remembered and will not be recalled by [sqlite3_errcode()]
5364
** or [sqlite3_errmsg()]. The underlying xFileControl method might
5365
** also return SQLITE_ERROR. There is no way to distinguish between
5366
** an incorrect zDbName and an SQLITE_ERROR return from the underlying
5367
** xFileControl method.
5369
** See also: [SQLITE_FCNTL_LOCKSTATE]
5371
SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
5374
** CAPI3REF: Testing Interface
5376
** ^The sqlite3_test_control() interface is used to read out internal
5377
** state of SQLite and to inject faults into SQLite for testing
5378
** purposes. ^The first parameter is an operation code that determines
5379
** the number, meaning, and operation of all subsequent parameters.
5381
** This interface is not for use by applications. It exists solely
5382
** for verifying the correct operation of the SQLite library. Depending
5383
** on how the SQLite library is compiled, this interface might not exist.
5385
** The details of the operation codes, their meanings, the parameters
5386
** they take, and what they do are all subject to change without notice.
5387
** Unlike most of the SQLite API, this function is not guaranteed to
5388
** operate consistently from one release to the next.
5390
SQLITE_API int sqlite3_test_control(int op, ...);
5393
** CAPI3REF: Testing Interface Operation Codes
5395
** These constants are the valid operation code parameters used
5396
** as the first argument to [sqlite3_test_control()].
5398
** These parameters and their meanings are subject to change
5399
** without notice. These values are for testing purposes only.
5400
** Applications should not use any of these parameters or the
5401
** [sqlite3_test_control()] interface.
5403
#define SQLITE_TESTCTRL_FIRST 5
5404
#define SQLITE_TESTCTRL_PRNG_SAVE 5
5405
#define SQLITE_TESTCTRL_PRNG_RESTORE 6
5406
#define SQLITE_TESTCTRL_PRNG_RESET 7
5407
#define SQLITE_TESTCTRL_BITVEC_TEST 8
5408
#define SQLITE_TESTCTRL_FAULT_INSTALL 9
5409
#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10
5410
#define SQLITE_TESTCTRL_PENDING_BYTE 11
5411
#define SQLITE_TESTCTRL_ASSERT 12
5412
#define SQLITE_TESTCTRL_ALWAYS 13
5413
#define SQLITE_TESTCTRL_RESERVE 14
5414
#define SQLITE_TESTCTRL_OPTIMIZATIONS 15
5415
#define SQLITE_TESTCTRL_ISKEYWORD 16
5416
#define SQLITE_TESTCTRL_PGHDRSZ 17
5417
#define SQLITE_TESTCTRL_SCRATCHMALLOC 18
5418
#define SQLITE_TESTCTRL_LAST 18
5421
** CAPI3REF: SQLite Runtime Status
5423
** ^This interface is used to retrieve runtime status information
5424
** about the performance of SQLite, and optionally to reset various
5425
** highwater marks. ^The first argument is an integer code for
5426
** the specific parameter to measure. ^(Recognized integer codes
5427
** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...].)^
5428
** ^The current value of the parameter is returned into *pCurrent.
5429
** ^The highest recorded value is returned in *pHighwater. ^If the
5430
** resetFlag is true, then the highest record value is reset after
5431
** *pHighwater is written. ^(Some parameters do not record the highest
5432
** value. For those parameters
5433
** nothing is written into *pHighwater and the resetFlag is ignored.)^
5434
** ^(Other parameters record only the highwater mark and not the current
5435
** value. For these latter parameters nothing is written into *pCurrent.)^
5437
** ^The sqlite3_status() routine returns SQLITE_OK on success and a
5438
** non-zero [error code] on failure.
5440
** This routine is threadsafe but is not atomic. This routine can be
5441
** called while other threads are running the same or different SQLite
5442
** interfaces. However the values returned in *pCurrent and
5443
** *pHighwater reflect the status of SQLite at different points in time
5444
** and it is possible that another thread might change the parameter
5445
** in between the times when *pCurrent and *pHighwater are written.
5447
** See also: [sqlite3_db_status()]
5449
SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
5453
** CAPI3REF: Status Parameters
5455
** These integer constants designate various run-time status parameters
5456
** that can be returned by [sqlite3_status()].
5459
** ^(<dt>SQLITE_STATUS_MEMORY_USED</dt>
5460
** <dd>This parameter is the current amount of memory checked out
5461
** using [sqlite3_malloc()], either directly or indirectly. The
5462
** figure includes calls made to [sqlite3_malloc()] by the application
5463
** and internal memory usage by the SQLite library. Scratch memory
5464
** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache
5465
** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
5466
** this parameter. The amount returned is the sum of the allocation
5467
** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^
5469
** ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt>
5470
** <dd>This parameter records the largest memory allocation request
5471
** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
5472
** internal equivalents). Only the value returned in the
5473
** *pHighwater parameter to [sqlite3_status()] is of interest.
5474
** The value written into the *pCurrent parameter is undefined.</dd>)^
5476
** ^(<dt>SQLITE_STATUS_MALLOC_COUNT</dt>
5477
** <dd>This parameter records the number of separate memory allocations
5478
** currently checked out.</dd>)^
5480
** ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt>
5481
** <dd>This parameter returns the number of pages used out of the
5482
** [pagecache memory allocator] that was configured using
5483
** [SQLITE_CONFIG_PAGECACHE]. The
5484
** value returned is in pages, not in bytes.</dd>)^
5486
** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
5487
** <dd>This parameter returns the number of bytes of page cache
5488
** allocation which could not be satisfied by the [SQLITE_CONFIG_PAGECACHE]
5489
** buffer and where forced to overflow to [sqlite3_malloc()]. The
5490
** returned value includes allocations that overflowed because they
5491
** where too large (they were larger than the "sz" parameter to
5492
** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
5493
** no space was left in the page cache.</dd>)^
5495
** ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
5496
** <dd>This parameter records the largest memory allocation request
5497
** handed to [pagecache memory allocator]. Only the value returned in the
5498
** *pHighwater parameter to [sqlite3_status()] is of interest.
5499
** The value written into the *pCurrent parameter is undefined.</dd>)^
5501
** ^(<dt>SQLITE_STATUS_SCRATCH_USED</dt>
5502
** <dd>This parameter returns the number of allocations used out of the
5503
** [scratch memory allocator] configured using
5504
** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not
5505
** in bytes. Since a single thread may only have one scratch allocation
5506
** outstanding at time, this parameter also reports the number of threads
5507
** using scratch memory at the same time.</dd>)^
5509
** ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
5510
** <dd>This parameter returns the number of bytes of scratch memory
5511
** allocation which could not be satisfied by the [SQLITE_CONFIG_SCRATCH]
5512
** buffer and where forced to overflow to [sqlite3_malloc()]. The values
5513
** returned include overflows because the requested allocation was too
5514
** larger (that is, because the requested allocation was larger than the
5515
** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer
5516
** slots were available.
5519
** ^(<dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
5520
** <dd>This parameter records the largest memory allocation request
5521
** handed to [scratch memory allocator]. Only the value returned in the
5522
** *pHighwater parameter to [sqlite3_status()] is of interest.
5523
** The value written into the *pCurrent parameter is undefined.</dd>)^
5525
** ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
5526
** <dd>This parameter records the deepest parser stack. It is only
5527
** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
5530
** New status parameters may be added from time to time.
5532
#define SQLITE_STATUS_MEMORY_USED 0
5533
#define SQLITE_STATUS_PAGECACHE_USED 1
5534
#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2
5535
#define SQLITE_STATUS_SCRATCH_USED 3
5536
#define SQLITE_STATUS_SCRATCH_OVERFLOW 4
5537
#define SQLITE_STATUS_MALLOC_SIZE 5
5538
#define SQLITE_STATUS_PARSER_STACK 6
5539
#define SQLITE_STATUS_PAGECACHE_SIZE 7
5540
#define SQLITE_STATUS_SCRATCH_SIZE 8
5541
#define SQLITE_STATUS_MALLOC_COUNT 9
5544
** CAPI3REF: Database Connection Status
5546
** ^This interface is used to retrieve runtime status information
5547
** about a single [database connection]. ^The first argument is the
5548
** database connection object to be interrogated. ^The second argument
5549
** is an integer constant, taken from the set of
5550
** [SQLITE_DBSTATUS_LOOKASIDE_USED | SQLITE_DBSTATUS_*] macros, that
5551
** determines the parameter to interrogate. The set of
5552
** [SQLITE_DBSTATUS_LOOKASIDE_USED | SQLITE_DBSTATUS_*] macros is likely
5553
** to grow in future releases of SQLite.
5555
** ^The current value of the requested parameter is written into *pCur
5556
** and the highest instantaneous value is written into *pHiwtr. ^If
5557
** the resetFlg is true, then the highest instantaneous value is
5558
** reset back down to the current value.
5560
** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a
5561
** non-zero [error code] on failure.
5563
** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
5565
SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
5568
** CAPI3REF: Status Parameters for database connections
5570
** These constants are the available integer "verbs" that can be passed as
5571
** the second argument to the [sqlite3_db_status()] interface.
5573
** New verbs may be added in future releases of SQLite. Existing verbs
5574
** might be discontinued. Applications should check the return code from
5575
** [sqlite3_db_status()] to make sure that the call worked.
5576
** The [sqlite3_db_status()] interface will return a non-zero error code
5577
** if a discontinued or unsupported verb is invoked.
5580
** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
5581
** <dd>This parameter returns the number of lookaside memory slots currently
5582
** checked out.</dd>)^
5584
** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_HIT</dt>
5585
** <dd>This parameter returns the number malloc attempts that were
5586
** satisfied using lookaside memory. Only the high-water value is meaningful;
5587
** the current value is always zero.)^
5589
** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</dt>
5590
** <dd>This parameter returns the number malloc attempts that might have
5591
** been satisfied using lookaside memory but failed due to the amount of
5592
** memory requested being larger than the lookaside slot size.
5593
** Only the high-water value is meaningful;
5594
** the current value is always zero.)^
5596
** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</dt>
5597
** <dd>This parameter returns the number malloc attempts that might have
5598
** been satisfied using lookaside memory but failed due to all lookaside
5599
** memory already being in use.
5600
** Only the high-water value is meaningful;
5601
** the current value is always zero.)^
5603
** ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt>
5604
** <dd>This parameter returns the approximate number of of bytes of heap
5605
** memory used by all pager caches associated with the database connection.)^
5606
** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
5608
** ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt>
5609
** <dd>This parameter returns the approximate number of of bytes of heap
5610
** memory used to store the schema for all databases associated
5611
** with the connection - main, temp, and any [ATTACH]-ed databases.)^
5612
** ^The full amount of memory used by the schemas is reported, even if the
5613
** schema memory is shared with other database connections due to
5614
** [shared cache mode] being enabled.
5615
** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.
5617
** ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt>
5618
** <dd>This parameter returns the approximate number of of bytes of heap
5619
** and lookaside memory used by all prepared statements associated with
5620
** the database connection.)^
5621
** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.
5625
#define SQLITE_DBSTATUS_LOOKASIDE_USED 0
5626
#define SQLITE_DBSTATUS_CACHE_USED 1
5627
#define SQLITE_DBSTATUS_SCHEMA_USED 2
5628
#define SQLITE_DBSTATUS_STMT_USED 3
5629
#define SQLITE_DBSTATUS_LOOKASIDE_HIT 4
5630
#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5
5631
#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6
5632
#define SQLITE_DBSTATUS_MAX 6 /* Largest defined DBSTATUS */
5636
** CAPI3REF: Prepared Statement Status
5638
** ^(Each prepared statement maintains various
5639
** [SQLITE_STMTSTATUS_SORT | counters] that measure the number
5640
** of times it has performed specific operations.)^ These counters can
5641
** be used to monitor the performance characteristics of the prepared
5642
** statements. For example, if the number of table steps greatly exceeds
5643
** the number of table searches or result rows, that would tend to indicate
5644
** that the prepared statement is using a full table scan rather than
5647
** ^(This interface is used to retrieve and reset counter values from
5648
** a [prepared statement]. The first argument is the prepared statement
5649
** object to be interrogated. The second argument
5650
** is an integer code for a specific [SQLITE_STMTSTATUS_SORT | counter]
5651
** to be interrogated.)^
5652
** ^The current value of the requested counter is returned.
5653
** ^If the resetFlg is true, then the counter is reset to zero after this
5654
** interface call returns.
5656
** See also: [sqlite3_status()] and [sqlite3_db_status()].
5658
SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
5661
** CAPI3REF: Status Parameters for prepared statements
5663
** These preprocessor macros define integer codes that name counter
5664
** values associated with the [sqlite3_stmt_status()] interface.
5665
** The meanings of the various counters are as follows:
5668
** <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>
5669
** <dd>^This is the number of times that SQLite has stepped forward in
5670
** a table as part of a full table scan. Large numbers for this counter
5671
** may indicate opportunities for performance improvement through
5672
** careful use of indices.</dd>
5674
** <dt>SQLITE_STMTSTATUS_SORT</dt>
5675
** <dd>^This is the number of sort operations that have occurred.
5676
** A non-zero value in this counter may indicate an opportunity to
5677
** improvement performance through careful use of indices.</dd>
5679
** <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt>
5680
** <dd>^This is the number of rows inserted into transient indices that
5681
** were created automatically in order to help joins run faster.
5682
** A non-zero value in this counter may indicate an opportunity to
5683
** improvement performance by adding permanent indices that do not
5684
** need to be reinitialized each time the statement is run.</dd>
5688
#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1
5689
#define SQLITE_STMTSTATUS_SORT 2
5690
#define SQLITE_STMTSTATUS_AUTOINDEX 3
5693
** CAPI3REF: Custom Page Cache Object
5695
** The sqlite3_pcache type is opaque. It is implemented by
5696
** the pluggable module. The SQLite core has no knowledge of
5697
** its size or internal structure and never deals with the
5698
** sqlite3_pcache object except by holding and passing pointers
5701
** See [sqlite3_pcache_methods] for additional information.
5703
typedef struct sqlite3_pcache sqlite3_pcache;
5706
** CAPI3REF: Application Defined Page Cache.
5707
** KEYWORDS: {page cache}
5709
** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
5710
** register an alternative page cache implementation by passing in an
5711
** instance of the sqlite3_pcache_methods structure.)^
5712
** In many applications, most of the heap memory allocated by
5713
** SQLite is used for the page cache.
5714
** By implementing a
5715
** custom page cache using this API, an application can better control
5716
** the amount of memory consumed by SQLite, the way in which
5717
** that memory is allocated and released, and the policies used to
5718
** determine exactly which parts of a database file are cached and for
5721
** The alternative page cache mechanism is an
5722
** extreme measure that is only needed by the most demanding applications.
5723
** The built-in page cache is recommended for most uses.
5725
** ^(The contents of the sqlite3_pcache_methods structure are copied to an
5726
** internal buffer by SQLite within the call to [sqlite3_config]. Hence
5727
** the application may discard the parameter after the call to
5728
** [sqlite3_config()] returns.)^
5730
** ^(The xInit() method is called once for each effective
5731
** call to [sqlite3_initialize()])^
5732
** (usually only once during the lifetime of the process). ^(The xInit()
5733
** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^
5734
** The intent of the xInit() method is to set up global data structures
5735
** required by the custom page cache implementation.
5736
** ^(If the xInit() method is NULL, then the
5737
** built-in default page cache is used instead of the application defined
5740
** ^The xShutdown() method is called by [sqlite3_shutdown()].
5741
** It can be used to clean up
5742
** any outstanding resources before process shutdown, if required.
5743
** ^The xShutdown() method may be NULL.
5745
** ^SQLite automatically serializes calls to the xInit method,
5746
** so the xInit method need not be threadsafe. ^The
5747
** xShutdown method is only called from [sqlite3_shutdown()] so it does
5748
** not need to be threadsafe either. All other methods must be threadsafe
5749
** in multithreaded applications.
5751
** ^SQLite will never invoke xInit() more than once without an intervening
5752
** call to xShutdown().
5754
** ^SQLite invokes the xCreate() method to construct a new cache instance.
5755
** SQLite will typically create one cache instance for each open database file,
5756
** though this is not guaranteed. ^The
5757
** first parameter, szPage, is the size in bytes of the pages that must
5758
** be allocated by the cache. ^szPage will not be a power of two. ^szPage
5759
** will the page size of the database file that is to be cached plus an
5760
** increment (here called "R") of less than 250. SQLite will use the
5761
** extra R bytes on each page to store metadata about the underlying
5762
** database page on disk. The value of R depends
5763
** on the SQLite version, the target platform, and how SQLite was compiled.
5764
** ^(R is constant for a particular build of SQLite. Except, there are two
5765
** distinct values of R when SQLite is compiled with the proprietary
5766
** ZIPVFS extension.)^ ^The second argument to
5767
** xCreate(), bPurgeable, is true if the cache being created will
5768
** be used to cache database pages of a file stored on disk, or
5769
** false if it is used for an in-memory database. The cache implementation
5770
** does not have to do anything special based with the value of bPurgeable;
5771
** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
5772
** never invoke xUnpin() except to deliberately delete a page.
5773
** ^In other words, calls to xUnpin() on a cache with bPurgeable set to
5774
** false will always have the "discard" flag set to true.
5775
** ^Hence, a cache created with bPurgeable false will
5776
** never contain any unpinned pages.
5778
** ^(The xCachesize() method may be called at any time by SQLite to set the
5779
** suggested maximum cache-size (number of pages stored by) the cache
5780
** instance passed as the first argument. This is the value configured using
5781
** the SQLite "[PRAGMA cache_size]" command.)^ As with the bPurgeable
5782
** parameter, the implementation is not required to do anything with this
5783
** value; it is advisory only.
5785
** The xPagecount() method must return the number of pages currently
5786
** stored in the cache, both pinned and unpinned.
5788
** The xFetch() method locates a page in the cache and returns a pointer to
5789
** the page, or a NULL pointer.
5790
** A "page", in this context, means a buffer of szPage bytes aligned at an
5791
** 8-byte boundary. The page to be fetched is determined by the key. ^The
5792
** mimimum key value is 1. After it has been retrieved using xFetch, the page
5793
** is considered to be "pinned".
5795
** If the requested page is already in the page cache, then the page cache
5796
** implementation must return a pointer to the page buffer with its content
5797
** intact. If the requested page is not already in the cache, then the
5798
** cache implementation should use the value of the createFlag
5799
** parameter to help it determined what action to take:
5801
** <table border=1 width=85% align=center>
5802
** <tr><th> createFlag <th> Behaviour when page is not already in cache
5803
** <tr><td> 0 <td> Do not allocate a new page. Return NULL.
5804
** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
5805
** Otherwise return NULL.
5806
** <tr><td> 2 <td> Make every effort to allocate a new page. Only return
5807
** NULL if allocating a new page is effectively impossible.
5810
** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite
5811
** will only use a createFlag of 2 after a prior call with a createFlag of 1
5812
** failed.)^ In between the to xFetch() calls, SQLite may
5813
** attempt to unpin one or more cache pages by spilling the content of
5814
** pinned pages to disk and synching the operating system disk cache.
5816
** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
5817
** as its second argument. If the third parameter, discard, is non-zero,
5818
** then the page must be evicted from the cache.
5819
** ^If the discard parameter is
5820
** zero, then the page may be discarded or retained at the discretion of
5821
** page cache implementation. ^The page cache implementation
5822
** may choose to evict unpinned pages at any time.
5824
** The cache must not perform any reference counting. A single
5825
** call to xUnpin() unpins the page regardless of the number of prior calls
5828
** The xRekey() method is used to change the key value associated with the
5829
** page passed as the second argument. If the cache
5830
** previously contains an entry associated with newKey, it must be
5831
** discarded. ^Any prior cache entry associated with newKey is guaranteed not
5834
** When SQLite calls the xTruncate() method, the cache must discard all
5835
** existing cache entries with page numbers (keys) greater than or equal
5836
** to the value of the iLimit parameter passed to xTruncate(). If any
5837
** of these pages are pinned, they are implicitly unpinned, meaning that
5838
** they can be safely discarded.
5840
** ^The xDestroy() method is used to delete a cache allocated by xCreate().
5841
** All resources associated with the specified cache should be freed. ^After
5842
** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
5843
** handle invalid, and will not use it with any other sqlite3_pcache_methods
5846
typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
5847
struct sqlite3_pcache_methods {
5849
int (*xInit)(void*);
5850
void (*xShutdown)(void*);
5851
sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);
5852
void (*xCachesize)(sqlite3_pcache*, int nCachesize);
5853
int (*xPagecount)(sqlite3_pcache*);
5854
void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
5855
void (*xUnpin)(sqlite3_pcache*, void*, int discard);
5856
void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
5857
void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
5858
void (*xDestroy)(sqlite3_pcache*);
5862
** CAPI3REF: Online Backup Object
5864
** The sqlite3_backup object records state information about an ongoing
5865
** online backup operation. ^The sqlite3_backup object is created by
5866
** a call to [sqlite3_backup_init()] and is destroyed by a call to
5867
** [sqlite3_backup_finish()].
5869
** See Also: [Using the SQLite Online Backup API]
5871
typedef struct sqlite3_backup sqlite3_backup;
5874
** CAPI3REF: Online Backup API.
5876
** The backup API copies the content of one database into another.
5877
** It is useful either for creating backups of databases or
5878
** for copying in-memory databases to or from persistent files.
5880
** See Also: [Using the SQLite Online Backup API]
5882
** ^SQLite holds a write transaction open on the destination database file
5883
** for the duration of the backup operation.
5884
** ^The source database is read-locked only while it is being read;
5885
** it is not locked continuously for the entire backup operation.
5886
** ^Thus, the backup may be performed on a live source database without
5887
** preventing other database connections from
5888
** reading or writing to the source database while the backup is underway.
5890
** ^(To perform a backup operation:
5892
** <li><b>sqlite3_backup_init()</b> is called once to initialize the
5894
** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
5895
** the data between the two databases, and finally
5896
** <li><b>sqlite3_backup_finish()</b> is called to release all resources
5897
** associated with the backup operation.
5899
** There should be exactly one call to sqlite3_backup_finish() for each
5900
** successful call to sqlite3_backup_init().
5902
** <b>sqlite3_backup_init()</b>
5904
** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
5905
** [database connection] associated with the destination database
5906
** and the database name, respectively.
5907
** ^The database name is "main" for the main database, "temp" for the
5908
** temporary database, or the name specified after the AS keyword in
5909
** an [ATTACH] statement for an attached database.
5910
** ^The S and M arguments passed to
5911
** sqlite3_backup_init(D,N,S,M) identify the [database connection]
5912
** and database name of the source database, respectively.
5913
** ^The source and destination [database connections] (parameters S and D)
5914
** must be different or else sqlite3_backup_init(D,N,S,M) will fail with
5917
** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
5918
** returned and an error code and error message are stored in the
5919
** destination [database connection] D.
5920
** ^The error code and message for the failed call to sqlite3_backup_init()
5921
** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
5922
** [sqlite3_errmsg16()] functions.
5923
** ^A successful call to sqlite3_backup_init() returns a pointer to an
5924
** [sqlite3_backup] object.
5925
** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
5926
** sqlite3_backup_finish() functions to perform the specified backup
5929
** <b>sqlite3_backup_step()</b>
5931
** ^Function sqlite3_backup_step(B,N) will copy up to N pages between
5932
** the source and destination databases specified by [sqlite3_backup] object B.
5933
** ^If N is negative, all remaining source pages are copied.
5934
** ^If sqlite3_backup_step(B,N) successfully copies N pages and there
5935
** are still more pages to be copied, then the function returns [SQLITE_OK].
5936
** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages
5937
** from source to destination, then it returns [SQLITE_DONE].
5938
** ^If an error occurs while running sqlite3_backup_step(B,N),
5939
** then an [error code] is returned. ^As well as [SQLITE_OK] and
5940
** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
5941
** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
5942
** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
5944
** ^(The sqlite3_backup_step() might return [SQLITE_READONLY] if
5946
** <li> the destination database was opened read-only, or
5947
** <li> the destination database is using write-ahead-log journaling
5948
** and the destination and source page sizes differ, or
5949
** <li> the destination database is an in-memory database and the
5950
** destination and source page sizes differ.
5953
** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
5954
** the [sqlite3_busy_handler | busy-handler function]
5955
** is invoked (if one is specified). ^If the
5956
** busy-handler returns non-zero before the lock is available, then
5957
** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
5958
** sqlite3_backup_step() can be retried later. ^If the source
5959
** [database connection]
5960
** is being used to write to the source database when sqlite3_backup_step()
5961
** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
5962
** case the call to sqlite3_backup_step() can be retried later on. ^(If
5963
** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
5964
** [SQLITE_READONLY] is returned, then
5965
** there is no point in retrying the call to sqlite3_backup_step(). These
5966
** errors are considered fatal.)^ The application must accept
5967
** that the backup operation has failed and pass the backup operation handle
5968
** to the sqlite3_backup_finish() to release associated resources.
5970
** ^The first call to sqlite3_backup_step() obtains an exclusive lock
5971
** on the destination file. ^The exclusive lock is not released until either
5972
** sqlite3_backup_finish() is called or the backup operation is complete
5973
** and sqlite3_backup_step() returns [SQLITE_DONE]. ^Every call to
5974
** sqlite3_backup_step() obtains a [shared lock] on the source database that
5975
** lasts for the duration of the sqlite3_backup_step() call.
5976
** ^Because the source database is not locked between calls to
5977
** sqlite3_backup_step(), the source database may be modified mid-way
5978
** through the backup process. ^If the source database is modified by an
5979
** external process or via a database connection other than the one being
5980
** used by the backup operation, then the backup will be automatically
5981
** restarted by the next call to sqlite3_backup_step(). ^If the source
5982
** database is modified by the using the same database connection as is used
5983
** by the backup operation, then the backup database is automatically
5984
** updated at the same time.
5986
** <b>sqlite3_backup_finish()</b>
5988
** When sqlite3_backup_step() has returned [SQLITE_DONE], or when the
5989
** application wishes to abandon the backup operation, the application
5990
** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
5991
** ^The sqlite3_backup_finish() interfaces releases all
5992
** resources associated with the [sqlite3_backup] object.
5993
** ^If sqlite3_backup_step() has not yet returned [SQLITE_DONE], then any
5994
** active write-transaction on the destination database is rolled back.
5995
** The [sqlite3_backup] object is invalid
5996
** and may not be used following a call to sqlite3_backup_finish().
5998
** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
5999
** sqlite3_backup_step() errors occurred, regardless or whether or not
6000
** sqlite3_backup_step() completed.
6001
** ^If an out-of-memory condition or IO error occurred during any prior
6002
** sqlite3_backup_step() call on the same [sqlite3_backup] object, then
6003
** sqlite3_backup_finish() returns the corresponding [error code].
6005
** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
6006
** is not a permanent error and does not affect the return value of
6007
** sqlite3_backup_finish().
6009
** <b>sqlite3_backup_remaining(), sqlite3_backup_pagecount()</b>
6011
** ^Each call to sqlite3_backup_step() sets two values inside
6012
** the [sqlite3_backup] object: the number of pages still to be backed
6013
** up and the total number of pages in the source database file.
6014
** The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces
6015
** retrieve these two values, respectively.
6017
** ^The values returned by these functions are only updated by
6018
** sqlite3_backup_step(). ^If the source database is modified during a backup
6019
** operation, then the values are not updated to account for any extra
6020
** pages that need to be updated or the size of the source database file
6023
** <b>Concurrent Usage of Database Handles</b>
6025
** ^The source [database connection] may be used by the application for other
6026
** purposes while a backup operation is underway or being initialized.
6027
** ^If SQLite is compiled and configured to support threadsafe database
6028
** connections, then the source database connection may be used concurrently
6029
** from within other threads.
6031
** However, the application must guarantee that the destination
6032
** [database connection] is not passed to any other API (by any thread) after
6033
** sqlite3_backup_init() is called and before the corresponding call to
6034
** sqlite3_backup_finish(). SQLite does not currently check to see
6035
** if the application incorrectly accesses the destination [database connection]
6036
** and so no error code is reported, but the operations may malfunction
6037
** nevertheless. Use of the destination database connection while a
6038
** backup is in progress might also also cause a mutex deadlock.
6040
** If running in [shared cache mode], the application must
6041
** guarantee that the shared cache used by the destination database
6042
** is not accessed while the backup is running. In practice this means
6043
** that the application must guarantee that the disk file being
6044
** backed up to is not accessed by any connection within the process,
6045
** not just the specific connection that was passed to sqlite3_backup_init().
6047
** The [sqlite3_backup] object itself is partially threadsafe. Multiple
6048
** threads may safely make multiple concurrent calls to sqlite3_backup_step().
6049
** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
6050
** APIs are not strictly speaking threadsafe. If they are invoked at the
6051
** same time as another thread is invoking sqlite3_backup_step() it is
6052
** possible that they return invalid values.
6054
SQLITE_API sqlite3_backup *sqlite3_backup_init(
6055
sqlite3 *pDest, /* Destination database handle */
6056
const char *zDestName, /* Destination database name */
6057
sqlite3 *pSource, /* Source database handle */
6058
const char *zSourceName /* Source database name */
6060
SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
6061
SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
6062
SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
6063
SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
6066
** CAPI3REF: Unlock Notification
6068
** ^When running in shared-cache mode, a database operation may fail with
6069
** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
6070
** individual tables within the shared-cache cannot be obtained. See
6071
** [SQLite Shared-Cache Mode] for a description of shared-cache locking.
6072
** ^This API may be used to register a callback that SQLite will invoke
6073
** when the connection currently holding the required lock relinquishes it.
6074
** ^This API is only available if the library was compiled with the
6075
** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
6077
** See Also: [Using the SQLite Unlock Notification Feature].
6079
** ^Shared-cache locks are released when a database connection concludes
6080
** its current transaction, either by committing it or rolling it back.
6082
** ^When a connection (known as the blocked connection) fails to obtain a
6083
** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
6084
** identity of the database connection (the blocking connection) that
6085
** has locked the required resource is stored internally. ^After an
6086
** application receives an SQLITE_LOCKED error, it may call the
6087
** sqlite3_unlock_notify() method with the blocked connection handle as
6088
** the first argument to register for a callback that will be invoked
6089
** when the blocking connections current transaction is concluded. ^The
6090
** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
6091
** call that concludes the blocking connections transaction.
6093
** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
6094
** there is a chance that the blocking connection will have already
6095
** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
6096
** If this happens, then the specified callback is invoked immediately,
6097
** from within the call to sqlite3_unlock_notify().)^
6099
** ^If the blocked connection is attempting to obtain a write-lock on a
6100
** shared-cache table, and more than one other connection currently holds
6101
** a read-lock on the same table, then SQLite arbitrarily selects one of
6102
** the other connections to use as the blocking connection.
6104
** ^(There may be at most one unlock-notify callback registered by a
6105
** blocked connection. If sqlite3_unlock_notify() is called when the
6106
** blocked connection already has a registered unlock-notify callback,
6107
** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
6108
** called with a NULL pointer as its second argument, then any existing
6109
** unlock-notify callback is canceled. ^The blocked connections
6110
** unlock-notify callback may also be canceled by closing the blocked
6111
** connection using [sqlite3_close()].
6113
** The unlock-notify callback is not reentrant. If an application invokes
6114
** any sqlite3_xxx API functions from within an unlock-notify callback, a
6115
** crash or deadlock may be the result.
6117
** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
6118
** returns SQLITE_OK.
6120
** <b>Callback Invocation Details</b>
6122
** When an unlock-notify callback is registered, the application provides a
6123
** single void* pointer that is passed to the callback when it is invoked.
6124
** However, the signature of the callback function allows SQLite to pass
6125
** it an array of void* context pointers. The first argument passed to
6126
** an unlock-notify callback is a pointer to an array of void* pointers,
6127
** and the second is the number of entries in the array.
6129
** When a blocking connections transaction is concluded, there may be
6130
** more than one blocked connection that has registered for an unlock-notify
6131
** callback. ^If two or more such blocked connections have specified the
6132
** same callback function, then instead of invoking the callback function
6133
** multiple times, it is invoked once with the set of void* context pointers
6134
** specified by the blocked connections bundled together into an array.
6135
** This gives the application an opportunity to prioritize any actions
6136
** related to the set of unblocked database connections.
6138
** <b>Deadlock Detection</b>
6140
** Assuming that after registering for an unlock-notify callback a
6141
** database waits for the callback to be issued before taking any further
6142
** action (a reasonable assumption), then using this API may cause the
6143
** application to deadlock. For example, if connection X is waiting for
6144
** connection Y's transaction to be concluded, and similarly connection
6145
** Y is waiting on connection X's transaction, then neither connection
6146
** will proceed and the system may remain deadlocked indefinitely.
6148
** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
6149
** detection. ^If a given call to sqlite3_unlock_notify() would put the
6150
** system in a deadlocked state, then SQLITE_LOCKED is returned and no
6151
** unlock-notify callback is registered. The system is said to be in
6152
** a deadlocked state if connection A has registered for an unlock-notify
6153
** callback on the conclusion of connection B's transaction, and connection
6154
** B has itself registered for an unlock-notify callback when connection
6155
** A's transaction is concluded. ^Indirect deadlock is also detected, so
6156
** the system is also considered to be deadlocked if connection B has
6157
** registered for an unlock-notify callback on the conclusion of connection
6158
** C's transaction, where connection C is waiting on connection A. ^Any
6159
** number of levels of indirection are allowed.
6161
** <b>The "DROP TABLE" Exception</b>
6163
** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
6164
** always appropriate to call sqlite3_unlock_notify(). There is however,
6165
** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
6166
** SQLite checks if there are any currently executing SELECT statements
6167
** that belong to the same connection. If there are, SQLITE_LOCKED is
6168
** returned. In this case there is no "blocking connection", so invoking
6169
** sqlite3_unlock_notify() results in the unlock-notify callback being
6170
** invoked immediately. If the application then re-attempts the "DROP TABLE"
6171
** or "DROP INDEX" query, an infinite loop might be the result.
6173
** One way around this problem is to check the extended error code returned
6174
** by an sqlite3_step() call. ^(If there is a blocking connection, then the
6175
** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
6176
** the special "DROP TABLE/INDEX" case, the extended error code is just
6179
SQLITE_API int sqlite3_unlock_notify(
6180
sqlite3 *pBlocked, /* Waiting connection */
6181
void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
6182
void *pNotifyArg /* Argument to pass to xNotify */
6187
** CAPI3REF: String Comparison
6189
** ^The [sqlite3_strnicmp()] API allows applications and extensions to
6190
** compare the contents of two buffers containing UTF-8 strings in a
6191
** case-independent fashion, using the same definition of case independence
6192
** that SQLite uses internally when comparing identifiers.
6194
SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
6197
** CAPI3REF: Error Logging Interface
6199
** ^The [sqlite3_log()] interface writes a message into the error log
6200
** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
6201
** ^If logging is enabled, the zFormat string and subsequent arguments are
6202
** used with [sqlite3_snprintf()] to generate the final output string.
6204
** The sqlite3_log() interface is intended for use by extensions such as
6205
** virtual tables, collating functions, and SQL functions. While there is
6206
** nothing to prevent an application from calling sqlite3_log(), doing so
6207
** is considered bad form.
6209
** The zFormat string must not be NULL.
6211
** To avoid deadlocks and other threading problems, the sqlite3_log() routine
6212
** will not use dynamically allocated memory. The log message is stored in
6213
** a fixed-length buffer on the stack. If the log message is longer than
6214
** a few hundred characters, it will be truncated to the length of the
6217
SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
6220
** CAPI3REF: Write-Ahead Log Commit Hook
6222
** ^The [sqlite3_wal_hook()] function is used to register a callback that
6223
** will be invoked each time a database connection commits data to a
6224
** [write-ahead log] (i.e. whenever a transaction is committed in
6225
** [journal_mode | journal_mode=WAL mode]).
6227
** ^The callback is invoked by SQLite after the commit has taken place and
6228
** the associated write-lock on the database released, so the implementation
6229
** may read, write or [checkpoint] the database as required.
6231
** ^The first parameter passed to the callback function when it is invoked
6232
** is a copy of the third parameter passed to sqlite3_wal_hook() when
6233
** registering the callback. ^The second is a copy of the database handle.
6234
** ^The third parameter is the name of the database that was written to -
6235
** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter
6236
** is the number of pages currently in the write-ahead log file,
6237
** including those that were just committed.
6239
** The callback function should normally return [SQLITE_OK]. ^If an error
6240
** code is returned, that error will propagate back up through the
6241
** SQLite code base to cause the statement that provoked the callback
6242
** to report an error, though the commit will have still occurred. If the
6243
** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value
6244
** that does not correspond to any valid SQLite error code, the results
6247
** A single database handle may have at most a single write-ahead log callback
6248
** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any
6249
** previously registered write-ahead log callback. ^Note that the
6250
** [sqlite3_wal_autocheckpoint()] interface and the
6251
** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
6252
** those overwrite any prior [sqlite3_wal_hook()] settings.
6254
SQLITE_API void *sqlite3_wal_hook(
6256
int(*)(void *,sqlite3*,const char*,int),
6261
** CAPI3REF: Configure an auto-checkpoint
6263
** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
6264
** [sqlite3_wal_hook()] that causes any database on [database connection] D
6265
** to automatically [checkpoint]
6266
** after committing a transaction if there are N or
6267
** more frames in the [write-ahead log] file. ^Passing zero or
6268
** a negative value as the nFrame parameter disables automatic
6269
** checkpoints entirely.
6271
** ^The callback registered by this function replaces any existing callback
6272
** registered using [sqlite3_wal_hook()]. ^Likewise, registering a callback
6273
** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism
6274
** configured by this function.
6276
** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
6279
** ^Every new [database connection] defaults to having the auto-checkpoint
6280
** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]
6281
** pages. The use of this interface
6282
** is only necessary if the default setting is found to be suboptimal
6283
** for a particular application.
6285
SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
6288
** CAPI3REF: Checkpoint a database
6290
** ^The [sqlite3_wal_checkpoint(D,X)] interface causes database named X
6291
** on [database connection] D to be [checkpointed]. ^If X is NULL or an
6292
** empty string, then a checkpoint is run on all databases of
6293
** connection D. ^If the database connection D is not in
6294
** [WAL | write-ahead log mode] then this interface is a harmless no-op.
6296
** ^The [wal_checkpoint pragma] can be used to invoke this interface
6297
** from SQL. ^The [sqlite3_wal_autocheckpoint()] interface and the
6298
** [wal_autocheckpoint pragma] can be used to cause this interface to be
6299
** run whenever the WAL reaches a certain size threshold.
6301
** See also: [sqlite3_wal_checkpoint_v2()]
6303
SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
6306
** CAPI3REF: Checkpoint a database
6308
** Run a checkpoint operation on WAL database zDb attached to database
6309
** handle db. The specific operation is determined by the value of the
6313
** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
6314
** Checkpoint as many frames as possible without waiting for any database
6315
** readers or writers to finish. Sync the db file if all frames in the log
6316
** are checkpointed. This mode is the same as calling
6317
** sqlite3_wal_checkpoint(). The busy-handler callback is never invoked.
6319
** <dt>SQLITE_CHECKPOINT_FULL<dd>
6320
** This mode blocks (calls the busy-handler callback) until there is no
6321
** database writer and all readers are reading from the most recent database
6322
** snapshot. It then checkpoints all frames in the log file and syncs the
6323
** database file. This call blocks database writers while it is running,
6324
** but not database readers.
6326
** <dt>SQLITE_CHECKPOINT_RESTART<dd>
6327
** This mode works the same way as SQLITE_CHECKPOINT_FULL, except after
6328
** checkpointing the log file it blocks (calls the busy-handler callback)
6329
** until all readers are reading from the database file only. This ensures
6330
** that the next client to write to the database file restarts the log file
6331
** from the beginning. This call blocks database writers while it is running,
6332
** but not database readers.
6335
** If pnLog is not NULL, then *pnLog is set to the total number of frames in
6336
** the log file before returning. If pnCkpt is not NULL, then *pnCkpt is set to
6337
** the total number of checkpointed frames (including any that were already
6338
** checkpointed when this function is called). *pnLog and *pnCkpt may be
6339
** populated even if sqlite3_wal_checkpoint_v2() returns other than SQLITE_OK.
6340
** If no values are available because of an error, they are both set to -1
6341
** before returning to communicate this to the caller.
6343
** All calls obtain an exclusive "checkpoint" lock on the database file. If
6344
** any other process is running a checkpoint operation at the same time, the
6345
** lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a
6346
** busy-handler configured, it will not be invoked in this case.
6348
** The SQLITE_CHECKPOINT_FULL and RESTART modes also obtain the exclusive
6349
** "writer" lock on the database file. If the writer lock cannot be obtained
6350
** immediately, and a busy-handler is configured, it is invoked and the writer
6351
** lock retried until either the busy-handler returns 0 or the lock is
6352
** successfully obtained. The busy-handler is also invoked while waiting for
6353
** database readers as described above. If the busy-handler returns 0 before
6354
** the writer lock is obtained or while waiting for database readers, the
6355
** checkpoint operation proceeds from that point in the same way as
6356
** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
6357
** without blocking any further. SQLITE_BUSY is returned in this case.
6359
** If parameter zDb is NULL or points to a zero length string, then the
6360
** specified operation is attempted on all WAL databases. In this case the
6361
** values written to output parameters *pnLog and *pnCkpt are undefined. If
6362
** an SQLITE_BUSY error is encountered when processing one or more of the
6363
** attached WAL databases, the operation is still attempted on any remaining
6364
** attached databases and SQLITE_BUSY is returned to the caller. If any other
6365
** error occurs while processing an attached database, processing is abandoned
6366
** and the error code returned to the caller immediately. If no error
6367
** (SQLITE_BUSY or otherwise) is encountered while processing the attached
6368
** databases, SQLITE_OK is returned.
6370
** If database zDb is the name of an attached database that is not in WAL
6371
** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If
6372
** zDb is not NULL (or a zero length string) and is not the name of any
6373
** attached database, SQLITE_ERROR is returned to the caller.
6375
SQLITE_API int sqlite3_wal_checkpoint_v2(
6376
sqlite3 *db, /* Database handle */
6377
const char *zDb, /* Name of attached database (or NULL) */
6378
int eMode, /* SQLITE_CHECKPOINT_* value */
6379
int *pnLog, /* OUT: Size of WAL log in frames */
6380
int *pnCkpt /* OUT: Total number of frames checkpointed */
6384
** CAPI3REF: Checkpoint operation parameters
6386
** These constants can be used as the 3rd parameter to
6387
** [sqlite3_wal_checkpoint_v2()]. See the [sqlite3_wal_checkpoint_v2()]
6388
** documentation for additional information about the meaning and use of
6389
** each of these values.
6391
#define SQLITE_CHECKPOINT_PASSIVE 0
6392
#define SQLITE_CHECKPOINT_FULL 1
6393
#define SQLITE_CHECKPOINT_RESTART 2
6397
** Undo the hack that converts floating point types to integer for
6398
** builds on processors without floating point support.
6400
#ifdef SQLITE_OMIT_FLOATING_POINT
6405
} /* End of the 'extern "C"' block */
6412
** The author disclaims copyright to this source code. In place of
6413
** a legal notice, here is a blessing:
6415
** May you do good and not evil.
6416
** May you find forgiveness for yourself and forgive others.
6417
** May you share freely, never taking more than you give.
6419
*************************************************************************
6422
#ifndef _SQLITE3RTREE_H_
6423
#define _SQLITE3RTREE_H_
6430
typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
6433
** Register a geometry callback named zGeom that can be used as part of an
6434
** R-Tree geometry query as follows:
6436
** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...)
6438
SQLITE_API int sqlite3_rtree_geometry_callback(
6441
int (*xGeom)(sqlite3_rtree_geometry *, int nCoord, double *aCoord, int *pRes),
6447
** A pointer to a structure of the following type is passed as the first
6448
** argument to callbacks registered using rtree_geometry_callback().
6450
struct sqlite3_rtree_geometry {
6451
void *pContext; /* Copy of pContext passed to s_r_g_c() */
6452
int nParam; /* Size of array aParam[] */
6453
double *aParam; /* Parameters passed to SQL geom function */
6454
void *pUser; /* Callback implementation user data */
6455
void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */
6460
} /* end of the 'extern "C"' block */
6463
#endif /* ifndef _SQLITE3RTREE_H_ */
added
removed
src/cadxcore/sqlite/sqlite3.h
