src/third-party/sqlite3/sqlite3.h (view raw)
1/*
2** 2001 September 15
3**
4** The author disclaims copyright to this source code. In place of
5** a legal notice, here is a blessing:
6**
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.
10**
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.
17**
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.
23**
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 supposed to operate.
27**
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.
32*/
33#ifndef SQLITE3_H
34#define SQLITE3_H
35#include <stdarg.h> /* Needed for the definition of va_list */
36
37/*
38** Make sure we can call this stuff from C++.
39*/
40#ifdef __cplusplus
41extern "C" {
42#endif
43
44
45/*
46** Provide the ability to override linkage features of the interface.
47*/
48#ifndef SQLITE_EXTERN
49# define SQLITE_EXTERN extern
50#endif
51#ifndef SQLITE_API
52# define SQLITE_API
53#endif
54#ifndef SQLITE_CDECL
55# define SQLITE_CDECL
56#endif
57#ifndef SQLITE_APICALL
58# define SQLITE_APICALL
59#endif
60#ifndef SQLITE_STDCALL
61# define SQLITE_STDCALL SQLITE_APICALL
62#endif
63#ifndef SQLITE_CALLBACK
64# define SQLITE_CALLBACK
65#endif
66#ifndef SQLITE_SYSAPI
67# define SQLITE_SYSAPI
68#endif
69
70/*
71** These no-op macros are used in front of interfaces to mark those
72** interfaces as either deprecated or experimental. New applications
73** should not use deprecated interfaces - they are supported for backwards
74** compatibility only. Application writers should be aware that
75** experimental interfaces are subject to change in point releases.
76**
77** These macros used to resolve to various kinds of compiler magic that
78** would generate warning messages when they were used. But that
79** compiler magic ended up generating such a flurry of bug reports
80** that we have taken it all out and gone back to using simple
81** noop macros.
82*/
83#define SQLITE_DEPRECATED
84#define SQLITE_EXPERIMENTAL
85
86/*
87** Ensure these symbols were not defined by some previous header file.
88*/
89#ifdef SQLITE_VERSION
90# undef SQLITE_VERSION
91#endif
92#ifdef SQLITE_VERSION_NUMBER
93# undef SQLITE_VERSION_NUMBER
94#endif
95
96/*
97** CAPI3REF: Compile-Time Library Version Numbers
98**
99** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
100** evaluates to a string literal that is the SQLite version in the
101** format "X.Y.Z" where X is the major version number (always 3 for
102** SQLite3) and Y is the minor version number and Z is the release number.)^
103** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
104** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
105** numbers used in [SQLITE_VERSION].)^
106** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
107** be larger than the release from which it is derived. Either Y will
108** be held constant and Z will be incremented or else Y will be incremented
109** and Z will be reset to zero.
110**
111** Since [version 3.6.18] ([dateof:3.6.18]),
112** SQLite source code has been stored in the
113** <a href="http://www.fossil-scm.org/">Fossil configuration management
114** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to
115** a string which identifies a particular check-in of SQLite
116** within its configuration management system. ^The SQLITE_SOURCE_ID
117** string contains the date and time of the check-in (UTC) and an SHA1
118** hash of the entire source tree.
119**
120** See also: [sqlite3_libversion()],
121** [sqlite3_libversion_number()], [sqlite3_sourceid()],
122** [sqlite_version()] and [sqlite_source_id()].
123*/
124#define SQLITE_VERSION "3.16.2"
125#define SQLITE_VERSION_NUMBER 3016002
126#define SQLITE_SOURCE_ID "2017-01-06 16:32:41 a65a62893ca8319e89e48b8a38cf8a59c69a8209"
127
128/*
129** CAPI3REF: Run-Time Library Version Numbers
130** KEYWORDS: sqlite3_version sqlite3_sourceid
131**
132** These interfaces provide the same information as the [SQLITE_VERSION],
133** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
134** but are associated with the library instead of the header file. ^(Cautious
135** programmers might include assert() statements in their application to
136** verify that values returned by these interfaces match the macros in
137** the header, and thus ensure that the application is
138** compiled with matching library and header files.
139**
140** <blockquote><pre>
141** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
142** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
143** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
144** </pre></blockquote>)^
145**
146** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
147** macro. ^The sqlite3_libversion() function returns a pointer to the
148** to the sqlite3_version[] string constant. The sqlite3_libversion()
149** function is provided for use in DLLs since DLL users usually do not have
150** direct access to string constants within the DLL. ^The
151** sqlite3_libversion_number() function returns an integer equal to
152** [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns
153** a pointer to a string constant whose value is the same as the
154** [SQLITE_SOURCE_ID] C preprocessor macro.
155**
156** See also: [sqlite_version()] and [sqlite_source_id()].
157*/
158SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
159SQLITE_API const char *sqlite3_libversion(void);
160SQLITE_API const char *sqlite3_sourceid(void);
161SQLITE_API int sqlite3_libversion_number(void);
162
163/*
164** CAPI3REF: Run-Time Library Compilation Options Diagnostics
165**
166** ^The sqlite3_compileoption_used() function returns 0 or 1
167** indicating whether the specified option was defined at
168** compile time. ^The SQLITE_ prefix may be omitted from the
169** option name passed to sqlite3_compileoption_used().
170**
171** ^The sqlite3_compileoption_get() function allows iterating
172** over the list of options that were defined at compile time by
173** returning the N-th compile time option string. ^If N is out of range,
174** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_
175** prefix is omitted from any strings returned by
176** sqlite3_compileoption_get().
177**
178** ^Support for the diagnostic functions sqlite3_compileoption_used()
179** and sqlite3_compileoption_get() may be omitted by specifying the
180** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
181**
182** See also: SQL functions [sqlite_compileoption_used()] and
183** [sqlite_compileoption_get()] and the [compile_options pragma].
184*/
185#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
186SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
187SQLITE_API const char *sqlite3_compileoption_get(int N);
188#endif
189
190/*
191** CAPI3REF: Test To See If The Library Is Threadsafe
192**
193** ^The sqlite3_threadsafe() function returns zero if and only if
194** SQLite was compiled with mutexing code omitted due to the
195** [SQLITE_THREADSAFE] compile-time option being set to 0.
196**
197** SQLite can be compiled with or without mutexes. When
198** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
199** are enabled and SQLite is threadsafe. When the
200** [SQLITE_THREADSAFE] macro is 0,
201** the mutexes are omitted. Without the mutexes, it is not safe
202** to use SQLite concurrently from more than one thread.
203**
204** Enabling mutexes incurs a measurable performance penalty.
205** So if speed is of utmost importance, it makes sense to disable
206** the mutexes. But for maximum safety, mutexes should be enabled.
207** ^The default behavior is for mutexes to be enabled.
208**
209** This interface can be used by an application to make sure that the
210** version of SQLite that it is linking against was compiled with
211** the desired setting of the [SQLITE_THREADSAFE] macro.
212**
213** This interface only reports on the compile-time mutex setting
214** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
215** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
216** can be fully or partially disabled using a call to [sqlite3_config()]
217** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
218** or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the
219** sqlite3_threadsafe() function shows only the compile-time setting of
220** thread safety, not any run-time changes to that setting made by
221** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
222** is unchanged by calls to sqlite3_config().)^
223**
224** See the [threading mode] documentation for additional information.
225*/
226SQLITE_API int sqlite3_threadsafe(void);
227
228/*
229** CAPI3REF: Database Connection Handle
230** KEYWORDS: {database connection} {database connections}
231**
232** Each open SQLite database is represented by a pointer to an instance of
233** the opaque structure named "sqlite3". It is useful to think of an sqlite3
234** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
235** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
236** and [sqlite3_close_v2()] are its destructors. There are many other
237** interfaces (such as
238** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
239** [sqlite3_busy_timeout()] to name but three) that are methods on an
240** sqlite3 object.
241*/
242typedef struct sqlite3 sqlite3;
243
244/*
245** CAPI3REF: 64-Bit Integer Types
246** KEYWORDS: sqlite_int64 sqlite_uint64
247**
248** Because there is no cross-platform way to specify 64-bit integer types
249** SQLite includes typedefs for 64-bit signed and unsigned integers.
250**
251** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
252** The sqlite_int64 and sqlite_uint64 types are supported for backwards
253** compatibility only.
254**
255** ^The sqlite3_int64 and sqlite_int64 types can store integer values
256** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
257** sqlite3_uint64 and sqlite_uint64 types can store integer values
258** between 0 and +18446744073709551615 inclusive.
259*/
260#ifdef SQLITE_INT64_TYPE
261 typedef SQLITE_INT64_TYPE sqlite_int64;
262 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
263#elif defined(_MSC_VER) || defined(__BORLANDC__)
264 typedef __int64 sqlite_int64;
265 typedef unsigned __int64 sqlite_uint64;
266#else
267 typedef long long int sqlite_int64;
268 typedef unsigned long long int sqlite_uint64;
269#endif
270typedef sqlite_int64 sqlite3_int64;
271typedef sqlite_uint64 sqlite3_uint64;
272
273/*
274** If compiling for a processor that lacks floating point support,
275** substitute integer for floating-point.
276*/
277#ifdef SQLITE_OMIT_FLOATING_POINT
278# define double sqlite3_int64
279#endif
280
281/*
282** CAPI3REF: Closing A Database Connection
283** DESTRUCTOR: sqlite3
284**
285** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
286** for the [sqlite3] object.
287** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
288** the [sqlite3] object is successfully destroyed and all associated
289** resources are deallocated.
290**
291** ^If the database connection is associated with unfinalized prepared
292** statements or unfinished sqlite3_backup objects then sqlite3_close()
293** will leave the database connection open and return [SQLITE_BUSY].
294** ^If sqlite3_close_v2() is called with unfinalized prepared statements
295** and/or unfinished sqlite3_backups, then the database connection becomes
296** an unusable "zombie" which will automatically be deallocated when the
297** last prepared statement is finalized or the last sqlite3_backup is
298** finished. The sqlite3_close_v2() interface is intended for use with
299** host languages that are garbage collected, and where the order in which
300** destructors are called is arbitrary.
301**
302** Applications should [sqlite3_finalize | finalize] all [prepared statements],
303** [sqlite3_blob_close | close] all [BLOB handles], and
304** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
305** with the [sqlite3] object prior to attempting to close the object. ^If
306** sqlite3_close_v2() is called on a [database connection] that still has
307** outstanding [prepared statements], [BLOB handles], and/or
308** [sqlite3_backup] objects then it returns [SQLITE_OK] and the deallocation
309** of resources is deferred until all [prepared statements], [BLOB handles],
310** and [sqlite3_backup] objects are also destroyed.
311**
312** ^If an [sqlite3] object is destroyed while a transaction is open,
313** the transaction is automatically rolled back.
314**
315** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
316** must be either a NULL
317** pointer or an [sqlite3] object pointer obtained
318** from [sqlite3_open()], [sqlite3_open16()], or
319** [sqlite3_open_v2()], and not previously closed.
320** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
321** argument is a harmless no-op.
322*/
323SQLITE_API int sqlite3_close(sqlite3*);
324SQLITE_API int sqlite3_close_v2(sqlite3*);
325
326/*
327** The type for a callback function.
328** This is legacy and deprecated. It is included for historical
329** compatibility and is not documented.
330*/
331typedef int (*sqlite3_callback)(void*,int,char**, char**);
332
333/*
334** CAPI3REF: One-Step Query Execution Interface
335** METHOD: sqlite3
336**
337** The sqlite3_exec() interface is a convenience wrapper around
338** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
339** that allows an application to run multiple statements of SQL
340** without having to use a lot of C code.
341**
342** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
343** semicolon-separate SQL statements passed into its 2nd argument,
344** in the context of the [database connection] passed in as its 1st
345** argument. ^If the callback function of the 3rd argument to
346** sqlite3_exec() is not NULL, then it is invoked for each result row
347** coming out of the evaluated SQL statements. ^The 4th argument to
348** sqlite3_exec() is relayed through to the 1st argument of each
349** callback invocation. ^If the callback pointer to sqlite3_exec()
350** is NULL, then no callback is ever invoked and result rows are
351** ignored.
352**
353** ^If an error occurs while evaluating the SQL statements passed into
354** sqlite3_exec(), then execution of the current statement stops and
355** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec()
356** is not NULL then any error message is written into memory obtained
357** from [sqlite3_malloc()] and passed back through the 5th parameter.
358** To avoid memory leaks, the application should invoke [sqlite3_free()]
359** on error message strings returned through the 5th parameter of
360** sqlite3_exec() after the error message string is no longer needed.
361** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
362** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
363** NULL before returning.
364**
365** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
366** routine returns SQLITE_ABORT without invoking the callback again and
367** without running any subsequent SQL statements.
368**
369** ^The 2nd argument to the sqlite3_exec() callback function is the
370** number of columns in the result. ^The 3rd argument to the sqlite3_exec()
371** callback is an array of pointers to strings obtained as if from
372** [sqlite3_column_text()], one for each column. ^If an element of a
373** result row is NULL then the corresponding string pointer for the
374** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
375** sqlite3_exec() callback is an array of pointers to strings where each
376** entry represents the name of corresponding result column as obtained
377** from [sqlite3_column_name()].
378**
379** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
380** to an empty string, or a pointer that contains only whitespace and/or
381** SQL comments, then no SQL statements are evaluated and the database
382** is not changed.
383**
384** Restrictions:
385**
386** <ul>
387** <li> The application must ensure that the 1st parameter to sqlite3_exec()
388** is a valid and open [database connection].
389** <li> The application must not close the [database connection] specified by
390** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
391** <li> The application must not modify the SQL statement text passed into
392** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
393** </ul>
394*/
395SQLITE_API int sqlite3_exec(
396 sqlite3*, /* An open database */
397 const char *sql, /* SQL to be evaluated */
398 int (*callback)(void*,int,char**,char**), /* Callback function */
399 void *, /* 1st argument to callback */
400 char **errmsg /* Error msg written here */
401);
402
403/*
404** CAPI3REF: Result Codes
405** KEYWORDS: {result code definitions}
406**
407** Many SQLite functions return an integer result code from the set shown
408** here in order to indicate success or failure.
409**
410** New error codes may be added in future versions of SQLite.
411**
412** See also: [extended result code definitions]
413*/
414#define SQLITE_OK 0 /* Successful result */
415/* beginning-of-error-codes */
416#define SQLITE_ERROR 1 /* SQL error or missing database */
417#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
418#define SQLITE_PERM 3 /* Access permission denied */
419#define SQLITE_ABORT 4 /* Callback routine requested an abort */
420#define SQLITE_BUSY 5 /* The database file is locked */
421#define SQLITE_LOCKED 6 /* A table in the database is locked */
422#define SQLITE_NOMEM 7 /* A malloc() failed */
423#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
424#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
425#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
426#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
427#define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */
428#define SQLITE_FULL 13 /* Insertion failed because database is full */
429#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
430#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
431#define SQLITE_EMPTY 16 /* Database is empty */
432#define SQLITE_SCHEMA 17 /* The database schema changed */
433#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
434#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
435#define SQLITE_MISMATCH 20 /* Data type mismatch */
436#define SQLITE_MISUSE 21 /* Library used incorrectly */
437#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
438#define SQLITE_AUTH 23 /* Authorization denied */
439#define SQLITE_FORMAT 24 /* Auxiliary database format error */
440#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
441#define SQLITE_NOTADB 26 /* File opened that is not a database file */
442#define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */
443#define SQLITE_WARNING 28 /* Warnings from sqlite3_log() */
444#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
445#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
446/* end-of-error-codes */
447
448/*
449** CAPI3REF: Extended Result Codes
450** KEYWORDS: {extended result code definitions}
451**
452** In its default configuration, SQLite API routines return one of 30 integer
453** [result codes]. However, experience has shown that many of
454** these result codes are too coarse-grained. They do not provide as
455** much information about problems as programmers might like. In an effort to
456** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8]
457** and later) include
458** support for additional result codes that provide more detailed information
459** about errors. These [extended result codes] are enabled or disabled
460** on a per database connection basis using the
461** [sqlite3_extended_result_codes()] API. Or, the extended code for
462** the most recent error can be obtained using
463** [sqlite3_extended_errcode()].
464*/
465#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
466#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
467#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
468#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))
469#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))
470#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))
471#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))
472#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))
473#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
474#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
475#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
476#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
477#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8))
478#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
479#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8))
480#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8))
481#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8))
482#define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8))
483#define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8))
484#define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8))
485#define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8))
486#define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8))
487#define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR | (23<<8))
488#define SQLITE_IOERR_MMAP (SQLITE_IOERR | (24<<8))
489#define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25<<8))
490#define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8))
491#define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27<<8))
492#define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8))
493#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
494#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
495#define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8))
496#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8))
497#define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8))
498#define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8))
499#define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8))
500#define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8))
501#define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8))
502#define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8))
503#define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8))
504#define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8))
505#define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8))
506#define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8))
507#define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8))
508#define SQLITE_CONSTRAINT_FOREIGNKEY (SQLITE_CONSTRAINT | (3<<8))
509#define SQLITE_CONSTRAINT_FUNCTION (SQLITE_CONSTRAINT | (4<<8))
510#define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8))
511#define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8))
512#define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8))
513#define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8))
514#define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8))
515#define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8))
516#define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8))
517#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
518#define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8))
519#define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8))
520#define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8))
521
522/*
523** CAPI3REF: Flags For File Open Operations
524**
525** These bit values are intended for use in the
526** 3rd parameter to the [sqlite3_open_v2()] interface and
527** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
528*/
529#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
530#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
531#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */
532#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */
533#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */
534#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */
535#define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */
536#define SQLITE_OPEN_MEMORY 0x00000080 /* Ok for sqlite3_open_v2() */
537#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */
538#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */
539#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */
540#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */
541#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */
542#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */
543#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */
544#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
545#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
546#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */
547#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
548#define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
549
550/* Reserved: 0x00F00000 */
551
552/*
553** CAPI3REF: Device Characteristics
554**
555** The xDeviceCharacteristics method of the [sqlite3_io_methods]
556** object returns an integer which is a vector of these
557** bit values expressing I/O characteristics of the mass storage
558** device that holds the file that the [sqlite3_io_methods]
559** refers to.
560**
561** The SQLITE_IOCAP_ATOMIC property means that all writes of
562** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
563** mean that writes of blocks that are nnn bytes in size and
564** are aligned to an address which is an integer multiple of
565** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
566** that when data is appended to a file, the data is appended
567** first then the size of the file is extended, never the other
568** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
569** information is written to disk in the same order as calls
570** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
571** after reboot following a crash or power loss, the only bytes in a
572** file that were written at the application level might have changed
573** and that adjacent bytes, even bytes within the same sector are
574** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
575** flag indicate that a file cannot be deleted when open. The
576** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
577** read-only media and cannot be changed even by processes with
578** elevated privileges.
579*/
580#define SQLITE_IOCAP_ATOMIC 0x00000001
581#define SQLITE_IOCAP_ATOMIC512 0x00000002
582#define SQLITE_IOCAP_ATOMIC1K 0x00000004
583#define SQLITE_IOCAP_ATOMIC2K 0x00000008
584#define SQLITE_IOCAP_ATOMIC4K 0x00000010
585#define SQLITE_IOCAP_ATOMIC8K 0x00000020
586#define SQLITE_IOCAP_ATOMIC16K 0x00000040
587#define SQLITE_IOCAP_ATOMIC32K 0x00000080
588#define SQLITE_IOCAP_ATOMIC64K 0x00000100
589#define SQLITE_IOCAP_SAFE_APPEND 0x00000200
590#define SQLITE_IOCAP_SEQUENTIAL 0x00000400
591#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
592#define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000
593#define SQLITE_IOCAP_IMMUTABLE 0x00002000
594
595/*
596** CAPI3REF: File Locking Levels
597**
598** SQLite uses one of these integer values as the second
599** argument to calls it makes to the xLock() and xUnlock() methods
600** of an [sqlite3_io_methods] object.
601*/
602#define SQLITE_LOCK_NONE 0
603#define SQLITE_LOCK_SHARED 1
604#define SQLITE_LOCK_RESERVED 2
605#define SQLITE_LOCK_PENDING 3
606#define SQLITE_LOCK_EXCLUSIVE 4
607
608/*
609** CAPI3REF: Synchronization Type Flags
610**
611** When SQLite invokes the xSync() method of an
612** [sqlite3_io_methods] object it uses a combination of
613** these integer values as the second argument.
614**
615** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
616** sync operation only needs to flush data to mass storage. Inode
617** information need not be flushed. If the lower four bits of the flag
618** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
619** If the lower four bits equal SQLITE_SYNC_FULL, that means
620** to use Mac OS X style fullsync instead of fsync().
621**
622** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
623** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
624** settings. The [synchronous pragma] determines when calls to the
625** xSync VFS method occur and applies uniformly across all platforms.
626** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
627** energetic or rigorous or forceful the sync operations are and
628** only make a difference on Mac OSX for the default SQLite code.
629** (Third-party VFS implementations might also make the distinction
630** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
631** operating systems natively supported by SQLite, only Mac OSX
632** cares about the difference.)
633*/
634#define SQLITE_SYNC_NORMAL 0x00002
635#define SQLITE_SYNC_FULL 0x00003
636#define SQLITE_SYNC_DATAONLY 0x00010
637
638/*
639** CAPI3REF: OS Interface Open File Handle
640**
641** An [sqlite3_file] object represents an open file in the
642** [sqlite3_vfs | OS interface layer]. Individual OS interface
643** implementations will
644** want to subclass this object by appending additional fields
645** for their own use. The pMethods entry is a pointer to an
646** [sqlite3_io_methods] object that defines methods for performing
647** I/O operations on the open file.
648*/
649typedef struct sqlite3_file sqlite3_file;
650struct sqlite3_file {
651 const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
652};
653
654/*
655** CAPI3REF: OS Interface File Virtual Methods Object
656**
657** Every file opened by the [sqlite3_vfs.xOpen] method populates an
658** [sqlite3_file] object (or, more commonly, a subclass of the
659** [sqlite3_file] object) with a pointer to an instance of this object.
660** This object defines the methods used to perform various operations
661** against the open file represented by the [sqlite3_file] object.
662**
663** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element
664** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
665** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed. The
666** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
667** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
668** to NULL.
669**
670** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
671** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
672** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
673** flag may be ORed in to indicate that only the data of the file
674** and not its inode needs to be synced.
675**
676** The integer values to xLock() and xUnlock() are one of
677** <ul>
678** <li> [SQLITE_LOCK_NONE],
679** <li> [SQLITE_LOCK_SHARED],
680** <li> [SQLITE_LOCK_RESERVED],
681** <li> [SQLITE_LOCK_PENDING], or
682** <li> [SQLITE_LOCK_EXCLUSIVE].
683** </ul>
684** xLock() increases the lock. xUnlock() decreases the lock.
685** The xCheckReservedLock() method checks whether any database connection,
686** either in this process or in some other process, is holding a RESERVED,
687** PENDING, or EXCLUSIVE lock on the file. It returns true
688** if such a lock exists and false otherwise.
689**
690** The xFileControl() method is a generic interface that allows custom
691** VFS implementations to directly control an open file using the
692** [sqlite3_file_control()] interface. The second "op" argument is an
693** integer opcode. The third argument is a generic pointer intended to
694** point to a structure that may contain arguments or space in which to
695** write return values. Potential uses for xFileControl() might be
696** functions to enable blocking locks with timeouts, to change the
697** locking strategy (for example to use dot-file locks), to inquire
698** about the status of a lock, or to break stale locks. The SQLite
699** core reserves all opcodes less than 100 for its own use.
700** A [file control opcodes | list of opcodes] less than 100 is available.
701** Applications that define a custom xFileControl method should use opcodes
702** greater than 100 to avoid conflicts. VFS implementations should
703** return [SQLITE_NOTFOUND] for file control opcodes that they do not
704** recognize.
705**
706** The xSectorSize() method returns the sector size of the
707** device that underlies the file. The sector size is the
708** minimum write that can be performed without disturbing
709** other bytes in the file. The xDeviceCharacteristics()
710** method returns a bit vector describing behaviors of the
711** underlying device:
712**
713** <ul>
714** <li> [SQLITE_IOCAP_ATOMIC]
715** <li> [SQLITE_IOCAP_ATOMIC512]
716** <li> [SQLITE_IOCAP_ATOMIC1K]
717** <li> [SQLITE_IOCAP_ATOMIC2K]
718** <li> [SQLITE_IOCAP_ATOMIC4K]
719** <li> [SQLITE_IOCAP_ATOMIC8K]
720** <li> [SQLITE_IOCAP_ATOMIC16K]
721** <li> [SQLITE_IOCAP_ATOMIC32K]
722** <li> [SQLITE_IOCAP_ATOMIC64K]
723** <li> [SQLITE_IOCAP_SAFE_APPEND]
724** <li> [SQLITE_IOCAP_SEQUENTIAL]
725** </ul>
726**
727** The SQLITE_IOCAP_ATOMIC property means that all writes of
728** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
729** mean that writes of blocks that are nnn bytes in size and
730** are aligned to an address which is an integer multiple of
731** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
732** that when data is appended to a file, the data is appended
733** first then the size of the file is extended, never the other
734** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
735** information is written to disk in the same order as calls
736** to xWrite().
737**
738** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
739** in the unread portions of the buffer with zeros. A VFS that
740** fails to zero-fill short reads might seem to work. However,
741** failure to zero-fill short reads will eventually lead to
742** database corruption.
743*/
744typedef struct sqlite3_io_methods sqlite3_io_methods;
745struct sqlite3_io_methods {
746 int iVersion;
747 int (*xClose)(sqlite3_file*);
748 int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
749 int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
750 int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
751 int (*xSync)(sqlite3_file*, int flags);
752 int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
753 int (*xLock)(sqlite3_file*, int);
754 int (*xUnlock)(sqlite3_file*, int);
755 int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
756 int (*xFileControl)(sqlite3_file*, int op, void *pArg);
757 int (*xSectorSize)(sqlite3_file*);
758 int (*xDeviceCharacteristics)(sqlite3_file*);
759 /* Methods above are valid for version 1 */
760 int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
761 int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
762 void (*xShmBarrier)(sqlite3_file*);
763 int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
764 /* Methods above are valid for version 2 */
765 int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
766 int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
767 /* Methods above are valid for version 3 */
768 /* Additional methods may be added in future releases */
769};
770
771/*
772** CAPI3REF: Standard File Control Opcodes
773** KEYWORDS: {file control opcodes} {file control opcode}
774**
775** These integer constants are opcodes for the xFileControl method
776** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
777** interface.
778**
779** <ul>
780** <li>[[SQLITE_FCNTL_LOCKSTATE]]
781** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
782** opcode causes the xFileControl method to write the current state of
783** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
784** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
785** into an integer that the pArg argument points to. This capability
786** is used during testing and is only available when the SQLITE_TEST
787** compile-time option is used.
788**
789** <li>[[SQLITE_FCNTL_SIZE_HINT]]
790** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
791** layer a hint of how large the database file will grow to be during the
792** current transaction. This hint is not guaranteed to be accurate but it
793** is often close. The underlying VFS might choose to preallocate database
794** file space based on this hint in order to help writes to the database
795** file run faster.
796**
797** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]
798** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
799** extends and truncates the database file in chunks of a size specified
800** by the user. The fourth argument to [sqlite3_file_control()] should
801** point to an integer (type int) containing the new chunk-size to use
802** for the nominated database. Allocating database file space in large
803** chunks (say 1MB at a time), may reduce file-system fragmentation and
804** improve performance on some systems.
805**
806** <li>[[SQLITE_FCNTL_FILE_POINTER]]
807** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
808** to the [sqlite3_file] object associated with a particular database
809** connection. See also [SQLITE_FCNTL_JOURNAL_POINTER].
810**
811** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]
812** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
813** to the [sqlite3_file] object associated with the journal file (either
814** the [rollback journal] or the [write-ahead log]) for a particular database
815** connection. See also [SQLITE_FCNTL_FILE_POINTER].
816**
817** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
818** No longer in use.
819**
820** <li>[[SQLITE_FCNTL_SYNC]]
821** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
822** sent to the VFS immediately before the xSync method is invoked on a
823** database file descriptor. Or, if the xSync method is not invoked
824** because the user has configured SQLite with
825** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place
826** of the xSync method. In most cases, the pointer argument passed with
827** this file-control is NULL. However, if the database file is being synced
828** as part of a multi-database commit, the argument points to a nul-terminated
829** string containing the transactions master-journal file name. VFSes that
830** do not need this signal should silently ignore this opcode. Applications
831** should not call [sqlite3_file_control()] with this opcode as doing so may
832** disrupt the operation of the specialized VFSes that do require it.
833**
834** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]
835** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
836** and sent to the VFS after a transaction has been committed immediately
837** but before the database is unlocked. VFSes that do not need this signal
838** should silently ignore this opcode. Applications should not call
839** [sqlite3_file_control()] with this opcode as doing so may disrupt the
840** operation of the specialized VFSes that do require it.
841**
842** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
843** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
844** retry counts and intervals for certain disk I/O operations for the
845** windows [VFS] in order to provide robustness in the presence of
846** anti-virus programs. By default, the windows VFS will retry file read,
847** file write, and file delete operations up to 10 times, with a delay
848** of 25 milliseconds before the first retry and with the delay increasing
849** by an additional 25 milliseconds with each subsequent retry. This
850** opcode allows these two values (10 retries and 25 milliseconds of delay)
851** to be adjusted. The values are changed for all database connections
852** within the same process. The argument is a pointer to an array of two
853** integers where the first integer i the new retry count and the second
854** integer is the delay. If either integer is negative, then the setting
855** is not changed but instead the prior value of that setting is written
856** into the array entry, allowing the current retry settings to be
857** interrogated. The zDbName parameter is ignored.
858**
859** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
860** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
861** persistent [WAL | Write Ahead Log] setting. By default, the auxiliary
862** write ahead log and shared memory files used for transaction control
863** are automatically deleted when the latest connection to the database
864** closes. Setting persistent WAL mode causes those files to persist after
865** close. Persisting the files is useful when other processes that do not
866** have write permission on the directory containing the database file want
867** to read the database file, as the WAL and shared memory files must exist
868** in order for the database to be readable. The fourth parameter to
869** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
870** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
871** WAL mode. If the integer is -1, then it is overwritten with the current
872** WAL persistence setting.
873**
874** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]
875** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
876** persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
877** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the
878** xDeviceCharacteristics methods. The fourth parameter to
879** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
880** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
881** mode. If the integer is -1, then it is overwritten with the current
882** zero-damage mode setting.
883**
884** <li>[[SQLITE_FCNTL_OVERWRITE]]
885** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
886** a write transaction to indicate that, unless it is rolled back for some
887** reason, the entire database file will be overwritten by the current
888** transaction. This is used by VACUUM operations.
889**
890** <li>[[SQLITE_FCNTL_VFSNAME]]
891** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
892** all [VFSes] in the VFS stack. The names are of all VFS shims and the
893** final bottom-level VFS are written into memory obtained from
894** [sqlite3_malloc()] and the result is stored in the char* variable
895** that the fourth parameter of [sqlite3_file_control()] points to.
896** The caller is responsible for freeing the memory when done. As with
897** all file-control actions, there is no guarantee that this will actually
898** do anything. Callers should initialize the char* variable to a NULL
899** pointer in case this file-control is not implemented. This file-control
900** is intended for diagnostic use only.
901**
902** <li>[[SQLITE_FCNTL_VFS_POINTER]]
903** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
904** [VFSes] currently in use. ^(The argument X in
905** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
906** of type "[sqlite3_vfs] **". This opcodes will set *X
907** to a pointer to the top-level VFS.)^
908** ^When there are multiple VFS shims in the stack, this opcode finds the
909** upper-most shim only.
910**
911** <li>[[SQLITE_FCNTL_PRAGMA]]
912** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
913** file control is sent to the open [sqlite3_file] object corresponding
914** to the database file to which the pragma statement refers. ^The argument
915** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
916** pointers to strings (char**) in which the second element of the array
917** is the name of the pragma and the third element is the argument to the
918** pragma or NULL if the pragma has no argument. ^The handler for an
919** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element
920** of the char** argument point to a string obtained from [sqlite3_mprintf()]
921** or the equivalent and that string will become the result of the pragma or
922** the error message if the pragma fails. ^If the
923** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal
924** [PRAGMA] processing continues. ^If the [SQLITE_FCNTL_PRAGMA]
925** file control returns [SQLITE_OK], then the parser assumes that the
926** VFS has handled the PRAGMA itself and the parser generates a no-op
927** prepared statement if result string is NULL, or that returns a copy
928** of the result string if the string is non-NULL.
929** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
930** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
931** that the VFS encountered an error while handling the [PRAGMA] and the
932** compilation of the PRAGMA fails with an error. ^The [SQLITE_FCNTL_PRAGMA]
933** file control occurs at the beginning of pragma statement analysis and so
934** it is able to override built-in [PRAGMA] statements.
935**
936** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
937** ^The [SQLITE_FCNTL_BUSYHANDLER]
938** file-control may be invoked by SQLite on the database file handle
939** shortly after it is opened in order to provide a custom VFS with access
940** to the connections busy-handler callback. The argument is of type (void **)
941** - an array of two (void *) values. The first (void *) actually points
942** to a function of type (int (*)(void *)). In order to invoke the connections
943** busy-handler, this function should be invoked with the second (void *) in
944** the array as the only argument. If it returns non-zero, then the operation
945** should be retried. If it returns zero, the custom VFS should abandon the
946** current operation.
947**
948** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
949** ^Application can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
950** to have SQLite generate a
951** temporary filename using the same algorithm that is followed to generate
952** temporary filenames for TEMP tables and other internal uses. The
953** argument should be a char** which will be filled with the filename
954** written into memory obtained from [sqlite3_malloc()]. The caller should
955** invoke [sqlite3_free()] on the result to avoid a memory leak.
956**
957** <li>[[SQLITE_FCNTL_MMAP_SIZE]]
958** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
959** maximum number of bytes that will be used for memory-mapped I/O.
960** The argument is a pointer to a value of type sqlite3_int64 that
961** is an advisory maximum number of bytes in the file to memory map. The
962** pointer is overwritten with the old value. The limit is not changed if
963** the value originally pointed to is negative, and so the current limit
964** can be queried by passing in a pointer to a negative number. This
965** file-control is used internally to implement [PRAGMA mmap_size].
966**
967** <li>[[SQLITE_FCNTL_TRACE]]
968** The [SQLITE_FCNTL_TRACE] file control provides advisory information
969** to the VFS about what the higher layers of the SQLite stack are doing.
970** This file control is used by some VFS activity tracing [shims].
971** The argument is a zero-terminated string. Higher layers in the
972** SQLite stack may generate instances of this file control if
973** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
974**
975** <li>[[SQLITE_FCNTL_HAS_MOVED]]
976** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
977** pointer to an integer and it writes a boolean into that integer depending
978** on whether or not the file has been renamed, moved, or deleted since it
979** was first opened.
980**
981** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]]
982** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the
983** underlying native file handle associated with a file handle. This file
984** control interprets its argument as a pointer to a native file handle and
985** writes the resulting value there.
986**
987** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
988** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This
989** opcode causes the xFileControl method to swap the file handle with the one
990** pointed to by the pArg argument. This capability is used during testing
991** and only needs to be supported when SQLITE_TEST is defined.
992**
993** <li>[[SQLITE_FCNTL_WAL_BLOCK]]
994** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
995** be advantageous to block on the next WAL lock if the lock is not immediately
996** available. The WAL subsystem issues this signal during rare
997** circumstances in order to fix a problem with priority inversion.
998** Applications should <em>not</em> use this file-control.
999**
1000** <li>[[SQLITE_FCNTL_ZIPVFS]]
1001** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
1002** VFS should return SQLITE_NOTFOUND for this opcode.
1003**
1004** <li>[[SQLITE_FCNTL_RBU]]
1005** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
1006** the RBU extension only. All other VFS should return SQLITE_NOTFOUND for
1007** this opcode.
1008** </ul>
1009*/
1010#define SQLITE_FCNTL_LOCKSTATE 1
1011#define SQLITE_FCNTL_GET_LOCKPROXYFILE 2
1012#define SQLITE_FCNTL_SET_LOCKPROXYFILE 3
1013#define SQLITE_FCNTL_LAST_ERRNO 4
1014#define SQLITE_FCNTL_SIZE_HINT 5
1015#define SQLITE_FCNTL_CHUNK_SIZE 6
1016#define SQLITE_FCNTL_FILE_POINTER 7
1017#define SQLITE_FCNTL_SYNC_OMITTED 8
1018#define SQLITE_FCNTL_WIN32_AV_RETRY 9
1019#define SQLITE_FCNTL_PERSIST_WAL 10
1020#define SQLITE_FCNTL_OVERWRITE 11
1021#define SQLITE_FCNTL_VFSNAME 12
1022#define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13
1023#define SQLITE_FCNTL_PRAGMA 14
1024#define SQLITE_FCNTL_BUSYHANDLER 15
1025#define SQLITE_FCNTL_TEMPFILENAME 16
1026#define SQLITE_FCNTL_MMAP_SIZE 18
1027#define SQLITE_FCNTL_TRACE 19
1028#define SQLITE_FCNTL_HAS_MOVED 20
1029#define SQLITE_FCNTL_SYNC 21
1030#define SQLITE_FCNTL_COMMIT_PHASETWO 22
1031#define SQLITE_FCNTL_WIN32_SET_HANDLE 23
1032#define SQLITE_FCNTL_WAL_BLOCK 24
1033#define SQLITE_FCNTL_ZIPVFS 25
1034#define SQLITE_FCNTL_RBU 26
1035#define SQLITE_FCNTL_VFS_POINTER 27
1036#define SQLITE_FCNTL_JOURNAL_POINTER 28
1037#define SQLITE_FCNTL_WIN32_GET_HANDLE 29
1038#define SQLITE_FCNTL_PDB 30
1039
1040/* deprecated names */
1041#define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE
1042#define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE
1043#define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO
1044
1045
1046/*
1047** CAPI3REF: Mutex Handle
1048**
1049** The mutex module within SQLite defines [sqlite3_mutex] to be an
1050** abstract type for a mutex object. The SQLite core never looks
1051** at the internal representation of an [sqlite3_mutex]. It only
1052** deals with pointers to the [sqlite3_mutex] object.
1053**
1054** Mutexes are created using [sqlite3_mutex_alloc()].
1055*/
1056typedef struct sqlite3_mutex sqlite3_mutex;
1057
1058/*
1059** CAPI3REF: Loadable Extension Thunk
1060**
1061** A pointer to the opaque sqlite3_api_routines structure is passed as
1062** the third parameter to entry points of [loadable extensions]. This
1063** structure must be typedefed in order to work around compiler warnings
1064** on some platforms.
1065*/
1066typedef struct sqlite3_api_routines sqlite3_api_routines;
1067
1068/*
1069** CAPI3REF: OS Interface Object
1070**
1071** An instance of the sqlite3_vfs object defines the interface between
1072** the SQLite core and the underlying operating system. The "vfs"
1073** in the name of the object stands for "virtual file system". See
1074** the [VFS | VFS documentation] for further information.
1075**
1076** The value of the iVersion field is initially 1 but may be larger in
1077** future versions of SQLite. Additional fields may be appended to this
1078** object when the iVersion value is increased. Note that the structure
1079** of the sqlite3_vfs object changes in the transaction between
1080** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
1081** modified.
1082**
1083** The szOsFile field is the size of the subclassed [sqlite3_file]
1084** structure used by this VFS. mxPathname is the maximum length of
1085** a pathname in this VFS.
1086**
1087** Registered sqlite3_vfs objects are kept on a linked list formed by
1088** the pNext pointer. The [sqlite3_vfs_register()]
1089** and [sqlite3_vfs_unregister()] interfaces manage this list
1090** in a thread-safe way. The [sqlite3_vfs_find()] interface
1091** searches the list. Neither the application code nor the VFS
1092** implementation should use the pNext pointer.
1093**
1094** The pNext field is the only field in the sqlite3_vfs
1095** structure that SQLite will ever modify. SQLite will only access
1096** or modify this field while holding a particular static mutex.
1097** The application should never modify anything within the sqlite3_vfs
1098** object once the object has been registered.
1099**
1100** The zName field holds the name of the VFS module. The name must
1101** be unique across all VFS modules.
1102**
1103** [[sqlite3_vfs.xOpen]]
1104** ^SQLite guarantees that the zFilename parameter to xOpen
1105** is either a NULL pointer or string obtained
1106** from xFullPathname() with an optional suffix added.
1107** ^If a suffix is added to the zFilename parameter, it will
1108** consist of a single "-" character followed by no more than
1109** 11 alphanumeric and/or "-" characters.
1110** ^SQLite further guarantees that
1111** the string will be valid and unchanged until xClose() is
1112** called. Because of the previous sentence,
1113** the [sqlite3_file] can safely store a pointer to the
1114** filename if it needs to remember the filename for some reason.
1115** If the zFilename parameter to xOpen is a NULL pointer then xOpen
1116** must invent its own temporary name for the file. ^Whenever the
1117** xFilename parameter is NULL it will also be the case that the
1118** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
1119**
1120** The flags argument to xOpen() includes all bits set in
1121** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
1122** or [sqlite3_open16()] is used, then flags includes at least
1123** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
1124** If xOpen() opens a file read-only then it sets *pOutFlags to
1125** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set.
1126**
1127** ^(SQLite will also add one of the following flags to the xOpen()
1128** call, depending on the object being opened:
1129**
1130** <ul>
1131** <li> [SQLITE_OPEN_MAIN_DB]
1132** <li> [SQLITE_OPEN_MAIN_JOURNAL]
1133** <li> [SQLITE_OPEN_TEMP_DB]
1134** <li> [SQLITE_OPEN_TEMP_JOURNAL]
1135** <li> [SQLITE_OPEN_TRANSIENT_DB]
1136** <li> [SQLITE_OPEN_SUBJOURNAL]
1137** <li> [SQLITE_OPEN_MASTER_JOURNAL]
1138** <li> [SQLITE_OPEN_WAL]
1139** </ul>)^
1140**
1141** The file I/O implementation can use the object type flags to
1142** change the way it deals with files. For example, an application
1143** that does not care about crash recovery or rollback might make
1144** the open of a journal file a no-op. Writes to this journal would
1145** also be no-ops, and any attempt to read the journal would return
1146** SQLITE_IOERR. Or the implementation might recognize that a database
1147** file will be doing page-aligned sector reads and writes in a random
1148** order and set up its I/O subsystem accordingly.
1149**
1150** SQLite might also add one of the following flags to the xOpen method:
1151**
1152** <ul>
1153** <li> [SQLITE_OPEN_DELETEONCLOSE]
1154** <li> [SQLITE_OPEN_EXCLUSIVE]
1155** </ul>
1156**
1157** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
1158** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE]
1159** will be set for TEMP databases and their journals, transient
1160** databases, and subjournals.
1161**
1162** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
1163** with the [SQLITE_OPEN_CREATE] flag, which are both directly
1164** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
1165** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
1166** SQLITE_OPEN_CREATE, is used to indicate that file should always
1167** be created, and that it is an error if it already exists.
1168** It is <i>not</i> used to indicate the file should be opened
1169** for exclusive access.
1170**
1171** ^At least szOsFile bytes of memory are allocated by SQLite
1172** to hold the [sqlite3_file] structure passed as the third
1173** argument to xOpen. The xOpen method does not have to
1174** allocate the structure; it should just fill it in. Note that
1175** the xOpen method must set the sqlite3_file.pMethods to either
1176** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
1177** this even if the open fails. SQLite expects that the sqlite3_file.pMethods
1178** element will be valid after xOpen returns regardless of the success
1179** or failure of the xOpen call.
1180**
1181** [[sqlite3_vfs.xAccess]]
1182** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
1183** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
1184** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
1185** to test whether a file is at least readable. The file can be a
1186** directory.
1187**
1188** ^SQLite will always allocate at least mxPathname+1 bytes for the
1189** output buffer xFullPathname. The exact size of the output buffer
1190** is also passed as a parameter to both methods. If the output buffer
1191** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
1192** handled as a fatal error by SQLite, vfs implementations should endeavor
1193** to prevent this by setting mxPathname to a sufficiently large value.
1194**
1195** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
1196** interfaces are not strictly a part of the filesystem, but they are
1197** included in the VFS structure for completeness.
1198** The xRandomness() function attempts to return nBytes bytes
1199** of good-quality randomness into zOut. The return value is
1200** the actual number of bytes of randomness obtained.
1201** The xSleep() method causes the calling thread to sleep for at
1202** least the number of microseconds given. ^The xCurrentTime()
1203** method returns a Julian Day Number for the current date and time as
1204** a floating point value.
1205** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
1206** Day Number multiplied by 86400000 (the number of milliseconds in
1207** a 24-hour day).
1208** ^SQLite will use the xCurrentTimeInt64() method to get the current
1209** date and time if that method is available (if iVersion is 2 or
1210** greater and the function pointer is not NULL) and will fall back
1211** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
1212**
1213** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
1214** are not used by the SQLite core. These optional interfaces are provided
1215** by some VFSes to facilitate testing of the VFS code. By overriding
1216** system calls with functions under its control, a test program can
1217** simulate faults and error conditions that would otherwise be difficult
1218** or impossible to induce. The set of system calls that can be overridden
1219** varies from one VFS to another, and from one version of the same VFS to the
1220** next. Applications that use these interfaces must be prepared for any
1221** or all of these interfaces to be NULL or for their behavior to change
1222** from one release to the next. Applications must not attempt to access
1223** any of these methods if the iVersion of the VFS is less than 3.
1224*/
1225typedef struct sqlite3_vfs sqlite3_vfs;
1226typedef void (*sqlite3_syscall_ptr)(void);
1227struct sqlite3_vfs {
1228 int iVersion; /* Structure version number (currently 3) */
1229 int szOsFile; /* Size of subclassed sqlite3_file */
1230 int mxPathname; /* Maximum file pathname length */
1231 sqlite3_vfs *pNext; /* Next registered VFS */
1232 const char *zName; /* Name of this virtual file system */
1233 void *pAppData; /* Pointer to application-specific data */
1234 int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
1235 int flags, int *pOutFlags);
1236 int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
1237 int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
1238 int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
1239 void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
1240 void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
1241 void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
1242 void (*xDlClose)(sqlite3_vfs*, void*);
1243 int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
1244 int (*xSleep)(sqlite3_vfs*, int microseconds);
1245 int (*xCurrentTime)(sqlite3_vfs*, double*);
1246 int (*xGetLastError)(sqlite3_vfs*, int, char *);
1247 /*
1248 ** The methods above are in version 1 of the sqlite_vfs object
1249 ** definition. Those that follow are added in version 2 or later
1250 */
1251 int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
1252 /*
1253 ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
1254 ** Those below are for version 3 and greater.
1255 */
1256 int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
1257 sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
1258 const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
1259 /*
1260 ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
1261 ** New fields may be appended in future versions. The iVersion
1262 ** value will increment whenever this happens.
1263 */
1264};
1265
1266/*
1267** CAPI3REF: Flags for the xAccess VFS method
1268**
1269** These integer constants can be used as the third parameter to
1270** the xAccess method of an [sqlite3_vfs] object. They determine
1271** what kind of permissions the xAccess method is looking for.
1272** With SQLITE_ACCESS_EXISTS, the xAccess method
1273** simply checks whether the file exists.
1274** With SQLITE_ACCESS_READWRITE, the xAccess method
1275** checks whether the named directory is both readable and writable
1276** (in other words, if files can be added, removed, and renamed within
1277** the directory).
1278** The SQLITE_ACCESS_READWRITE constant is currently used only by the
1279** [temp_store_directory pragma], though this could change in a future
1280** release of SQLite.
1281** With SQLITE_ACCESS_READ, the xAccess method
1282** checks whether the file is readable. The SQLITE_ACCESS_READ constant is
1283** currently unused, though it might be used in a future release of
1284** SQLite.
1285*/
1286#define SQLITE_ACCESS_EXISTS 0
1287#define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */
1288#define SQLITE_ACCESS_READ 2 /* Unused */
1289
1290/*
1291** CAPI3REF: Flags for the xShmLock VFS method
1292**
1293** These integer constants define the various locking operations
1294** allowed by the xShmLock method of [sqlite3_io_methods]. The
1295** following are the only legal combinations of flags to the
1296** xShmLock method:
1297**
1298** <ul>
1299** <li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
1300** <li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
1301** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
1302** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
1303** </ul>
1304**
1305** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
1306** was given on the corresponding lock.
1307**
1308** The xShmLock method can transition between unlocked and SHARED or
1309** between unlocked and EXCLUSIVE. It cannot transition between SHARED
1310** and EXCLUSIVE.
1311*/
1312#define SQLITE_SHM_UNLOCK 1
1313#define SQLITE_SHM_LOCK 2
1314#define SQLITE_SHM_SHARED 4
1315#define SQLITE_SHM_EXCLUSIVE 8
1316
1317/*
1318** CAPI3REF: Maximum xShmLock index
1319**
1320** The xShmLock method on [sqlite3_io_methods] may use values
1321** between 0 and this upper bound as its "offset" argument.
1322** The SQLite core will never attempt to acquire or release a
1323** lock outside of this range
1324*/
1325#define SQLITE_SHM_NLOCK 8
1326
1327
1328/*
1329** CAPI3REF: Initialize The SQLite Library
1330**
1331** ^The sqlite3_initialize() routine initializes the
1332** SQLite library. ^The sqlite3_shutdown() routine
1333** deallocates any resources that were allocated by sqlite3_initialize().
1334** These routines are designed to aid in process initialization and
1335** shutdown on embedded systems. Workstation applications using
1336** SQLite normally do not need to invoke either of these routines.
1337**
1338** A call to sqlite3_initialize() is an "effective" call if it is
1339** the first time sqlite3_initialize() is invoked during the lifetime of
1340** the process, or if it is the first time sqlite3_initialize() is invoked
1341** following a call to sqlite3_shutdown(). ^(Only an effective call
1342** of sqlite3_initialize() does any initialization. All other calls
1343** are harmless no-ops.)^
1344**
1345** A call to sqlite3_shutdown() is an "effective" call if it is the first
1346** call to sqlite3_shutdown() since the last sqlite3_initialize(). ^(Only
1347** an effective call to sqlite3_shutdown() does any deinitialization.
1348** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
1349**
1350** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
1351** is not. The sqlite3_shutdown() interface must only be called from a
1352** single thread. All open [database connections] must be closed and all
1353** other SQLite resources must be deallocated prior to invoking
1354** sqlite3_shutdown().
1355**
1356** Among other things, ^sqlite3_initialize() will invoke
1357** sqlite3_os_init(). Similarly, ^sqlite3_shutdown()
1358** will invoke sqlite3_os_end().
1359**
1360** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
1361** ^If for some reason, sqlite3_initialize() is unable to initialize
1362** the library (perhaps it is unable to allocate a needed resource such
1363** as a mutex) it returns an [error code] other than [SQLITE_OK].
1364**
1365** ^The sqlite3_initialize() routine is called internally by many other
1366** SQLite interfaces so that an application usually does not need to
1367** invoke sqlite3_initialize() directly. For example, [sqlite3_open()]
1368** calls sqlite3_initialize() so the SQLite library will be automatically
1369** initialized when [sqlite3_open()] is called if it has not be initialized
1370** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
1371** compile-time option, then the automatic calls to sqlite3_initialize()
1372** are omitted and the application must call sqlite3_initialize() directly
1373** prior to using any other SQLite interface. For maximum portability,
1374** it is recommended that applications always invoke sqlite3_initialize()
1375** directly prior to using any other SQLite interface. Future releases
1376** of SQLite may require this. In other words, the behavior exhibited
1377** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
1378** default behavior in some future release of SQLite.
1379**
1380** The sqlite3_os_init() routine does operating-system specific
1381** initialization of the SQLite library. The sqlite3_os_end()
1382** routine undoes the effect of sqlite3_os_init(). Typical tasks
1383** performed by these routines include allocation or deallocation
1384** of static resources, initialization of global variables,
1385** setting up a default [sqlite3_vfs] module, or setting up
1386** a default configuration using [sqlite3_config()].
1387**
1388** The application should never invoke either sqlite3_os_init()
1389** or sqlite3_os_end() directly. The application should only invoke
1390** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()
1391** interface is called automatically by sqlite3_initialize() and
1392** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
1393** implementations for sqlite3_os_init() and sqlite3_os_end()
1394** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
1395** When [custom builds | built for other platforms]
1396** (using the [SQLITE_OS_OTHER=1] compile-time
1397** option) the application must supply a suitable implementation for
1398** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
1399** implementation of sqlite3_os_init() or sqlite3_os_end()
1400** must return [SQLITE_OK] on success and some other [error code] upon
1401** failure.
1402*/
1403SQLITE_API int sqlite3_initialize(void);
1404SQLITE_API int sqlite3_shutdown(void);
1405SQLITE_API int sqlite3_os_init(void);
1406SQLITE_API int sqlite3_os_end(void);
1407
1408/*
1409** CAPI3REF: Configuring The SQLite Library
1410**
1411** The sqlite3_config() interface is used to make global configuration
1412** changes to SQLite in order to tune SQLite to the specific needs of
1413** the application. The default configuration is recommended for most
1414** applications and so this routine is usually not necessary. It is
1415** provided to support rare applications with unusual needs.
1416**
1417** <b>The sqlite3_config() interface is not threadsafe. The application
1418** must ensure that no other SQLite interfaces are invoked by other
1419** threads while sqlite3_config() is running.</b>
1420**
1421** The sqlite3_config() interface
1422** may only be invoked prior to library initialization using
1423** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
1424** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
1425** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
1426** Note, however, that ^sqlite3_config() can be called as part of the
1427** implementation of an application-defined [sqlite3_os_init()].
1428**
1429** The first argument to sqlite3_config() is an integer
1430** [configuration option] that determines
1431** what property of SQLite is to be configured. Subsequent arguments
1432** vary depending on the [configuration option]
1433** in the first argument.
1434**
1435** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
1436** ^If the option is unknown or SQLite is unable to set the option
1437** then this routine returns a non-zero [error code].
1438*/
1439SQLITE_API int sqlite3_config(int, ...);
1440
1441/*
1442** CAPI3REF: Configure database connections
1443** METHOD: sqlite3
1444**
1445** The sqlite3_db_config() interface is used to make configuration
1446** changes to a [database connection]. The interface is similar to
1447** [sqlite3_config()] except that the changes apply to a single
1448** [database connection] (specified in the first argument).
1449**
1450** The second argument to sqlite3_db_config(D,V,...) is the
1451** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code
1452** that indicates what aspect of the [database connection] is being configured.
1453** Subsequent arguments vary depending on the configuration verb.
1454**
1455** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
1456** the call is considered successful.
1457*/
1458SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
1459
1460/*
1461** CAPI3REF: Memory Allocation Routines
1462**
1463** An instance of this object defines the interface between SQLite
1464** and low-level memory allocation routines.
1465**
1466** This object is used in only one place in the SQLite interface.
1467** A pointer to an instance of this object is the argument to
1468** [sqlite3_config()] when the configuration option is
1469** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
1470** By creating an instance of this object
1471** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
1472** during configuration, an application can specify an alternative
1473** memory allocation subsystem for SQLite to use for all of its
1474** dynamic memory needs.
1475**
1476** Note that SQLite comes with several [built-in memory allocators]
1477** that are perfectly adequate for the overwhelming majority of applications
1478** and that this object is only useful to a tiny minority of applications
1479** with specialized memory allocation requirements. This object is
1480** also used during testing of SQLite in order to specify an alternative
1481** memory allocator that simulates memory out-of-memory conditions in
1482** order to verify that SQLite recovers gracefully from such
1483** conditions.
1484**
1485** The xMalloc, xRealloc, and xFree methods must work like the
1486** malloc(), realloc() and free() functions from the standard C library.
1487** ^SQLite guarantees that the second argument to
1488** xRealloc is always a value returned by a prior call to xRoundup.
1489**
1490** xSize should return the allocated size of a memory allocation
1491** previously obtained from xMalloc or xRealloc. The allocated size
1492** is always at least as big as the requested size but may be larger.
1493**
1494** The xRoundup method returns what would be the allocated size of
1495** a memory allocation given a particular requested size. Most memory
1496** allocators round up memory allocations at least to the next multiple
1497** of 8. Some allocators round up to a larger multiple or to a power of 2.
1498** Every memory allocation request coming in through [sqlite3_malloc()]
1499** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
1500** that causes the corresponding memory allocation to fail.
1501**
1502** The xInit method initializes the memory allocator. For example,
1503** it might allocate any require mutexes or initialize internal data
1504** structures. The xShutdown method is invoked (indirectly) by
1505** [sqlite3_shutdown()] and should deallocate any resources acquired
1506** by xInit. The pAppData pointer is used as the only parameter to
1507** xInit and xShutdown.
1508**
1509** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
1510** the xInit method, so the xInit method need not be threadsafe. The
1511** xShutdown method is only called from [sqlite3_shutdown()] so it does
1512** not need to be threadsafe either. For all other methods, SQLite
1513** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
1514** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
1515** it is by default) and so the methods are automatically serialized.
1516** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
1517** methods must be threadsafe or else make their own arrangements for
1518** serialization.
1519**
1520** SQLite will never invoke xInit() more than once without an intervening
1521** call to xShutdown().
1522*/
1523typedef struct sqlite3_mem_methods sqlite3_mem_methods;
1524struct sqlite3_mem_methods {
1525 void *(*xMalloc)(int); /* Memory allocation function */
1526 void (*xFree)(void*); /* Free a prior allocation */
1527 void *(*xRealloc)(void*,int); /* Resize an allocation */
1528 int (*xSize)(void*); /* Return the size of an allocation */
1529 int (*xRoundup)(int); /* Round up request size to allocation size */
1530 int (*xInit)(void*); /* Initialize the memory allocator */
1531 void (*xShutdown)(void*); /* Deinitialize the memory allocator */
1532 void *pAppData; /* Argument to xInit() and xShutdown() */
1533};
1534
1535/*
1536** CAPI3REF: Configuration Options
1537** KEYWORDS: {configuration option}
1538**
1539** These constants are the available integer configuration options that
1540** can be passed as the first argument to the [sqlite3_config()] interface.
1541**
1542** New configuration options may be added in future releases of SQLite.
1543** Existing configuration options might be discontinued. Applications
1544** should check the return code from [sqlite3_config()] to make sure that
1545** the call worked. The [sqlite3_config()] interface will return a
1546** non-zero [error code] if a discontinued or unsupported configuration option
1547** is invoked.
1548**
1549** <dl>
1550** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
1551** <dd>There are no arguments to this option. ^This option sets the
1552** [threading mode] to Single-thread. In other words, it disables
1553** all mutexing and puts SQLite into a mode where it can only be used
1554** by a single thread. ^If SQLite is compiled with
1555** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1556** it is not possible to change the [threading mode] from its default
1557** value of Single-thread and so [sqlite3_config()] will return
1558** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
1559** configuration option.</dd>
1560**
1561** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
1562** <dd>There are no arguments to this option. ^This option sets the
1563** [threading mode] to Multi-thread. In other words, it disables
1564** mutexing on [database connection] and [prepared statement] objects.
1565** The application is responsible for serializing access to
1566** [database connections] and [prepared statements]. But other mutexes
1567** are enabled so that SQLite will be safe to use in a multi-threaded
1568** environment as long as no two threads attempt to use the same
1569** [database connection] at the same time. ^If SQLite is compiled with
1570** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1571** it is not possible to set the Multi-thread [threading mode] and
1572** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1573** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
1574**
1575** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
1576** <dd>There are no arguments to this option. ^This option sets the
1577** [threading mode] to Serialized. In other words, this option enables
1578** all mutexes including the recursive
1579** mutexes on [database connection] and [prepared statement] objects.
1580** In this mode (which is the default when SQLite is compiled with
1581** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
1582** to [database connections] and [prepared statements] so that the
1583** application is free to use the same [database connection] or the
1584** same [prepared statement] in different threads at the same time.
1585** ^If SQLite is compiled with
1586** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1587** it is not possible to set the Serialized [threading mode] and
1588** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1589** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
1590**
1591** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
1592** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is
1593** a pointer to an instance of the [sqlite3_mem_methods] structure.
1594** The argument specifies
1595** alternative low-level memory allocation routines to be used in place of
1596** the memory allocation routines built into SQLite.)^ ^SQLite makes
1597** its own private copy of the content of the [sqlite3_mem_methods] structure
1598** before the [sqlite3_config()] call returns.</dd>
1599**
1600** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
1601** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which
1602** is a pointer to an instance of the [sqlite3_mem_methods] structure.
1603** The [sqlite3_mem_methods]
1604** structure is filled with the currently defined memory allocation routines.)^
1605** This option can be used to overload the default memory allocation
1606** routines with a wrapper that simulations memory allocation failure or
1607** tracks memory usage, for example. </dd>
1608**
1609** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
1610** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
1611** interpreted as a boolean, which enables or disables the collection of
1612** memory allocation statistics. ^(When memory allocation statistics are
1613** disabled, the following SQLite interfaces become non-operational:
1614** <ul>
1615** <li> [sqlite3_memory_used()]
1616** <li> [sqlite3_memory_highwater()]
1617** <li> [sqlite3_soft_heap_limit64()]
1618** <li> [sqlite3_status64()]
1619** </ul>)^
1620** ^Memory allocation statistics are enabled by default unless SQLite is
1621** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
1622** allocation statistics are disabled by default.
1623** </dd>
1624**
1625** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
1626** <dd> ^The SQLITE_CONFIG_SCRATCH option specifies a static memory buffer
1627** that SQLite can use for scratch memory. ^(There are three arguments
1628** to SQLITE_CONFIG_SCRATCH: A pointer an 8-byte
1629** aligned memory buffer from which the scratch allocations will be
1630** drawn, the size of each scratch allocation (sz),
1631** and the maximum number of scratch allocations (N).)^
1632** The first argument must be a pointer to an 8-byte aligned buffer
1633** of at least sz*N bytes of memory.
1634** ^SQLite will not use more than one scratch buffers per thread.
1635** ^SQLite will never request a scratch buffer that is more than 6
1636** times the database page size.
1637** ^If SQLite needs needs additional
1638** scratch memory beyond what is provided by this configuration option, then
1639** [sqlite3_malloc()] will be used to obtain the memory needed.<p>
1640** ^When the application provides any amount of scratch memory using
1641** SQLITE_CONFIG_SCRATCH, SQLite avoids unnecessary large
1642** [sqlite3_malloc|heap allocations].
1643** This can help [Robson proof|prevent memory allocation failures] due to heap
1644** fragmentation in low-memory embedded systems.
1645** </dd>
1646**
1647** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
1648** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
1649** that SQLite can use for the database page cache with the default page
1650** cache implementation.
1651** This configuration option is a no-op if an application-define page
1652** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
1653** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
1654** 8-byte aligned memory (pMem), the size of each page cache line (sz),
1655** and the number of cache lines (N).
1656** The sz argument should be the size of the largest database page
1657** (a power of two between 512 and 65536) plus some extra bytes for each
1658** page header. ^The number of extra bytes needed by the page header
1659** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
1660** ^It is harmless, apart from the wasted memory,
1661** for the sz parameter to be larger than necessary. The pMem
1662** argument must be either a NULL pointer or a pointer to an 8-byte
1663** aligned block of memory of at least sz*N bytes, otherwise
1664** subsequent behavior is undefined.
1665** ^When pMem is not NULL, SQLite will strive to use the memory provided
1666** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
1667** a page cache line is larger than sz bytes or if all of the pMem buffer
1668** is exhausted.
1669** ^If pMem is NULL and N is non-zero, then each database connection
1670** does an initial bulk allocation for page cache memory
1671** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
1672** of -1024*N bytes if N is negative, . ^If additional
1673** page cache memory is needed beyond what is provided by the initial
1674** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
1675** additional cache line. </dd>
1676**
1677** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
1678** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer
1679** that SQLite will use for all of its dynamic memory allocation needs
1680** beyond those provided for by [SQLITE_CONFIG_SCRATCH] and
1681** [SQLITE_CONFIG_PAGECACHE].
1682** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
1683** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
1684** [SQLITE_ERROR] if invoked otherwise.
1685** ^There are three arguments to SQLITE_CONFIG_HEAP:
1686** An 8-byte aligned pointer to the memory,
1687** the number of bytes in the memory buffer, and the minimum allocation size.
1688** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
1689** to using its default memory allocator (the system malloc() implementation),
1690** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the
1691** memory pointer is not NULL then the alternative memory
1692** allocator is engaged to handle all of SQLites memory allocation needs.
1693** The first pointer (the memory pointer) must be aligned to an 8-byte
1694** boundary or subsequent behavior of SQLite will be undefined.
1695** The minimum allocation size is capped at 2**12. Reasonable values
1696** for the minimum allocation size are 2**5 through 2**8.</dd>
1697**
1698** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
1699** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
1700** pointer to an instance of the [sqlite3_mutex_methods] structure.
1701** The argument specifies alternative low-level mutex routines to be used
1702** in place the mutex routines built into SQLite.)^ ^SQLite makes a copy of
1703** the content of the [sqlite3_mutex_methods] structure before the call to
1704** [sqlite3_config()] returns. ^If SQLite is compiled with
1705** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1706** the entire mutexing subsystem is omitted from the build and hence calls to
1707** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
1708** return [SQLITE_ERROR].</dd>
1709**
1710** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
1711** <dd> ^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which
1712** is a pointer to an instance of the [sqlite3_mutex_methods] structure. The
1713** [sqlite3_mutex_methods]
1714** structure is filled with the currently defined mutex routines.)^
1715** This option can be used to overload the default mutex allocation
1716** routines with a wrapper used to track mutex usage for performance
1717** profiling or testing, for example. ^If SQLite is compiled with
1718** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1719** the entire mutexing subsystem is omitted from the build and hence calls to
1720** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
1721** return [SQLITE_ERROR].</dd>
1722**
1723** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
1724** <dd> ^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
1725** the default size of lookaside memory on each [database connection].
1726** The first argument is the
1727** size of each lookaside buffer slot and the second is the number of
1728** slots allocated to each database connection.)^ ^(SQLITE_CONFIG_LOOKASIDE
1729** sets the <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
1730** option to [sqlite3_db_config()] can be used to change the lookaside
1731** configuration on individual connections.)^ </dd>
1732**
1733** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
1734** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
1735** a pointer to an [sqlite3_pcache_methods2] object. This object specifies
1736** the interface to a custom page cache implementation.)^
1737** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
1738**
1739** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
1740** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
1741** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of
1742** the current page cache implementation into that object.)^ </dd>
1743**
1744** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
1745** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
1746** global [error log].
1747** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
1748** function with a call signature of void(*)(void*,int,const char*),
1749** and a pointer to void. ^If the function pointer is not NULL, it is
1750** invoked by [sqlite3_log()] to process each logging event. ^If the
1751** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
1752** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
1753** passed through as the first parameter to the application-defined logger
1754** function whenever that function is invoked. ^The second parameter to
1755** the logger function is a copy of the first parameter to the corresponding
1756** [sqlite3_log()] call and is intended to be a [result code] or an
1757** [extended result code]. ^The third parameter passed to the logger is
1758** log message after formatting via [sqlite3_snprintf()].
1759** The SQLite logging interface is not reentrant; the logger function
1760** supplied by the application must not invoke any SQLite interface.
1761** In a multi-threaded application, the application-defined logger
1762** function must be threadsafe. </dd>
1763**
1764** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
1765** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
1766** If non-zero, then URI handling is globally enabled. If the parameter is zero,
1767** then URI handling is globally disabled.)^ ^If URI handling is globally
1768** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
1769** [sqlite3_open16()] or
1770** specified as part of [ATTACH] commands are interpreted as URIs, regardless
1771** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
1772** connection is opened. ^If it is globally disabled, filenames are
1773** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
1774** database connection is opened. ^(By default, URI handling is globally
1775** disabled. The default value may be changed by compiling with the
1776** [SQLITE_USE_URI] symbol defined.)^
1777**
1778** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
1779** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
1780** argument which is interpreted as a boolean in order to enable or disable
1781** the use of covering indices for full table scans in the query optimizer.
1782** ^The default setting is determined
1783** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
1784** if that compile-time option is omitted.
1785** The ability to disable the use of covering indices for full table scans
1786** is because some incorrectly coded legacy applications might malfunction
1787** when the optimization is enabled. Providing the ability to
1788** disable the optimization allows the older, buggy application code to work
1789** without change even with newer versions of SQLite.
1790**
1791** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
1792** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
1793** <dd> These options are obsolete and should not be used by new code.
1794** They are retained for backwards compatibility but are now no-ops.
1795** </dd>
1796**
1797** [[SQLITE_CONFIG_SQLLOG]]
1798** <dt>SQLITE_CONFIG_SQLLOG
1799** <dd>This option is only available if sqlite is compiled with the
1800** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
1801** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
1802** The second should be of type (void*). The callback is invoked by the library
1803** in three separate circumstances, identified by the value passed as the
1804** fourth parameter. If the fourth parameter is 0, then the database connection
1805** passed as the second argument has just been opened. The third argument
1806** points to a buffer containing the name of the main database file. If the
1807** fourth parameter is 1, then the SQL statement that the third parameter
1808** points to has just been executed. Or, if the fourth parameter is 2, then
1809** the connection being passed as the second parameter is being closed. The
1810** third parameter is passed NULL In this case. An example of using this
1811** configuration option can be seen in the "test_sqllog.c" source file in
1812** the canonical SQLite source tree.</dd>
1813**
1814** [[SQLITE_CONFIG_MMAP_SIZE]]
1815** <dt>SQLITE_CONFIG_MMAP_SIZE
1816** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
1817** that are the default mmap size limit (the default setting for
1818** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
1819** ^The default setting can be overridden by each database connection using
1820** either the [PRAGMA mmap_size] command, or by using the
1821** [SQLITE_FCNTL_MMAP_SIZE] file control. ^(The maximum allowed mmap size
1822** will be silently truncated if necessary so that it does not exceed the
1823** compile-time maximum mmap size set by the
1824** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
1825** ^If either argument to this option is negative, then that argument is
1826** changed to its compile-time default.
1827**
1828** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
1829** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
1830** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
1831** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
1832** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
1833** that specifies the maximum size of the created heap.
1834**
1835** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
1836** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
1837** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
1838** is a pointer to an integer and writes into that integer the number of extra
1839** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].
1840** The amount of extra space required can change depending on the compiler,
1841** target platform, and SQLite version.
1842**
1843** [[SQLITE_CONFIG_PMASZ]]
1844** <dt>SQLITE_CONFIG_PMASZ
1845** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which
1846** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
1847** sorter to that integer. The default minimum PMA Size is set by the
1848** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched
1849** to help with sort operations when multithreaded sorting
1850** is enabled (using the [PRAGMA threads] command) and the amount of content
1851** to be sorted exceeds the page size times the minimum of the
1852** [PRAGMA cache_size] setting and this value.
1853**
1854** [[SQLITE_CONFIG_STMTJRNL_SPILL]]
1855** <dt>SQLITE_CONFIG_STMTJRNL_SPILL
1856** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
1857** becomes the [statement journal] spill-to-disk threshold.
1858** [Statement journals] are held in memory until their size (in bytes)
1859** exceeds this threshold, at which point they are written to disk.
1860** Or if the threshold is -1, statement journals are always held
1861** exclusively in memory.
1862** Since many statement journals never become large, setting the spill
1863** threshold to a value such as 64KiB can greatly reduce the amount of
1864** I/O required to support statement rollback.
1865** The default value for this setting is controlled by the
1866** [SQLITE_STMTJRNL_SPILL] compile-time option.
1867** </dl>
1868*/
1869#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
1870#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
1871#define SQLITE_CONFIG_SERIALIZED 3 /* nil */
1872#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
1873#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
1874#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */
1875#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
1876#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
1877#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
1878#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
1879#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
1880/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
1881#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
1882#define SQLITE_CONFIG_PCACHE 14 /* no-op */
1883#define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
1884#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
1885#define SQLITE_CONFIG_URI 17 /* int */
1886#define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
1887#define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
1888#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
1889#define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
1890#define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
1891#define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
1892#define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
1893#define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
1894#define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
1895
1896/*
1897** CAPI3REF: Database Connection Configuration Options
1898**
1899** These constants are the available integer configuration options that
1900** can be passed as the second argument to the [sqlite3_db_config()] interface.
1901**
1902** New configuration options may be added in future releases of SQLite.
1903** Existing configuration options might be discontinued. Applications
1904** should check the return code from [sqlite3_db_config()] to make sure that
1905** the call worked. ^The [sqlite3_db_config()] interface will return a
1906** non-zero [error code] if a discontinued or unsupported configuration option
1907** is invoked.
1908**
1909** <dl>
1910** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
1911** <dd> ^This option takes three additional arguments that determine the
1912** [lookaside memory allocator] configuration for the [database connection].
1913** ^The first argument (the third parameter to [sqlite3_db_config()] is a
1914** pointer to a memory buffer to use for lookaside memory.
1915** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
1916** may be NULL in which case SQLite will allocate the
1917** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
1918** size of each lookaside buffer slot. ^The third argument is the number of
1919** slots. The size of the buffer in the first argument must be greater than
1920** or equal to the product of the second and third arguments. The buffer
1921** must be aligned to an 8-byte boundary. ^If the second argument to
1922** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
1923** rounded down to the next smaller multiple of 8. ^(The lookaside memory
1924** configuration for a database connection can only be changed when that
1925** connection is not currently using lookaside memory, or in other words
1926** when the "current value" returned by
1927** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
1928** Any attempt to change the lookaside memory configuration when lookaside
1929** memory is in use leaves the configuration unchanged and returns
1930** [SQLITE_BUSY].)^</dd>
1931**
1932** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
1933** <dd> ^This option is used to enable or disable the enforcement of
1934** [foreign key constraints]. There should be two additional arguments.
1935** The first argument is an integer which is 0 to disable FK enforcement,
1936** positive to enable FK enforcement or negative to leave FK enforcement
1937** unchanged. The second parameter is a pointer to an integer into which
1938** is written 0 or 1 to indicate whether FK enforcement is off or on
1939** following this call. The second parameter may be a NULL pointer, in
1940** which case the FK enforcement setting is not reported back. </dd>
1941**
1942** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
1943** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
1944** There should be two additional arguments.
1945** The first argument is an integer which is 0 to disable triggers,
1946** positive to enable triggers or negative to leave the setting unchanged.
1947** The second parameter is a pointer to an integer into which
1948** is written 0 or 1 to indicate whether triggers are disabled or enabled
1949** following this call. The second parameter may be a NULL pointer, in
1950** which case the trigger setting is not reported back. </dd>
1951**
1952** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
1953** <dd> ^This option is used to enable or disable the two-argument
1954** version of the [fts3_tokenizer()] function which is part of the
1955** [FTS3] full-text search engine extension.
1956** There should be two additional arguments.
1957** The first argument is an integer which is 0 to disable fts3_tokenizer() or
1958** positive to enable fts3_tokenizer() or negative to leave the setting
1959** unchanged.
1960** The second parameter is a pointer to an integer into which
1961** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
1962** following this call. The second parameter may be a NULL pointer, in
1963** which case the new setting is not reported back. </dd>
1964**
1965** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt>
1966** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
1967** interface independently of the [load_extension()] SQL function.
1968** The [sqlite3_enable_load_extension()] API enables or disables both the
1969** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].
1970** There should be two additional arguments.
1971** When the first argument to this interface is 1, then only the C-API is
1972** enabled and the SQL function remains disabled. If the first argument to
1973** this interface is 0, then both the C-API and the SQL function are disabled.
1974** If the first argument is -1, then no changes are made to state of either the
1975** C-API or the SQL function.
1976** The second parameter is a pointer to an integer into which
1977** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface
1978** is disabled or enabled following this call. The second parameter may
1979** be a NULL pointer, in which case the new setting is not reported back.
1980** </dd>
1981**
1982** <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>
1983** <dd> ^This option is used to change the name of the "main" database
1984** schema. ^The sole argument is a pointer to a constant UTF8 string
1985** which will become the new schema name in place of "main". ^SQLite
1986** does not make a copy of the new main schema name string, so the application
1987** must ensure that the argument passed into this DBCONFIG option is unchanged
1988** until after the database connection closes.
1989** </dd>
1990**
1991** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>
1992** <dd> Usually, when a database in wal mode is closed or detached from a
1993** database handle, SQLite checks if this will mean that there are now no
1994** connections at all to the database. If so, it performs a checkpoint
1995** operation before closing the connection. This option may be used to
1996** override this behaviour. The first parameter passed to this operation
1997** is an integer - non-zero to disable checkpoints-on-close, or zero (the
1998** default) to enable them. The second parameter is a pointer to an integer
1999** into which is written 0 or 1 to indicate whether checkpoints-on-close
2000** have been disabled - 0 if they are not disabled, 1 if they are.
2001** </dd>
2002**
2003** </dl>
2004*/
2005#define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */
2006#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
2007#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
2008#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
2009#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
2010#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
2011#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */
2012
2013
2014/*
2015** CAPI3REF: Enable Or Disable Extended Result Codes
2016** METHOD: sqlite3
2017**
2018** ^The sqlite3_extended_result_codes() routine enables or disables the
2019** [extended result codes] feature of SQLite. ^The extended result
2020** codes are disabled by default for historical compatibility.
2021*/
2022SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
2023
2024/*
2025** CAPI3REF: Last Insert Rowid
2026** METHOD: sqlite3
2027**
2028** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
2029** has a unique 64-bit signed
2030** integer key called the [ROWID | "rowid"]. ^The rowid is always available
2031** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
2032** names are not also used by explicitly declared columns. ^If
2033** the table has a column of type [INTEGER PRIMARY KEY] then that column
2034** is another alias for the rowid.
2035**
2036** ^The sqlite3_last_insert_rowid(D) interface returns the [rowid] of the
2037** most recent successful [INSERT] into a rowid table or [virtual table]
2038** on database connection D.
2039** ^Inserts into [WITHOUT ROWID] tables are not recorded.
2040** ^If no successful [INSERT]s into rowid tables
2041** have ever occurred on the database connection D,
2042** then sqlite3_last_insert_rowid(D) returns zero.
2043**
2044** ^(If an [INSERT] occurs within a trigger or within a [virtual table]
2045** method, then this routine will return the [rowid] of the inserted
2046** row as long as the trigger or virtual table method is running.
2047** But once the trigger or virtual table method ends, the value returned
2048** by this routine reverts to what it was before the trigger or virtual
2049** table method began.)^
2050**
2051** ^An [INSERT] that fails due to a constraint violation is not a
2052** successful [INSERT] and does not change the value returned by this
2053** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
2054** and INSERT OR ABORT make no changes to the return value of this
2055** routine when their insertion fails. ^(When INSERT OR REPLACE
2056** encounters a constraint violation, it does not fail. The
2057** INSERT continues to completion after deleting rows that caused
2058** the constraint problem so INSERT OR REPLACE will always change
2059** the return value of this interface.)^
2060**
2061** ^For the purposes of this routine, an [INSERT] is considered to
2062** be successful even if it is subsequently rolled back.
2063**
2064** This function is accessible to SQL statements via the
2065** [last_insert_rowid() SQL function].
2066**
2067** If a separate thread performs a new [INSERT] on the same
2068** database connection while the [sqlite3_last_insert_rowid()]
2069** function is running and thus changes the last insert [rowid],
2070** then the value returned by [sqlite3_last_insert_rowid()] is
2071** unpredictable and might not equal either the old or the new
2072** last insert [rowid].
2073*/
2074SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
2075
2076/*
2077** CAPI3REF: Count The Number Of Rows Modified
2078** METHOD: sqlite3
2079**
2080** ^This function returns the number of rows modified, inserted or
2081** deleted by the most recently completed INSERT, UPDATE or DELETE
2082** statement on the database connection specified by the only parameter.
2083** ^Executing any other type of SQL statement does not modify the value
2084** returned by this function.
2085**
2086** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
2087** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
2088** [foreign key actions] or [REPLACE] constraint resolution are not counted.
2089**
2090** Changes to a view that are intercepted by
2091** [INSTEAD OF trigger | INSTEAD OF triggers] are not counted. ^The value
2092** returned by sqlite3_changes() immediately after an INSERT, UPDATE or
2093** DELETE statement run on a view is always zero. Only changes made to real
2094** tables are counted.
2095**
2096** Things are more complicated if the sqlite3_changes() function is
2097** executed while a trigger program is running. This may happen if the
2098** program uses the [changes() SQL function], or if some other callback
2099** function invokes sqlite3_changes() directly. Essentially:
2100**
2101** <ul>
2102** <li> ^(Before entering a trigger program the value returned by
2103** sqlite3_changes() function is saved. After the trigger program
2104** has finished, the original value is restored.)^
2105**
2106** <li> ^(Within a trigger program each INSERT, UPDATE and DELETE
2107** statement sets the value returned by sqlite3_changes()
2108** upon completion as normal. Of course, this value will not include
2109** any changes performed by sub-triggers, as the sqlite3_changes()
2110** value will be saved and restored after each sub-trigger has run.)^
2111** </ul>
2112**
2113** ^This means that if the changes() SQL function (or similar) is used
2114** by the first INSERT, UPDATE or DELETE statement within a trigger, it
2115** returns the value as set when the calling statement began executing.
2116** ^If it is used by the second or subsequent such statement within a trigger
2117** program, the value returned reflects the number of rows modified by the
2118** previous INSERT, UPDATE or DELETE statement within the same trigger.
2119**
2120** See also the [sqlite3_total_changes()] interface, the
2121** [count_changes pragma], and the [changes() SQL function].
2122**
2123** If a separate thread makes changes on the same database connection
2124** while [sqlite3_changes()] is running then the value returned
2125** is unpredictable and not meaningful.
2126*/
2127SQLITE_API int sqlite3_changes(sqlite3*);
2128
2129/*
2130** CAPI3REF: Total Number Of Rows Modified
2131** METHOD: sqlite3
2132**
2133** ^This function returns the total number of rows inserted, modified or
2134** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed
2135** since the database connection was opened, including those executed as
2136** part of trigger programs. ^Executing any other type of SQL statement
2137** does not affect the value returned by sqlite3_total_changes().
2138**
2139** ^Changes made as part of [foreign key actions] are included in the
2140** count, but those made as part of REPLACE constraint resolution are
2141** not. ^Changes to a view that are intercepted by INSTEAD OF triggers
2142** are not counted.
2143**
2144** See also the [sqlite3_changes()] interface, the
2145** [count_changes pragma], and the [total_changes() SQL function].
2146**
2147** If a separate thread makes changes on the same database connection
2148** while [sqlite3_total_changes()] is running then the value
2149** returned is unpredictable and not meaningful.
2150*/
2151SQLITE_API int sqlite3_total_changes(sqlite3*);
2152
2153/*
2154** CAPI3REF: Interrupt A Long-Running Query
2155** METHOD: sqlite3
2156**
2157** ^This function causes any pending database operation to abort and
2158** return at its earliest opportunity. This routine is typically
2159** called in response to a user action such as pressing "Cancel"
2160** or Ctrl-C where the user wants a long query operation to halt
2161** immediately.
2162**
2163** ^It is safe to call this routine from a thread different from the
2164** thread that is currently running the database operation. But it
2165** is not safe to call this routine with a [database connection] that
2166** is closed or might close before sqlite3_interrupt() returns.
2167**
2168** ^If an SQL operation is very nearly finished at the time when
2169** sqlite3_interrupt() is called, then it might not have an opportunity
2170** to be interrupted and might continue to completion.
2171**
2172** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
2173** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
2174** that is inside an explicit transaction, then the entire transaction
2175** will be rolled back automatically.
2176**
2177** ^The sqlite3_interrupt(D) call is in effect until all currently running
2178** SQL statements on [database connection] D complete. ^Any new SQL statements
2179** that are started after the sqlite3_interrupt() call and before the
2180** running statements reaches zero are interrupted as if they had been
2181** running prior to the sqlite3_interrupt() call. ^New SQL statements
2182** that are started after the running statement count reaches zero are
2183** not effected by the sqlite3_interrupt().
2184** ^A call to sqlite3_interrupt(D) that occurs when there are no running
2185** SQL statements is a no-op and has no effect on SQL statements
2186** that are started after the sqlite3_interrupt() call returns.
2187**
2188** If the database connection closes while [sqlite3_interrupt()]
2189** is running then bad things will likely happen.
2190*/
2191SQLITE_API void sqlite3_interrupt(sqlite3*);
2192
2193/*
2194** CAPI3REF: Determine If An SQL Statement Is Complete
2195**
2196** These routines are useful during command-line input to determine if the
2197** currently entered text seems to form a complete SQL statement or
2198** if additional input is needed before sending the text into
2199** SQLite for parsing. ^These routines return 1 if the input string
2200** appears to be a complete SQL statement. ^A statement is judged to be
2201** complete if it ends with a semicolon token and is not a prefix of a
2202** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within
2203** string literals or quoted identifier names or comments are not
2204** independent tokens (they are part of the token in which they are
2205** embedded) and thus do not count as a statement terminator. ^Whitespace
2206** and comments that follow the final semicolon are ignored.
2207**
2208** ^These routines return 0 if the statement is incomplete. ^If a
2209** memory allocation fails, then SQLITE_NOMEM is returned.
2210**
2211** ^These routines do not parse the SQL statements thus
2212** will not detect syntactically incorrect SQL.
2213**
2214** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior
2215** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
2216** automatically by sqlite3_complete16(). If that initialization fails,
2217** then the return value from sqlite3_complete16() will be non-zero
2218** regardless of whether or not the input SQL is complete.)^
2219**
2220** The input to [sqlite3_complete()] must be a zero-terminated
2221** UTF-8 string.
2222**
2223** The input to [sqlite3_complete16()] must be a zero-terminated
2224** UTF-16 string in native byte order.
2225*/
2226SQLITE_API int sqlite3_complete(const char *sql);
2227SQLITE_API int sqlite3_complete16(const void *sql);
2228
2229/*
2230** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
2231** KEYWORDS: {busy-handler callback} {busy handler}
2232** METHOD: sqlite3
2233**
2234** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
2235** that might be invoked with argument P whenever
2236** an attempt is made to access a database table associated with
2237** [database connection] D when another thread
2238** or process has the table locked.
2239** The sqlite3_busy_handler() interface is used to implement
2240** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
2241**
2242** ^If the busy callback is NULL, then [SQLITE_BUSY]
2243** is returned immediately upon encountering the lock. ^If the busy callback
2244** is not NULL, then the callback might be invoked with two arguments.
2245**
2246** ^The first argument to the busy handler is a copy of the void* pointer which
2247** is the third argument to sqlite3_busy_handler(). ^The second argument to
2248** the busy handler callback is the number of times that the busy handler has
2249** been invoked previously for the same locking event. ^If the
2250** busy callback returns 0, then no additional attempts are made to
2251** access the database and [SQLITE_BUSY] is returned
2252** to the application.
2253** ^If the callback returns non-zero, then another attempt
2254** is made to access the database and the cycle repeats.
2255**
2256** The presence of a busy handler does not guarantee that it will be invoked
2257** when there is lock contention. ^If SQLite determines that invoking the busy
2258** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
2259** to the application instead of invoking the
2260** busy handler.
2261** Consider a scenario where one process is holding a read lock that
2262** it is trying to promote to a reserved lock and
2263** a second process is holding a reserved lock that it is trying
2264** to promote to an exclusive lock. The first process cannot proceed
2265** because it is blocked by the second and the second process cannot
2266** proceed because it is blocked by the first. If both processes
2267** invoke the busy handlers, neither will make any progress. Therefore,
2268** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
2269** will induce the first process to release its read lock and allow
2270** the second process to proceed.
2271**
2272** ^The default busy callback is NULL.
2273**
2274** ^(There can only be a single busy handler defined for each
2275** [database connection]. Setting a new busy handler clears any
2276** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
2277** or evaluating [PRAGMA busy_timeout=N] will change the
2278** busy handler and thus clear any previously set busy handler.
2279**
2280** The busy callback should not take any actions which modify the
2281** database connection that invoked the busy handler. In other words,
2282** the busy handler is not reentrant. Any such actions
2283** result in undefined behavior.
2284**
2285** A busy handler must not close the database connection
2286** or [prepared statement] that invoked the busy handler.
2287*/
2288SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);
2289
2290/*
2291** CAPI3REF: Set A Busy Timeout
2292** METHOD: sqlite3
2293**
2294** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
2295** for a specified amount of time when a table is locked. ^The handler
2296** will sleep multiple times until at least "ms" milliseconds of sleeping
2297** have accumulated. ^After at least "ms" milliseconds of sleeping,
2298** the handler returns 0 which causes [sqlite3_step()] to return
2299** [SQLITE_BUSY].
2300**
2301** ^Calling this routine with an argument less than or equal to zero
2302** turns off all busy handlers.
2303**
2304** ^(There can only be a single busy handler for a particular
2305** [database connection] at any given moment. If another busy handler
2306** was defined (using [sqlite3_busy_handler()]) prior to calling
2307** this routine, that other busy handler is cleared.)^
2308**
2309** See also: [PRAGMA busy_timeout]
2310*/
2311SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
2312
2313/*
2314** CAPI3REF: Convenience Routines For Running Queries
2315** METHOD: sqlite3
2316**
2317** This is a legacy interface that is preserved for backwards compatibility.
2318** Use of this interface is not recommended.
2319**
2320** Definition: A <b>result table</b> is memory data structure created by the
2321** [sqlite3_get_table()] interface. A result table records the
2322** complete query results from one or more queries.
2323**
2324** The table conceptually has a number of rows and columns. But
2325** these numbers are not part of the result table itself. These
2326** numbers are obtained separately. Let N be the number of rows
2327** and M be the number of columns.
2328**
2329** A result table is an array of pointers to zero-terminated UTF-8 strings.
2330** There are (N+1)*M elements in the array. The first M pointers point
2331** to zero-terminated strings that contain the names of the columns.
2332** The remaining entries all point to query results. NULL values result
2333** in NULL pointers. All other values are in their UTF-8 zero-terminated
2334** string representation as returned by [sqlite3_column_text()].
2335**
2336** A result table might consist of one or more memory allocations.
2337** It is not safe to pass a result table directly to [sqlite3_free()].
2338** A result table should be deallocated using [sqlite3_free_table()].
2339**
2340** ^(As an example of the result table format, suppose a query result
2341** is as follows:
2342**
2343** <blockquote><pre>
2344** Name | Age
2345** -----------------------
2346** Alice | 43
2347** Bob | 28
2348** Cindy | 21
2349** </pre></blockquote>
2350**
2351** There are two column (M==2) and three rows (N==3). Thus the
2352** result table has 8 entries. Suppose the result table is stored
2353** in an array names azResult. Then azResult holds this content:
2354**
2355** <blockquote><pre>
2356** azResult[0] = "Name";
2357** azResult[1] = "Age";
2358** azResult[2] = "Alice";
2359** azResult[3] = "43";
2360** azResult[4] = "Bob";
2361** azResult[5] = "28";
2362** azResult[6] = "Cindy";
2363** azResult[7] = "21";
2364** </pre></blockquote>)^
2365**
2366** ^The sqlite3_get_table() function evaluates one or more
2367** semicolon-separated SQL statements in the zero-terminated UTF-8
2368** string of its 2nd parameter and returns a result table to the
2369** pointer given in its 3rd parameter.
2370**
2371** After the application has finished with the result from sqlite3_get_table(),
2372** it must pass the result table pointer to sqlite3_free_table() in order to
2373** release the memory that was malloced. Because of the way the
2374** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
2375** function must not try to call [sqlite3_free()] directly. Only
2376** [sqlite3_free_table()] is able to release the memory properly and safely.
2377**
2378** The sqlite3_get_table() interface is implemented as a wrapper around
2379** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
2380** to any internal data structures of SQLite. It uses only the public
2381** interface defined here. As a consequence, errors that occur in the
2382** wrapper layer outside of the internal [sqlite3_exec()] call are not
2383** reflected in subsequent calls to [sqlite3_errcode()] or
2384** [sqlite3_errmsg()].
2385*/
2386SQLITE_API int sqlite3_get_table(
2387 sqlite3 *db, /* An open database */
2388 const char *zSql, /* SQL to be evaluated */
2389 char ***pazResult, /* Results of the query */
2390 int *pnRow, /* Number of result rows written here */
2391 int *pnColumn, /* Number of result columns written here */
2392 char **pzErrmsg /* Error msg written here */
2393);
2394SQLITE_API void sqlite3_free_table(char **result);
2395
2396/*
2397** CAPI3REF: Formatted String Printing Functions
2398**
2399** These routines are work-alikes of the "printf()" family of functions
2400** from the standard C library.
2401** These routines understand most of the common K&R formatting options,
2402** plus some additional non-standard formats, detailed below.
2403** Note that some of the more obscure formatting options from recent
2404** C-library standards are omitted from this implementation.
2405**
2406** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
2407** results into memory obtained from [sqlite3_malloc()].
2408** The strings returned by these two routines should be
2409** released by [sqlite3_free()]. ^Both routines return a
2410** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
2411** memory to hold the resulting string.
2412**
2413** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
2414** the standard C library. The result is written into the
2415** buffer supplied as the second parameter whose size is given by
2416** the first parameter. Note that the order of the
2417** first two parameters is reversed from snprintf().)^ This is an
2418** historical accident that cannot be fixed without breaking
2419** backwards compatibility. ^(Note also that sqlite3_snprintf()
2420** returns a pointer to its buffer instead of the number of
2421** characters actually written into the buffer.)^ We admit that
2422** the number of characters written would be a more useful return
2423** value but we cannot change the implementation of sqlite3_snprintf()
2424** now without breaking compatibility.
2425**
2426** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
2427** guarantees that the buffer is always zero-terminated. ^The first
2428** parameter "n" is the total size of the buffer, including space for
2429** the zero terminator. So the longest string that can be completely
2430** written will be n-1 characters.
2431**
2432** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
2433**
2434** These routines all implement some additional formatting
2435** options that are useful for constructing SQL statements.
2436** All of the usual printf() formatting options apply. In addition, there
2437** is are "%q", "%Q", "%w" and "%z" options.
2438**
2439** ^(The %q option works like %s in that it substitutes a nul-terminated
2440** string from the argument list. But %q also doubles every '\'' character.
2441** %q is designed for use inside a string literal.)^ By doubling each '\''
2442** character it escapes that character and allows it to be inserted into
2443** the string.
2444**
2445** For example, assume the string variable zText contains text as follows:
2446**
2447** <blockquote><pre>
2448** char *zText = "It's a happy day!";
2449** </pre></blockquote>
2450**
2451** One can use this text in an SQL statement as follows:
2452**
2453** <blockquote><pre>
2454** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
2455** sqlite3_exec(db, zSQL, 0, 0, 0);
2456** sqlite3_free(zSQL);
2457** </pre></blockquote>
2458**
2459** Because the %q format string is used, the '\'' character in zText
2460** is escaped and the SQL generated is as follows:
2461**
2462** <blockquote><pre>
2463** INSERT INTO table1 VALUES('It''s a happy day!')
2464** </pre></blockquote>
2465**
2466** This is correct. Had we used %s instead of %q, the generated SQL
2467** would have looked like this:
2468**
2469** <blockquote><pre>
2470** INSERT INTO table1 VALUES('It's a happy day!');
2471** </pre></blockquote>
2472**
2473** This second example is an SQL syntax error. As a general rule you should
2474** always use %q instead of %s when inserting text into a string literal.
2475**
2476** ^(The %Q option works like %q except it also adds single quotes around
2477** the outside of the total string. Additionally, if the parameter in the
2478** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
2479** single quotes).)^ So, for example, one could say:
2480**
2481** <blockquote><pre>
2482** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
2483** sqlite3_exec(db, zSQL, 0, 0, 0);
2484** sqlite3_free(zSQL);
2485** </pre></blockquote>
2486**
2487** The code above will render a correct SQL statement in the zSQL
2488** variable even if the zText variable is a NULL pointer.
2489**
2490** ^(The "%w" formatting option is like "%q" except that it expects to
2491** be contained within double-quotes instead of single quotes, and it
2492** escapes the double-quote character instead of the single-quote
2493** character.)^ The "%w" formatting option is intended for safely inserting
2494** table and column names into a constructed SQL statement.
2495**
2496** ^(The "%z" formatting option works like "%s" but with the
2497** addition that after the string has been read and copied into
2498** the result, [sqlite3_free()] is called on the input string.)^
2499*/
2500SQLITE_API char *sqlite3_mprintf(const char*,...);
2501SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
2502SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
2503SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
2504
2505/*
2506** CAPI3REF: Memory Allocation Subsystem
2507**
2508** The SQLite core uses these three routines for all of its own
2509** internal memory allocation needs. "Core" in the previous sentence
2510** does not include operating-system specific VFS implementation. The
2511** Windows VFS uses native malloc() and free() for some operations.
2512**
2513** ^The sqlite3_malloc() routine returns a pointer to a block
2514** of memory at least N bytes in length, where N is the parameter.
2515** ^If sqlite3_malloc() is unable to obtain sufficient free
2516** memory, it returns a NULL pointer. ^If the parameter N to
2517** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
2518** a NULL pointer.
2519**
2520** ^The sqlite3_malloc64(N) routine works just like
2521** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
2522** of a signed 32-bit integer.
2523**
2524** ^Calling sqlite3_free() with a pointer previously returned
2525** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
2526** that it might be reused. ^The sqlite3_free() routine is
2527** a no-op if is called with a NULL pointer. Passing a NULL pointer
2528** to sqlite3_free() is harmless. After being freed, memory
2529** should neither be read nor written. Even reading previously freed
2530** memory might result in a segmentation fault or other severe error.
2531** Memory corruption, a segmentation fault, or other severe error
2532** might result if sqlite3_free() is called with a non-NULL pointer that
2533** was not obtained from sqlite3_malloc() or sqlite3_realloc().
2534**
2535** ^The sqlite3_realloc(X,N) interface attempts to resize a
2536** prior memory allocation X to be at least N bytes.
2537** ^If the X parameter to sqlite3_realloc(X,N)
2538** is a NULL pointer then its behavior is identical to calling
2539** sqlite3_malloc(N).
2540** ^If the N parameter to sqlite3_realloc(X,N) is zero or
2541** negative then the behavior is exactly the same as calling
2542** sqlite3_free(X).
2543** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
2544** of at least N bytes in size or NULL if insufficient memory is available.
2545** ^If M is the size of the prior allocation, then min(N,M) bytes
2546** of the prior allocation are copied into the beginning of buffer returned
2547** by sqlite3_realloc(X,N) and the prior allocation is freed.
2548** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
2549** prior allocation is not freed.
2550**
2551** ^The sqlite3_realloc64(X,N) interfaces works the same as
2552** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
2553** of a 32-bit signed integer.
2554**
2555** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
2556** sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
2557** sqlite3_msize(X) returns the size of that memory allocation in bytes.
2558** ^The value returned by sqlite3_msize(X) might be larger than the number
2559** of bytes requested when X was allocated. ^If X is a NULL pointer then
2560** sqlite3_msize(X) returns zero. If X points to something that is not
2561** the beginning of memory allocation, or if it points to a formerly
2562** valid memory allocation that has now been freed, then the behavior
2563** of sqlite3_msize(X) is undefined and possibly harmful.
2564**
2565** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(),
2566** sqlite3_malloc64(), and sqlite3_realloc64()
2567** is always aligned to at least an 8 byte boundary, or to a
2568** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
2569** option is used.
2570**
2571** In SQLite version 3.5.0 and 3.5.1, it was possible to define
2572** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
2573** implementation of these routines to be omitted. That capability
2574** is no longer provided. Only built-in memory allocators can be used.
2575**
2576** Prior to SQLite version 3.7.10, the Windows OS interface layer called
2577** the system malloc() and free() directly when converting
2578** filenames between the UTF-8 encoding used by SQLite
2579** and whatever filename encoding is used by the particular Windows
2580** installation. Memory allocation errors were detected, but
2581** they were reported back as [SQLITE_CANTOPEN] or
2582** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
2583**
2584** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
2585** must be either NULL or else pointers obtained from a prior
2586** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
2587** not yet been released.
2588**
2589** The application must not read or write any part of
2590** a block of memory after it has been released using
2591** [sqlite3_free()] or [sqlite3_realloc()].
2592*/
2593SQLITE_API void *sqlite3_malloc(int);
2594SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);
2595SQLITE_API void *sqlite3_realloc(void*, int);
2596SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64);
2597SQLITE_API void sqlite3_free(void*);
2598SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
2599
2600/*
2601** CAPI3REF: Memory Allocator Statistics
2602**
2603** SQLite provides these two interfaces for reporting on the status
2604** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
2605** routines, which form the built-in memory allocation subsystem.
2606**
2607** ^The [sqlite3_memory_used()] routine returns the number of bytes
2608** of memory currently outstanding (malloced but not freed).
2609** ^The [sqlite3_memory_highwater()] routine returns the maximum
2610** value of [sqlite3_memory_used()] since the high-water mark
2611** was last reset. ^The values returned by [sqlite3_memory_used()] and
2612** [sqlite3_memory_highwater()] include any overhead
2613** added by SQLite in its implementation of [sqlite3_malloc()],
2614** but not overhead added by the any underlying system library
2615** routines that [sqlite3_malloc()] may call.
2616**
2617** ^The memory high-water mark is reset to the current value of
2618** [sqlite3_memory_used()] if and only if the parameter to
2619** [sqlite3_memory_highwater()] is true. ^The value returned
2620** by [sqlite3_memory_highwater(1)] is the high-water mark
2621** prior to the reset.
2622*/
2623SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
2624SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
2625
2626/*
2627** CAPI3REF: Pseudo-Random Number Generator
2628**
2629** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
2630** select random [ROWID | ROWIDs] when inserting new records into a table that
2631** already uses the largest possible [ROWID]. The PRNG is also used for
2632** the build-in random() and randomblob() SQL functions. This interface allows
2633** applications to access the same PRNG for other purposes.
2634**
2635** ^A call to this routine stores N bytes of randomness into buffer P.
2636** ^The P parameter can be a NULL pointer.
2637**
2638** ^If this routine has not been previously called or if the previous
2639** call had N less than one or a NULL pointer for P, then the PRNG is
2640** seeded using randomness obtained from the xRandomness method of
2641** the default [sqlite3_vfs] object.
2642** ^If the previous call to this routine had an N of 1 or more and a
2643** non-NULL P then the pseudo-randomness is generated
2644** internally and without recourse to the [sqlite3_vfs] xRandomness
2645** method.
2646*/
2647SQLITE_API void sqlite3_randomness(int N, void *P);
2648
2649/*
2650** CAPI3REF: Compile-Time Authorization Callbacks
2651** METHOD: sqlite3
2652**
2653** ^This routine registers an authorizer callback with a particular
2654** [database connection], supplied in the first argument.
2655** ^The authorizer callback is invoked as SQL statements are being compiled
2656** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
2657** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. ^At various
2658** points during the compilation process, as logic is being created
2659** to perform various actions, the authorizer callback is invoked to
2660** see if those actions are allowed. ^The authorizer callback should
2661** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
2662** specific action but allow the SQL statement to continue to be
2663** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
2664** rejected with an error. ^If the authorizer callback returns
2665** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
2666** then the [sqlite3_prepare_v2()] or equivalent call that triggered
2667** the authorizer will fail with an error message.
2668**
2669** When the callback returns [SQLITE_OK], that means the operation
2670** requested is ok. ^When the callback returns [SQLITE_DENY], the
2671** [sqlite3_prepare_v2()] or equivalent call that triggered the
2672** authorizer will fail with an error message explaining that
2673** access is denied.
2674**
2675** ^The first parameter to the authorizer callback is a copy of the third
2676** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
2677** to the callback is an integer [SQLITE_COPY | action code] that specifies
2678** the particular action to be authorized. ^The third through sixth parameters
2679** to the callback are zero-terminated strings that contain additional
2680** details about the action to be authorized.
2681**
2682** ^If the action code is [SQLITE_READ]
2683** and the callback returns [SQLITE_IGNORE] then the
2684** [prepared statement] statement is constructed to substitute
2685** a NULL value in place of the table column that would have
2686** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
2687** return can be used to deny an untrusted user access to individual
2688** columns of a table.
2689** ^If the action code is [SQLITE_DELETE] and the callback returns
2690** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
2691** [truncate optimization] is disabled and all rows are deleted individually.
2692**
2693** An authorizer is used when [sqlite3_prepare | preparing]
2694** SQL statements from an untrusted source, to ensure that the SQL statements
2695** do not try to access data they are not allowed to see, or that they do not
2696** try to execute malicious statements that damage the database. For
2697** example, an application may allow a user to enter arbitrary
2698** SQL queries for evaluation by a database. But the application does
2699** not want the user to be able to make arbitrary changes to the
2700** database. An authorizer could then be put in place while the
2701** user-entered SQL is being [sqlite3_prepare | prepared] that
2702** disallows everything except [SELECT] statements.
2703**
2704** Applications that need to process SQL from untrusted sources
2705** might also consider lowering resource limits using [sqlite3_limit()]
2706** and limiting database size using the [max_page_count] [PRAGMA]
2707** in addition to using an authorizer.
2708**
2709** ^(Only a single authorizer can be in place on a database connection
2710** at a time. Each call to sqlite3_set_authorizer overrides the
2711** previous call.)^ ^Disable the authorizer by installing a NULL callback.
2712** The authorizer is disabled by default.
2713**
2714** The authorizer callback must not do anything that will modify
2715** the database connection that invoked the authorizer callback.
2716** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
2717** database connections for the meaning of "modify" in this paragraph.
2718**
2719** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
2720** statement might be re-prepared during [sqlite3_step()] due to a
2721** schema change. Hence, the application should ensure that the
2722** correct authorizer callback remains in place during the [sqlite3_step()].
2723**
2724** ^Note that the authorizer callback is invoked only during
2725** [sqlite3_prepare()] or its variants. Authorization is not
2726** performed during statement evaluation in [sqlite3_step()], unless
2727** as stated in the previous paragraph, sqlite3_step() invokes
2728** sqlite3_prepare_v2() to reprepare a statement after a schema change.
2729*/
2730SQLITE_API int sqlite3_set_authorizer(
2731 sqlite3*,
2732 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
2733 void *pUserData
2734);
2735
2736/*
2737** CAPI3REF: Authorizer Return Codes
2738**
2739** The [sqlite3_set_authorizer | authorizer callback function] must
2740** return either [SQLITE_OK] or one of these two constants in order
2741** to signal SQLite whether or not the action is permitted. See the
2742** [sqlite3_set_authorizer | authorizer documentation] for additional
2743** information.
2744**
2745** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
2746** returned from the [sqlite3_vtab_on_conflict()] interface.
2747*/
2748#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
2749#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
2750
2751/*
2752** CAPI3REF: Authorizer Action Codes
2753**
2754** The [sqlite3_set_authorizer()] interface registers a callback function
2755** that is invoked to authorize certain SQL statement actions. The
2756** second parameter to the callback is an integer code that specifies
2757** what action is being authorized. These are the integer action codes that
2758** the authorizer callback may be passed.
2759**
2760** These action code values signify what kind of operation is to be
2761** authorized. The 3rd and 4th parameters to the authorization
2762** callback function will be parameters or NULL depending on which of these
2763** codes is used as the second parameter. ^(The 5th parameter to the
2764** authorizer callback is the name of the database ("main", "temp",
2765** etc.) if applicable.)^ ^The 6th parameter to the authorizer callback
2766** is the name of the inner-most trigger or view that is responsible for
2767** the access attempt or NULL if this access attempt is directly from
2768** top-level SQL code.
2769*/
2770/******************************************* 3rd ************ 4th ***********/
2771#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
2772#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
2773#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
2774#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
2775#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
2776#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
2777#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
2778#define SQLITE_CREATE_VIEW 8 /* View Name NULL */
2779#define SQLITE_DELETE 9 /* Table Name NULL */
2780#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
2781#define SQLITE_DROP_TABLE 11 /* Table Name NULL */
2782#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
2783#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
2784#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
2785#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
2786#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
2787#define SQLITE_DROP_VIEW 17 /* View Name NULL */
2788#define SQLITE_INSERT 18 /* Table Name NULL */
2789#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
2790#define SQLITE_READ 20 /* Table Name Column Name */
2791#define SQLITE_SELECT 21 /* NULL NULL */
2792#define SQLITE_TRANSACTION 22 /* Operation NULL */
2793#define SQLITE_UPDATE 23 /* Table Name Column Name */
2794#define SQLITE_ATTACH 24 /* Filename NULL */
2795#define SQLITE_DETACH 25 /* Database Name NULL */
2796#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
2797#define SQLITE_REINDEX 27 /* Index Name NULL */
2798#define SQLITE_ANALYZE 28 /* Table Name NULL */
2799#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
2800#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
2801#define SQLITE_FUNCTION 31 /* NULL Function Name */
2802#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
2803#define SQLITE_COPY 0 /* No longer used */
2804#define SQLITE_RECURSIVE 33 /* NULL NULL */
2805
2806/*
2807** CAPI3REF: Tracing And Profiling Functions
2808** METHOD: sqlite3
2809**
2810** These routines are deprecated. Use the [sqlite3_trace_v2()] interface
2811** instead of the routines described here.
2812**
2813** These routines register callback functions that can be used for
2814** tracing and profiling the execution of SQL statements.
2815**
2816** ^The callback function registered by sqlite3_trace() is invoked at
2817** various times when an SQL statement is being run by [sqlite3_step()].
2818** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
2819** SQL statement text as the statement first begins executing.
2820** ^(Additional sqlite3_trace() callbacks might occur
2821** as each triggered subprogram is entered. The callbacks for triggers
2822** contain a UTF-8 SQL comment that identifies the trigger.)^
2823**
2824** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
2825** the length of [bound parameter] expansion in the output of sqlite3_trace().
2826**
2827** ^The callback function registered by sqlite3_profile() is invoked
2828** as each SQL statement finishes. ^The profile callback contains
2829** the original statement text and an estimate of wall-clock time
2830** of how long that statement took to run. ^The profile callback
2831** time is in units of nanoseconds, however the current implementation
2832** is only capable of millisecond resolution so the six least significant
2833** digits in the time are meaningless. Future versions of SQLite
2834** might provide greater resolution on the profiler callback. The
2835** sqlite3_profile() function is considered experimental and is
2836** subject to change in future versions of SQLite.
2837*/
2838SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*,
2839 void(*xTrace)(void*,const char*), void*);
2840SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
2841 void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
2842
2843/*
2844** CAPI3REF: SQL Trace Event Codes
2845** KEYWORDS: SQLITE_TRACE
2846**
2847** These constants identify classes of events that can be monitored
2848** using the [sqlite3_trace_v2()] tracing logic. The third argument
2849** to [sqlite3_trace_v2()] is an OR-ed combination of one or more of
2850** the following constants. ^The first argument to the trace callback
2851** is one of the following constants.
2852**
2853** New tracing constants may be added in future releases.
2854**
2855** ^A trace callback has four arguments: xCallback(T,C,P,X).
2856** ^The T argument is one of the integer type codes above.
2857** ^The C argument is a copy of the context pointer passed in as the
2858** fourth argument to [sqlite3_trace_v2()].
2859** The P and X arguments are pointers whose meanings depend on T.
2860**
2861** <dl>
2862** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt>
2863** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
2864** first begins running and possibly at other times during the
2865** execution of the prepared statement, such as at the start of each
2866** trigger subprogram. ^The P argument is a pointer to the
2867** [prepared statement]. ^The X argument is a pointer to a string which
2868** is the unexpanded SQL text of the prepared statement or an SQL comment
2869** that indicates the invocation of a trigger. ^The callback can compute
2870** the same text that would have been returned by the legacy [sqlite3_trace()]
2871** interface by using the X argument when X begins with "--" and invoking
2872** [sqlite3_expanded_sql(P)] otherwise.
2873**
2874** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
2875** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
2876** information as is provided by the [sqlite3_profile()] callback.
2877** ^The P argument is a pointer to the [prepared statement] and the
2878** X argument points to a 64-bit integer which is the estimated of
2879** the number of nanosecond that the prepared statement took to run.
2880** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
2881**
2882** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
2883** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
2884** statement generates a single row of result.
2885** ^The P argument is a pointer to the [prepared statement] and the
2886** X argument is unused.
2887**
2888** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt>
2889** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
2890** connection closes.
2891** ^The P argument is a pointer to the [database connection] object
2892** and the X argument is unused.
2893** </dl>
2894*/
2895#define SQLITE_TRACE_STMT 0x01
2896#define SQLITE_TRACE_PROFILE 0x02
2897#define SQLITE_TRACE_ROW 0x04
2898#define SQLITE_TRACE_CLOSE 0x08
2899
2900/*
2901** CAPI3REF: SQL Trace Hook
2902** METHOD: sqlite3
2903**
2904** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
2905** function X against [database connection] D, using property mask M
2906** and context pointer P. ^If the X callback is
2907** NULL or if the M mask is zero, then tracing is disabled. The
2908** M argument should be the bitwise OR-ed combination of
2909** zero or more [SQLITE_TRACE] constants.
2910**
2911** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides
2912** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
2913**
2914** ^The X callback is invoked whenever any of the events identified by
2915** mask M occur. ^The integer return value from the callback is currently
2916** ignored, though this may change in future releases. Callback
2917** implementations should return zero to ensure future compatibility.
2918**
2919** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
2920** ^The T argument is one of the [SQLITE_TRACE]
2921** constants to indicate why the callback was invoked.
2922** ^The C argument is a copy of the context pointer.
2923** The P and X arguments are pointers whose meanings depend on T.
2924**
2925** The sqlite3_trace_v2() interface is intended to replace the legacy
2926** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which
2927** are deprecated.
2928*/
2929SQLITE_API int sqlite3_trace_v2(
2930 sqlite3*,
2931 unsigned uMask,
2932 int(*xCallback)(unsigned,void*,void*,void*),
2933 void *pCtx
2934);
2935
2936/*
2937** CAPI3REF: Query Progress Callbacks
2938** METHOD: sqlite3
2939**
2940** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
2941** function X to be invoked periodically during long running calls to
2942** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
2943** database connection D. An example use for this
2944** interface is to keep a GUI updated during a large query.
2945**
2946** ^The parameter P is passed through as the only parameter to the
2947** callback function X. ^The parameter N is the approximate number of
2948** [virtual machine instructions] that are evaluated between successive
2949** invocations of the callback X. ^If N is less than one then the progress
2950** handler is disabled.
2951**
2952** ^Only a single progress handler may be defined at one time per
2953** [database connection]; setting a new progress handler cancels the
2954** old one. ^Setting parameter X to NULL disables the progress handler.
2955** ^The progress handler is also disabled by setting N to a value less
2956** than 1.
2957**
2958** ^If the progress callback returns non-zero, the operation is
2959** interrupted. This feature can be used to implement a
2960** "Cancel" button on a GUI progress dialog box.
2961**
2962** The progress handler callback must not do anything that will modify
2963** the database connection that invoked the progress handler.
2964** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
2965** database connections for the meaning of "modify" in this paragraph.
2966**
2967*/
2968SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
2969
2970/*
2971** CAPI3REF: Opening A New Database Connection
2972** CONSTRUCTOR: sqlite3
2973**
2974** ^These routines open an SQLite database file as specified by the
2975** filename argument. ^The filename argument is interpreted as UTF-8 for
2976** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
2977** order for sqlite3_open16(). ^(A [database connection] handle is usually
2978** returned in *ppDb, even if an error occurs. The only exception is that
2979** if SQLite is unable to allocate memory to hold the [sqlite3] object,
2980** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
2981** object.)^ ^(If the database is opened (and/or created) successfully, then
2982** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The
2983** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
2984** an English language description of the error following a failure of any
2985** of the sqlite3_open() routines.
2986**
2987** ^The default encoding will be UTF-8 for databases created using
2988** sqlite3_open() or sqlite3_open_v2(). ^The default encoding for databases
2989** created using sqlite3_open16() will be UTF-16 in the native byte order.
2990**
2991** Whether or not an error occurs when it is opened, resources
2992** associated with the [database connection] handle should be released by
2993** passing it to [sqlite3_close()] when it is no longer required.
2994**
2995** The sqlite3_open_v2() interface works like sqlite3_open()
2996** except that it accepts two additional parameters for additional control
2997** over the new database connection. ^(The flags parameter to
2998** sqlite3_open_v2() can take one of
2999** the following three values, optionally combined with the
3000** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
3001** [SQLITE_OPEN_PRIVATECACHE], and/or [SQLITE_OPEN_URI] flags:)^
3002**
3003** <dl>
3004** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
3005** <dd>The database is opened in read-only mode. If the database does not
3006** already exist, an error is returned.</dd>)^
3007**
3008** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
3009** <dd>The database is opened for reading and writing if possible, or reading
3010** only if the file is write protected by the operating system. In either
3011** case the database must already exist, otherwise an error is returned.</dd>)^
3012**
3013** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
3014** <dd>The database is opened for reading and writing, and is created if
3015** it does not already exist. This is the behavior that is always used for
3016** sqlite3_open() and sqlite3_open16().</dd>)^
3017** </dl>
3018**
3019** If the 3rd parameter to sqlite3_open_v2() is not one of the
3020** combinations shown above optionally combined with other
3021** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
3022** then the behavior is undefined.
3023**
3024** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
3025** opens in the multi-thread [threading mode] as long as the single-thread
3026** mode has not been set at compile-time or start-time. ^If the
3027** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
3028** in the serialized [threading mode] unless single-thread was
3029** previously selected at compile-time or start-time.
3030** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
3031** eligible to use [shared cache mode], regardless of whether or not shared
3032** cache is enabled using [sqlite3_enable_shared_cache()]. ^The
3033** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
3034** participate in [shared cache mode] even if it is enabled.
3035**
3036** ^The fourth parameter to sqlite3_open_v2() is the name of the
3037** [sqlite3_vfs] object that defines the operating system interface that
3038** the new database connection should use. ^If the fourth parameter is
3039** a NULL pointer then the default [sqlite3_vfs] object is used.
3040**
3041** ^If the filename is ":memory:", then a private, temporary in-memory database
3042** is created for the connection. ^This in-memory database will vanish when
3043** the database connection is closed. Future versions of SQLite might
3044** make use of additional special filenames that begin with the ":" character.
3045** It is recommended that when a database filename actually does begin with
3046** a ":" character you should prefix the filename with a pathname such as
3047** "./" to avoid ambiguity.
3048**
3049** ^If the filename is an empty string, then a private, temporary
3050** on-disk database will be created. ^This private database will be
3051** automatically deleted as soon as the database connection is closed.
3052**
3053** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
3054**
3055** ^If [URI filename] interpretation is enabled, and the filename argument
3056** begins with "file:", then the filename is interpreted as a URI. ^URI
3057** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
3058** set in the fourth argument to sqlite3_open_v2(), or if it has
3059** been enabled globally using the [SQLITE_CONFIG_URI] option with the
3060** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
3061** As of SQLite version 3.7.7, URI filename interpretation is turned off
3062** by default, but future releases of SQLite might enable URI filename
3063** interpretation by default. See "[URI filenames]" for additional
3064** information.
3065**
3066** URI filenames are parsed according to RFC 3986. ^If the URI contains an
3067** authority, then it must be either an empty string or the string
3068** "localhost". ^If the authority is not an empty string or "localhost", an
3069** error is returned to the caller. ^The fragment component of a URI, if
3070** present, is ignored.
3071**
3072** ^SQLite uses the path component of the URI as the name of the disk file
3073** which contains the database. ^If the path begins with a '/' character,
3074** then it is interpreted as an absolute path. ^If the path does not begin
3075** with a '/' (meaning that the authority section is omitted from the URI)
3076** then the path is interpreted as a relative path.
3077** ^(On windows, the first component of an absolute path
3078** is a drive specification (e.g. "C:").)^
3079**
3080** [[core URI query parameters]]
3081** The query component of a URI may contain parameters that are interpreted
3082** either by SQLite itself, or by a [VFS | custom VFS implementation].
3083** SQLite and its built-in [VFSes] interpret the
3084** following query parameters:
3085**
3086** <ul>
3087** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
3088** a VFS object that provides the operating system interface that should
3089** be used to access the database file on disk. ^If this option is set to
3090** an empty string the default VFS object is used. ^Specifying an unknown
3091** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
3092** present, then the VFS specified by the option takes precedence over
3093** the value passed as the fourth parameter to sqlite3_open_v2().
3094**
3095** <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
3096** "rwc", or "memory". Attempting to set it to any other value is
3097** an error)^.
3098** ^If "ro" is specified, then the database is opened for read-only
3099** access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the
3100** third argument to sqlite3_open_v2(). ^If the mode option is set to
3101** "rw", then the database is opened for read-write (but not create)
3102** access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
3103** been set. ^Value "rwc" is equivalent to setting both
3104** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If the mode option is
3105** set to "memory" then a pure [in-memory database] that never reads
3106** or writes from disk is used. ^It is an error to specify a value for
3107** the mode parameter that is less restrictive than that specified by
3108** the flags passed in the third parameter to sqlite3_open_v2().
3109**
3110** <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
3111** "private". ^Setting it to "shared" is equivalent to setting the
3112** SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
3113** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
3114** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
3115** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
3116** a URI filename, its value overrides any behavior requested by setting
3117** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
3118**
3119** <li> <b>psow</b>: ^The psow parameter indicates whether or not the
3120** [powersafe overwrite] property does or does not apply to the
3121** storage media on which the database file resides.
3122**
3123** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
3124** which if set disables file locking in rollback journal modes. This
3125** is useful for accessing a database on a filesystem that does not
3126** support locking. Caution: Database corruption might result if two
3127** or more processes write to the same database and any one of those
3128** processes uses nolock=1.
3129**
3130** <li> <b>immutable</b>: ^The immutable parameter is a boolean query
3131** parameter that indicates that the database file is stored on
3132** read-only media. ^When immutable is set, SQLite assumes that the
3133** database file cannot be changed, even by a process with higher
3134** privilege, and so the database is opened read-only and all locking
3135** and change detection is disabled. Caution: Setting the immutable
3136** property on a database file that does in fact change can result
3137** in incorrect query results and/or [SQLITE_CORRUPT] errors.
3138** See also: [SQLITE_IOCAP_IMMUTABLE].
3139**
3140** </ul>
3141**
3142** ^Specifying an unknown parameter in the query component of a URI is not an
3143** error. Future versions of SQLite might understand additional query
3144** parameters. See "[query parameters with special meaning to SQLite]" for
3145** additional information.
3146**
3147** [[URI filename examples]] <h3>URI filename examples</h3>
3148**
3149** <table border="1" align=center cellpadding=5>
3150** <tr><th> URI filenames <th> Results
3151** <tr><td> file:data.db <td>
3152** Open the file "data.db" in the current directory.
3153** <tr><td> file:/home/fred/data.db<br>
3154** file:///home/fred/data.db <br>
3155** file://localhost/home/fred/data.db <br> <td>
3156** Open the database file "/home/fred/data.db".
3157** <tr><td> file://darkstar/home/fred/data.db <td>
3158** An error. "darkstar" is not a recognized authority.
3159** <tr><td style="white-space:nowrap">
3160** file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
3161** <td> Windows only: Open the file "data.db" on fred's desktop on drive
3162** C:. Note that the %20 escaping in this example is not strictly
3163** necessary - space characters can be used literally
3164** in URI filenames.
3165** <tr><td> file:data.db?mode=ro&cache=private <td>
3166** Open file "data.db" in the current directory for read-only access.
3167** Regardless of whether or not shared-cache mode is enabled by
3168** default, use a private cache.
3169** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
3170** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
3171** that uses dot-files in place of posix advisory locking.
3172** <tr><td> file:data.db?mode=readonly <td>
3173** An error. "readonly" is not a valid option for the "mode" parameter.
3174** </table>
3175**
3176** ^URI hexadecimal escape sequences (%HH) are supported within the path and
3177** query components of a URI. A hexadecimal escape sequence consists of a
3178** percent sign - "%" - followed by exactly two hexadecimal digits
3179** specifying an octet value. ^Before the path or query components of a
3180** URI filename are interpreted, they are encoded using UTF-8 and all
3181** hexadecimal escape sequences replaced by a single byte containing the
3182** corresponding octet. If this process generates an invalid UTF-8 encoding,
3183** the results are undefined.
3184**
3185** <b>Note to Windows users:</b> The encoding used for the filename argument
3186** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
3187** codepage is currently defined. Filenames containing international
3188** characters must be converted to UTF-8 prior to passing them into
3189** sqlite3_open() or sqlite3_open_v2().
3190**
3191** <b>Note to Windows Runtime users:</b> The temporary directory must be set
3192** prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various
3193** features that require the use of temporary files may fail.
3194**
3195** See also: [sqlite3_temp_directory]
3196*/
3197SQLITE_API int sqlite3_open(
3198 const char *filename, /* Database filename (UTF-8) */
3199 sqlite3 **ppDb /* OUT: SQLite db handle */
3200);
3201SQLITE_API int sqlite3_open16(
3202 const void *filename, /* Database filename (UTF-16) */
3203 sqlite3 **ppDb /* OUT: SQLite db handle */
3204);
3205SQLITE_API int sqlite3_open_v2(
3206 const char *filename, /* Database filename (UTF-8) */
3207 sqlite3 **ppDb, /* OUT: SQLite db handle */
3208 int flags, /* Flags */
3209 const char *zVfs /* Name of VFS module to use */
3210);
3211
3212/*
3213** CAPI3REF: Obtain Values For URI Parameters
3214**
3215** These are utility routines, useful to VFS implementations, that check
3216** to see if a database file was a URI that contained a specific query
3217** parameter, and if so obtains the value of that query parameter.
3218**
3219** If F is the database filename pointer passed into the xOpen() method of
3220** a VFS implementation when the flags parameter to xOpen() has one or
3221** more of the [SQLITE_OPEN_URI] or [SQLITE_OPEN_MAIN_DB] bits set and
3222** P is the name of the query parameter, then
3223** sqlite3_uri_parameter(F,P) returns the value of the P
3224** parameter if it exists or a NULL pointer if P does not appear as a
3225** query parameter on F. If P is a query parameter of F
3226** has no explicit value, then sqlite3_uri_parameter(F,P) returns
3227** a pointer to an empty string.
3228**
3229** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
3230** parameter and returns true (1) or false (0) according to the value
3231** of P. The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
3232** value of query parameter P is one of "yes", "true", or "on" in any
3233** case or if the value begins with a non-zero number. The
3234** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
3235** query parameter P is one of "no", "false", or "off" in any case or
3236** if the value begins with a numeric zero. If P is not a query
3237** parameter on F or if the value of P is does not match any of the
3238** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).
3239**
3240** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
3241** 64-bit signed integer and returns that integer, or D if P does not
3242** exist. If the value of P is something other than an integer, then
3243** zero is returned.
3244**
3245** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
3246** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
3247** is not a database file pathname pointer that SQLite passed into the xOpen
3248** VFS method, then the behavior of this routine is undefined and probably
3249** undesirable.
3250*/
3251SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
3252SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
3253SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
3254
3255
3256/*
3257** CAPI3REF: Error Codes And Messages
3258** METHOD: sqlite3
3259**
3260** ^If the most recent sqlite3_* API call associated with
3261** [database connection] D failed, then the sqlite3_errcode(D) interface
3262** returns the numeric [result code] or [extended result code] for that
3263** API call.
3264** If the most recent API call was successful,
3265** then the return value from sqlite3_errcode() is undefined.
3266** ^The sqlite3_extended_errcode()
3267** interface is the same except that it always returns the
3268** [extended result code] even when extended result codes are
3269** disabled.
3270**
3271** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
3272** text that describes the error, as either UTF-8 or UTF-16 respectively.
3273** ^(Memory to hold the error message string is managed internally.
3274** The application does not need to worry about freeing the result.
3275** However, the error string might be overwritten or deallocated by
3276** subsequent calls to other SQLite interface functions.)^
3277**
3278** ^The sqlite3_errstr() interface returns the English-language text
3279** that describes the [result code], as UTF-8.
3280** ^(Memory to hold the error message string is managed internally
3281** and must not be freed by the application)^.
3282**
3283** When the serialized [threading mode] is in use, it might be the
3284** case that a second error occurs on a separate thread in between
3285** the time of the first error and the call to these interfaces.
3286** When that happens, the second error will be reported since these
3287** interfaces always report the most recent result. To avoid
3288** this, each thread can obtain exclusive use of the [database connection] D
3289** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
3290** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
3291** all calls to the interfaces listed here are completed.
3292**
3293** If an interface fails with SQLITE_MISUSE, that means the interface
3294** was invoked incorrectly by the application. In that case, the
3295** error code and message may or may not be set.
3296*/
3297SQLITE_API int sqlite3_errcode(sqlite3 *db);
3298SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
3299SQLITE_API const char *sqlite3_errmsg(sqlite3*);
3300SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
3301SQLITE_API const char *sqlite3_errstr(int);
3302
3303/*
3304** CAPI3REF: Prepared Statement Object
3305** KEYWORDS: {prepared statement} {prepared statements}
3306**
3307** An instance of this object represents a single SQL statement that
3308** has been compiled into binary form and is ready to be evaluated.
3309**
3310** Think of each SQL statement as a separate computer program. The
3311** original SQL text is source code. A prepared statement object
3312** is the compiled object code. All SQL must be converted into a
3313** prepared statement before it can be run.
3314**
3315** The life-cycle of a prepared statement object usually goes like this:
3316**
3317** <ol>
3318** <li> Create the prepared statement object using [sqlite3_prepare_v2()].
3319** <li> Bind values to [parameters] using the sqlite3_bind_*()
3320** interfaces.
3321** <li> Run the SQL by calling [sqlite3_step()] one or more times.
3322** <li> Reset the prepared statement using [sqlite3_reset()] then go back
3323** to step 2. Do this zero or more times.
3324** <li> Destroy the object using [sqlite3_finalize()].
3325** </ol>
3326*/
3327typedef struct sqlite3_stmt sqlite3_stmt;
3328
3329/*
3330** CAPI3REF: Run-time Limits
3331** METHOD: sqlite3
3332**
3333** ^(This interface allows the size of various constructs to be limited
3334** on a connection by connection basis. The first parameter is the
3335** [database connection] whose limit is to be set or queried. The
3336** second parameter is one of the [limit categories] that define a
3337** class of constructs to be size limited. The third parameter is the
3338** new limit for that construct.)^
3339**
3340** ^If the new limit is a negative number, the limit is unchanged.
3341** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
3342** [limits | hard upper bound]
3343** set at compile-time by a C preprocessor macro called
3344** [limits | SQLITE_MAX_<i>NAME</i>].
3345** (The "_LIMIT_" in the name is changed to "_MAX_".))^
3346** ^Attempts to increase a limit above its hard upper bound are
3347** silently truncated to the hard upper bound.
3348**
3349** ^Regardless of whether or not the limit was changed, the
3350** [sqlite3_limit()] interface returns the prior value of the limit.
3351** ^Hence, to find the current value of a limit without changing it,
3352** simply invoke this interface with the third parameter set to -1.
3353**
3354** Run-time limits are intended for use in applications that manage
3355** both their own internal database and also databases that are controlled
3356** by untrusted external sources. An example application might be a
3357** web browser that has its own databases for storing history and
3358** separate databases controlled by JavaScript applications downloaded
3359** off the Internet. The internal databases can be given the
3360** large, default limits. Databases managed by external sources can
3361** be given much smaller limits designed to prevent a denial of service
3362** attack. Developers might also want to use the [sqlite3_set_authorizer()]
3363** interface to further control untrusted SQL. The size of the database
3364** created by an untrusted script can be contained using the
3365** [max_page_count] [PRAGMA].
3366**
3367** New run-time limit categories may be added in future releases.
3368*/
3369SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
3370
3371/*
3372** CAPI3REF: Run-Time Limit Categories
3373** KEYWORDS: {limit category} {*limit categories}
3374**
3375** These constants define various performance limits
3376** that can be lowered at run-time using [sqlite3_limit()].
3377** The synopsis of the meanings of the various limits is shown below.
3378** Additional information is available at [limits | Limits in SQLite].
3379**
3380** <dl>
3381** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
3382** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
3383**
3384** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
3385** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
3386**
3387** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
3388** <dd>The maximum number of columns in a table definition or in the
3389** result set of a [SELECT] or the maximum number of columns in an index
3390** or in an ORDER BY or GROUP BY clause.</dd>)^
3391**
3392** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
3393** <dd>The maximum depth of the parse tree on any expression.</dd>)^
3394**
3395** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
3396** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
3397**
3398** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
3399** <dd>The maximum number of instructions in a virtual machine program
3400** used to implement an SQL statement. This limit is not currently
3401** enforced, though that might be added in some future release of
3402** SQLite.</dd>)^
3403**
3404** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
3405** <dd>The maximum number of arguments on a function.</dd>)^
3406**
3407** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
3408** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
3409**
3410** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
3411** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
3412** <dd>The maximum length of the pattern argument to the [LIKE] or
3413** [GLOB] operators.</dd>)^
3414**
3415** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
3416** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
3417** <dd>The maximum index number of any [parameter] in an SQL statement.)^
3418**
3419** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
3420** <dd>The maximum depth of recursion for triggers.</dd>)^
3421**
3422** [[SQLITE_LIMIT_WORKER_THREADS]] ^(<dt>SQLITE_LIMIT_WORKER_THREADS</dt>
3423** <dd>The maximum number of auxiliary worker threads that a single
3424** [prepared statement] may start.</dd>)^
3425** </dl>
3426*/
3427#define SQLITE_LIMIT_LENGTH 0
3428#define SQLITE_LIMIT_SQL_LENGTH 1
3429#define SQLITE_LIMIT_COLUMN 2
3430#define SQLITE_LIMIT_EXPR_DEPTH 3
3431#define SQLITE_LIMIT_COMPOUND_SELECT 4
3432#define SQLITE_LIMIT_VDBE_OP 5
3433#define SQLITE_LIMIT_FUNCTION_ARG 6
3434#define SQLITE_LIMIT_ATTACHED 7
3435#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8
3436#define SQLITE_LIMIT_VARIABLE_NUMBER 9
3437#define SQLITE_LIMIT_TRIGGER_DEPTH 10
3438#define SQLITE_LIMIT_WORKER_THREADS 11
3439
3440/*
3441** CAPI3REF: Compiling An SQL Statement
3442** KEYWORDS: {SQL statement compiler}
3443** METHOD: sqlite3
3444** CONSTRUCTOR: sqlite3_stmt
3445**
3446** To execute an SQL query, it must first be compiled into a byte-code
3447** program using one of these routines.
3448**
3449** The first argument, "db", is a [database connection] obtained from a
3450** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
3451** [sqlite3_open16()]. The database connection must not have been closed.
3452**
3453** The second argument, "zSql", is the statement to be compiled, encoded
3454** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()
3455** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
3456** use UTF-16.
3457**
3458** ^If the nByte argument is negative, then zSql is read up to the
3459** first zero terminator. ^If nByte is positive, then it is the
3460** number of bytes read from zSql. ^If nByte is zero, then no prepared
3461** statement is generated.
3462** If the caller knows that the supplied string is nul-terminated, then
3463** there is a small performance advantage to passing an nByte parameter that
3464** is the number of bytes in the input string <i>including</i>
3465** the nul-terminator.
3466**
3467** ^If pzTail is not NULL then *pzTail is made to point to the first byte
3468** past the end of the first SQL statement in zSql. These routines only
3469** compile the first statement in zSql, so *pzTail is left pointing to
3470** what remains uncompiled.
3471**
3472** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
3473** executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set
3474** to NULL. ^If the input text contains no SQL (if the input is an empty
3475** string or a comment) then *ppStmt is set to NULL.
3476** The calling procedure is responsible for deleting the compiled
3477** SQL statement using [sqlite3_finalize()] after it has finished with it.
3478** ppStmt may not be NULL.
3479**
3480** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
3481** otherwise an [error code] is returned.
3482**
3483** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
3484** recommended for all new programs. The two older interfaces are retained
3485** for backwards compatibility, but their use is discouraged.
3486** ^In the "v2" interfaces, the prepared statement
3487** that is returned (the [sqlite3_stmt] object) contains a copy of the
3488** original SQL text. This causes the [sqlite3_step()] interface to
3489** behave differently in three ways:
3490**
3491** <ol>
3492** <li>
3493** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
3494** always used to do, [sqlite3_step()] will automatically recompile the SQL
3495** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
3496** retries will occur before sqlite3_step() gives up and returns an error.
3497** </li>
3498**
3499** <li>
3500** ^When an error occurs, [sqlite3_step()] will return one of the detailed
3501** [error codes] or [extended error codes]. ^The legacy behavior was that
3502** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
3503** and the application would have to make a second call to [sqlite3_reset()]
3504** in order to find the underlying cause of the problem. With the "v2" prepare
3505** interfaces, the underlying reason for the error is returned immediately.
3506** </li>
3507**
3508** <li>
3509** ^If the specific value bound to [parameter | host parameter] in the
3510** WHERE clause might influence the choice of query plan for a statement,
3511** then the statement will be automatically recompiled, as if there had been
3512** a schema change, on the first [sqlite3_step()] call following any change
3513** to the [sqlite3_bind_text | bindings] of that [parameter].
3514** ^The specific value of WHERE-clause [parameter] might influence the
3515** choice of query plan if the parameter is the left-hand side of a [LIKE]
3516** or [GLOB] operator or if the parameter is compared to an indexed column
3517** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.
3518** </li>
3519** </ol>
3520*/
3521SQLITE_API int sqlite3_prepare(
3522 sqlite3 *db, /* Database handle */
3523 const char *zSql, /* SQL statement, UTF-8 encoded */
3524 int nByte, /* Maximum length of zSql in bytes. */
3525 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
3526 const char **pzTail /* OUT: Pointer to unused portion of zSql */
3527);
3528SQLITE_API int sqlite3_prepare_v2(
3529 sqlite3 *db, /* Database handle */
3530 const char *zSql, /* SQL statement, UTF-8 encoded */
3531 int nByte, /* Maximum length of zSql in bytes. */
3532 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
3533 const char **pzTail /* OUT: Pointer to unused portion of zSql */
3534);
3535SQLITE_API int sqlite3_prepare16(
3536 sqlite3 *db, /* Database handle */
3537 const void *zSql, /* SQL statement, UTF-16 encoded */
3538 int nByte, /* Maximum length of zSql in bytes. */
3539 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
3540 const void **pzTail /* OUT: Pointer to unused portion of zSql */
3541);
3542SQLITE_API int sqlite3_prepare16_v2(
3543 sqlite3 *db, /* Database handle */
3544 const void *zSql, /* SQL statement, UTF-16 encoded */
3545 int nByte, /* Maximum length of zSql in bytes. */
3546 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
3547 const void **pzTail /* OUT: Pointer to unused portion of zSql */
3548);
3549
3550/*
3551** CAPI3REF: Retrieving Statement SQL
3552** METHOD: sqlite3_stmt
3553**
3554** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
3555** SQL text used to create [prepared statement] P if P was
3556** created by either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
3557** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
3558** string containing the SQL text of prepared statement P with
3559** [bound parameters] expanded.
3560**
3561** ^(For example, if a prepared statement is created using the SQL
3562** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
3563** and parameter :xyz is unbound, then sqlite3_sql() will return
3564** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()
3565** will return "SELECT 2345,NULL".)^
3566**
3567** ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory
3568** is available to hold the result, or if the result would exceed the
3569** the maximum string length determined by the [SQLITE_LIMIT_LENGTH].
3570**
3571** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of
3572** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time
3573** option causes sqlite3_expanded_sql() to always return NULL.
3574**
3575** ^The string returned by sqlite3_sql(P) is managed by SQLite and is
3576** automatically freed when the prepared statement is finalized.
3577** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
3578** is obtained from [sqlite3_malloc()] and must be free by the application
3579** by passing it to [sqlite3_free()].
3580*/
3581SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
3582SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
3583
3584/*
3585** CAPI3REF: Determine If An SQL Statement Writes The Database
3586** METHOD: sqlite3_stmt
3587**
3588** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
3589** and only if the [prepared statement] X makes no direct changes to
3590** the content of the database file.
3591**
3592** Note that [application-defined SQL functions] or
3593** [virtual tables] might change the database indirectly as a side effect.
3594** ^(For example, if an application defines a function "eval()" that
3595** calls [sqlite3_exec()], then the following SQL statement would
3596** change the database file through side-effects:
3597**
3598** <blockquote><pre>
3599** SELECT eval('DELETE FROM t1') FROM t2;
3600** </pre></blockquote>
3601**
3602** But because the [SELECT] statement does not change the database file
3603** directly, sqlite3_stmt_readonly() would still return true.)^
3604**
3605** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
3606** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
3607** since the statements themselves do not actually modify the database but
3608** rather they control the timing of when other statements modify the
3609** database. ^The [ATTACH] and [DETACH] statements also cause
3610** sqlite3_stmt_readonly() to return true since, while those statements
3611** change the configuration of a database connection, they do not make
3612** changes to the content of the database files on disk.
3613** ^The sqlite3_stmt_readonly() interface returns true for [BEGIN] since
3614** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and
3615** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so
3616** sqlite3_stmt_readonly() returns false for those commands.
3617*/
3618SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
3619
3620/*
3621** CAPI3REF: Determine If A Prepared Statement Has Been Reset
3622** METHOD: sqlite3_stmt
3623**
3624** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
3625** [prepared statement] S has been stepped at least once using
3626** [sqlite3_step(S)] but has neither run to completion (returned
3627** [SQLITE_DONE] from [sqlite3_step(S)]) nor
3628** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S)
3629** interface returns false if S is a NULL pointer. If S is not a
3630** NULL pointer and is not a pointer to a valid [prepared statement]
3631** object, then the behavior is undefined and probably undesirable.
3632**
3633** This interface can be used in combination [sqlite3_next_stmt()]
3634** to locate all prepared statements associated with a database
3635** connection that are in need of being reset. This can be used,
3636** for example, in diagnostic routines to search for prepared
3637** statements that are holding a transaction open.
3638*/
3639SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
3640
3641/*
3642** CAPI3REF: Dynamically Typed Value Object
3643** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
3644**
3645** SQLite uses the sqlite3_value object to represent all values
3646** that can be stored in a database table. SQLite uses dynamic typing
3647** for the values it stores. ^Values stored in sqlite3_value objects
3648** can be integers, floating point values, strings, BLOBs, or NULL.
3649**
3650** An sqlite3_value object may be either "protected" or "unprotected".
3651** Some interfaces require a protected sqlite3_value. Other interfaces
3652** will accept either a protected or an unprotected sqlite3_value.
3653** Every interface that accepts sqlite3_value arguments specifies
3654** whether or not it requires a protected sqlite3_value. The
3655** [sqlite3_value_dup()] interface can be used to construct a new
3656** protected sqlite3_value from an unprotected sqlite3_value.
3657**
3658** The terms "protected" and "unprotected" refer to whether or not
3659** a mutex is held. An internal mutex is held for a protected
3660** sqlite3_value object but no mutex is held for an unprotected
3661** sqlite3_value object. If SQLite is compiled to be single-threaded
3662** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
3663** or if SQLite is run in one of reduced mutex modes
3664** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
3665** then there is no distinction between protected and unprotected
3666** sqlite3_value objects and they can be used interchangeably. However,
3667** for maximum code portability it is recommended that applications
3668** still make the distinction between protected and unprotected
3669** sqlite3_value objects even when not strictly required.
3670**
3671** ^The sqlite3_value objects that are passed as parameters into the
3672** implementation of [application-defined SQL functions] are protected.
3673** ^The sqlite3_value object returned by
3674** [sqlite3_column_value()] is unprotected.
3675** Unprotected sqlite3_value objects may only be used with
3676** [sqlite3_result_value()] and [sqlite3_bind_value()].
3677** The [sqlite3_value_blob | sqlite3_value_type()] family of
3678** interfaces require protected sqlite3_value objects.
3679*/
3680typedef struct Mem sqlite3_value;
3681
3682/*
3683** CAPI3REF: SQL Function Context Object
3684**
3685** The context in which an SQL function executes is stored in an
3686** sqlite3_context object. ^A pointer to an sqlite3_context object
3687** is always first parameter to [application-defined SQL functions].
3688** The application-defined SQL function implementation will pass this
3689** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
3690** [sqlite3_aggregate_context()], [sqlite3_user_data()],
3691** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
3692** and/or [sqlite3_set_auxdata()].
3693*/
3694typedef struct sqlite3_context sqlite3_context;
3695
3696/*
3697** CAPI3REF: Binding Values To Prepared Statements
3698** KEYWORDS: {host parameter} {host parameters} {host parameter name}
3699** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
3700** METHOD: sqlite3_stmt
3701**
3702** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
3703** literals may be replaced by a [parameter] that matches one of following
3704** templates:
3705**
3706** <ul>
3707** <li> ?
3708** <li> ?NNN
3709** <li> :VVV
3710** <li> @VVV
3711** <li> $VVV
3712** </ul>
3713**
3714** In the templates above, NNN represents an integer literal,
3715** and VVV represents an alphanumeric identifier.)^ ^The values of these
3716** parameters (also called "host parameter names" or "SQL parameters")
3717** can be set using the sqlite3_bind_*() routines defined here.
3718**
3719** ^The first argument to the sqlite3_bind_*() routines is always
3720** a pointer to the [sqlite3_stmt] object returned from
3721** [sqlite3_prepare_v2()] or its variants.
3722**
3723** ^The second argument is the index of the SQL parameter to be set.
3724** ^The leftmost SQL parameter has an index of 1. ^When the same named
3725** SQL parameter is used more than once, second and subsequent
3726** occurrences have the same index as the first occurrence.
3727** ^The index for named parameters can be looked up using the
3728** [sqlite3_bind_parameter_index()] API if desired. ^The index
3729** for "?NNN" parameters is the value of NNN.
3730** ^The NNN value must be between 1 and the [sqlite3_limit()]
3731** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
3732**
3733** ^The third argument is the value to bind to the parameter.
3734** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
3735** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
3736** is ignored and the end result is the same as sqlite3_bind_null().
3737**
3738** ^(In those routines that have a fourth argument, its value is the
3739** number of bytes in the parameter. To be clear: the value is the
3740** number of <u>bytes</u> in the value, not the number of characters.)^
3741** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
3742** is negative, then the length of the string is
3743** the number of bytes up to the first zero terminator.
3744** If the fourth parameter to sqlite3_bind_blob() is negative, then
3745** the behavior is undefined.
3746** If a non-negative fourth parameter is provided to sqlite3_bind_text()
3747** or sqlite3_bind_text16() or sqlite3_bind_text64() then
3748** that parameter must be the byte offset
3749** where the NUL terminator would occur assuming the string were NUL
3750** terminated. If any NUL characters occur at byte offsets less than
3751** the value of the fourth parameter then the resulting string value will
3752** contain embedded NULs. The result of expressions involving strings
3753** with embedded NULs is undefined.
3754**
3755** ^The fifth argument to the BLOB and string binding interfaces
3756** is a destructor used to dispose of the BLOB or
3757** string after SQLite has finished with it. ^The destructor is called
3758** to dispose of the BLOB or string even if the call to bind API fails.
3759** ^If the fifth argument is
3760** the special value [SQLITE_STATIC], then SQLite assumes that the
3761** information is in static, unmanaged space and does not need to be freed.
3762** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
3763** SQLite makes its own private copy of the data immediately, before
3764** the sqlite3_bind_*() routine returns.
3765**
3766** ^The sixth argument to sqlite3_bind_text64() must be one of
3767** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]
3768** to specify the encoding of the text in the third parameter. If
3769** the sixth argument to sqlite3_bind_text64() is not one of the
3770** allowed values shown above, or if the text encoding is different
3771** from the encoding specified by the sixth parameter, then the behavior
3772** is undefined.
3773**
3774** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
3775** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
3776** (just an integer to hold its size) while it is being processed.
3777** Zeroblobs are intended to serve as placeholders for BLOBs whose
3778** content is later written using
3779** [sqlite3_blob_open | incremental BLOB I/O] routines.
3780** ^A negative value for the zeroblob results in a zero-length BLOB.
3781**
3782** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
3783** for the [prepared statement] or with a prepared statement for which
3784** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
3785** then the call will return [SQLITE_MISUSE]. If any sqlite3_bind_()
3786** routine is passed a [prepared statement] that has been finalized, the
3787** result is undefined and probably harmful.
3788**
3789** ^Bindings are not cleared by the [sqlite3_reset()] routine.
3790** ^Unbound parameters are interpreted as NULL.
3791**
3792** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
3793** [error code] if anything goes wrong.
3794** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB
3795** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or
3796** [SQLITE_MAX_LENGTH].
3797** ^[SQLITE_RANGE] is returned if the parameter
3798** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
3799**
3800** See also: [sqlite3_bind_parameter_count()],
3801** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
3802*/
3803SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
3804SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
3805 void(*)(void*));
3806SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
3807SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
3808SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
3809SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
3810SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
3811SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
3812SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
3813 void(*)(void*), unsigned char encoding);
3814SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
3815SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
3816SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
3817
3818/*
3819** CAPI3REF: Number Of SQL Parameters
3820** METHOD: sqlite3_stmt
3821**
3822** ^This routine can be used to find the number of [SQL parameters]
3823** in a [prepared statement]. SQL parameters are tokens of the
3824** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
3825** placeholders for values that are [sqlite3_bind_blob | bound]
3826** to the parameters at a later time.
3827**
3828** ^(This routine actually returns the index of the largest (rightmost)
3829** parameter. For all forms except ?NNN, this will correspond to the
3830** number of unique parameters. If parameters of the ?NNN form are used,
3831** there may be gaps in the list.)^
3832**
3833** See also: [sqlite3_bind_blob|sqlite3_bind()],
3834** [sqlite3_bind_parameter_name()], and
3835** [sqlite3_bind_parameter_index()].
3836*/
3837SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
3838
3839/*
3840** CAPI3REF: Name Of A Host Parameter
3841** METHOD: sqlite3_stmt
3842**
3843** ^The sqlite3_bind_parameter_name(P,N) interface returns
3844** the name of the N-th [SQL parameter] in the [prepared statement] P.
3845** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
3846** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
3847** respectively.
3848** In other words, the initial ":" or "$" or "@" or "?"
3849** is included as part of the name.)^
3850** ^Parameters of the form "?" without a following integer have no name
3851** and are referred to as "nameless" or "anonymous parameters".
3852**
3853** ^The first host parameter has an index of 1, not 0.
3854**
3855** ^If the value N is out of range or if the N-th parameter is
3856** nameless, then NULL is returned. ^The returned string is
3857** always in UTF-8 encoding even if the named parameter was
3858** originally specified as UTF-16 in [sqlite3_prepare16()] or
3859** [sqlite3_prepare16_v2()].
3860**
3861** See also: [sqlite3_bind_blob|sqlite3_bind()],
3862** [sqlite3_bind_parameter_count()], and
3863** [sqlite3_bind_parameter_index()].
3864*/
3865SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
3866
3867/*
3868** CAPI3REF: Index Of A Parameter With A Given Name
3869** METHOD: sqlite3_stmt
3870**
3871** ^Return the index of an SQL parameter given its name. ^The
3872** index value returned is suitable for use as the second
3873** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero
3874** is returned if no matching parameter is found. ^The parameter
3875** name must be given in UTF-8 even if the original statement
3876** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
3877**
3878** See also: [sqlite3_bind_blob|sqlite3_bind()],
3879** [sqlite3_bind_parameter_count()], and
3880** [sqlite3_bind_parameter_name()].
3881*/
3882SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
3883
3884/*
3885** CAPI3REF: Reset All Bindings On A Prepared Statement
3886** METHOD: sqlite3_stmt
3887**
3888** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
3889** the [sqlite3_bind_blob | bindings] on a [prepared statement].
3890** ^Use this routine to reset all host parameters to NULL.
3891*/
3892SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
3893
3894/*
3895** CAPI3REF: Number Of Columns In A Result Set
3896** METHOD: sqlite3_stmt
3897**
3898** ^Return the number of columns in the result set returned by the
3899** [prepared statement]. ^If this routine returns 0, that means the
3900** [prepared statement] returns no data (for example an [UPDATE]).
3901** ^However, just because this routine returns a positive number does not
3902** mean that one or more rows of data will be returned. ^A SELECT statement
3903** will always have a positive sqlite3_column_count() but depending on the
3904** WHERE clause constraints and the table content, it might return no rows.
3905**
3906** See also: [sqlite3_data_count()]
3907*/
3908SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
3909
3910/*
3911** CAPI3REF: Column Names In A Result Set
3912** METHOD: sqlite3_stmt
3913**
3914** ^These routines return the name assigned to a particular column
3915** in the result set of a [SELECT] statement. ^The sqlite3_column_name()
3916** interface returns a pointer to a zero-terminated UTF-8 string
3917** and sqlite3_column_name16() returns a pointer to a zero-terminated
3918** UTF-16 string. ^The first parameter is the [prepared statement]
3919** that implements the [SELECT] statement. ^The second parameter is the
3920** column number. ^The leftmost column is number 0.
3921**
3922** ^The returned string pointer is valid until either the [prepared statement]
3923** is destroyed by [sqlite3_finalize()] or until the statement is automatically
3924** reprepared by the first call to [sqlite3_step()] for a particular run
3925** or until the next call to
3926** sqlite3_column_name() or sqlite3_column_name16() on the same column.
3927**
3928** ^If sqlite3_malloc() fails during the processing of either routine
3929** (for example during a conversion from UTF-8 to UTF-16) then a
3930** NULL pointer is returned.
3931**
3932** ^The name of a result column is the value of the "AS" clause for
3933** that column, if there is an AS clause. If there is no AS clause
3934** then the name of the column is unspecified and may change from
3935** one release of SQLite to the next.
3936*/
3937SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
3938SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
3939
3940/*
3941** CAPI3REF: Source Of Data In A Query Result
3942** METHOD: sqlite3_stmt
3943**
3944** ^These routines provide a means to determine the database, table, and
3945** table column that is the origin of a particular result column in
3946** [SELECT] statement.
3947** ^The name of the database or table or column can be returned as
3948** either a UTF-8 or UTF-16 string. ^The _database_ routines return
3949** the database name, the _table_ routines return the table name, and
3950** the origin_ routines return the column name.
3951** ^The returned string is valid until the [prepared statement] is destroyed
3952** using [sqlite3_finalize()] or until the statement is automatically
3953** reprepared by the first call to [sqlite3_step()] for a particular run
3954** or until the same information is requested
3955** again in a different encoding.
3956**
3957** ^The names returned are the original un-aliased names of the
3958** database, table, and column.
3959**
3960** ^The first argument to these interfaces is a [prepared statement].
3961** ^These functions return information about the Nth result column returned by
3962** the statement, where N is the second function argument.
3963** ^The left-most column is column 0 for these routines.
3964**
3965** ^If the Nth column returned by the statement is an expression or
3966** subquery and is not a column value, then all of these functions return
3967** NULL. ^These routine might also return NULL if a memory allocation error
3968** occurs. ^Otherwise, they return the name of the attached database, table,
3969** or column that query result column was extracted from.
3970**
3971** ^As with all other SQLite APIs, those whose names end with "16" return
3972** UTF-16 encoded strings and the other functions return UTF-8.
3973**
3974** ^These APIs are only available if the library was compiled with the
3975** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
3976**
3977** If two or more threads call one or more of these routines against the same
3978** prepared statement and column at the same time then the results are
3979** undefined.
3980**
3981** If two or more threads call one or more
3982** [sqlite3_column_database_name | column metadata interfaces]
3983** for the same [prepared statement] and result column
3984** at the same time then the results are undefined.
3985*/
3986SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
3987SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
3988SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
3989SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
3990SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
3991SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
3992
3993/*
3994** CAPI3REF: Declared Datatype Of A Query Result
3995** METHOD: sqlite3_stmt
3996**
3997** ^(The first parameter is a [prepared statement].
3998** If this statement is a [SELECT] statement and the Nth column of the
3999** returned result set of that [SELECT] is a table column (not an
4000** expression or subquery) then the declared type of the table
4001** column is returned.)^ ^If the Nth column of the result set is an
4002** expression or subquery, then a NULL pointer is returned.
4003** ^The returned string is always UTF-8 encoded.
4004**
4005** ^(For example, given the database schema:
4006**
4007** CREATE TABLE t1(c1 VARIANT);
4008**
4009** and the following statement to be compiled:
4010**
4011** SELECT c1 + 1, c1 FROM t1;
4012**
4013** this routine would return the string "VARIANT" for the second result
4014** column (i==1), and a NULL pointer for the first result column (i==0).)^
4015**
4016** ^SQLite uses dynamic run-time typing. ^So just because a column
4017** is declared to contain a particular type does not mean that the
4018** data stored in that column is of the declared type. SQLite is
4019** strongly typed, but the typing is dynamic not static. ^Type
4020** is associated with individual values, not with the containers
4021** used to hold those values.
4022*/
4023SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
4024SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
4025
4026/*
4027** CAPI3REF: Evaluate An SQL Statement
4028** METHOD: sqlite3_stmt
4029**
4030** After a [prepared statement] has been prepared using either
4031** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
4032** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
4033** must be called one or more times to evaluate the statement.
4034**
4035** The details of the behavior of the sqlite3_step() interface depend
4036** on whether the statement was prepared using the newer "v2" interface
4037** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
4038** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
4039** new "v2" interface is recommended for new applications but the legacy
4040** interface will continue to be supported.
4041**
4042** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
4043** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
4044** ^With the "v2" interface, any of the other [result codes] or
4045** [extended result codes] might be returned as well.
4046**
4047** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
4048** database locks it needs to do its job. ^If the statement is a [COMMIT]
4049** or occurs outside of an explicit transaction, then you can retry the
4050** statement. If the statement is not a [COMMIT] and occurs within an
4051** explicit transaction then you should rollback the transaction before
4052** continuing.
4053**
4054** ^[SQLITE_DONE] means that the statement has finished executing
4055** successfully. sqlite3_step() should not be called again on this virtual
4056** machine without first calling [sqlite3_reset()] to reset the virtual
4057** machine back to its initial state.
4058**
4059** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
4060** is returned each time a new row of data is ready for processing by the
4061** caller. The values may be accessed using the [column access functions].
4062** sqlite3_step() is called again to retrieve the next row of data.
4063**
4064** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
4065** violation) has occurred. sqlite3_step() should not be called again on
4066** the VM. More information may be found by calling [sqlite3_errmsg()].
4067** ^With the legacy interface, a more specific error code (for example,
4068** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
4069** can be obtained by calling [sqlite3_reset()] on the
4070** [prepared statement]. ^In the "v2" interface,
4071** the more specific error code is returned directly by sqlite3_step().
4072**
4073** [SQLITE_MISUSE] means that the this routine was called inappropriately.
4074** Perhaps it was called on a [prepared statement] that has
4075** already been [sqlite3_finalize | finalized] or on one that had
4076** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
4077** be the case that the same database connection is being used by two or
4078** more threads at the same moment in time.
4079**
4080** For all versions of SQLite up to and including 3.6.23.1, a call to
4081** [sqlite3_reset()] was required after sqlite3_step() returned anything
4082** other than [SQLITE_ROW] before any subsequent invocation of
4083** sqlite3_step(). Failure to reset the prepared statement using
4084** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
4085** sqlite3_step(). But after [version 3.6.23.1] ([dateof:3.6.23.1],
4086** sqlite3_step() began
4087** calling [sqlite3_reset()] automatically in this circumstance rather
4088** than returning [SQLITE_MISUSE]. This is not considered a compatibility
4089** break because any application that ever receives an SQLITE_MISUSE error
4090** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
4091** can be used to restore the legacy behavior.
4092**
4093** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
4094** API always returns a generic error code, [SQLITE_ERROR], following any
4095** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call
4096** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
4097** specific [error codes] that better describes the error.
4098** We admit that this is a goofy design. The problem has been fixed
4099** with the "v2" interface. If you prepare all of your SQL statements
4100** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
4101** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
4102** then the more specific [error codes] are returned directly
4103** by sqlite3_step(). The use of the "v2" interface is recommended.
4104*/
4105SQLITE_API int sqlite3_step(sqlite3_stmt*);
4106
4107/*
4108** CAPI3REF: Number of columns in a result set
4109** METHOD: sqlite3_stmt
4110**
4111** ^The sqlite3_data_count(P) interface returns the number of columns in the
4112** current row of the result set of [prepared statement] P.
4113** ^If prepared statement P does not have results ready to return
4114** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of
4115** interfaces) then sqlite3_data_count(P) returns 0.
4116** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
4117** ^The sqlite3_data_count(P) routine returns 0 if the previous call to
4118** [sqlite3_step](P) returned [SQLITE_DONE]. ^The sqlite3_data_count(P)
4119** will return non-zero if previous call to [sqlite3_step](P) returned
4120** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum]
4121** where it always returns zero since each step of that multi-step
4122** pragma returns 0 columns of data.
4123**
4124** See also: [sqlite3_column_count()]
4125*/
4126SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
4127
4128/*
4129** CAPI3REF: Fundamental Datatypes
4130** KEYWORDS: SQLITE_TEXT
4131**
4132** ^(Every value in SQLite has one of five fundamental datatypes:
4133**
4134** <ul>
4135** <li> 64-bit signed integer
4136** <li> 64-bit IEEE floating point number
4137** <li> string
4138** <li> BLOB
4139** <li> NULL
4140** </ul>)^
4141**
4142** These constants are codes for each of those types.
4143**
4144** Note that the SQLITE_TEXT constant was also used in SQLite version 2
4145** for a completely different meaning. Software that links against both
4146** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
4147** SQLITE_TEXT.
4148*/
4149#define SQLITE_INTEGER 1
4150#define SQLITE_FLOAT 2
4151#define SQLITE_BLOB 4
4152#define SQLITE_NULL 5
4153#ifdef SQLITE_TEXT
4154# undef SQLITE_TEXT
4155#else
4156# define SQLITE_TEXT 3
4157#endif
4158#define SQLITE3_TEXT 3
4159
4160/*
4161** CAPI3REF: Result Values From A Query
4162** KEYWORDS: {column access functions}
4163** METHOD: sqlite3_stmt
4164**
4165** ^These routines return information about a single column of the current
4166** result row of a query. ^In every case the first argument is a pointer
4167** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
4168** that was returned from [sqlite3_prepare_v2()] or one of its variants)
4169** and the second argument is the index of the column for which information
4170** should be returned. ^The leftmost column of the result set has the index 0.
4171** ^The number of columns in the result can be determined using
4172** [sqlite3_column_count()].
4173**
4174** If the SQL statement does not currently point to a valid row, or if the
4175** column index is out of range, the result is undefined.
4176** These routines may only be called when the most recent call to
4177** [sqlite3_step()] has returned [SQLITE_ROW] and neither
4178** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
4179** If any of these routines are called after [sqlite3_reset()] or
4180** [sqlite3_finalize()] or after [sqlite3_step()] has returned
4181** something other than [SQLITE_ROW], the results are undefined.
4182** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
4183** are called from a different thread while any of these routines
4184** are pending, then the results are undefined.
4185**
4186** ^The sqlite3_column_type() routine returns the
4187** [SQLITE_INTEGER | datatype code] for the initial data type
4188** of the result column. ^The returned value is one of [SQLITE_INTEGER],
4189** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value
4190** returned by sqlite3_column_type() is only meaningful if no type
4191** conversions have occurred as described below. After a type conversion,
4192** the value returned by sqlite3_column_type() is undefined. Future
4193** versions of SQLite may change the behavior of sqlite3_column_type()
4194** following a type conversion.
4195**
4196** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
4197** routine returns the number of bytes in that BLOB or string.
4198** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
4199** the string to UTF-8 and then returns the number of bytes.
4200** ^If the result is a numeric value then sqlite3_column_bytes() uses
4201** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
4202** the number of bytes in that string.
4203** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
4204**
4205** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
4206** routine returns the number of bytes in that BLOB or string.
4207** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
4208** the string to UTF-16 and then returns the number of bytes.
4209** ^If the result is a numeric value then sqlite3_column_bytes16() uses
4210** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
4211** the number of bytes in that string.
4212** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
4213**
4214** ^The values returned by [sqlite3_column_bytes()] and
4215** [sqlite3_column_bytes16()] do not include the zero terminators at the end
4216** of the string. ^For clarity: the values returned by
4217** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
4218** bytes in the string, not the number of characters.
4219**
4220** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
4221** even empty strings, are always zero-terminated. ^The return
4222** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
4223**
4224** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
4225** [unprotected sqlite3_value] object. In a multithreaded environment,
4226** an unprotected sqlite3_value object may only be used safely with
4227** [sqlite3_bind_value()] and [sqlite3_result_value()].
4228** If the [unprotected sqlite3_value] object returned by
4229** [sqlite3_column_value()] is used in any other way, including calls
4230** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
4231** or [sqlite3_value_bytes()], the behavior is not threadsafe.
4232**
4233** These routines attempt to convert the value where appropriate. ^For
4234** example, if the internal representation is FLOAT and a text result
4235** is requested, [sqlite3_snprintf()] is used internally to perform the
4236** conversion automatically. ^(The following table details the conversions
4237** that are applied:
4238**
4239** <blockquote>
4240** <table border="1">
4241** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion
4242**
4243** <tr><td> NULL <td> INTEGER <td> Result is 0
4244** <tr><td> NULL <td> FLOAT <td> Result is 0.0
4245** <tr><td> NULL <td> TEXT <td> Result is a NULL pointer
4246** <tr><td> NULL <td> BLOB <td> Result is a NULL pointer
4247** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
4248** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
4249** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
4250** <tr><td> FLOAT <td> INTEGER <td> [CAST] to INTEGER
4251** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
4252** <tr><td> FLOAT <td> BLOB <td> [CAST] to BLOB
4253** <tr><td> TEXT <td> INTEGER <td> [CAST] to INTEGER
4254** <tr><td> TEXT <td> FLOAT <td> [CAST] to REAL
4255** <tr><td> TEXT <td> BLOB <td> No change
4256** <tr><td> BLOB <td> INTEGER <td> [CAST] to INTEGER
4257** <tr><td> BLOB <td> FLOAT <td> [CAST] to REAL
4258** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
4259** </table>
4260** </blockquote>)^
4261**
4262** Note that when type conversions occur, pointers returned by prior
4263** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
4264** sqlite3_column_text16() may be invalidated.
4265** Type conversions and pointer invalidations might occur
4266** in the following cases:
4267**
4268** <ul>
4269** <li> The initial content is a BLOB and sqlite3_column_text() or
4270** sqlite3_column_text16() is called. A zero-terminator might
4271** need to be added to the string.</li>
4272** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
4273** sqlite3_column_text16() is called. The content must be converted
4274** to UTF-16.</li>
4275** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
4276** sqlite3_column_text() is called. The content must be converted
4277** to UTF-8.</li>
4278** </ul>
4279**
4280** ^Conversions between UTF-16be and UTF-16le are always done in place and do
4281** not invalidate a prior pointer, though of course the content of the buffer
4282** that the prior pointer references will have been modified. Other kinds
4283** of conversion are done in place when it is possible, but sometimes they
4284** are not possible and in those cases prior pointers are invalidated.
4285**
4286** The safest policy is to invoke these routines
4287** in one of the following ways:
4288**
4289** <ul>
4290** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
4291** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
4292** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
4293** </ul>
4294**
4295** In other words, you should call sqlite3_column_text(),
4296** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
4297** into the desired format, then invoke sqlite3_column_bytes() or
4298** sqlite3_column_bytes16() to find the size of the result. Do not mix calls
4299** to sqlite3_column_text() or sqlite3_column_blob() with calls to
4300** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
4301** with calls to sqlite3_column_bytes().
4302**
4303** ^The pointers returned are valid until a type conversion occurs as
4304** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
4305** [sqlite3_finalize()] is called. ^The memory space used to hold strings
4306** and BLOBs is freed automatically. Do <em>not</em> pass the pointers returned
4307** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
4308** [sqlite3_free()].
4309**
4310** ^(If a memory allocation error occurs during the evaluation of any
4311** of these routines, a default value is returned. The default value
4312** is either the integer 0, the floating point number 0.0, or a NULL
4313** pointer. Subsequent calls to [sqlite3_errcode()] will return
4314** [SQLITE_NOMEM].)^
4315*/
4316SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
4317SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
4318SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
4319SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
4320SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
4321SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
4322SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
4323SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
4324SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
4325SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
4326
4327/*
4328** CAPI3REF: Destroy A Prepared Statement Object
4329** DESTRUCTOR: sqlite3_stmt
4330**
4331** ^The sqlite3_finalize() function is called to delete a [prepared statement].
4332** ^If the most recent evaluation of the statement encountered no errors
4333** or if the statement is never been evaluated, then sqlite3_finalize() returns
4334** SQLITE_OK. ^If the most recent evaluation of statement S failed, then
4335** sqlite3_finalize(S) returns the appropriate [error code] or
4336** [extended error code].
4337**
4338** ^The sqlite3_finalize(S) routine can be called at any point during
4339** the life cycle of [prepared statement] S:
4340** before statement S is ever evaluated, after
4341** one or more calls to [sqlite3_reset()], or after any call
4342** to [sqlite3_step()] regardless of whether or not the statement has
4343** completed execution.
4344**
4345** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
4346**
4347** The application must finalize every [prepared statement] in order to avoid
4348** resource leaks. It is a grievous error for the application to try to use
4349** a prepared statement after it has been finalized. Any use of a prepared
4350** statement after it has been finalized can result in undefined and
4351** undesirable behavior such as segfaults and heap corruption.
4352*/
4353SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
4354
4355/*
4356** CAPI3REF: Reset A Prepared Statement Object
4357** METHOD: sqlite3_stmt
4358**
4359** The sqlite3_reset() function is called to reset a [prepared statement]
4360** object back to its initial state, ready to be re-executed.
4361** ^Any SQL statement variables that had values bound to them using
4362** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
4363** Use [sqlite3_clear_bindings()] to reset the bindings.
4364**
4365** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
4366** back to the beginning of its program.
4367**
4368** ^If the most recent call to [sqlite3_step(S)] for the
4369** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
4370** or if [sqlite3_step(S)] has never before been called on S,
4371** then [sqlite3_reset(S)] returns [SQLITE_OK].
4372**
4373** ^If the most recent call to [sqlite3_step(S)] for the
4374** [prepared statement] S indicated an error, then
4375** [sqlite3_reset(S)] returns an appropriate [error code].
4376**
4377** ^The [sqlite3_reset(S)] interface does not change the values
4378** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
4379*/
4380SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
4381
4382/*
4383** CAPI3REF: Create Or Redefine SQL Functions
4384** KEYWORDS: {function creation routines}
4385** KEYWORDS: {application-defined SQL function}
4386** KEYWORDS: {application-defined SQL functions}
4387** METHOD: sqlite3
4388**
4389** ^These functions (collectively known as "function creation routines")
4390** are used to add SQL functions or aggregates or to redefine the behavior
4391** of existing SQL functions or aggregates. The only differences between
4392** these routines are the text encoding expected for
4393** the second parameter (the name of the function being created)
4394** and the presence or absence of a destructor callback for
4395** the application data pointer.
4396**
4397** ^The first parameter is the [database connection] to which the SQL
4398** function is to be added. ^If an application uses more than one database
4399** connection then application-defined SQL functions must be added
4400** to each database connection separately.
4401**
4402** ^The second parameter is the name of the SQL function to be created or
4403** redefined. ^The length of the name is limited to 255 bytes in a UTF-8
4404** representation, exclusive of the zero-terminator. ^Note that the name
4405** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
4406** ^Any attempt to create a function with a longer name
4407** will result in [SQLITE_MISUSE] being returned.
4408**
4409** ^The third parameter (nArg)
4410** is the number of arguments that the SQL function or
4411** aggregate takes. ^If this parameter is -1, then the SQL function or
4412** aggregate may take any number of arguments between 0 and the limit
4413** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third
4414** parameter is less than -1 or greater than 127 then the behavior is
4415** undefined.
4416**
4417** ^The fourth parameter, eTextRep, specifies what
4418** [SQLITE_UTF8 | text encoding] this SQL function prefers for
4419** its parameters. The application should set this parameter to
4420** [SQLITE_UTF16LE] if the function implementation invokes
4421** [sqlite3_value_text16le()] on an input, or [SQLITE_UTF16BE] if the
4422** implementation invokes [sqlite3_value_text16be()] on an input, or
4423** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8]
4424** otherwise. ^The same SQL function may be registered multiple times using
4425** different preferred text encodings, with different implementations for
4426** each encoding.
4427** ^When multiple implementations of the same function are available, SQLite
4428** will pick the one that involves the least amount of data conversion.
4429**
4430** ^The fourth parameter may optionally be ORed with [SQLITE_DETERMINISTIC]
4431** to signal that the function will always return the same result given
4432** the same inputs within a single SQL statement. Most SQL functions are
4433** deterministic. The built-in [random()] SQL function is an example of a
4434** function that is not deterministic. The SQLite query planner is able to
4435** perform additional optimizations on deterministic functions, so use
4436** of the [SQLITE_DETERMINISTIC] flag is recommended where possible.
4437**
4438** ^(The fifth parameter is an arbitrary pointer. The implementation of the
4439** function can gain access to this pointer using [sqlite3_user_data()].)^
4440**
4441** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are
4442** pointers to C-language functions that implement the SQL function or
4443** aggregate. ^A scalar SQL function requires an implementation of the xFunc
4444** callback only; NULL pointers must be passed as the xStep and xFinal
4445** parameters. ^An aggregate SQL function requires an implementation of xStep
4446** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
4447** SQL function or aggregate, pass NULL pointers for all three function
4448** callbacks.
4449**
4450** ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL,
4451** then it is destructor for the application data pointer.
4452** The destructor is invoked when the function is deleted, either by being
4453** overloaded or when the database connection closes.)^
4454** ^The destructor is also invoked if the call to
4455** sqlite3_create_function_v2() fails.
4456** ^When the destructor callback of the tenth parameter is invoked, it
4457** is passed a single argument which is a copy of the application data
4458** pointer which was the fifth parameter to sqlite3_create_function_v2().
4459**
4460** ^It is permitted to register multiple implementations of the same
4461** functions with the same name but with either differing numbers of
4462** arguments or differing preferred text encodings. ^SQLite will use
4463** the implementation that most closely matches the way in which the
4464** SQL function is used. ^A function implementation with a non-negative
4465** nArg parameter is a better match than a function implementation with
4466** a negative nArg. ^A function where the preferred text encoding
4467** matches the database encoding is a better
4468** match than a function where the encoding is different.
4469** ^A function where the encoding difference is between UTF16le and UTF16be
4470** is a closer match than a function where the encoding difference is
4471** between UTF8 and UTF16.
4472**
4473** ^Built-in functions may be overloaded by new application-defined functions.
4474**
4475** ^An application-defined function is permitted to call other
4476** SQLite interfaces. However, such calls must not
4477** close the database connection nor finalize or reset the prepared
4478** statement in which the function is running.
4479*/
4480SQLITE_API int sqlite3_create_function(
4481 sqlite3 *db,
4482 const char *zFunctionName,
4483 int nArg,
4484 int eTextRep,
4485 void *pApp,
4486 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
4487 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
4488 void (*xFinal)(sqlite3_context*)
4489);
4490SQLITE_API int sqlite3_create_function16(
4491 sqlite3 *db,
4492 const void *zFunctionName,
4493 int nArg,
4494 int eTextRep,
4495 void *pApp,
4496 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
4497 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
4498 void (*xFinal)(sqlite3_context*)
4499);
4500SQLITE_API int sqlite3_create_function_v2(
4501 sqlite3 *db,
4502 const char *zFunctionName,
4503 int nArg,
4504 int eTextRep,
4505 void *pApp,
4506 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
4507 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
4508 void (*xFinal)(sqlite3_context*),
4509 void(*xDestroy)(void*)
4510);
4511
4512/*
4513** CAPI3REF: Text Encodings
4514**
4515** These constant define integer codes that represent the various
4516** text encodings supported by SQLite.
4517*/
4518#define SQLITE_UTF8 1 /* IMP: R-37514-35566 */
4519#define SQLITE_UTF16LE 2 /* IMP: R-03371-37637 */
4520#define SQLITE_UTF16BE 3 /* IMP: R-51971-34154 */
4521#define SQLITE_UTF16 4 /* Use native byte order */
4522#define SQLITE_ANY 5 /* Deprecated */
4523#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
4524
4525/*
4526** CAPI3REF: Function Flags
4527**
4528** These constants may be ORed together with the
4529** [SQLITE_UTF8 | preferred text encoding] as the fourth argument
4530** to [sqlite3_create_function()], [sqlite3_create_function16()], or
4531** [sqlite3_create_function_v2()].
4532*/
4533#define SQLITE_DETERMINISTIC 0x800
4534
4535/*
4536** CAPI3REF: Deprecated Functions
4537** DEPRECATED
4538**
4539** These functions are [deprecated]. In order to maintain
4540** backwards compatibility with older code, these functions continue
4541** to be supported. However, new applications should avoid
4542** the use of these functions. To encourage programmers to avoid
4543** these functions, we will not explain what they do.
4544*/
4545#ifndef SQLITE_OMIT_DEPRECATED
4546SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
4547SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
4548SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
4549SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
4550SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
4551SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
4552 void*,sqlite3_int64);
4553#endif
4554
4555/*
4556** CAPI3REF: Obtaining SQL Values
4557** METHOD: sqlite3_value
4558**
4559** The C-language implementation of SQL functions and aggregates uses
4560** this set of interface routines to access the parameter values on
4561** the function or aggregate.
4562**
4563** The xFunc (for scalar functions) or xStep (for aggregates) parameters
4564** to [sqlite3_create_function()] and [sqlite3_create_function16()]
4565** define callbacks that implement the SQL functions and aggregates.
4566** The 3rd parameter to these callbacks is an array of pointers to
4567** [protected sqlite3_value] objects. There is one [sqlite3_value] object for
4568** each parameter to the SQL function. These routines are used to
4569** extract values from the [sqlite3_value] objects.
4570**
4571** These routines work only with [protected sqlite3_value] objects.
4572** Any attempt to use these routines on an [unprotected sqlite3_value]
4573** object results in undefined behavior.
4574**
4575** ^These routines work just like the corresponding [column access functions]
4576** except that these routines take a single [protected sqlite3_value] object
4577** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
4578**
4579** ^The sqlite3_value_text16() interface extracts a UTF-16 string
4580** in the native byte-order of the host machine. ^The
4581** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
4582** extract UTF-16 strings as big-endian and little-endian respectively.
4583**
4584** ^(The sqlite3_value_numeric_type() interface attempts to apply
4585** numeric affinity to the value. This means that an attempt is
4586** made to convert the value to an integer or floating point. If
4587** such a conversion is possible without loss of information (in other
4588** words, if the value is a string that looks like a number)
4589** then the conversion is performed. Otherwise no conversion occurs.
4590** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
4591**
4592** Please pay particular attention to the fact that the pointer returned
4593** from [sqlite3_value_blob()], [sqlite3_value_text()], or
4594** [sqlite3_value_text16()] can be invalidated by a subsequent call to
4595** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
4596** or [sqlite3_value_text16()].
4597**
4598** These routines must be called from the same thread as
4599** the SQL function that supplied the [sqlite3_value*] parameters.
4600*/
4601SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
4602SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
4603SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
4604SQLITE_API double sqlite3_value_double(sqlite3_value*);
4605SQLITE_API int sqlite3_value_int(sqlite3_value*);
4606SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
4607SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
4608SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
4609SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
4610SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
4611SQLITE_API int sqlite3_value_type(sqlite3_value*);
4612SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
4613
4614/*
4615** CAPI3REF: Finding The Subtype Of SQL Values
4616** METHOD: sqlite3_value
4617**
4618** The sqlite3_value_subtype(V) function returns the subtype for
4619** an [application-defined SQL function] argument V. The subtype
4620** information can be used to pass a limited amount of context from
4621** one SQL function to another. Use the [sqlite3_result_subtype()]
4622** routine to set the subtype for the return value of an SQL function.
4623**
4624** SQLite makes no use of subtype itself. It merely passes the subtype
4625** from the result of one [application-defined SQL function] into the
4626** input of another.
4627*/
4628SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*);
4629
4630/*
4631** CAPI3REF: Copy And Free SQL Values
4632** METHOD: sqlite3_value
4633**
4634** ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value]
4635** object D and returns a pointer to that copy. ^The [sqlite3_value] returned
4636** is a [protected sqlite3_value] object even if the input is not.
4637** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
4638** memory allocation fails.
4639**
4640** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object
4641** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer
4642** then sqlite3_value_free(V) is a harmless no-op.
4643*/
4644SQLITE_API sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
4645SQLITE_API void sqlite3_value_free(sqlite3_value*);
4646
4647/*
4648** CAPI3REF: Obtain Aggregate Function Context
4649** METHOD: sqlite3_context
4650**
4651** Implementations of aggregate SQL functions use this
4652** routine to allocate memory for storing their state.
4653**
4654** ^The first time the sqlite3_aggregate_context(C,N) routine is called
4655** for a particular aggregate function, SQLite
4656** allocates N of memory, zeroes out that memory, and returns a pointer
4657** to the new memory. ^On second and subsequent calls to
4658** sqlite3_aggregate_context() for the same aggregate function instance,
4659** the same buffer is returned. Sqlite3_aggregate_context() is normally
4660** called once for each invocation of the xStep callback and then one
4661** last time when the xFinal callback is invoked. ^(When no rows match
4662** an aggregate query, the xStep() callback of the aggregate function
4663** implementation is never called and xFinal() is called exactly once.
4664** In those cases, sqlite3_aggregate_context() might be called for the
4665** first time from within xFinal().)^
4666**
4667** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer
4668** when first called if N is less than or equal to zero or if a memory
4669** allocate error occurs.
4670**
4671** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
4672** determined by the N parameter on first successful call. Changing the
4673** value of N in subsequent call to sqlite3_aggregate_context() within
4674** the same aggregate function instance will not resize the memory
4675** allocation.)^ Within the xFinal callback, it is customary to set
4676** N=0 in calls to sqlite3_aggregate_context(C,N) so that no
4677** pointless memory allocations occur.
4678**
4679** ^SQLite automatically frees the memory allocated by
4680** sqlite3_aggregate_context() when the aggregate query concludes.
4681**
4682** The first parameter must be a copy of the
4683** [sqlite3_context | SQL function context] that is the first parameter
4684** to the xStep or xFinal callback routine that implements the aggregate
4685** function.
4686**
4687** This routine must be called from the same thread in which
4688** the aggregate SQL function is running.
4689*/
4690SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
4691
4692/*
4693** CAPI3REF: User Data For Functions
4694** METHOD: sqlite3_context
4695**
4696** ^The sqlite3_user_data() interface returns a copy of
4697** the pointer that was the pUserData parameter (the 5th parameter)
4698** of the [sqlite3_create_function()]
4699** and [sqlite3_create_function16()] routines that originally
4700** registered the application defined function.
4701**
4702** This routine must be called from the same thread in which
4703** the application-defined function is running.
4704*/
4705SQLITE_API void *sqlite3_user_data(sqlite3_context*);
4706
4707/*
4708** CAPI3REF: Database Connection For Functions
4709** METHOD: sqlite3_context
4710**
4711** ^The sqlite3_context_db_handle() interface returns a copy of
4712** the pointer to the [database connection] (the 1st parameter)
4713** of the [sqlite3_create_function()]
4714** and [sqlite3_create_function16()] routines that originally
4715** registered the application defined function.
4716*/
4717SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
4718
4719/*
4720** CAPI3REF: Function Auxiliary Data
4721** METHOD: sqlite3_context
4722**
4723** These functions may be used by (non-aggregate) SQL functions to
4724** associate metadata with argument values. If the same value is passed to
4725** multiple invocations of the same SQL function during query execution, under
4726** some circumstances the associated metadata may be preserved. An example
4727** of where this might be useful is in a regular-expression matching
4728** function. The compiled version of the regular expression can be stored as
4729** metadata associated with the pattern string.
4730** Then as long as the pattern string remains the same,
4731** the compiled regular expression can be reused on multiple
4732** invocations of the same function.
4733**
4734** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata
4735** associated by the sqlite3_set_auxdata() function with the Nth argument
4736** value to the application-defined function. ^If there is no metadata
4737** associated with the function argument, this sqlite3_get_auxdata() interface
4738** returns a NULL pointer.
4739**
4740** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th
4741** argument of the application-defined function. ^Subsequent
4742** calls to sqlite3_get_auxdata(C,N) return P from the most recent
4743** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or
4744** NULL if the metadata has been discarded.
4745** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
4746** SQLite will invoke the destructor function X with parameter P exactly
4747** once, when the metadata is discarded.
4748** SQLite is free to discard the metadata at any time, including: <ul>
4749** <li> ^(when the corresponding function parameter changes)^, or
4750** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
4751** SQL statement)^, or
4752** <li> ^(when sqlite3_set_auxdata() is invoked again on the same
4753** parameter)^, or
4754** <li> ^(during the original sqlite3_set_auxdata() call when a memory
4755** allocation error occurs.)^ </ul>
4756**
4757** Note the last bullet in particular. The destructor X in
4758** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
4759** sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata()
4760** should be called near the end of the function implementation and the
4761** function implementation should not make any use of P after
4762** sqlite3_set_auxdata() has been called.
4763**
4764** ^(In practice, metadata is preserved between function calls for
4765** function parameters that are compile-time constants, including literal
4766** values and [parameters] and expressions composed from the same.)^
4767**
4768** These routines must be called from the same thread in which
4769** the SQL function is running.
4770*/
4771SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
4772SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
4773
4774
4775/*
4776** CAPI3REF: Constants Defining Special Destructor Behavior
4777**
4778** These are special values for the destructor that is passed in as the
4779** final argument to routines like [sqlite3_result_blob()]. ^If the destructor
4780** argument is SQLITE_STATIC, it means that the content pointer is constant
4781** and will never change. It does not need to be destroyed. ^The
4782** SQLITE_TRANSIENT value means that the content will likely change in
4783** the near future and that SQLite should make its own private copy of
4784** the content before returning.
4785**
4786** The typedef is necessary to work around problems in certain
4787** C++ compilers.
4788*/
4789typedef void (*sqlite3_destructor_type)(void*);
4790#define SQLITE_STATIC ((sqlite3_destructor_type)0)
4791#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
4792
4793/*
4794** CAPI3REF: Setting The Result Of An SQL Function
4795** METHOD: sqlite3_context
4796**
4797** These routines are used by the xFunc or xFinal callbacks that
4798** implement SQL functions and aggregates. See
4799** [sqlite3_create_function()] and [sqlite3_create_function16()]
4800** for additional information.
4801**
4802** These functions work very much like the [parameter binding] family of
4803** functions used to bind values to host parameters in prepared statements.
4804** Refer to the [SQL parameter] documentation for additional information.
4805**
4806** ^The sqlite3_result_blob() interface sets the result from
4807** an application-defined function to be the BLOB whose content is pointed
4808** to by the second parameter and which is N bytes long where N is the
4809** third parameter.
4810**
4811** ^The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
4812** interfaces set the result of the application-defined function to be
4813** a BLOB containing all zero bytes and N bytes in size.
4814**
4815** ^The sqlite3_result_double() interface sets the result from
4816** an application-defined function to be a floating point value specified
4817** by its 2nd argument.
4818**
4819** ^The sqlite3_result_error() and sqlite3_result_error16() functions
4820** cause the implemented SQL function to throw an exception.
4821** ^SQLite uses the string pointed to by the
4822** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
4823** as the text of an error message. ^SQLite interprets the error
4824** message string from sqlite3_result_error() as UTF-8. ^SQLite
4825** interprets the string from sqlite3_result_error16() as UTF-16 in native
4826** byte order. ^If the third parameter to sqlite3_result_error()
4827** or sqlite3_result_error16() is negative then SQLite takes as the error
4828** message all text up through the first zero character.
4829** ^If the third parameter to sqlite3_result_error() or
4830** sqlite3_result_error16() is non-negative then SQLite takes that many
4831** bytes (not characters) from the 2nd parameter as the error message.
4832** ^The sqlite3_result_error() and sqlite3_result_error16()
4833** routines make a private copy of the error message text before
4834** they return. Hence, the calling function can deallocate or
4835** modify the text after they return without harm.
4836** ^The sqlite3_result_error_code() function changes the error code
4837** returned by SQLite as a result of an error in a function. ^By default,
4838** the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error()
4839** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
4840**
4841** ^The sqlite3_result_error_toobig() interface causes SQLite to throw an
4842** error indicating that a string or BLOB is too long to represent.
4843**
4844** ^The sqlite3_result_error_nomem() interface causes SQLite to throw an
4845** error indicating that a memory allocation failed.
4846**
4847** ^The sqlite3_result_int() interface sets the return value
4848** of the application-defined function to be the 32-bit signed integer
4849** value given in the 2nd argument.
4850** ^The sqlite3_result_int64() interface sets the return value
4851** of the application-defined function to be the 64-bit signed integer
4852** value given in the 2nd argument.
4853**
4854** ^The sqlite3_result_null() interface sets the return value
4855** of the application-defined function to be NULL.
4856**
4857** ^The sqlite3_result_text(), sqlite3_result_text16(),
4858** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
4859** set the return value of the application-defined function to be
4860** a text string which is represented as UTF-8, UTF-16 native byte order,
4861** UTF-16 little endian, or UTF-16 big endian, respectively.
4862** ^The sqlite3_result_text64() interface sets the return value of an
4863** application-defined function to be a text string in an encoding
4864** specified by the fifth (and last) parameter, which must be one
4865** of [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE].
4866** ^SQLite takes the text result from the application from
4867** the 2nd parameter of the sqlite3_result_text* interfaces.
4868** ^If the 3rd parameter to the sqlite3_result_text* interfaces
4869** is negative, then SQLite takes result text from the 2nd parameter
4870** through the first zero character.
4871** ^If the 3rd parameter to the sqlite3_result_text* interfaces
4872** is non-negative, then as many bytes (not characters) of the text
4873** pointed to by the 2nd parameter are taken as the application-defined
4874** function result. If the 3rd parameter is non-negative, then it
4875** must be the byte offset into the string where the NUL terminator would
4876** appear if the string where NUL terminated. If any NUL characters occur
4877** in the string at a byte offset that is less than the value of the 3rd
4878** parameter, then the resulting string will contain embedded NULs and the
4879** result of expressions operating on strings with embedded NULs is undefined.
4880** ^If the 4th parameter to the sqlite3_result_text* interfaces
4881** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
4882** function as the destructor on the text or BLOB result when it has
4883** finished using that result.
4884** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
4885** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
4886** assumes that the text or BLOB result is in constant space and does not
4887** copy the content of the parameter nor call a destructor on the content
4888** when it has finished using that result.
4889** ^If the 4th parameter to the sqlite3_result_text* interfaces
4890** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
4891** then SQLite makes a copy of the result into space obtained from
4892** from [sqlite3_malloc()] before it returns.
4893**
4894** ^The sqlite3_result_value() interface sets the result of
4895** the application-defined function to be a copy of the
4896** [unprotected sqlite3_value] object specified by the 2nd parameter. ^The
4897** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
4898** so that the [sqlite3_value] specified in the parameter may change or
4899** be deallocated after sqlite3_result_value() returns without harm.
4900** ^A [protected sqlite3_value] object may always be used where an
4901** [unprotected sqlite3_value] object is required, so either
4902** kind of [sqlite3_value] object can be used with this interface.
4903**
4904** If these routines are called from within the different thread
4905** than the one containing the application-defined function that received
4906** the [sqlite3_context] pointer, the results are undefined.
4907*/
4908SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
4909SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*,
4910 sqlite3_uint64,void(*)(void*));
4911SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
4912SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
4913SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
4914SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
4915SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
4916SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
4917SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
4918SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
4919SQLITE_API void sqlite3_result_null(sqlite3_context*);
4920SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
4921SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64,
4922 void(*)(void*), unsigned char encoding);
4923SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
4924SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
4925SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
4926SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
4927SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
4928SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
4929
4930
4931/*
4932** CAPI3REF: Setting The Subtype Of An SQL Function
4933** METHOD: sqlite3_context
4934**
4935** The sqlite3_result_subtype(C,T) function causes the subtype of
4936** the result from the [application-defined SQL function] with
4937** [sqlite3_context] C to be the value T. Only the lower 8 bits
4938** of the subtype T are preserved in current versions of SQLite;
4939** higher order bits are discarded.
4940** The number of subtype bytes preserved by SQLite might increase
4941** in future releases of SQLite.
4942*/
4943SQLITE_API void sqlite3_result_subtype(sqlite3_context*,unsigned int);
4944
4945/*
4946** CAPI3REF: Define New Collating Sequences
4947** METHOD: sqlite3
4948**
4949** ^These functions add, remove, or modify a [collation] associated
4950** with the [database connection] specified as the first argument.
4951**
4952** ^The name of the collation is a UTF-8 string
4953** for sqlite3_create_collation() and sqlite3_create_collation_v2()
4954** and a UTF-16 string in native byte order for sqlite3_create_collation16().
4955** ^Collation names that compare equal according to [sqlite3_strnicmp()] are
4956** considered to be the same name.
4957**
4958** ^(The third argument (eTextRep) must be one of the constants:
4959** <ul>
4960** <li> [SQLITE_UTF8],
4961** <li> [SQLITE_UTF16LE],
4962** <li> [SQLITE_UTF16BE],
4963** <li> [SQLITE_UTF16], or
4964** <li> [SQLITE_UTF16_ALIGNED].
4965** </ul>)^
4966** ^The eTextRep argument determines the encoding of strings passed
4967** to the collating function callback, xCallback.
4968** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep
4969** force strings to be UTF16 with native byte order.
4970** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin
4971** on an even byte address.
4972**
4973** ^The fourth argument, pArg, is an application data pointer that is passed
4974** through as the first argument to the collating function callback.
4975**
4976** ^The fifth argument, xCallback, is a pointer to the collating function.
4977** ^Multiple collating functions can be registered using the same name but
4978** with different eTextRep parameters and SQLite will use whichever
4979** function requires the least amount of data transformation.
4980** ^If the xCallback argument is NULL then the collating function is
4981** deleted. ^When all collating functions having the same name are deleted,
4982** that collation is no longer usable.
4983**
4984** ^The collating function callback is invoked with a copy of the pArg
4985** application data pointer and with two strings in the encoding specified
4986** by the eTextRep argument. The collating function must return an
4987** integer that is negative, zero, or positive
4988** if the first string is less than, equal to, or greater than the second,
4989** respectively. A collating function must always return the same answer
4990** given the same inputs. If two or more collating functions are registered
4991** to the same collation name (using different eTextRep values) then all
4992** must give an equivalent answer when invoked with equivalent strings.
4993** The collating function must obey the following properties for all
4994** strings A, B, and C:
4995**
4996** <ol>
4997** <li> If A==B then B==A.
4998** <li> If A==B and B==C then A==C.
4999** <li> If A<B THEN B>A.
5000** <li> If A<B and B<C then A<C.
5001** </ol>
5002**
5003** If a collating function fails any of the above constraints and that
5004** collating function is registered and used, then the behavior of SQLite
5005** is undefined.
5006**
5007** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
5008** with the addition that the xDestroy callback is invoked on pArg when
5009** the collating function is deleted.
5010** ^Collating functions are deleted when they are overridden by later
5011** calls to the collation creation functions or when the
5012** [database connection] is closed using [sqlite3_close()].
5013**
5014** ^The xDestroy callback is <u>not</u> called if the
5015** sqlite3_create_collation_v2() function fails. Applications that invoke
5016** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
5017** check the return code and dispose of the application data pointer
5018** themselves rather than expecting SQLite to deal with it for them.
5019** This is different from every other SQLite interface. The inconsistency
5020** is unfortunate but cannot be changed without breaking backwards
5021** compatibility.
5022**
5023** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
5024*/
5025SQLITE_API int sqlite3_create_collation(
5026 sqlite3*,
5027 const char *zName,
5028 int eTextRep,
5029 void *pArg,
5030 int(*xCompare)(void*,int,const void*,int,const void*)
5031);
5032SQLITE_API int sqlite3_create_collation_v2(
5033 sqlite3*,
5034 const char *zName,
5035 int eTextRep,
5036 void *pArg,
5037 int(*xCompare)(void*,int,const void*,int,const void*),
5038 void(*xDestroy)(void*)
5039);
5040SQLITE_API int sqlite3_create_collation16(
5041 sqlite3*,
5042 const void *zName,
5043 int eTextRep,
5044 void *pArg,
5045 int(*xCompare)(void*,int,const void*,int,const void*)
5046);
5047
5048/*
5049** CAPI3REF: Collation Needed Callbacks
5050** METHOD: sqlite3
5051**
5052** ^To avoid having to register all collation sequences before a database
5053** can be used, a single callback function may be registered with the
5054** [database connection] to be invoked whenever an undefined collation
5055** sequence is required.
5056**
5057** ^If the function is registered using the sqlite3_collation_needed() API,
5058** then it is passed the names of undefined collation sequences as strings
5059** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
5060** the names are passed as UTF-16 in machine native byte order.
5061** ^A call to either function replaces the existing collation-needed callback.
5062**
5063** ^(When the callback is invoked, the first argument passed is a copy
5064** of the second argument to sqlite3_collation_needed() or
5065** sqlite3_collation_needed16(). The second argument is the database
5066** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
5067** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
5068** sequence function required. The fourth parameter is the name of the
5069** required collation sequence.)^
5070**
5071** The callback function should register the desired collation using
5072** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
5073** [sqlite3_create_collation_v2()].
5074*/
5075SQLITE_API int sqlite3_collation_needed(
5076 sqlite3*,
5077 void*,
5078 void(*)(void*,sqlite3*,int eTextRep,const char*)
5079);
5080SQLITE_API int sqlite3_collation_needed16(
5081 sqlite3*,
5082 void*,
5083 void(*)(void*,sqlite3*,int eTextRep,const void*)
5084);
5085
5086#ifdef SQLITE_HAS_CODEC
5087/*
5088** Specify the key for an encrypted database. This routine should be
5089** called right after sqlite3_open().
5090**
5091** The code to implement this API is not available in the public release
5092** of SQLite.
5093*/
5094SQLITE_API int sqlite3_key(
5095 sqlite3 *db, /* Database to be rekeyed */
5096 const void *pKey, int nKey /* The key */
5097);
5098SQLITE_API int sqlite3_key_v2(
5099 sqlite3 *db, /* Database to be rekeyed */
5100 const char *zDbName, /* Name of the database */
5101 const void *pKey, int nKey /* The key */
5102);
5103
5104/*
5105** Change the key on an open database. If the current database is not
5106** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
5107** database is decrypted.
5108**
5109** The code to implement this API is not available in the public release
5110** of SQLite.
5111*/
5112SQLITE_API int sqlite3_rekey(
5113 sqlite3 *db, /* Database to be rekeyed */
5114 const void *pKey, int nKey /* The new key */
5115);
5116SQLITE_API int sqlite3_rekey_v2(
5117 sqlite3 *db, /* Database to be rekeyed */
5118 const char *zDbName, /* Name of the database */
5119 const void *pKey, int nKey /* The new key */
5120);
5121
5122/*
5123** Specify the activation key for a SEE database. Unless
5124** activated, none of the SEE routines will work.
5125*/
5126SQLITE_API void sqlite3_activate_see(
5127 const char *zPassPhrase /* Activation phrase */
5128);
5129#endif
5130
5131#ifdef SQLITE_ENABLE_CEROD
5132/*
5133** Specify the activation key for a CEROD database. Unless
5134** activated, none of the CEROD routines will work.
5135*/
5136SQLITE_API void sqlite3_activate_cerod(
5137 const char *zPassPhrase /* Activation phrase */
5138);
5139#endif
5140
5141/*
5142** CAPI3REF: Suspend Execution For A Short Time
5143**
5144** The sqlite3_sleep() function causes the current thread to suspend execution
5145** for at least a number of milliseconds specified in its parameter.
5146**
5147** If the operating system does not support sleep requests with
5148** millisecond time resolution, then the time will be rounded up to
5149** the nearest second. The number of milliseconds of sleep actually
5150** requested from the operating system is returned.
5151**
5152** ^SQLite implements this interface by calling the xSleep()
5153** method of the default [sqlite3_vfs] object. If the xSleep() method
5154** of the default VFS is not implemented correctly, or not implemented at
5155** all, then the behavior of sqlite3_sleep() may deviate from the description
5156** in the previous paragraphs.
5157*/
5158SQLITE_API int sqlite3_sleep(int);
5159
5160/*
5161** CAPI3REF: Name Of The Folder Holding Temporary Files
5162**
5163** ^(If this global variable is made to point to a string which is
5164** the name of a folder (a.k.a. directory), then all temporary files
5165** created by SQLite when using a built-in [sqlite3_vfs | VFS]
5166** will be placed in that directory.)^ ^If this variable
5167** is a NULL pointer, then SQLite performs a search for an appropriate
5168** temporary file directory.
5169**
5170** Applications are strongly discouraged from using this global variable.
5171** It is required to set a temporary folder on Windows Runtime (WinRT).
5172** But for all other platforms, it is highly recommended that applications
5173** neither read nor write this variable. This global variable is a relic
5174** that exists for backwards compatibility of legacy applications and should
5175** be avoided in new projects.
5176**
5177** It is not safe to read or modify this variable in more than one
5178** thread at a time. It is not safe to read or modify this variable
5179** if a [database connection] is being used at the same time in a separate
5180** thread.
5181** It is intended that this variable be set once
5182** as part of process initialization and before any SQLite interface
5183** routines have been called and that this variable remain unchanged
5184** thereafter.
5185**
5186** ^The [temp_store_directory pragma] may modify this variable and cause
5187** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore,
5188** the [temp_store_directory pragma] always assumes that any string
5189** that this variable points to is held in memory obtained from
5190** [sqlite3_malloc] and the pragma may attempt to free that memory
5191** using [sqlite3_free].
5192** Hence, if this variable is modified directly, either it should be
5193** made NULL or made to point to memory obtained from [sqlite3_malloc]
5194** or else the use of the [temp_store_directory pragma] should be avoided.
5195** Except when requested by the [temp_store_directory pragma], SQLite
5196** does not free the memory that sqlite3_temp_directory points to. If
5197** the application wants that memory to be freed, it must do
5198** so itself, taking care to only do so after all [database connection]
5199** objects have been destroyed.
5200**
5201** <b>Note to Windows Runtime users:</b> The temporary directory must be set
5202** prior to calling [sqlite3_open] or [sqlite3_open_v2]. Otherwise, various
5203** features that require the use of temporary files may fail. Here is an
5204** example of how to do this using C++ with the Windows Runtime:
5205**
5206** <blockquote><pre>
5207** LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
5208** TemporaryFolder->Path->Data();
5209** char zPathBuf[MAX_PATH + 1];
5210** memset(zPathBuf, 0, sizeof(zPathBuf));
5211** WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
5212** NULL, NULL);
5213** sqlite3_temp_directory = sqlite3_mprintf("%s", zPathBuf);
5214** </pre></blockquote>
5215*/
5216SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;
5217
5218/*
5219** CAPI3REF: Name Of The Folder Holding Database Files
5220**
5221** ^(If this global variable is made to point to a string which is
5222** the name of a folder (a.k.a. directory), then all database files
5223** specified with a relative pathname and created or accessed by
5224** SQLite when using a built-in windows [sqlite3_vfs | VFS] will be assumed
5225** to be relative to that directory.)^ ^If this variable is a NULL
5226** pointer, then SQLite assumes that all database files specified
5227** with a relative pathname are relative to the current directory
5228** for the process. Only the windows VFS makes use of this global
5229** variable; it is ignored by the unix VFS.
5230**
5231** Changing the value of this variable while a database connection is
5232** open can result in a corrupt database.
5233**
5234** It is not safe to read or modify this variable in more than one
5235** thread at a time. It is not safe to read or modify this variable
5236** if a [database connection] is being used at the same time in a separate
5237** thread.
5238** It is intended that this variable be set once
5239** as part of process initialization and before any SQLite interface
5240** routines have been called and that this variable remain unchanged
5241** thereafter.
5242**
5243** ^The [data_store_directory pragma] may modify this variable and cause
5244** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore,
5245** the [data_store_directory pragma] always assumes that any string
5246** that this variable points to is held in memory obtained from
5247** [sqlite3_malloc] and the pragma may attempt to free that memory
5248** using [sqlite3_free].
5249** Hence, if this variable is modified directly, either it should be
5250** made NULL or made to point to memory obtained from [sqlite3_malloc]
5251** or else the use of the [data_store_directory pragma] should be avoided.
5252*/
5253SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory;
5254
5255/*
5256** CAPI3REF: Test For Auto-Commit Mode
5257** KEYWORDS: {autocommit mode}
5258** METHOD: sqlite3
5259**
5260** ^The sqlite3_get_autocommit() interface returns non-zero or
5261** zero if the given database connection is or is not in autocommit mode,
5262** respectively. ^Autocommit mode is on by default.
5263** ^Autocommit mode is disabled by a [BEGIN] statement.
5264** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
5265**
5266** If certain kinds of errors occur on a statement within a multi-statement
5267** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],
5268** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
5269** transaction might be rolled back automatically. The only way to
5270** find out whether SQLite automatically rolled back the transaction after
5271** an error is to use this function.
5272**
5273** If another thread changes the autocommit status of the database
5274** connection while this routine is running, then the return value
5275** is undefined.
5276*/
5277SQLITE_API int sqlite3_get_autocommit(sqlite3*);
5278
5279/*
5280** CAPI3REF: Find The Database Handle Of A Prepared Statement
5281** METHOD: sqlite3_stmt
5282**
5283** ^The sqlite3_db_handle interface returns the [database connection] handle
5284** to which a [prepared statement] belongs. ^The [database connection]
5285** returned by sqlite3_db_handle is the same [database connection]
5286** that was the first argument
5287** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
5288** create the statement in the first place.
5289*/
5290SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
5291
5292/*
5293** CAPI3REF: Return The Filename For A Database Connection
5294** METHOD: sqlite3
5295**
5296** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename
5297** associated with database N of connection D. ^The main database file
5298** has the name "main". If there is no attached database N on the database
5299** connection D, or if database N is a temporary or in-memory database, then
5300** a NULL pointer is returned.
5301**
5302** ^The filename returned by this function is the output of the
5303** xFullPathname method of the [VFS]. ^In other words, the filename
5304** will be an absolute pathname, even if the filename used
5305** to open the database originally was a URI or relative pathname.
5306*/
5307SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName);
5308
5309/*
5310** CAPI3REF: Determine if a database is read-only
5311** METHOD: sqlite3
5312**
5313** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N
5314** of connection D is read-only, 0 if it is read/write, or -1 if N is not
5315** the name of a database on connection D.
5316*/
5317SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
5318
5319/*
5320** CAPI3REF: Find the next prepared statement
5321** METHOD: sqlite3
5322**
5323** ^This interface returns a pointer to the next [prepared statement] after
5324** pStmt associated with the [database connection] pDb. ^If pStmt is NULL
5325** then this interface returns a pointer to the first prepared statement
5326** associated with the database connection pDb. ^If no prepared statement
5327** satisfies the conditions of this routine, it returns NULL.
5328**
5329** The [database connection] pointer D in a call to
5330** [sqlite3_next_stmt(D,S)] must refer to an open database
5331** connection and in particular must not be a NULL pointer.
5332*/
5333SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
5334
5335/*
5336** CAPI3REF: Commit And Rollback Notification Callbacks
5337** METHOD: sqlite3
5338**
5339** ^The sqlite3_commit_hook() interface registers a callback
5340** function to be invoked whenever a transaction is [COMMIT | committed].
5341** ^Any callback set by a previous call to sqlite3_commit_hook()
5342** for the same database connection is overridden.
5343** ^The sqlite3_rollback_hook() interface registers a callback
5344** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
5345** ^Any callback set by a previous call to sqlite3_rollback_hook()
5346** for the same database connection is overridden.
5347** ^The pArg argument is passed through to the callback.
5348** ^If the callback on a commit hook function returns non-zero,
5349** then the commit is converted into a rollback.
5350**
5351** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
5352** return the P argument from the previous call of the same function
5353** on the same [database connection] D, or NULL for
5354** the first call for each function on D.
5355**
5356** The commit and rollback hook callbacks are not reentrant.
5357** The callback implementation must not do anything that will modify
5358** the database connection that invoked the callback. Any actions
5359** to modify the database connection must be deferred until after the
5360** completion of the [sqlite3_step()] call that triggered the commit
5361** or rollback hook in the first place.
5362** Note that running any other SQL statements, including SELECT statements,
5363** or merely calling [sqlite3_prepare_v2()] and [sqlite3_step()] will modify
5364** the database connections for the meaning of "modify" in this paragraph.
5365**
5366** ^Registering a NULL function disables the callback.
5367**
5368** ^When the commit hook callback routine returns zero, the [COMMIT]
5369** operation is allowed to continue normally. ^If the commit hook
5370** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
5371** ^The rollback hook is invoked on a rollback that results from a commit
5372** hook returning non-zero, just as it would be with any other rollback.
5373**
5374** ^For the purposes of this API, a transaction is said to have been
5375** rolled back if an explicit "ROLLBACK" statement is executed, or
5376** an error or constraint causes an implicit rollback to occur.
5377** ^The rollback callback is not invoked if a transaction is
5378** automatically rolled back because the database connection is closed.
5379**
5380** See also the [sqlite3_update_hook()] interface.
5381*/
5382SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
5383SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
5384
5385/*
5386** CAPI3REF: Data Change Notification Callbacks
5387** METHOD: sqlite3
5388**
5389** ^The sqlite3_update_hook() interface registers a callback function
5390** with the [database connection] identified by the first argument
5391** to be invoked whenever a row is updated, inserted or deleted in
5392** a [rowid table].
5393** ^Any callback set by a previous call to this function
5394** for the same database connection is overridden.
5395**
5396** ^The second argument is a pointer to the function to invoke when a
5397** row is updated, inserted or deleted in a rowid table.
5398** ^The first argument to the callback is a copy of the third argument
5399** to sqlite3_update_hook().
5400** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
5401** or [SQLITE_UPDATE], depending on the operation that caused the callback
5402** to be invoked.
5403** ^The third and fourth arguments to the callback contain pointers to the
5404** database and table name containing the affected row.
5405** ^The final callback parameter is the [rowid] of the row.
5406** ^In the case of an update, this is the [rowid] after the update takes place.
5407**
5408** ^(The update hook is not invoked when internal system tables are
5409** modified (i.e. sqlite_master and sqlite_sequence).)^
5410** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.
5411**
5412** ^In the current implementation, the update hook
5413** is not invoked when duplication rows are deleted because of an
5414** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook
5415** invoked when rows are deleted using the [truncate optimization].
5416** The exceptions defined in this paragraph might change in a future
5417** release of SQLite.
5418**
5419** The update hook implementation must not do anything that will modify
5420** the database connection that invoked the update hook. Any actions
5421** to modify the database connection must be deferred until after the
5422** completion of the [sqlite3_step()] call that triggered the update hook.
5423** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
5424** database connections for the meaning of "modify" in this paragraph.
5425**
5426** ^The sqlite3_update_hook(D,C,P) function
5427** returns the P argument from the previous call
5428** on the same [database connection] D, or NULL for
5429** the first call on D.
5430**
5431** See also the [sqlite3_commit_hook()], [sqlite3_rollback_hook()],
5432** and [sqlite3_preupdate_hook()] interfaces.
5433*/
5434SQLITE_API void *sqlite3_update_hook(
5435 sqlite3*,
5436 void(*)(void *,int ,char const *,char const *,sqlite3_int64),
5437 void*
5438);
5439
5440/*
5441** CAPI3REF: Enable Or Disable Shared Pager Cache
5442**
5443** ^(This routine enables or disables the sharing of the database cache
5444** and schema data structures between [database connection | connections]
5445** to the same database. Sharing is enabled if the argument is true
5446** and disabled if the argument is false.)^
5447**
5448** ^Cache sharing is enabled and disabled for an entire process.
5449** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).
5450** In prior versions of SQLite,
5451** sharing was enabled or disabled for each thread separately.
5452**
5453** ^(The cache sharing mode set by this interface effects all subsequent
5454** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
5455** Existing database connections continue use the sharing mode
5456** that was in effect at the time they were opened.)^
5457**
5458** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled
5459** successfully. An [error code] is returned otherwise.)^
5460**
5461** ^Shared cache is disabled by default. But this might change in
5462** future releases of SQLite. Applications that care about shared
5463** cache setting should set it explicitly.
5464**
5465** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0
5466** and will always return SQLITE_MISUSE. On those systems,
5467** shared cache mode should be enabled per-database connection via
5468** [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE].
5469**
5470** This interface is threadsafe on processors where writing a
5471** 32-bit integer is atomic.
5472**
5473** See Also: [SQLite Shared-Cache Mode]
5474*/
5475SQLITE_API int sqlite3_enable_shared_cache(int);
5476
5477/*
5478** CAPI3REF: Attempt To Free Heap Memory
5479**
5480** ^The sqlite3_release_memory() interface attempts to free N bytes
5481** of heap memory by deallocating non-essential memory allocations
5482** held by the database library. Memory used to cache database
5483** pages to improve performance is an example of non-essential memory.
5484** ^sqlite3_release_memory() returns the number of bytes actually freed,
5485** which might be more or less than the amount requested.
5486** ^The sqlite3_release_memory() routine is a no-op returning zero
5487** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].
5488**
5489** See also: [sqlite3_db_release_memory()]
5490*/
5491SQLITE_API int sqlite3_release_memory(int);
5492
5493/*
5494** CAPI3REF: Free Memory Used By A Database Connection
5495** METHOD: sqlite3
5496**
5497** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap
5498** memory as possible from database connection D. Unlike the
5499** [sqlite3_release_memory()] interface, this interface is in effect even
5500** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
5501** omitted.
5502**
5503** See also: [sqlite3_release_memory()]
5504*/
5505SQLITE_API int sqlite3_db_release_memory(sqlite3*);
5506
5507/*
5508** CAPI3REF: Impose A Limit On Heap Size
5509**
5510** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the
5511** soft limit on the amount of heap memory that may be allocated by SQLite.
5512** ^SQLite strives to keep heap memory utilization below the soft heap
5513** limit by reducing the number of pages held in the page cache
5514** as heap memory usages approaches the limit.
5515** ^The soft heap limit is "soft" because even though SQLite strives to stay
5516** below the limit, it will exceed the limit rather than generate
5517** an [SQLITE_NOMEM] error. In other words, the soft heap limit
5518** is advisory only.
5519**
5520** ^The return value from sqlite3_soft_heap_limit64() is the size of
5521** the soft heap limit prior to the call, or negative in the case of an
5522** error. ^If the argument N is negative
5523** then no change is made to the soft heap limit. Hence, the current
5524** size of the soft heap limit can be determined by invoking
5525** sqlite3_soft_heap_limit64() with a negative argument.
5526**
5527** ^If the argument N is zero then the soft heap limit is disabled.
5528**
5529** ^(The soft heap limit is not enforced in the current implementation
5530** if one or more of following conditions are true:
5531**
5532** <ul>
5533** <li> The soft heap limit is set to zero.
5534** <li> Memory accounting is disabled using a combination of the
5535** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and
5536** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.
5537** <li> An alternative page cache implementation is specified using
5538** [sqlite3_config]([SQLITE_CONFIG_PCACHE2],...).
5539** <li> The page cache allocates from its own memory pool supplied
5540** by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than
5541** from the heap.
5542** </ul>)^
5543**
5544** Beginning with SQLite [version 3.7.3] ([dateof:3.7.3]),
5545** the soft heap limit is enforced
5546** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT]
5547** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT],
5548** the soft heap limit is enforced on every memory allocation. Without
5549** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced
5550** when memory is allocated by the page cache. Testing suggests that because
5551** the page cache is the predominate memory user in SQLite, most
5552** applications will achieve adequate soft heap limit enforcement without
5553** the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT].
5554**
5555** The circumstances under which SQLite will enforce the soft heap limit may
5556** changes in future releases of SQLite.
5557*/
5558SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
5559
5560/*
5561** CAPI3REF: Deprecated Soft Heap Limit Interface
5562** DEPRECATED
5563**
5564** This is a deprecated version of the [sqlite3_soft_heap_limit64()]
5565** interface. This routine is provided for historical compatibility
5566** only. All new applications should use the
5567** [sqlite3_soft_heap_limit64()] interface rather than this one.
5568*/
5569SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
5570
5571
5572/*
5573** CAPI3REF: Extract Metadata About A Column Of A Table
5574** METHOD: sqlite3
5575**
5576** ^(The sqlite3_table_column_metadata(X,D,T,C,....) routine returns
5577** information about column C of table T in database D
5578** on [database connection] X.)^ ^The sqlite3_table_column_metadata()
5579** interface returns SQLITE_OK and fills in the non-NULL pointers in
5580** the final five arguments with appropriate values if the specified
5581** column exists. ^The sqlite3_table_column_metadata() interface returns
5582** SQLITE_ERROR and if the specified column does not exist.
5583** ^If the column-name parameter to sqlite3_table_column_metadata() is a
5584** NULL pointer, then this routine simply checks for the existence of the
5585** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it
5586** does not.
5587**
5588** ^The column is identified by the second, third and fourth parameters to
5589** this function. ^(The second parameter is either the name of the database
5590** (i.e. "main", "temp", or an attached database) containing the specified
5591** table or NULL.)^ ^If it is NULL, then all attached databases are searched
5592** for the table using the same algorithm used by the database engine to
5593** resolve unqualified table references.
5594**
5595** ^The third and fourth parameters to this function are the table and column
5596** name of the desired column, respectively.
5597**
5598** ^Metadata is returned by writing to the memory locations passed as the 5th
5599** and subsequent parameters to this function. ^Any of these arguments may be
5600** NULL, in which case the corresponding element of metadata is omitted.
5601**
5602** ^(<blockquote>
5603** <table border="1">
5604** <tr><th> Parameter <th> Output<br>Type <th> Description
5605**
5606** <tr><td> 5th <td> const char* <td> Data type
5607** <tr><td> 6th <td> const char* <td> Name of default collation sequence
5608** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint
5609** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY
5610** <tr><td> 9th <td> int <td> True if column is [AUTOINCREMENT]
5611** </table>
5612** </blockquote>)^
5613**
5614** ^The memory pointed to by the character pointers returned for the
5615** declaration type and collation sequence is valid until the next
5616** call to any SQLite API function.
5617**
5618** ^If the specified table is actually a view, an [error code] is returned.
5619**
5620** ^If the specified column is "rowid", "oid" or "_rowid_" and the table
5621** is not a [WITHOUT ROWID] table and an
5622** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output
5623** parameters are set for the explicitly declared column. ^(If there is no
5624** [INTEGER PRIMARY KEY] column, then the outputs
5625** for the [rowid] are set as follows:
5626**
5627** <pre>
5628** data type: "INTEGER"
5629** collation sequence: "BINARY"
5630** not null: 0
5631** primary key: 1
5632** auto increment: 0
5633** </pre>)^
5634**
5635** ^This function causes all database schemas to be read from disk and
5636** parsed, if that has not already been done, and returns an error if
5637** any errors are encountered while loading the schema.
5638*/
5639SQLITE_API int sqlite3_table_column_metadata(
5640 sqlite3 *db, /* Connection handle */
5641 const char *zDbName, /* Database name or NULL */
5642 const char *zTableName, /* Table name */
5643 const char *zColumnName, /* Column name */
5644 char const **pzDataType, /* OUTPUT: Declared data type */
5645 char const **pzCollSeq, /* OUTPUT: Collation sequence name */
5646 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
5647 int *pPrimaryKey, /* OUTPUT: True if column part of PK */
5648 int *pAutoinc /* OUTPUT: True if column is auto-increment */
5649);
5650
5651/*
5652** CAPI3REF: Load An Extension
5653** METHOD: sqlite3
5654**
5655** ^This interface loads an SQLite extension library from the named file.
5656**
5657** ^The sqlite3_load_extension() interface attempts to load an
5658** [SQLite extension] library contained in the file zFile. If
5659** the file cannot be loaded directly, attempts are made to load
5660** with various operating-system specific extensions added.
5661** So for example, if "samplelib" cannot be loaded, then names like
5662** "samplelib.so" or "samplelib.dylib" or "samplelib.dll" might
5663** be tried also.
5664**
5665** ^The entry point is zProc.
5666** ^(zProc may be 0, in which case SQLite will try to come up with an
5667** entry point name on its own. It first tries "sqlite3_extension_init".
5668** If that does not work, it constructs a name "sqlite3_X_init" where the
5669** X is consists of the lower-case equivalent of all ASCII alphabetic
5670** characters in the filename from the last "/" to the first following
5671** "." and omitting any initial "lib".)^
5672** ^The sqlite3_load_extension() interface returns
5673** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
5674** ^If an error occurs and pzErrMsg is not 0, then the
5675** [sqlite3_load_extension()] interface shall attempt to
5676** fill *pzErrMsg with error message text stored in memory
5677** obtained from [sqlite3_malloc()]. The calling function
5678** should free this memory by calling [sqlite3_free()].
5679**
5680** ^Extension loading must be enabled using
5681** [sqlite3_enable_load_extension()] or
5682** [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],1,NULL)
5683** prior to calling this API,
5684** otherwise an error will be returned.
5685**
5686** <b>Security warning:</b> It is recommended that the
5687** [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method be used to enable only this
5688** interface. The use of the [sqlite3_enable_load_extension()] interface
5689** should be avoided. This will keep the SQL function [load_extension()]
5690** disabled and prevent SQL injections from giving attackers
5691** access to extension loading capabilities.
5692**
5693** See also the [load_extension() SQL function].
5694*/
5695SQLITE_API int sqlite3_load_extension(
5696 sqlite3 *db, /* Load the extension into this database connection */
5697 const char *zFile, /* Name of the shared library containing extension */
5698 const char *zProc, /* Entry point. Derived from zFile if 0 */
5699 char **pzErrMsg /* Put error message here if not 0 */
5700);
5701
5702/*
5703** CAPI3REF: Enable Or Disable Extension Loading
5704** METHOD: sqlite3
5705**
5706** ^So as not to open security holes in older applications that are
5707** unprepared to deal with [extension loading], and as a means of disabling
5708** [extension loading] while evaluating user-entered SQL, the following API
5709** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
5710**
5711** ^Extension loading is off by default.
5712** ^Call the sqlite3_enable_load_extension() routine with onoff==1
5713** to turn extension loading on and call it with onoff==0 to turn
5714** it back off again.
5715**
5716** ^This interface enables or disables both the C-API
5717** [sqlite3_load_extension()] and the SQL function [load_extension()].
5718** ^(Use [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],..)
5719** to enable or disable only the C-API.)^
5720**
5721** <b>Security warning:</b> It is recommended that extension loading
5722** be disabled using the [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method
5723** rather than this interface, so the [load_extension()] SQL function
5724** remains disabled. This will prevent SQL injections from giving attackers
5725** access to extension loading capabilities.
5726*/
5727SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
5728
5729/*
5730** CAPI3REF: Automatically Load Statically Linked Extensions
5731**
5732** ^This interface causes the xEntryPoint() function to be invoked for
5733** each new [database connection] that is created. The idea here is that
5734** xEntryPoint() is the entry point for a statically linked [SQLite extension]
5735** that is to be automatically loaded into all new database connections.
5736**
5737** ^(Even though the function prototype shows that xEntryPoint() takes
5738** no arguments and returns void, SQLite invokes xEntryPoint() with three
5739** arguments and expects an integer result as if the signature of the
5740** entry point where as follows:
5741**
5742** <blockquote><pre>
5743** int xEntryPoint(
5744** sqlite3 *db,
5745** const char **pzErrMsg,
5746** const struct sqlite3_api_routines *pThunk
5747** );
5748** </pre></blockquote>)^
5749**
5750** If the xEntryPoint routine encounters an error, it should make *pzErrMsg
5751** point to an appropriate error message (obtained from [sqlite3_mprintf()])
5752** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg
5753** is NULL before calling the xEntryPoint(). ^SQLite will invoke
5754** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns. ^If any
5755** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()],
5756** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail.
5757**
5758** ^Calling sqlite3_auto_extension(X) with an entry point X that is already
5759** on the list of automatic extensions is a harmless no-op. ^No entry point
5760** will be called more than once for each database connection that is opened.
5761**
5762** See also: [sqlite3_reset_auto_extension()]
5763** and [sqlite3_cancel_auto_extension()]
5764*/
5765SQLITE_API int sqlite3_auto_extension(void(*xEntryPoint)(void));
5766
5767/*
5768** CAPI3REF: Cancel Automatic Extension Loading
5769**
5770** ^The [sqlite3_cancel_auto_extension(X)] interface unregisters the
5771** initialization routine X that was registered using a prior call to
5772** [sqlite3_auto_extension(X)]. ^The [sqlite3_cancel_auto_extension(X)]
5773** routine returns 1 if initialization routine X was successfully
5774** unregistered and it returns 0 if X was not on the list of initialization
5775** routines.
5776*/
5777SQLITE_API int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void));
5778
5779/*
5780** CAPI3REF: Reset Automatic Extension Loading
5781**
5782** ^This interface disables all automatic extensions previously
5783** registered using [sqlite3_auto_extension()].
5784*/
5785SQLITE_API void sqlite3_reset_auto_extension(void);
5786
5787/*
5788** The interface to the virtual-table mechanism is currently considered
5789** to be experimental. The interface might change in incompatible ways.
5790** If this is a problem for you, do not use the interface at this time.
5791**
5792** When the virtual-table mechanism stabilizes, we will declare the
5793** interface fixed, support it indefinitely, and remove this comment.
5794*/
5795
5796/*
5797** Structures used by the virtual table interface
5798*/
5799typedef struct sqlite3_vtab sqlite3_vtab;
5800typedef struct sqlite3_index_info sqlite3_index_info;
5801typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
5802typedef struct sqlite3_module sqlite3_module;
5803
5804/*
5805** CAPI3REF: Virtual Table Object
5806** KEYWORDS: sqlite3_module {virtual table module}
5807**
5808** This structure, sometimes called a "virtual table module",
5809** defines the implementation of a [virtual tables].
5810** This structure consists mostly of methods for the module.
5811**
5812** ^A virtual table module is created by filling in a persistent
5813** instance of this structure and passing a pointer to that instance
5814** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].
5815** ^The registration remains valid until it is replaced by a different
5816** module or until the [database connection] closes. The content
5817** of this structure must not change while it is registered with
5818** any database connection.
5819*/
5820struct sqlite3_module {
5821 int iVersion;
5822 int (*xCreate)(sqlite3*, void *pAux,
5823 int argc, const char *const*argv,
5824 sqlite3_vtab **ppVTab, char**);
5825 int (*xConnect)(sqlite3*, void *pAux,
5826 int argc, const char *const*argv,
5827 sqlite3_vtab **ppVTab, char**);
5828 int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
5829 int (*xDisconnect)(sqlite3_vtab *pVTab);
5830 int (*xDestroy)(sqlite3_vtab *pVTab);
5831 int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
5832 int (*xClose)(sqlite3_vtab_cursor*);
5833 int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
5834 int argc, sqlite3_value **argv);
5835 int (*xNext)(sqlite3_vtab_cursor*);
5836 int (*xEof)(sqlite3_vtab_cursor*);
5837 int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
5838 int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
5839 int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
5840 int (*xBegin)(sqlite3_vtab *pVTab);
5841 int (*xSync)(sqlite3_vtab *pVTab);
5842 int (*xCommit)(sqlite3_vtab *pVTab);
5843 int (*xRollback)(sqlite3_vtab *pVTab);
5844 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
5845 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
5846 void **ppArg);
5847 int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
5848 /* The methods above are in version 1 of the sqlite_module object. Those
5849 ** below are for version 2 and greater. */
5850 int (*xSavepoint)(sqlite3_vtab *pVTab, int);
5851 int (*xRelease)(sqlite3_vtab *pVTab, int);
5852 int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
5853};
5854
5855/*
5856** CAPI3REF: Virtual Table Indexing Information
5857** KEYWORDS: sqlite3_index_info
5858**
5859** The sqlite3_index_info structure and its substructures is used as part
5860** of the [virtual table] interface to
5861** pass information into and receive the reply from the [xBestIndex]
5862** method of a [virtual table module]. The fields under **Inputs** are the
5863** inputs to xBestIndex and are read-only. xBestIndex inserts its
5864** results into the **Outputs** fields.
5865**
5866** ^(The aConstraint[] array records WHERE clause constraints of the form:
5867**
5868** <blockquote>column OP expr</blockquote>
5869**
5870** where OP is =, <, <=, >, or >=.)^ ^(The particular operator is
5871** stored in aConstraint[].op using one of the
5872** [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^
5873** ^(The index of the column is stored in
5874** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the
5875** expr on the right-hand side can be evaluated (and thus the constraint
5876** is usable) and false if it cannot.)^
5877**
5878** ^The optimizer automatically inverts terms of the form "expr OP column"
5879** and makes other simplifications to the WHERE clause in an attempt to
5880** get as many WHERE clause terms into the form shown above as possible.
5881** ^The aConstraint[] array only reports WHERE clause terms that are
5882** relevant to the particular virtual table being queried.
5883**
5884** ^Information about the ORDER BY clause is stored in aOrderBy[].
5885** ^Each term of aOrderBy records a column of the ORDER BY clause.
5886**
5887** The colUsed field indicates which columns of the virtual table may be
5888** required by the current scan. Virtual table columns are numbered from
5889** zero in the order in which they appear within the CREATE TABLE statement
5890** passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),
5891** the corresponding bit is set within the colUsed mask if the column may be
5892** required by SQLite. If the table has at least 64 columns and any column
5893** to the right of the first 63 is required, then bit 63 of colUsed is also
5894** set. In other words, column iCol may be required if the expression
5895** (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to
5896** non-zero.
5897**
5898** The [xBestIndex] method must fill aConstraintUsage[] with information
5899** about what parameters to pass to xFilter. ^If argvIndex>0 then
5900** the right-hand side of the corresponding aConstraint[] is evaluated
5901** and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit
5902** is true, then the constraint is assumed to be fully handled by the
5903** virtual table and is not checked again by SQLite.)^
5904**
5905** ^The idxNum and idxPtr values are recorded and passed into the
5906** [xFilter] method.
5907** ^[sqlite3_free()] is used to free idxPtr if and only if
5908** needToFreeIdxPtr is true.
5909**
5910** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in
5911** the correct order to satisfy the ORDER BY clause so that no separate
5912** sorting step is required.
5913**
5914** ^The estimatedCost value is an estimate of the cost of a particular
5915** strategy. A cost of N indicates that the cost of the strategy is similar
5916** to a linear scan of an SQLite table with N rows. A cost of log(N)
5917** indicates that the expense of the operation is similar to that of a
5918** binary search on a unique indexed field of an SQLite table with N rows.
5919**
5920** ^The estimatedRows value is an estimate of the number of rows that
5921** will be returned by the strategy.
5922**
5923** The xBestIndex method may optionally populate the idxFlags field with a
5924** mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag -
5925** SQLITE_INDEX_SCAN_UNIQUE. If the xBestIndex method sets this flag, SQLite
5926** assumes that the strategy may visit at most one row.
5927**
5928** Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then
5929** SQLite also assumes that if a call to the xUpdate() method is made as
5930** part of the same statement to delete or update a virtual table row and the
5931** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback
5932** any database changes. In other words, if the xUpdate() returns
5933** SQLITE_CONSTRAINT, the database contents must be exactly as they were
5934** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not
5935** set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by
5936** the xUpdate method are automatically rolled back by SQLite.
5937**
5938** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info
5939** structure for SQLite [version 3.8.2] ([dateof:3.8.2]).
5940** If a virtual table extension is
5941** used with an SQLite version earlier than 3.8.2, the results of attempting
5942** to read or write the estimatedRows field are undefined (but are likely
5943** to included crashing the application). The estimatedRows field should
5944** therefore only be used if [sqlite3_libversion_number()] returns a
5945** value greater than or equal to 3008002. Similarly, the idxFlags field
5946** was added for [version 3.9.0] ([dateof:3.9.0]).
5947** It may therefore only be used if
5948** sqlite3_libversion_number() returns a value greater than or equal to
5949** 3009000.
5950*/
5951struct sqlite3_index_info {
5952 /* Inputs */
5953 int nConstraint; /* Number of entries in aConstraint */
5954 struct sqlite3_index_constraint {
5955 int iColumn; /* Column constrained. -1 for ROWID */
5956 unsigned char op; /* Constraint operator */
5957 unsigned char usable; /* True if this constraint is usable */
5958 int iTermOffset; /* Used internally - xBestIndex should ignore */
5959 } *aConstraint; /* Table of WHERE clause constraints */
5960 int nOrderBy; /* Number of terms in the ORDER BY clause */
5961 struct sqlite3_index_orderby {
5962 int iColumn; /* Column number */
5963 unsigned char desc; /* True for DESC. False for ASC. */
5964 } *aOrderBy; /* The ORDER BY clause */
5965 /* Outputs */
5966 struct sqlite3_index_constraint_usage {
5967 int argvIndex; /* if >0, constraint is part of argv to xFilter */
5968 unsigned char omit; /* Do not code a test for this constraint */
5969 } *aConstraintUsage;
5970 int idxNum; /* Number used to identify the index */
5971 char *idxStr; /* String, possibly obtained from sqlite3_malloc */
5972 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
5973 int orderByConsumed; /* True if output is already ordered */
5974 double estimatedCost; /* Estimated cost of using this index */
5975 /* Fields below are only available in SQLite 3.8.2 and later */
5976 sqlite3_int64 estimatedRows; /* Estimated number of rows returned */
5977 /* Fields below are only available in SQLite 3.9.0 and later */
5978 int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */
5979 /* Fields below are only available in SQLite 3.10.0 and later */
5980 sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */
5981};
5982
5983/*
5984** CAPI3REF: Virtual Table Scan Flags
5985*/
5986#define SQLITE_INDEX_SCAN_UNIQUE 1 /* Scan visits at most 1 row */
5987
5988/*
5989** CAPI3REF: Virtual Table Constraint Operator Codes
5990**
5991** These macros defined the allowed values for the
5992** [sqlite3_index_info].aConstraint[].op field. Each value represents
5993** an operator that is part of a constraint term in the wHERE clause of
5994** a query that uses a [virtual table].
5995*/
5996#define SQLITE_INDEX_CONSTRAINT_EQ 2
5997#define SQLITE_INDEX_CONSTRAINT_GT 4
5998#define SQLITE_INDEX_CONSTRAINT_LE 8
5999#define SQLITE_INDEX_CONSTRAINT_LT 16
6000#define SQLITE_INDEX_CONSTRAINT_GE 32
6001#define SQLITE_INDEX_CONSTRAINT_MATCH 64
6002#define SQLITE_INDEX_CONSTRAINT_LIKE 65
6003#define SQLITE_INDEX_CONSTRAINT_GLOB 66
6004#define SQLITE_INDEX_CONSTRAINT_REGEXP 67
6005
6006/*
6007** CAPI3REF: Register A Virtual Table Implementation
6008** METHOD: sqlite3
6009**
6010** ^These routines are used to register a new [virtual table module] name.
6011** ^Module names must be registered before
6012** creating a new [virtual table] using the module and before using a
6013** preexisting [virtual table] for the module.
6014**
6015** ^The module name is registered on the [database connection] specified
6016** by the first parameter. ^The name of the module is given by the
6017** second parameter. ^The third parameter is a pointer to
6018** the implementation of the [virtual table module]. ^The fourth
6019** parameter is an arbitrary client data pointer that is passed through
6020** into the [xCreate] and [xConnect] methods of the virtual table module
6021** when a new virtual table is be being created or reinitialized.
6022**
6023** ^The sqlite3_create_module_v2() interface has a fifth parameter which
6024** is a pointer to a destructor for the pClientData. ^SQLite will
6025** invoke the destructor function (if it is not NULL) when SQLite
6026** no longer needs the pClientData pointer. ^The destructor will also
6027** be invoked if the call to sqlite3_create_module_v2() fails.
6028** ^The sqlite3_create_module()
6029** interface is equivalent to sqlite3_create_module_v2() with a NULL
6030** destructor.
6031*/
6032SQLITE_API int sqlite3_create_module(
6033 sqlite3 *db, /* SQLite connection to register module with */
6034 const char *zName, /* Name of the module */
6035 const sqlite3_module *p, /* Methods for the module */
6036 void *pClientData /* Client data for xCreate/xConnect */
6037);
6038SQLITE_API int sqlite3_create_module_v2(
6039 sqlite3 *db, /* SQLite connection to register module with */
6040 const char *zName, /* Name of the module */
6041 const sqlite3_module *p, /* Methods for the module */
6042 void *pClientData, /* Client data for xCreate/xConnect */
6043 void(*xDestroy)(void*) /* Module destructor function */
6044);
6045
6046/*
6047** CAPI3REF: Virtual Table Instance Object
6048** KEYWORDS: sqlite3_vtab
6049**
6050** Every [virtual table module] implementation uses a subclass
6051** of this object to describe a particular instance
6052** of the [virtual table]. Each subclass will
6053** be tailored to the specific needs of the module implementation.
6054** The purpose of this superclass is to define certain fields that are
6055** common to all module implementations.
6056**
6057** ^Virtual tables methods can set an error message by assigning a
6058** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should
6059** take care that any prior string is freed by a call to [sqlite3_free()]
6060** prior to assigning a new string to zErrMsg. ^After the error message
6061** is delivered up to the client application, the string will be automatically
6062** freed by sqlite3_free() and the zErrMsg field will be zeroed.
6063*/
6064struct sqlite3_vtab {
6065 const sqlite3_module *pModule; /* The module for this virtual table */
6066 int nRef; /* Number of open cursors */
6067 char *zErrMsg; /* Error message from sqlite3_mprintf() */
6068 /* Virtual table implementations will typically add additional fields */
6069};
6070
6071/*
6072** CAPI3REF: Virtual Table Cursor Object
6073** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
6074**
6075** Every [virtual table module] implementation uses a subclass of the
6076** following structure to describe cursors that point into the
6077** [virtual table] and are used
6078** to loop through the virtual table. Cursors are created using the
6079** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed
6080** by the [sqlite3_module.xClose | xClose] method. Cursors are used
6081** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods
6082** of the module. Each module implementation will define
6083** the content of a cursor structure to suit its own needs.
6084**
6085** This superclass exists in order to define fields of the cursor that
6086** are common to all implementations.
6087*/
6088struct sqlite3_vtab_cursor {
6089 sqlite3_vtab *pVtab; /* Virtual table of this cursor */
6090 /* Virtual table implementations will typically add additional fields */
6091};
6092
6093/*
6094** CAPI3REF: Declare The Schema Of A Virtual Table
6095**
6096** ^The [xCreate] and [xConnect] methods of a
6097** [virtual table module] call this interface
6098** to declare the format (the names and datatypes of the columns) of
6099** the virtual tables they implement.
6100*/
6101SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
6102
6103/*
6104** CAPI3REF: Overload A Function For A Virtual Table
6105** METHOD: sqlite3
6106**
6107** ^(Virtual tables can provide alternative implementations of functions
6108** using the [xFindFunction] method of the [virtual table module].
6109** But global versions of those functions
6110** must exist in order to be overloaded.)^
6111**
6112** ^(This API makes sure a global version of a function with a particular
6113** name and number of parameters exists. If no such function exists
6114** before this API is called, a new function is created.)^ ^The implementation
6115** of the new function always causes an exception to be thrown. So
6116** the new function is not good for anything by itself. Its only
6117** purpose is to be a placeholder function that can be overloaded
6118** by a [virtual table].
6119*/
6120SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
6121
6122/*
6123** The interface to the virtual-table mechanism defined above (back up
6124** to a comment remarkably similar to this one) is currently considered
6125** to be experimental. The interface might change in incompatible ways.
6126** If this is a problem for you, do not use the interface at this time.
6127**
6128** When the virtual-table mechanism stabilizes, we will declare the
6129** interface fixed, support it indefinitely, and remove this comment.
6130*/
6131
6132/*
6133** CAPI3REF: A Handle To An Open BLOB
6134** KEYWORDS: {BLOB handle} {BLOB handles}
6135**
6136** An instance of this object represents an open BLOB on which
6137** [sqlite3_blob_open | incremental BLOB I/O] can be performed.
6138** ^Objects of this type are created by [sqlite3_blob_open()]
6139** and destroyed by [sqlite3_blob_close()].
6140** ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
6141** can be used to read or write small subsections of the BLOB.
6142** ^The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.
6143*/
6144typedef struct sqlite3_blob sqlite3_blob;
6145
6146/*
6147** CAPI3REF: Open A BLOB For Incremental I/O
6148** METHOD: sqlite3
6149** CONSTRUCTOR: sqlite3_blob
6150**
6151** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located
6152** in row iRow, column zColumn, table zTable in database zDb;
6153** in other words, the same BLOB that would be selected by:
6154**
6155** <pre>
6156** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
6157** </pre>)^
6158**
6159** ^(Parameter zDb is not the filename that contains the database, but
6160** rather the symbolic name of the database. For attached databases, this is
6161** the name that appears after the AS keyword in the [ATTACH] statement.
6162** For the main database file, the database name is "main". For TEMP
6163** tables, the database name is "temp".)^
6164**
6165** ^If the flags parameter is non-zero, then the BLOB is opened for read
6166** and write access. ^If the flags parameter is zero, the BLOB is opened for
6167** read-only access.
6168**
6169** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is stored
6170** in *ppBlob. Otherwise an [error code] is returned and, unless the error
6171** code is SQLITE_MISUSE, *ppBlob is set to NULL.)^ ^This means that, provided
6172** the API is not misused, it is always safe to call [sqlite3_blob_close()]
6173** on *ppBlob after this function it returns.
6174**
6175** This function fails with SQLITE_ERROR if any of the following are true:
6176** <ul>
6177** <li> ^(Database zDb does not exist)^,
6178** <li> ^(Table zTable does not exist within database zDb)^,
6179** <li> ^(Table zTable is a WITHOUT ROWID table)^,
6180** <li> ^(Column zColumn does not exist)^,
6181** <li> ^(Row iRow is not present in the table)^,
6182** <li> ^(The specified column of row iRow contains a value that is not
6183** a TEXT or BLOB value)^,
6184** <li> ^(Column zColumn is part of an index, PRIMARY KEY or UNIQUE
6185** constraint and the blob is being opened for read/write access)^,
6186** <li> ^([foreign key constraints | Foreign key constraints] are enabled,
6187** column zColumn is part of a [child key] definition and the blob is
6188** being opened for read/write access)^.
6189** </ul>
6190**
6191** ^Unless it returns SQLITE_MISUSE, this function sets the
6192** [database connection] error code and message accessible via
6193** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
6194**
6195**
6196** ^(If the row that a BLOB handle points to is modified by an
6197** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
6198** then the BLOB handle is marked as "expired".
6199** This is true if any column of the row is changed, even a column
6200** other than the one the BLOB handle is open on.)^
6201** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
6202** an expired BLOB handle fail with a return code of [SQLITE_ABORT].
6203** ^(Changes written into a BLOB prior to the BLOB expiring are not
6204** rolled back by the expiration of the BLOB. Such changes will eventually
6205** commit if the transaction continues to completion.)^
6206**
6207** ^Use the [sqlite3_blob_bytes()] interface to determine the size of
6208** the opened blob. ^The size of a blob may not be changed by this
6209** interface. Use the [UPDATE] SQL command to change the size of a
6210** blob.
6211**
6212** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
6213** and the built-in [zeroblob] SQL function may be used to create a
6214** zero-filled blob to read or write using the incremental-blob interface.
6215**
6216** To avoid a resource leak, every open [BLOB handle] should eventually
6217** be released by a call to [sqlite3_blob_close()].
6218*/
6219SQLITE_API int sqlite3_blob_open(
6220 sqlite3*,
6221 const char *zDb,
6222 const char *zTable,
6223 const char *zColumn,
6224 sqlite3_int64 iRow,
6225 int flags,
6226 sqlite3_blob **ppBlob
6227);
6228
6229/*
6230** CAPI3REF: Move a BLOB Handle to a New Row
6231** METHOD: sqlite3_blob
6232**
6233** ^This function is used to move an existing blob handle so that it points
6234** to a different row of the same database table. ^The new row is identified
6235** by the rowid value passed as the second argument. Only the row can be
6236** changed. ^The database, table and column on which the blob handle is open
6237** remain the same. Moving an existing blob handle to a new row can be
6238** faster than closing the existing handle and opening a new one.
6239**
6240** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -
6241** it must exist and there must be either a blob or text value stored in
6242** the nominated column.)^ ^If the new row is not present in the table, or if
6243** it does not contain a blob or text value, or if another error occurs, an
6244** SQLite error code is returned and the blob handle is considered aborted.
6245** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or
6246** [sqlite3_blob_reopen()] on an aborted blob handle immediately return
6247** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle
6248** always returns zero.
6249**
6250** ^This function sets the database handle error code and message.
6251*/
6252SQLITE_API int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
6253
6254/*
6255** CAPI3REF: Close A BLOB Handle
6256** DESTRUCTOR: sqlite3_blob
6257**
6258** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed
6259** unconditionally. Even if this routine returns an error code, the
6260** handle is still closed.)^
6261**
6262** ^If the blob handle being closed was opened for read-write access, and if
6263** the database is in auto-commit mode and there are no other open read-write
6264** blob handles or active write statements, the current transaction is
6265** committed. ^If an error occurs while committing the transaction, an error
6266** code is returned and the transaction rolled back.
6267**
6268** Calling this function with an argument that is not a NULL pointer or an
6269** open blob handle results in undefined behaviour. ^Calling this routine
6270** with a null pointer (such as would be returned by a failed call to
6271** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function
6272** is passed a valid open blob handle, the values returned by the
6273** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning.
6274*/
6275SQLITE_API int sqlite3_blob_close(sqlite3_blob *);
6276
6277/*
6278** CAPI3REF: Return The Size Of An Open BLOB
6279** METHOD: sqlite3_blob
6280**
6281** ^Returns the size in bytes of the BLOB accessible via the
6282** successfully opened [BLOB handle] in its only argument. ^The
6283** incremental blob I/O routines can only read or overwriting existing
6284** blob content; they cannot change the size of a blob.
6285**
6286** This routine only works on a [BLOB handle] which has been created
6287** by a prior successful call to [sqlite3_blob_open()] and which has not
6288** been closed by [sqlite3_blob_close()]. Passing any other pointer in
6289** to this routine results in undefined and probably undesirable behavior.
6290*/
6291SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *);
6292
6293/*
6294** CAPI3REF: Read Data From A BLOB Incrementally
6295** METHOD: sqlite3_blob
6296**
6297** ^(This function is used to read data from an open [BLOB handle] into a
6298** caller-supplied buffer. N bytes of data are copied into buffer Z
6299** from the open BLOB, starting at offset iOffset.)^
6300**
6301** ^If offset iOffset is less than N bytes from the end of the BLOB,
6302** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is
6303** less than zero, [SQLITE_ERROR] is returned and no data is read.
6304** ^The size of the blob (and hence the maximum value of N+iOffset)
6305** can be determined using the [sqlite3_blob_bytes()] interface.
6306**
6307** ^An attempt to read from an expired [BLOB handle] fails with an
6308** error code of [SQLITE_ABORT].
6309**
6310** ^(On success, sqlite3_blob_read() returns SQLITE_OK.
6311** Otherwise, an [error code] or an [extended error code] is returned.)^
6312**
6313** This routine only works on a [BLOB handle] which has been created
6314** by a prior successful call to [sqlite3_blob_open()] and which has not
6315** been closed by [sqlite3_blob_close()]. Passing any other pointer in
6316** to this routine results in undefined and probably undesirable behavior.
6317**
6318** See also: [sqlite3_blob_write()].
6319*/
6320SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
6321
6322/*
6323** CAPI3REF: Write Data Into A BLOB Incrementally
6324** METHOD: sqlite3_blob
6325**
6326** ^(This function is used to write data into an open [BLOB handle] from a
6327** caller-supplied buffer. N bytes of data are copied from the buffer Z
6328** into the open BLOB, starting at offset iOffset.)^
6329**
6330** ^(On success, sqlite3_blob_write() returns SQLITE_OK.
6331** Otherwise, an [error code] or an [extended error code] is returned.)^
6332** ^Unless SQLITE_MISUSE is returned, this function sets the
6333** [database connection] error code and message accessible via
6334** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
6335**
6336** ^If the [BLOB handle] passed as the first argument was not opened for
6337** writing (the flags parameter to [sqlite3_blob_open()] was zero),
6338** this function returns [SQLITE_READONLY].
6339**
6340** This function may only modify the contents of the BLOB; it is
6341** not possible to increase the size of a BLOB using this API.
6342** ^If offset iOffset is less than N bytes from the end of the BLOB,
6343** [SQLITE_ERROR] is returned and no data is written. The size of the
6344** BLOB (and hence the maximum value of N+iOffset) can be determined
6345** using the [sqlite3_blob_bytes()] interface. ^If N or iOffset are less
6346** than zero [SQLITE_ERROR] is returned and no data is written.
6347**
6348** ^An attempt to write to an expired [BLOB handle] fails with an
6349** error code of [SQLITE_ABORT]. ^Writes to the BLOB that occurred
6350** before the [BLOB handle] expired are not rolled back by the
6351** expiration of the handle, though of course those changes might
6352** have been overwritten by the statement that expired the BLOB handle
6353** or by other independent statements.
6354**
6355** This routine only works on a [BLOB handle] which has been created
6356** by a prior successful call to [sqlite3_blob_open()] and which has not
6357** been closed by [sqlite3_blob_close()]. Passing any other pointer in
6358** to this routine results in undefined and probably undesirable behavior.
6359**
6360** See also: [sqlite3_blob_read()].
6361*/
6362SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
6363
6364/*
6365** CAPI3REF: Virtual File System Objects
6366**
6367** A virtual filesystem (VFS) is an [sqlite3_vfs] object
6368** that SQLite uses to interact
6369** with the underlying operating system. Most SQLite builds come with a
6370** single default VFS that is appropriate for the host computer.
6371** New VFSes can be registered and existing VFSes can be unregistered.
6372** The following interfaces are provided.
6373**
6374** ^The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.
6375** ^Names are case sensitive.
6376** ^Names are zero-terminated UTF-8 strings.
6377** ^If there is no match, a NULL pointer is returned.
6378** ^If zVfsName is NULL then the default VFS is returned.
6379**
6380** ^New VFSes are registered with sqlite3_vfs_register().
6381** ^Each new VFS becomes the default VFS if the makeDflt flag is set.
6382** ^The same VFS can be registered multiple times without injury.
6383** ^To make an existing VFS into the default VFS, register it again
6384** with the makeDflt flag set. If two different VFSes with the
6385** same name are registered, the behavior is undefined. If a
6386** VFS is registered with a name that is NULL or an empty string,
6387** then the behavior is undefined.
6388**
6389** ^Unregister a VFS with the sqlite3_vfs_unregister() interface.
6390** ^(If the default VFS is unregistered, another VFS is chosen as
6391** the default. The choice for the new VFS is arbitrary.)^
6392*/
6393SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
6394SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
6395SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
6396
6397/*
6398** CAPI3REF: Mutexes
6399**
6400** The SQLite core uses these routines for thread
6401** synchronization. Though they are intended for internal
6402** use by SQLite, code that links against SQLite is
6403** permitted to use any of these routines.
6404**
6405** The SQLite source code contains multiple implementations
6406** of these mutex routines. An appropriate implementation
6407** is selected automatically at compile-time. The following
6408** implementations are available in the SQLite core:
6409**
6410** <ul>
6411** <li> SQLITE_MUTEX_PTHREADS
6412** <li> SQLITE_MUTEX_W32
6413** <li> SQLITE_MUTEX_NOOP
6414** </ul>
6415**
6416** The SQLITE_MUTEX_NOOP implementation is a set of routines
6417** that does no real locking and is appropriate for use in
6418** a single-threaded application. The SQLITE_MUTEX_PTHREADS and
6419** SQLITE_MUTEX_W32 implementations are appropriate for use on Unix
6420** and Windows.
6421**
6422** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
6423** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
6424** implementation is included with the library. In this case the
6425** application must supply a custom mutex implementation using the
6426** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function
6427** before calling sqlite3_initialize() or any other public sqlite3_
6428** function that calls sqlite3_initialize().
6429**
6430** ^The sqlite3_mutex_alloc() routine allocates a new
6431** mutex and returns a pointer to it. ^The sqlite3_mutex_alloc()
6432** routine returns NULL if it is unable to allocate the requested
6433** mutex. The argument to sqlite3_mutex_alloc() must one of these
6434** integer constants:
6435**
6436** <ul>
6437** <li> SQLITE_MUTEX_FAST
6438** <li> SQLITE_MUTEX_RECURSIVE
6439** <li> SQLITE_MUTEX_STATIC_MASTER
6440** <li> SQLITE_MUTEX_STATIC_MEM
6441** <li> SQLITE_MUTEX_STATIC_OPEN
6442** <li> SQLITE_MUTEX_STATIC_PRNG
6443** <li> SQLITE_MUTEX_STATIC_LRU
6444** <li> SQLITE_MUTEX_STATIC_PMEM
6445** <li> SQLITE_MUTEX_STATIC_APP1
6446** <li> SQLITE_MUTEX_STATIC_APP2
6447** <li> SQLITE_MUTEX_STATIC_APP3
6448** <li> SQLITE_MUTEX_STATIC_VFS1
6449** <li> SQLITE_MUTEX_STATIC_VFS2
6450** <li> SQLITE_MUTEX_STATIC_VFS3
6451** </ul>
6452**
6453** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
6454** cause sqlite3_mutex_alloc() to create
6455** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
6456** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
6457** The mutex implementation does not need to make a distinction
6458** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
6459** not want to. SQLite will only request a recursive mutex in
6460** cases where it really needs one. If a faster non-recursive mutex
6461** implementation is available on the host platform, the mutex subsystem
6462** might return such a mutex in response to SQLITE_MUTEX_FAST.
6463**
6464** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other
6465** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
6466** a pointer to a static preexisting mutex. ^Nine static mutexes are
6467** used by the current version of SQLite. Future versions of SQLite
6468** may add additional static mutexes. Static mutexes are for internal
6469** use by SQLite only. Applications that use SQLite mutexes should
6470** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
6471** SQLITE_MUTEX_RECURSIVE.
6472**
6473** ^Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
6474** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
6475** returns a different mutex on every call. ^For the static
6476** mutex types, the same mutex is returned on every call that has
6477** the same type number.
6478**
6479** ^The sqlite3_mutex_free() routine deallocates a previously
6480** allocated dynamic mutex. Attempting to deallocate a static
6481** mutex results in undefined behavior.
6482**
6483** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
6484** to enter a mutex. ^If another thread is already within the mutex,
6485** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
6486** SQLITE_BUSY. ^The sqlite3_mutex_try() interface returns [SQLITE_OK]
6487** upon successful entry. ^(Mutexes created using
6488** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
6489** In such cases, the
6490** mutex must be exited an equal number of times before another thread
6491** can enter.)^ If the same thread tries to enter any mutex other
6492** than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.
6493**
6494** ^(Some systems (for example, Windows 95) do not support the operation
6495** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try()
6496** will always return SQLITE_BUSY. The SQLite core only ever uses
6497** sqlite3_mutex_try() as an optimization so this is acceptable
6498** behavior.)^
6499**
6500** ^The sqlite3_mutex_leave() routine exits a mutex that was
6501** previously entered by the same thread. The behavior
6502** is undefined if the mutex is not currently entered by the
6503** calling thread or is not currently allocated.
6504**
6505** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
6506** sqlite3_mutex_leave() is a NULL pointer, then all three routines
6507** behave as no-ops.
6508**
6509** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
6510*/
6511SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);
6512SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*);
6513SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*);
6514SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
6515SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
6516
6517/*
6518** CAPI3REF: Mutex Methods Object
6519**
6520** An instance of this structure defines the low-level routines
6521** used to allocate and use mutexes.
6522**
6523** Usually, the default mutex implementations provided by SQLite are
6524** sufficient, however the application has the option of substituting a custom
6525** implementation for specialized deployments or systems for which SQLite
6526** does not provide a suitable implementation. In this case, the application
6527** creates and populates an instance of this structure to pass
6528** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
6529** Additionally, an instance of this structure can be used as an
6530** output variable when querying the system for the current mutex
6531** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.
6532**
6533** ^The xMutexInit method defined by this structure is invoked as
6534** part of system initialization by the sqlite3_initialize() function.
6535** ^The xMutexInit routine is called by SQLite exactly once for each
6536** effective call to [sqlite3_initialize()].
6537**
6538** ^The xMutexEnd method defined by this structure is invoked as
6539** part of system shutdown by the sqlite3_shutdown() function. The
6540** implementation of this method is expected to release all outstanding
6541** resources obtained by the mutex methods implementation, especially
6542** those obtained by the xMutexInit method. ^The xMutexEnd()
6543** interface is invoked exactly once for each call to [sqlite3_shutdown()].
6544**
6545** ^(The remaining seven methods defined by this structure (xMutexAlloc,
6546** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
6547** xMutexNotheld) implement the following interfaces (respectively):
6548**
6549** <ul>
6550** <li> [sqlite3_mutex_alloc()] </li>
6551** <li> [sqlite3_mutex_free()] </li>
6552** <li> [sqlite3_mutex_enter()] </li>
6553** <li> [sqlite3_mutex_try()] </li>
6554** <li> [sqlite3_mutex_leave()] </li>
6555** <li> [sqlite3_mutex_held()] </li>
6556** <li> [sqlite3_mutex_notheld()] </li>
6557** </ul>)^
6558**
6559** The only difference is that the public sqlite3_XXX functions enumerated
6560** above silently ignore any invocations that pass a NULL pointer instead
6561** of a valid mutex handle. The implementations of the methods defined
6562** by this structure are not required to handle this case, the results
6563** of passing a NULL pointer instead of a valid mutex handle are undefined
6564** (i.e. it is acceptable to provide an implementation that segfaults if
6565** it is passed a NULL pointer).
6566**
6567** The xMutexInit() method must be threadsafe. It must be harmless to
6568** invoke xMutexInit() multiple times within the same process and without
6569** intervening calls to xMutexEnd(). Second and subsequent calls to
6570** xMutexInit() must be no-ops.
6571**
6572** xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
6573** and its associates). Similarly, xMutexAlloc() must not use SQLite memory
6574** allocation for a static mutex. ^However xMutexAlloc() may use SQLite
6575** memory allocation for a fast or recursive mutex.
6576**
6577** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
6578** called, but only if the prior call to xMutexInit returned SQLITE_OK.
6579** If xMutexInit fails in any way, it is expected to clean up after itself
6580** prior to returning.
6581*/
6582typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
6583struct sqlite3_mutex_methods {
6584 int (*xMutexInit)(void);
6585 int (*xMutexEnd)(void);
6586 sqlite3_mutex *(*xMutexAlloc)(int);
6587 void (*xMutexFree)(sqlite3_mutex *);
6588 void (*xMutexEnter)(sqlite3_mutex *);
6589 int (*xMutexTry)(sqlite3_mutex *);
6590 void (*xMutexLeave)(sqlite3_mutex *);
6591 int (*xMutexHeld)(sqlite3_mutex *);
6592 int (*xMutexNotheld)(sqlite3_mutex *);
6593};
6594
6595/*
6596** CAPI3REF: Mutex Verification Routines
6597**
6598** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
6599** are intended for use inside assert() statements. The SQLite core
6600** never uses these routines except inside an assert() and applications
6601** are advised to follow the lead of the core. The SQLite core only
6602** provides implementations for these routines when it is compiled
6603** with the SQLITE_DEBUG flag. External mutex implementations
6604** are only required to provide these routines if SQLITE_DEBUG is
6605** defined and if NDEBUG is not defined.
6606**
6607** These routines should return true if the mutex in their argument
6608** is held or not held, respectively, by the calling thread.
6609**
6610** The implementation is not required to provide versions of these
6611** routines that actually work. If the implementation does not provide working
6612** versions of these routines, it should at least provide stubs that always
6613** return true so that one does not get spurious assertion failures.
6614**
6615** If the argument to sqlite3_mutex_held() is a NULL pointer then
6616** the routine should return 1. This seems counter-intuitive since
6617** clearly the mutex cannot be held if it does not exist. But
6618** the reason the mutex does not exist is because the build is not
6619** using mutexes. And we do not want the assert() containing the
6620** call to sqlite3_mutex_held() to fail, so a non-zero return is
6621** the appropriate thing to do. The sqlite3_mutex_notheld()
6622** interface should also return 1 when given a NULL pointer.
6623*/
6624#ifndef NDEBUG
6625SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);
6626SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
6627#endif
6628
6629/*
6630** CAPI3REF: Mutex Types
6631**
6632** The [sqlite3_mutex_alloc()] interface takes a single argument
6633** which is one of these integer constants.
6634**
6635** The set of static mutexes may change from one SQLite release to the
6636** next. Applications that override the built-in mutex logic must be
6637** prepared to accommodate additional static mutexes.
6638*/
6639#define SQLITE_MUTEX_FAST 0
6640#define SQLITE_MUTEX_RECURSIVE 1
6641#define SQLITE_MUTEX_STATIC_MASTER 2
6642#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
6643#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */
6644#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */
6645#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_randomness() */
6646#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
6647#define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */
6648#define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */
6649#define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */
6650#define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */
6651#define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */
6652#define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */
6653#define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */
6654#define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */
6655
6656/*
6657** CAPI3REF: Retrieve the mutex for a database connection
6658** METHOD: sqlite3
6659**
6660** ^This interface returns a pointer the [sqlite3_mutex] object that
6661** serializes access to the [database connection] given in the argument
6662** when the [threading mode] is Serialized.
6663** ^If the [threading mode] is Single-thread or Multi-thread then this
6664** routine returns a NULL pointer.
6665*/
6666SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
6667
6668/*
6669** CAPI3REF: Low-Level Control Of Database Files
6670** METHOD: sqlite3
6671**
6672** ^The [sqlite3_file_control()] interface makes a direct call to the
6673** xFileControl method for the [sqlite3_io_methods] object associated
6674** with a particular database identified by the second argument. ^The
6675** name of the database is "main" for the main database or "temp" for the
6676** TEMP database, or the name that appears after the AS keyword for
6677** databases that are added using the [ATTACH] SQL command.
6678** ^A NULL pointer can be used in place of "main" to refer to the
6679** main database file.
6680** ^The third and fourth parameters to this routine
6681** are passed directly through to the second and third parameters of
6682** the xFileControl method. ^The return value of the xFileControl
6683** method becomes the return value of this routine.
6684**
6685** ^The SQLITE_FCNTL_FILE_POINTER value for the op parameter causes
6686** a pointer to the underlying [sqlite3_file] object to be written into
6687** the space pointed to by the 4th parameter. ^The SQLITE_FCNTL_FILE_POINTER
6688** case is a short-circuit path which does not actually invoke the
6689** underlying sqlite3_io_methods.xFileControl method.
6690**
6691** ^If the second parameter (zDbName) does not match the name of any
6692** open database file, then SQLITE_ERROR is returned. ^This error
6693** code is not remembered and will not be recalled by [sqlite3_errcode()]
6694** or [sqlite3_errmsg()]. The underlying xFileControl method might
6695** also return SQLITE_ERROR. There is no way to distinguish between
6696** an incorrect zDbName and an SQLITE_ERROR return from the underlying
6697** xFileControl method.
6698**
6699** See also: [SQLITE_FCNTL_LOCKSTATE]
6700*/
6701SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
6702
6703/*
6704** CAPI3REF: Testing Interface
6705**
6706** ^The sqlite3_test_control() interface is used to read out internal
6707** state of SQLite and to inject faults into SQLite for testing
6708** purposes. ^The first parameter is an operation code that determines
6709** the number, meaning, and operation of all subsequent parameters.
6710**
6711** This interface is not for use by applications. It exists solely
6712** for verifying the correct operation of the SQLite library. Depending
6713** on how the SQLite library is compiled, this interface might not exist.
6714**
6715** The details of the operation codes, their meanings, the parameters
6716** they take, and what they do are all subject to change without notice.
6717** Unlike most of the SQLite API, this function is not guaranteed to
6718** operate consistently from one release to the next.
6719*/
6720SQLITE_API int sqlite3_test_control(int op, ...);
6721
6722/*
6723** CAPI3REF: Testing Interface Operation Codes
6724**
6725** These constants are the valid operation code parameters used
6726** as the first argument to [sqlite3_test_control()].
6727**
6728** These parameters and their meanings are subject to change
6729** without notice. These values are for testing purposes only.
6730** Applications should not use any of these parameters or the
6731** [sqlite3_test_control()] interface.
6732*/
6733#define SQLITE_TESTCTRL_FIRST 5
6734#define SQLITE_TESTCTRL_PRNG_SAVE 5
6735#define SQLITE_TESTCTRL_PRNG_RESTORE 6
6736#define SQLITE_TESTCTRL_PRNG_RESET 7
6737#define SQLITE_TESTCTRL_BITVEC_TEST 8
6738#define SQLITE_TESTCTRL_FAULT_INSTALL 9
6739#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10
6740#define SQLITE_TESTCTRL_PENDING_BYTE 11
6741#define SQLITE_TESTCTRL_ASSERT 12
6742#define SQLITE_TESTCTRL_ALWAYS 13
6743#define SQLITE_TESTCTRL_RESERVE 14
6744#define SQLITE_TESTCTRL_OPTIMIZATIONS 15
6745#define SQLITE_TESTCTRL_ISKEYWORD 16
6746#define SQLITE_TESTCTRL_SCRATCHMALLOC 17
6747#define SQLITE_TESTCTRL_LOCALTIME_FAULT 18
6748#define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */
6749#define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19
6750#define SQLITE_TESTCTRL_NEVER_CORRUPT 20
6751#define SQLITE_TESTCTRL_VDBE_COVERAGE 21
6752#define SQLITE_TESTCTRL_BYTEORDER 22
6753#define SQLITE_TESTCTRL_ISINIT 23
6754#define SQLITE_TESTCTRL_SORTER_MMAP 24
6755#define SQLITE_TESTCTRL_IMPOSTER 25
6756#define SQLITE_TESTCTRL_LAST 25
6757
6758/*
6759** CAPI3REF: SQLite Runtime Status
6760**
6761** ^These interfaces are used to retrieve runtime status information
6762** about the performance of SQLite, and optionally to reset various
6763** highwater marks. ^The first argument is an integer code for
6764** the specific parameter to measure. ^(Recognized integer codes
6765** are of the form [status parameters | SQLITE_STATUS_...].)^
6766** ^The current value of the parameter is returned into *pCurrent.
6767** ^The highest recorded value is returned in *pHighwater. ^If the
6768** resetFlag is true, then the highest record value is reset after
6769** *pHighwater is written. ^(Some parameters do not record the highest
6770** value. For those parameters
6771** nothing is written into *pHighwater and the resetFlag is ignored.)^
6772** ^(Other parameters record only the highwater mark and not the current
6773** value. For these latter parameters nothing is written into *pCurrent.)^
6774**
6775** ^The sqlite3_status() and sqlite3_status64() routines return
6776** SQLITE_OK on success and a non-zero [error code] on failure.
6777**
6778** If either the current value or the highwater mark is too large to
6779** be represented by a 32-bit integer, then the values returned by
6780** sqlite3_status() are undefined.
6781**
6782** See also: [sqlite3_db_status()]
6783*/
6784SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
6785SQLITE_API int sqlite3_status64(
6786 int op,
6787 sqlite3_int64 *pCurrent,
6788 sqlite3_int64 *pHighwater,
6789 int resetFlag
6790);
6791
6792
6793/*
6794** CAPI3REF: Status Parameters
6795** KEYWORDS: {status parameters}
6796**
6797** These integer constants designate various run-time status parameters
6798** that can be returned by [sqlite3_status()].
6799**
6800** <dl>
6801** [[SQLITE_STATUS_MEMORY_USED]] ^(<dt>SQLITE_STATUS_MEMORY_USED</dt>
6802** <dd>This parameter is the current amount of memory checked out
6803** using [sqlite3_malloc()], either directly or indirectly. The
6804** figure includes calls made to [sqlite3_malloc()] by the application
6805** and internal memory usage by the SQLite library. Scratch memory
6806** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache
6807** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
6808** this parameter. The amount returned is the sum of the allocation
6809** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^
6810**
6811** [[SQLITE_STATUS_MALLOC_SIZE]] ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt>
6812** <dd>This parameter records the largest memory allocation request
6813** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
6814** internal equivalents). Only the value returned in the
6815** *pHighwater parameter to [sqlite3_status()] is of interest.
6816** The value written into the *pCurrent parameter is undefined.</dd>)^
6817**
6818** [[SQLITE_STATUS_MALLOC_COUNT]] ^(<dt>SQLITE_STATUS_MALLOC_COUNT</dt>
6819** <dd>This parameter records the number of separate memory allocations
6820** currently checked out.</dd>)^
6821**
6822** [[SQLITE_STATUS_PAGECACHE_USED]] ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt>
6823** <dd>This parameter returns the number of pages used out of the
6824** [pagecache memory allocator] that was configured using
6825** [SQLITE_CONFIG_PAGECACHE]. The
6826** value returned is in pages, not in bytes.</dd>)^
6827**
6828** [[SQLITE_STATUS_PAGECACHE_OVERFLOW]]
6829** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
6830** <dd>This parameter returns the number of bytes of page cache
6831** allocation which could not be satisfied by the [SQLITE_CONFIG_PAGECACHE]
6832** buffer and where forced to overflow to [sqlite3_malloc()]. The
6833** returned value includes allocations that overflowed because they
6834** where too large (they were larger than the "sz" parameter to
6835** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
6836** no space was left in the page cache.</dd>)^
6837**
6838** [[SQLITE_STATUS_PAGECACHE_SIZE]] ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
6839** <dd>This parameter records the largest memory allocation request
6840** handed to [pagecache memory allocator]. Only the value returned in the
6841** *pHighwater parameter to [sqlite3_status()] is of interest.
6842** The value written into the *pCurrent parameter is undefined.</dd>)^
6843**
6844** [[SQLITE_STATUS_SCRATCH_USED]] ^(<dt>SQLITE_STATUS_SCRATCH_USED</dt>
6845** <dd>This parameter returns the number of allocations used out of the
6846** [scratch memory allocator] configured using
6847** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not
6848** in bytes. Since a single thread may only have one scratch allocation
6849** outstanding at time, this parameter also reports the number of threads
6850** using scratch memory at the same time.</dd>)^
6851**
6852** [[SQLITE_STATUS_SCRATCH_OVERFLOW]] ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
6853** <dd>This parameter returns the number of bytes of scratch memory
6854** allocation which could not be satisfied by the [SQLITE_CONFIG_SCRATCH]
6855** buffer and where forced to overflow to [sqlite3_malloc()]. The values
6856** returned include overflows because the requested allocation was too
6857** larger (that is, because the requested allocation was larger than the
6858** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer
6859** slots were available.
6860** </dd>)^
6861**
6862** [[SQLITE_STATUS_SCRATCH_SIZE]] ^(<dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
6863** <dd>This parameter records the largest memory allocation request
6864** handed to [scratch memory allocator]. Only the value returned in the
6865** *pHighwater parameter to [sqlite3_status()] is of interest.
6866** The value written into the *pCurrent parameter is undefined.</dd>)^
6867**
6868** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
6869** <dd>The *pHighwater parameter records the deepest parser stack.
6870** The *pCurrent value is undefined. The *pHighwater value is only
6871** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
6872** </dl>
6873**
6874** New status parameters may be added from time to time.
6875*/
6876#define SQLITE_STATUS_MEMORY_USED 0
6877#define SQLITE_STATUS_PAGECACHE_USED 1
6878#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2
6879#define SQLITE_STATUS_SCRATCH_USED 3
6880#define SQLITE_STATUS_SCRATCH_OVERFLOW 4
6881#define SQLITE_STATUS_MALLOC_SIZE 5
6882#define SQLITE_STATUS_PARSER_STACK 6
6883#define SQLITE_STATUS_PAGECACHE_SIZE 7
6884#define SQLITE_STATUS_SCRATCH_SIZE 8
6885#define SQLITE_STATUS_MALLOC_COUNT 9
6886
6887/*
6888** CAPI3REF: Database Connection Status
6889** METHOD: sqlite3
6890**
6891** ^This interface is used to retrieve runtime status information
6892** about a single [database connection]. ^The first argument is the
6893** database connection object to be interrogated. ^The second argument
6894** is an integer constant, taken from the set of
6895** [SQLITE_DBSTATUS options], that
6896** determines the parameter to interrogate. The set of
6897** [SQLITE_DBSTATUS options] is likely
6898** to grow in future releases of SQLite.
6899**
6900** ^The current value of the requested parameter is written into *pCur
6901** and the highest instantaneous value is written into *pHiwtr. ^If
6902** the resetFlg is true, then the highest instantaneous value is
6903** reset back down to the current value.
6904**
6905** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a
6906** non-zero [error code] on failure.
6907**
6908** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
6909*/
6910SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
6911
6912/*
6913** CAPI3REF: Status Parameters for database connections
6914** KEYWORDS: {SQLITE_DBSTATUS options}
6915**
6916** These constants are the available integer "verbs" that can be passed as
6917** the second argument to the [sqlite3_db_status()] interface.
6918**
6919** New verbs may be added in future releases of SQLite. Existing verbs
6920** might be discontinued. Applications should check the return code from
6921** [sqlite3_db_status()] to make sure that the call worked.
6922** The [sqlite3_db_status()] interface will return a non-zero error code
6923** if a discontinued or unsupported verb is invoked.
6924**
6925** <dl>
6926** [[SQLITE_DBSTATUS_LOOKASIDE_USED]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
6927** <dd>This parameter returns the number of lookaside memory slots currently
6928** checked out.</dd>)^
6929**
6930** [[SQLITE_DBSTATUS_LOOKASIDE_HIT]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_HIT</dt>
6931** <dd>This parameter returns the number malloc attempts that were
6932** satisfied using lookaside memory. Only the high-water value is meaningful;
6933** the current value is always zero.)^
6934**
6935** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE]]
6936** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</dt>
6937** <dd>This parameter returns the number malloc attempts that might have
6938** been satisfied using lookaside memory but failed due to the amount of
6939** memory requested being larger than the lookaside slot size.
6940** Only the high-water value is meaningful;
6941** the current value is always zero.)^
6942**
6943** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL]]
6944** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</dt>
6945** <dd>This parameter returns the number malloc attempts that might have
6946** been satisfied using lookaside memory but failed due to all lookaside
6947** memory already being in use.
6948** Only the high-water value is meaningful;
6949** the current value is always zero.)^
6950**
6951** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt>
6952** <dd>This parameter returns the approximate number of bytes of heap
6953** memory used by all pager caches associated with the database connection.)^
6954** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
6955**
6956** [[SQLITE_DBSTATUS_CACHE_USED_SHARED]]
6957** ^(<dt>SQLITE_DBSTATUS_CACHE_USED_SHARED</dt>
6958** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a
6959** pager cache is shared between two or more connections the bytes of heap
6960** memory used by that pager cache is divided evenly between the attached
6961** connections.)^ In other words, if none of the pager caches associated
6962** with the database connection are shared, this request returns the same
6963** value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are
6964** shared, the value returned by this call will be smaller than that returned
6965** by DBSTATUS_CACHE_USED. ^The highwater mark associated with
6966** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.
6967**
6968** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt>
6969** <dd>This parameter returns the approximate number of bytes of heap
6970** memory used to store the schema for all databases associated
6971** with the connection - main, temp, and any [ATTACH]-ed databases.)^
6972** ^The full amount of memory used by the schemas is reported, even if the
6973** schema memory is shared with other database connections due to
6974** [shared cache mode] being enabled.
6975** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.
6976**
6977** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt>
6978** <dd>This parameter returns the approximate number of bytes of heap
6979** and lookaside memory used by all prepared statements associated with
6980** the database connection.)^
6981** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.
6982** </dd>
6983**
6984** [[SQLITE_DBSTATUS_CACHE_HIT]] ^(<dt>SQLITE_DBSTATUS_CACHE_HIT</dt>
6985** <dd>This parameter returns the number of pager cache hits that have
6986** occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT
6987** is always 0.
6988** </dd>
6989**
6990** [[SQLITE_DBSTATUS_CACHE_MISS]] ^(<dt>SQLITE_DBSTATUS_CACHE_MISS</dt>
6991** <dd>This parameter returns the number of pager cache misses that have
6992** occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS
6993** is always 0.
6994** </dd>
6995**
6996** [[SQLITE_DBSTATUS_CACHE_WRITE]] ^(<dt>SQLITE_DBSTATUS_CACHE_WRITE</dt>
6997** <dd>This parameter returns the number of dirty cache entries that have
6998** been written to disk. Specifically, the number of pages written to the
6999** wal file in wal mode databases, or the number of pages written to the
7000** database file in rollback mode databases. Any pages written as part of
7001** transaction rollback or database recovery operations are not included.
7002** If an IO or other error occurs while writing a page to disk, the effect
7003** on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The
7004** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.
7005** </dd>
7006**
7007** [[SQLITE_DBSTATUS_DEFERRED_FKS]] ^(<dt>SQLITE_DBSTATUS_DEFERRED_FKS</dt>
7008** <dd>This parameter returns zero for the current value if and only if
7009** all foreign key constraints (deferred or immediate) have been
7010** resolved.)^ ^The highwater mark is always 0.
7011** </dd>
7012** </dl>
7013*/
7014#define SQLITE_DBSTATUS_LOOKASIDE_USED 0
7015#define SQLITE_DBSTATUS_CACHE_USED 1
7016#define SQLITE_DBSTATUS_SCHEMA_USED 2
7017#define SQLITE_DBSTATUS_STMT_USED 3
7018#define SQLITE_DBSTATUS_LOOKASIDE_HIT 4
7019#define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5
7020#define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6
7021#define SQLITE_DBSTATUS_CACHE_HIT 7
7022#define SQLITE_DBSTATUS_CACHE_MISS 8
7023#define SQLITE_DBSTATUS_CACHE_WRITE 9
7024#define SQLITE_DBSTATUS_DEFERRED_FKS 10
7025#define SQLITE_DBSTATUS_CACHE_USED_SHARED 11
7026#define SQLITE_DBSTATUS_MAX 11 /* Largest defined DBSTATUS */
7027
7028
7029/*
7030** CAPI3REF: Prepared Statement Status
7031** METHOD: sqlite3_stmt
7032**
7033** ^(Each prepared statement maintains various
7034** [SQLITE_STMTSTATUS counters] that measure the number
7035** of times it has performed specific operations.)^ These counters can
7036** be used to monitor the performance characteristics of the prepared
7037** statements. For example, if the number of table steps greatly exceeds
7038** the number of table searches or result rows, that would tend to indicate
7039** that the prepared statement is using a full table scan rather than
7040** an index.
7041**
7042** ^(This interface is used to retrieve and reset counter values from
7043** a [prepared statement]. The first argument is the prepared statement
7044** object to be interrogated. The second argument
7045** is an integer code for a specific [SQLITE_STMTSTATUS counter]
7046** to be interrogated.)^
7047** ^The current value of the requested counter is returned.
7048** ^If the resetFlg is true, then the counter is reset to zero after this
7049** interface call returns.
7050**
7051** See also: [sqlite3_status()] and [sqlite3_db_status()].
7052*/
7053SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
7054
7055/*
7056** CAPI3REF: Status Parameters for prepared statements
7057** KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters}
7058**
7059** These preprocessor macros define integer codes that name counter
7060** values associated with the [sqlite3_stmt_status()] interface.
7061** The meanings of the various counters are as follows:
7062**
7063** <dl>
7064** [[SQLITE_STMTSTATUS_FULLSCAN_STEP]] <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>
7065** <dd>^This is the number of times that SQLite has stepped forward in
7066** a table as part of a full table scan. Large numbers for this counter
7067** may indicate opportunities for performance improvement through
7068** careful use of indices.</dd>
7069**
7070** [[SQLITE_STMTSTATUS_SORT]] <dt>SQLITE_STMTSTATUS_SORT</dt>
7071** <dd>^This is the number of sort operations that have occurred.
7072** A non-zero value in this counter may indicate an opportunity to
7073** improvement performance through careful use of indices.</dd>
7074**
7075** [[SQLITE_STMTSTATUS_AUTOINDEX]] <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt>
7076** <dd>^This is the number of rows inserted into transient indices that
7077** were created automatically in order to help joins run faster.
7078** A non-zero value in this counter may indicate an opportunity to
7079** improvement performance by adding permanent indices that do not
7080** need to be reinitialized each time the statement is run.</dd>
7081**
7082** [[SQLITE_STMTSTATUS_VM_STEP]] <dt>SQLITE_STMTSTATUS_VM_STEP</dt>
7083** <dd>^This is the number of virtual machine operations executed
7084** by the prepared statement if that number is less than or equal
7085** to 2147483647. The number of virtual machine operations can be
7086** used as a proxy for the total work done by the prepared statement.
7087** If the number of virtual machine operations exceeds 2147483647
7088** then the value returned by this statement status code is undefined.
7089** </dd>
7090** </dl>
7091*/
7092#define SQLITE_STMTSTATUS_FULLSCAN_STEP 1
7093#define SQLITE_STMTSTATUS_SORT 2
7094#define SQLITE_STMTSTATUS_AUTOINDEX 3
7095#define SQLITE_STMTSTATUS_VM_STEP 4
7096
7097/*
7098** CAPI3REF: Custom Page Cache Object
7099**
7100** The sqlite3_pcache type is opaque. It is implemented by
7101** the pluggable module. The SQLite core has no knowledge of
7102** its size or internal structure and never deals with the
7103** sqlite3_pcache object except by holding and passing pointers
7104** to the object.
7105**
7106** See [sqlite3_pcache_methods2] for additional information.
7107*/
7108typedef struct sqlite3_pcache sqlite3_pcache;
7109
7110/*
7111** CAPI3REF: Custom Page Cache Object
7112**
7113** The sqlite3_pcache_page object represents a single page in the
7114** page cache. The page cache will allocate instances of this
7115** object. Various methods of the page cache use pointers to instances
7116** of this object as parameters or as their return value.
7117**
7118** See [sqlite3_pcache_methods2] for additional information.
7119*/
7120typedef struct sqlite3_pcache_page sqlite3_pcache_page;
7121struct sqlite3_pcache_page {
7122 void *pBuf; /* The content of the page */
7123 void *pExtra; /* Extra information associated with the page */
7124};
7125
7126/*
7127** CAPI3REF: Application Defined Page Cache.
7128** KEYWORDS: {page cache}
7129**
7130** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE2], ...) interface can
7131** register an alternative page cache implementation by passing in an
7132** instance of the sqlite3_pcache_methods2 structure.)^
7133** In many applications, most of the heap memory allocated by
7134** SQLite is used for the page cache.
7135** By implementing a
7136** custom page cache using this API, an application can better control
7137** the amount of memory consumed by SQLite, the way in which
7138** that memory is allocated and released, and the policies used to
7139** determine exactly which parts of a database file are cached and for
7140** how long.
7141**
7142** The alternative page cache mechanism is an
7143** extreme measure that is only needed by the most demanding applications.
7144** The built-in page cache is recommended for most uses.
7145**
7146** ^(The contents of the sqlite3_pcache_methods2 structure are copied to an
7147** internal buffer by SQLite within the call to [sqlite3_config]. Hence
7148** the application may discard the parameter after the call to
7149** [sqlite3_config()] returns.)^
7150**
7151** [[the xInit() page cache method]]
7152** ^(The xInit() method is called once for each effective
7153** call to [sqlite3_initialize()])^
7154** (usually only once during the lifetime of the process). ^(The xInit()
7155** method is passed a copy of the sqlite3_pcache_methods2.pArg value.)^
7156** The intent of the xInit() method is to set up global data structures
7157** required by the custom page cache implementation.
7158** ^(If the xInit() method is NULL, then the
7159** built-in default page cache is used instead of the application defined
7160** page cache.)^
7161**
7162** [[the xShutdown() page cache method]]
7163** ^The xShutdown() method is called by [sqlite3_shutdown()].
7164** It can be used to clean up
7165** any outstanding resources before process shutdown, if required.
7166** ^The xShutdown() method may be NULL.
7167**
7168** ^SQLite automatically serializes calls to the xInit method,
7169** so the xInit method need not be threadsafe. ^The
7170** xShutdown method is only called from [sqlite3_shutdown()] so it does
7171** not need to be threadsafe either. All other methods must be threadsafe
7172** in multithreaded applications.
7173**
7174** ^SQLite will never invoke xInit() more than once without an intervening
7175** call to xShutdown().
7176**
7177** [[the xCreate() page cache methods]]
7178** ^SQLite invokes the xCreate() method to construct a new cache instance.
7179** SQLite will typically create one cache instance for each open database file,
7180** though this is not guaranteed. ^The
7181** first parameter, szPage, is the size in bytes of the pages that must
7182** be allocated by the cache. ^szPage will always a power of two. ^The
7183** second parameter szExtra is a number of bytes of extra storage
7184** associated with each page cache entry. ^The szExtra parameter will
7185** a number less than 250. SQLite will use the
7186** extra szExtra bytes on each page to store metadata about the underlying
7187** database page on disk. The value passed into szExtra depends
7188** on the SQLite version, the target platform, and how SQLite was compiled.
7189** ^The third argument to xCreate(), bPurgeable, is true if the cache being
7190** created will be used to cache database pages of a file stored on disk, or
7191** false if it is used for an in-memory database. The cache implementation
7192** does not have to do anything special based with the value of bPurgeable;
7193** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
7194** never invoke xUnpin() except to deliberately delete a page.
7195** ^In other words, calls to xUnpin() on a cache with bPurgeable set to
7196** false will always have the "discard" flag set to true.
7197** ^Hence, a cache created with bPurgeable false will
7198** never contain any unpinned pages.
7199**
7200** [[the xCachesize() page cache method]]
7201** ^(The xCachesize() method may be called at any time by SQLite to set the
7202** suggested maximum cache-size (number of pages stored by) the cache
7203** instance passed as the first argument. This is the value configured using
7204** the SQLite "[PRAGMA cache_size]" command.)^ As with the bPurgeable
7205** parameter, the implementation is not required to do anything with this
7206** value; it is advisory only.
7207**
7208** [[the xPagecount() page cache methods]]
7209** The xPagecount() method must return the number of pages currently
7210** stored in the cache, both pinned and unpinned.
7211**
7212** [[the xFetch() page cache methods]]
7213** The xFetch() method locates a page in the cache and returns a pointer to
7214** an sqlite3_pcache_page object associated with that page, or a NULL pointer.
7215** The pBuf element of the returned sqlite3_pcache_page object will be a
7216** pointer to a buffer of szPage bytes used to store the content of a
7217** single database page. The pExtra element of sqlite3_pcache_page will be
7218** a pointer to the szExtra bytes of extra storage that SQLite has requested
7219** for each entry in the page cache.
7220**
7221** The page to be fetched is determined by the key. ^The minimum key value
7222** is 1. After it has been retrieved using xFetch, the page is considered
7223** to be "pinned".
7224**
7225** If the requested page is already in the page cache, then the page cache
7226** implementation must return a pointer to the page buffer with its content
7227** intact. If the requested page is not already in the cache, then the
7228** cache implementation should use the value of the createFlag
7229** parameter to help it determined what action to take:
7230**
7231** <table border=1 width=85% align=center>
7232** <tr><th> createFlag <th> Behavior when page is not already in cache
7233** <tr><td> 0 <td> Do not allocate a new page. Return NULL.
7234** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
7235** Otherwise return NULL.
7236** <tr><td> 2 <td> Make every effort to allocate a new page. Only return
7237** NULL if allocating a new page is effectively impossible.
7238** </table>
7239**
7240** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite
7241** will only use a createFlag of 2 after a prior call with a createFlag of 1
7242** failed.)^ In between the to xFetch() calls, SQLite may
7243** attempt to unpin one or more cache pages by spilling the content of
7244** pinned pages to disk and synching the operating system disk cache.
7245**
7246** [[the xUnpin() page cache method]]
7247** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
7248** as its second argument. If the third parameter, discard, is non-zero,
7249** then the page must be evicted from the cache.
7250** ^If the discard parameter is
7251** zero, then the page may be discarded or retained at the discretion of
7252** page cache implementation. ^The page cache implementation
7253** may choose to evict unpinned pages at any time.
7254**
7255** The cache must not perform any reference counting. A single
7256** call to xUnpin() unpins the page regardless of the number of prior calls
7257** to xFetch().
7258**
7259** [[the xRekey() page cache methods]]
7260** The xRekey() method is used to change the key value associated with the
7261** page passed as the second argument. If the cache
7262** previously contains an entry associated with newKey, it must be
7263** discarded. ^Any prior cache entry associated with newKey is guaranteed not
7264** to be pinned.
7265**
7266** When SQLite calls the xTruncate() method, the cache must discard all
7267** existing cache entries with page numbers (keys) greater than or equal
7268** to the value of the iLimit parameter passed to xTruncate(). If any
7269** of these pages are pinned, they are implicitly unpinned, meaning that
7270** they can be safely discarded.
7271**
7272** [[the xDestroy() page cache method]]
7273** ^The xDestroy() method is used to delete a cache allocated by xCreate().
7274** All resources associated with the specified cache should be freed. ^After
7275** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
7276** handle invalid, and will not use it with any other sqlite3_pcache_methods2
7277** functions.
7278**
7279** [[the xShrink() page cache method]]
7280** ^SQLite invokes the xShrink() method when it wants the page cache to
7281** free up as much of heap memory as possible. The page cache implementation
7282** is not obligated to free any memory, but well-behaved implementations should
7283** do their best.
7284*/
7285typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;
7286struct sqlite3_pcache_methods2 {
7287 int iVersion;
7288 void *pArg;
7289 int (*xInit)(void*);
7290 void (*xShutdown)(void*);
7291 sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);
7292 void (*xCachesize)(sqlite3_pcache*, int nCachesize);
7293 int (*xPagecount)(sqlite3_pcache*);
7294 sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
7295 void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);
7296 void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*,
7297 unsigned oldKey, unsigned newKey);
7298 void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
7299 void (*xDestroy)(sqlite3_pcache*);
7300 void (*xShrink)(sqlite3_pcache*);
7301};
7302
7303/*
7304** This is the obsolete pcache_methods object that has now been replaced
7305** by sqlite3_pcache_methods2. This object is not used by SQLite. It is
7306** retained in the header file for backwards compatibility only.
7307*/
7308typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
7309struct sqlite3_pcache_methods {
7310 void *pArg;
7311 int (*xInit)(void*);
7312 void (*xShutdown)(void*);
7313 sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);
7314 void (*xCachesize)(sqlite3_pcache*, int nCachesize);
7315 int (*xPagecount)(sqlite3_pcache*);
7316 void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
7317 void (*xUnpin)(sqlite3_pcache*, void*, int discard);
7318 void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
7319 void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
7320 void (*xDestroy)(sqlite3_pcache*);
7321};
7322
7323
7324/*
7325** CAPI3REF: Online Backup Object
7326**
7327** The sqlite3_backup object records state information about an ongoing
7328** online backup operation. ^The sqlite3_backup object is created by
7329** a call to [sqlite3_backup_init()] and is destroyed by a call to
7330** [sqlite3_backup_finish()].
7331**
7332** See Also: [Using the SQLite Online Backup API]
7333*/
7334typedef struct sqlite3_backup sqlite3_backup;
7335
7336/*
7337** CAPI3REF: Online Backup API.
7338**
7339** The backup API copies the content of one database into another.
7340** It is useful either for creating backups of databases or
7341** for copying in-memory databases to or from persistent files.
7342**
7343** See Also: [Using the SQLite Online Backup API]
7344**
7345** ^SQLite holds a write transaction open on the destination database file
7346** for the duration of the backup operation.
7347** ^The source database is read-locked only while it is being read;
7348** it is not locked continuously for the entire backup operation.
7349** ^Thus, the backup may be performed on a live source database without
7350** preventing other database connections from
7351** reading or writing to the source database while the backup is underway.
7352**
7353** ^(To perform a backup operation:
7354** <ol>
7355** <li><b>sqlite3_backup_init()</b> is called once to initialize the
7356** backup,
7357** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
7358** the data between the two databases, and finally
7359** <li><b>sqlite3_backup_finish()</b> is called to release all resources
7360** associated with the backup operation.
7361** </ol>)^
7362** There should be exactly one call to sqlite3_backup_finish() for each
7363** successful call to sqlite3_backup_init().
7364**
7365** [[sqlite3_backup_init()]] <b>sqlite3_backup_init()</b>
7366**
7367** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
7368** [database connection] associated with the destination database
7369** and the database name, respectively.
7370** ^The database name is "main" for the main database, "temp" for the
7371** temporary database, or the name specified after the AS keyword in
7372** an [ATTACH] statement for an attached database.
7373** ^The S and M arguments passed to
7374** sqlite3_backup_init(D,N,S,M) identify the [database connection]
7375** and database name of the source database, respectively.
7376** ^The source and destination [database connections] (parameters S and D)
7377** must be different or else sqlite3_backup_init(D,N,S,M) will fail with
7378** an error.
7379**
7380** ^A call to sqlite3_backup_init() will fail, returning NULL, if
7381** there is already a read or read-write transaction open on the
7382** destination database.
7383**
7384** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
7385** returned and an error code and error message are stored in the
7386** destination [database connection] D.
7387** ^The error code and message for the failed call to sqlite3_backup_init()
7388** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
7389** [sqlite3_errmsg16()] functions.
7390** ^A successful call to sqlite3_backup_init() returns a pointer to an
7391** [sqlite3_backup] object.
7392** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
7393** sqlite3_backup_finish() functions to perform the specified backup
7394** operation.
7395**
7396** [[sqlite3_backup_step()]] <b>sqlite3_backup_step()</b>
7397**
7398** ^Function sqlite3_backup_step(B,N) will copy up to N pages between
7399** the source and destination databases specified by [sqlite3_backup] object B.
7400** ^If N is negative, all remaining source pages are copied.
7401** ^If sqlite3_backup_step(B,N) successfully copies N pages and there
7402** are still more pages to be copied, then the function returns [SQLITE_OK].
7403** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages
7404** from source to destination, then it returns [SQLITE_DONE].
7405** ^If an error occurs while running sqlite3_backup_step(B,N),
7406** then an [error code] is returned. ^As well as [SQLITE_OK] and
7407** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
7408** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
7409** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
7410**
7411** ^(The sqlite3_backup_step() might return [SQLITE_READONLY] if
7412** <ol>
7413** <li> the destination database was opened read-only, or
7414** <li> the destination database is using write-ahead-log journaling
7415** and the destination and source page sizes differ, or
7416** <li> the destination database is an in-memory database and the
7417** destination and source page sizes differ.
7418** </ol>)^
7419**
7420** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
7421** the [sqlite3_busy_handler | busy-handler function]
7422** is invoked (if one is specified). ^If the
7423** busy-handler returns non-zero before the lock is available, then
7424** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
7425** sqlite3_backup_step() can be retried later. ^If the source
7426** [database connection]
7427** is being used to write to the source database when sqlite3_backup_step()
7428** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
7429** case the call to sqlite3_backup_step() can be retried later on. ^(If
7430** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
7431** [SQLITE_READONLY] is returned, then
7432** there is no point in retrying the call to sqlite3_backup_step(). These
7433** errors are considered fatal.)^ The application must accept
7434** that the backup operation has failed and pass the backup operation handle
7435** to the sqlite3_backup_finish() to release associated resources.
7436**
7437** ^The first call to sqlite3_backup_step() obtains an exclusive lock
7438** on the destination file. ^The exclusive lock is not released until either
7439** sqlite3_backup_finish() is called or the backup operation is complete
7440** and sqlite3_backup_step() returns [SQLITE_DONE]. ^Every call to
7441** sqlite3_backup_step() obtains a [shared lock] on the source database that
7442** lasts for the duration of the sqlite3_backup_step() call.
7443** ^Because the source database is not locked between calls to
7444** sqlite3_backup_step(), the source database may be modified mid-way
7445** through the backup process. ^If the source database is modified by an
7446** external process or via a database connection other than the one being
7447** used by the backup operation, then the backup will be automatically
7448** restarted by the next call to sqlite3_backup_step(). ^If the source
7449** database is modified by the using the same database connection as is used
7450** by the backup operation, then the backup database is automatically
7451** updated at the same time.
7452**
7453** [[sqlite3_backup_finish()]] <b>sqlite3_backup_finish()</b>
7454**
7455** When sqlite3_backup_step() has returned [SQLITE_DONE], or when the
7456** application wishes to abandon the backup operation, the application
7457** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
7458** ^The sqlite3_backup_finish() interfaces releases all
7459** resources associated with the [sqlite3_backup] object.
7460** ^If sqlite3_backup_step() has not yet returned [SQLITE_DONE], then any
7461** active write-transaction on the destination database is rolled back.
7462** The [sqlite3_backup] object is invalid
7463** and may not be used following a call to sqlite3_backup_finish().
7464**
7465** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
7466** sqlite3_backup_step() errors occurred, regardless or whether or not
7467** sqlite3_backup_step() completed.
7468** ^If an out-of-memory condition or IO error occurred during any prior
7469** sqlite3_backup_step() call on the same [sqlite3_backup] object, then
7470** sqlite3_backup_finish() returns the corresponding [error code].
7471**
7472** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
7473** is not a permanent error and does not affect the return value of
7474** sqlite3_backup_finish().
7475**
7476** [[sqlite3_backup_remaining()]] [[sqlite3_backup_pagecount()]]
7477** <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b>
7478**
7479** ^The sqlite3_backup_remaining() routine returns the number of pages still
7480** to be backed up at the conclusion of the most recent sqlite3_backup_step().
7481** ^The sqlite3_backup_pagecount() routine returns the total number of pages
7482** in the source database at the conclusion of the most recent
7483** sqlite3_backup_step().
7484** ^(The values returned by these functions are only updated by
7485** sqlite3_backup_step(). If the source database is modified in a way that
7486** changes the size of the source database or the number of pages remaining,
7487** those changes are not reflected in the output of sqlite3_backup_pagecount()
7488** and sqlite3_backup_remaining() until after the next
7489** sqlite3_backup_step().)^
7490**
7491** <b>Concurrent Usage of Database Handles</b>
7492**
7493** ^The source [database connection] may be used by the application for other
7494** purposes while a backup operation is underway or being initialized.
7495** ^If SQLite is compiled and configured to support threadsafe database
7496** connections, then the source database connection may be used concurrently
7497** from within other threads.
7498**
7499** However, the application must guarantee that the destination
7500** [database connection] is not passed to any other API (by any thread) after
7501** sqlite3_backup_init() is called and before the corresponding call to
7502** sqlite3_backup_finish(). SQLite does not currently check to see
7503** if the application incorrectly accesses the destination [database connection]
7504** and so no error code is reported, but the operations may malfunction
7505** nevertheless. Use of the destination database connection while a
7506** backup is in progress might also also cause a mutex deadlock.
7507**
7508** If running in [shared cache mode], the application must
7509** guarantee that the shared cache used by the destination database
7510** is not accessed while the backup is running. In practice this means
7511** that the application must guarantee that the disk file being
7512** backed up to is not accessed by any connection within the process,
7513** not just the specific connection that was passed to sqlite3_backup_init().
7514**
7515** The [sqlite3_backup] object itself is partially threadsafe. Multiple
7516** threads may safely make multiple concurrent calls to sqlite3_backup_step().
7517** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
7518** APIs are not strictly speaking threadsafe. If they are invoked at the
7519** same time as another thread is invoking sqlite3_backup_step() it is
7520** possible that they return invalid values.
7521*/
7522SQLITE_API sqlite3_backup *sqlite3_backup_init(
7523 sqlite3 *pDest, /* Destination database handle */
7524 const char *zDestName, /* Destination database name */
7525 sqlite3 *pSource, /* Source database handle */
7526 const char *zSourceName /* Source database name */
7527);
7528SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
7529SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
7530SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
7531SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
7532
7533/*
7534** CAPI3REF: Unlock Notification
7535** METHOD: sqlite3
7536**
7537** ^When running in shared-cache mode, a database operation may fail with
7538** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
7539** individual tables within the shared-cache cannot be obtained. See
7540** [SQLite Shared-Cache Mode] for a description of shared-cache locking.
7541** ^This API may be used to register a callback that SQLite will invoke
7542** when the connection currently holding the required lock relinquishes it.
7543** ^This API is only available if the library was compiled with the
7544** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
7545**
7546** See Also: [Using the SQLite Unlock Notification Feature].
7547**
7548** ^Shared-cache locks are released when a database connection concludes
7549** its current transaction, either by committing it or rolling it back.
7550**
7551** ^When a connection (known as the blocked connection) fails to obtain a
7552** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
7553** identity of the database connection (the blocking connection) that
7554** has locked the required resource is stored internally. ^After an
7555** application receives an SQLITE_LOCKED error, it may call the
7556** sqlite3_unlock_notify() method with the blocked connection handle as
7557** the first argument to register for a callback that will be invoked
7558** when the blocking connections current transaction is concluded. ^The
7559** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
7560** call that concludes the blocking connections transaction.
7561**
7562** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
7563** there is a chance that the blocking connection will have already
7564** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
7565** If this happens, then the specified callback is invoked immediately,
7566** from within the call to sqlite3_unlock_notify().)^
7567**
7568** ^If the blocked connection is attempting to obtain a write-lock on a
7569** shared-cache table, and more than one other connection currently holds
7570** a read-lock on the same table, then SQLite arbitrarily selects one of
7571** the other connections to use as the blocking connection.
7572**
7573** ^(There may be at most one unlock-notify callback registered by a
7574** blocked connection. If sqlite3_unlock_notify() is called when the
7575** blocked connection already has a registered unlock-notify callback,
7576** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
7577** called with a NULL pointer as its second argument, then any existing
7578** unlock-notify callback is canceled. ^The blocked connections
7579** unlock-notify callback may also be canceled by closing the blocked
7580** connection using [sqlite3_close()].
7581**
7582** The unlock-notify callback is not reentrant. If an application invokes
7583** any sqlite3_xxx API functions from within an unlock-notify callback, a
7584** crash or deadlock may be the result.
7585**
7586** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
7587** returns SQLITE_OK.
7588**
7589** <b>Callback Invocation Details</b>
7590**
7591** When an unlock-notify callback is registered, the application provides a
7592** single void* pointer that is passed to the callback when it is invoked.
7593** However, the signature of the callback function allows SQLite to pass
7594** it an array of void* context pointers. The first argument passed to
7595** an unlock-notify callback is a pointer to an array of void* pointers,
7596** and the second is the number of entries in the array.
7597**
7598** When a blocking connections transaction is concluded, there may be
7599** more than one blocked connection that has registered for an unlock-notify
7600** callback. ^If two or more such blocked connections have specified the
7601** same callback function, then instead of invoking the callback function
7602** multiple times, it is invoked once with the set of void* context pointers
7603** specified by the blocked connections bundled together into an array.
7604** This gives the application an opportunity to prioritize any actions
7605** related to the set of unblocked database connections.
7606**
7607** <b>Deadlock Detection</b>
7608**
7609** Assuming that after registering for an unlock-notify callback a
7610** database waits for the callback to be issued before taking any further
7611** action (a reasonable assumption), then using this API may cause the
7612** application to deadlock. For example, if connection X is waiting for
7613** connection Y's transaction to be concluded, and similarly connection
7614** Y is waiting on connection X's transaction, then neither connection
7615** will proceed and the system may remain deadlocked indefinitely.
7616**
7617** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
7618** detection. ^If a given call to sqlite3_unlock_notify() would put the
7619** system in a deadlocked state, then SQLITE_LOCKED is returned and no
7620** unlock-notify callback is registered. The system is said to be in
7621** a deadlocked state if connection A has registered for an unlock-notify
7622** callback on the conclusion of connection B's transaction, and connection
7623** B has itself registered for an unlock-notify callback when connection
7624** A's transaction is concluded. ^Indirect deadlock is also detected, so
7625** the system is also considered to be deadlocked if connection B has
7626** registered for an unlock-notify callback on the conclusion of connection
7627** C's transaction, where connection C is waiting on connection A. ^Any
7628** number of levels of indirection are allowed.
7629**
7630** <b>The "DROP TABLE" Exception</b>
7631**
7632** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
7633** always appropriate to call sqlite3_unlock_notify(). There is however,
7634** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
7635** SQLite checks if there are any currently executing SELECT statements
7636** that belong to the same connection. If there are, SQLITE_LOCKED is
7637** returned. In this case there is no "blocking connection", so invoking
7638** sqlite3_unlock_notify() results in the unlock-notify callback being
7639** invoked immediately. If the application then re-attempts the "DROP TABLE"
7640** or "DROP INDEX" query, an infinite loop might be the result.
7641**
7642** One way around this problem is to check the extended error code returned
7643** by an sqlite3_step() call. ^(If there is a blocking connection, then the
7644** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
7645** the special "DROP TABLE/INDEX" case, the extended error code is just
7646** SQLITE_LOCKED.)^
7647*/
7648SQLITE_API int sqlite3_unlock_notify(
7649 sqlite3 *pBlocked, /* Waiting connection */
7650 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
7651 void *pNotifyArg /* Argument to pass to xNotify */
7652);
7653
7654
7655/*
7656** CAPI3REF: String Comparison
7657**
7658** ^The [sqlite3_stricmp()] and [sqlite3_strnicmp()] APIs allow applications
7659** and extensions to compare the contents of two buffers containing UTF-8
7660** strings in a case-independent fashion, using the same definition of "case
7661** independence" that SQLite uses internally when comparing identifiers.
7662*/
7663SQLITE_API int sqlite3_stricmp(const char *, const char *);
7664SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
7665
7666/*
7667** CAPI3REF: String Globbing
7668*
7669** ^The [sqlite3_strglob(P,X)] interface returns zero if and only if
7670** string X matches the [GLOB] pattern P.
7671** ^The definition of [GLOB] pattern matching used in
7672** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the
7673** SQL dialect understood by SQLite. ^The [sqlite3_strglob(P,X)] function
7674** is case sensitive.
7675**
7676** Note that this routine returns zero on a match and non-zero if the strings
7677** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
7678**
7679** See also: [sqlite3_strlike()].
7680*/
7681SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr);
7682
7683/*
7684** CAPI3REF: String LIKE Matching
7685*
7686** ^The [sqlite3_strlike(P,X,E)] interface returns zero if and only if
7687** string X matches the [LIKE] pattern P with escape character E.
7688** ^The definition of [LIKE] pattern matching used in
7689** [sqlite3_strlike(P,X,E)] is the same as for the "X LIKE P ESCAPE E"
7690** operator in the SQL dialect understood by SQLite. ^For "X LIKE P" without
7691** the ESCAPE clause, set the E parameter of [sqlite3_strlike(P,X,E)] to 0.
7692** ^As with the LIKE operator, the [sqlite3_strlike(P,X,E)] function is case
7693** insensitive - equivalent upper and lower case ASCII characters match
7694** one another.
7695**
7696** ^The [sqlite3_strlike(P,X,E)] function matches Unicode characters, though
7697** only ASCII characters are case folded.
7698**
7699** Note that this routine returns zero on a match and non-zero if the strings
7700** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
7701**
7702** See also: [sqlite3_strglob()].
7703*/
7704SQLITE_API int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc);
7705
7706/*
7707** CAPI3REF: Error Logging Interface
7708**
7709** ^The [sqlite3_log()] interface writes a message into the [error log]
7710** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
7711** ^If logging is enabled, the zFormat string and subsequent arguments are
7712** used with [sqlite3_snprintf()] to generate the final output string.
7713**
7714** The sqlite3_log() interface is intended for use by extensions such as
7715** virtual tables, collating functions, and SQL functions. While there is
7716** nothing to prevent an application from calling sqlite3_log(), doing so
7717** is considered bad form.
7718**
7719** The zFormat string must not be NULL.
7720**
7721** To avoid deadlocks and other threading problems, the sqlite3_log() routine
7722** will not use dynamically allocated memory. The log message is stored in
7723** a fixed-length buffer on the stack. If the log message is longer than
7724** a few hundred characters, it will be truncated to the length of the
7725** buffer.
7726*/
7727SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
7728
7729/*
7730** CAPI3REF: Write-Ahead Log Commit Hook
7731** METHOD: sqlite3
7732**
7733** ^The [sqlite3_wal_hook()] function is used to register a callback that
7734** is invoked each time data is committed to a database in wal mode.
7735**
7736** ^(The callback is invoked by SQLite after the commit has taken place and
7737** the associated write-lock on the database released)^, so the implementation
7738** may read, write or [checkpoint] the database as required.
7739**
7740** ^The first parameter passed to the callback function when it is invoked
7741** is a copy of the third parameter passed to sqlite3_wal_hook() when
7742** registering the callback. ^The second is a copy of the database handle.
7743** ^The third parameter is the name of the database that was written to -
7744** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter
7745** is the number of pages currently in the write-ahead log file,
7746** including those that were just committed.
7747**
7748** The callback function should normally return [SQLITE_OK]. ^If an error
7749** code is returned, that error will propagate back up through the
7750** SQLite code base to cause the statement that provoked the callback
7751** to report an error, though the commit will have still occurred. If the
7752** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value
7753** that does not correspond to any valid SQLite error code, the results
7754** are undefined.
7755**
7756** A single database handle may have at most a single write-ahead log callback
7757** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any
7758** previously registered write-ahead log callback. ^Note that the
7759** [sqlite3_wal_autocheckpoint()] interface and the
7760** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
7761** overwrite any prior [sqlite3_wal_hook()] settings.
7762*/
7763SQLITE_API void *sqlite3_wal_hook(
7764 sqlite3*,
7765 int(*)(void *,sqlite3*,const char*,int),
7766 void*
7767);
7768
7769/*
7770** CAPI3REF: Configure an auto-checkpoint
7771** METHOD: sqlite3
7772**
7773** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
7774** [sqlite3_wal_hook()] that causes any database on [database connection] D
7775** to automatically [checkpoint]
7776** after committing a transaction if there are N or
7777** more frames in the [write-ahead log] file. ^Passing zero or
7778** a negative value as the nFrame parameter disables automatic
7779** checkpoints entirely.
7780**
7781** ^The callback registered by this function replaces any existing callback
7782** registered using [sqlite3_wal_hook()]. ^Likewise, registering a callback
7783** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism
7784** configured by this function.
7785**
7786** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
7787** from SQL.
7788**
7789** ^Checkpoints initiated by this mechanism are
7790** [sqlite3_wal_checkpoint_v2|PASSIVE].
7791**
7792** ^Every new [database connection] defaults to having the auto-checkpoint
7793** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]
7794** pages. The use of this interface
7795** is only necessary if the default setting is found to be suboptimal
7796** for a particular application.
7797*/
7798SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
7799
7800/*
7801** CAPI3REF: Checkpoint a database
7802** METHOD: sqlite3
7803**
7804** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to
7805** [sqlite3_wal_checkpoint_v2](D,X,[SQLITE_CHECKPOINT_PASSIVE],0,0).)^
7806**
7807** In brief, sqlite3_wal_checkpoint(D,X) causes the content in the
7808** [write-ahead log] for database X on [database connection] D to be
7809** transferred into the database file and for the write-ahead log to
7810** be reset. See the [checkpointing] documentation for addition
7811** information.
7812**
7813** This interface used to be the only way to cause a checkpoint to
7814** occur. But then the newer and more powerful [sqlite3_wal_checkpoint_v2()]
7815** interface was added. This interface is retained for backwards
7816** compatibility and as a convenience for applications that need to manually
7817** start a callback but which do not need the full power (and corresponding
7818** complication) of [sqlite3_wal_checkpoint_v2()].
7819*/
7820SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
7821
7822/*
7823** CAPI3REF: Checkpoint a database
7824** METHOD: sqlite3
7825**
7826** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint
7827** operation on database X of [database connection] D in mode M. Status
7828** information is written back into integers pointed to by L and C.)^
7829** ^(The M parameter must be a valid [checkpoint mode]:)^
7830**
7831** <dl>
7832** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
7833** ^Checkpoint as many frames as possible without waiting for any database
7834** readers or writers to finish, then sync the database file if all frames
7835** in the log were checkpointed. ^The [busy-handler callback]
7836** is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.
7837** ^On the other hand, passive mode might leave the checkpoint unfinished
7838** if there are concurrent readers or writers.
7839**
7840** <dt>SQLITE_CHECKPOINT_FULL<dd>
7841** ^This mode blocks (it invokes the
7842** [sqlite3_busy_handler|busy-handler callback]) until there is no
7843** database writer and all readers are reading from the most recent database
7844** snapshot. ^It then checkpoints all frames in the log file and syncs the
7845** database file. ^This mode blocks new database writers while it is pending,
7846** but new database readers are allowed to continue unimpeded.
7847**
7848** <dt>SQLITE_CHECKPOINT_RESTART<dd>
7849** ^This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition
7850** that after checkpointing the log file it blocks (calls the
7851** [busy-handler callback])
7852** until all readers are reading from the database file only. ^This ensures
7853** that the next writer will restart the log file from the beginning.
7854** ^Like SQLITE_CHECKPOINT_FULL, this mode blocks new
7855** database writer attempts while it is pending, but does not impede readers.
7856**
7857** <dt>SQLITE_CHECKPOINT_TRUNCATE<dd>
7858** ^This mode works the same way as SQLITE_CHECKPOINT_RESTART with the
7859** addition that it also truncates the log file to zero bytes just prior
7860** to a successful return.
7861** </dl>
7862**
7863** ^If pnLog is not NULL, then *pnLog is set to the total number of frames in
7864** the log file or to -1 if the checkpoint could not run because
7865** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not
7866** NULL,then *pnCkpt is set to the total number of checkpointed frames in the
7867** log file (including any that were already checkpointed before the function
7868** was called) or to -1 if the checkpoint could not run due to an error or
7869** because the database is not in WAL mode. ^Note that upon successful
7870** completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been
7871** truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.
7872**
7873** ^All calls obtain an exclusive "checkpoint" lock on the database file. ^If
7874** any other process is running a checkpoint operation at the same time, the
7875** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a
7876** busy-handler configured, it will not be invoked in this case.
7877**
7878** ^The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the
7879** exclusive "writer" lock on the database file. ^If the writer lock cannot be
7880** obtained immediately, and a busy-handler is configured, it is invoked and
7881** the writer lock retried until either the busy-handler returns 0 or the lock
7882** is successfully obtained. ^The busy-handler is also invoked while waiting for
7883** database readers as described above. ^If the busy-handler returns 0 before
7884** the writer lock is obtained or while waiting for database readers, the
7885** checkpoint operation proceeds from that point in the same way as
7886** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
7887** without blocking any further. ^SQLITE_BUSY is returned in this case.
7888**
7889** ^If parameter zDb is NULL or points to a zero length string, then the
7890** specified operation is attempted on all WAL databases [attached] to
7891** [database connection] db. In this case the
7892** values written to output parameters *pnLog and *pnCkpt are undefined. ^If
7893** an SQLITE_BUSY error is encountered when processing one or more of the
7894** attached WAL databases, the operation is still attempted on any remaining
7895** attached databases and SQLITE_BUSY is returned at the end. ^If any other
7896** error occurs while processing an attached database, processing is abandoned
7897** and the error code is returned to the caller immediately. ^If no error
7898** (SQLITE_BUSY or otherwise) is encountered while processing the attached
7899** databases, SQLITE_OK is returned.
7900**
7901** ^If database zDb is the name of an attached database that is not in WAL
7902** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If
7903** zDb is not NULL (or a zero length string) and is not the name of any
7904** attached database, SQLITE_ERROR is returned to the caller.
7905**
7906** ^Unless it returns SQLITE_MISUSE,
7907** the sqlite3_wal_checkpoint_v2() interface
7908** sets the error information that is queried by
7909** [sqlite3_errcode()] and [sqlite3_errmsg()].
7910**
7911** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface
7912** from SQL.
7913*/
7914SQLITE_API int sqlite3_wal_checkpoint_v2(
7915 sqlite3 *db, /* Database handle */
7916 const char *zDb, /* Name of attached database (or NULL) */
7917 int eMode, /* SQLITE_CHECKPOINT_* value */
7918 int *pnLog, /* OUT: Size of WAL log in frames */
7919 int *pnCkpt /* OUT: Total number of frames checkpointed */
7920);
7921
7922/*
7923** CAPI3REF: Checkpoint Mode Values
7924** KEYWORDS: {checkpoint mode}
7925**
7926** These constants define all valid values for the "checkpoint mode" passed
7927** as the third parameter to the [sqlite3_wal_checkpoint_v2()] interface.
7928** See the [sqlite3_wal_checkpoint_v2()] documentation for details on the
7929** meaning of each of these checkpoint modes.
7930*/
7931#define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */
7932#define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */
7933#define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for for readers */
7934#define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */
7935
7936/*
7937** CAPI3REF: Virtual Table Interface Configuration
7938**
7939** This function may be called by either the [xConnect] or [xCreate] method
7940** of a [virtual table] implementation to configure
7941** various facets of the virtual table interface.
7942**
7943** If this interface is invoked outside the context of an xConnect or
7944** xCreate virtual table method then the behavior is undefined.
7945**
7946** At present, there is only one option that may be configured using
7947** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].) Further options
7948** may be added in the future.
7949*/
7950SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);
7951
7952/*
7953** CAPI3REF: Virtual Table Configuration Options
7954**
7955** These macros define the various options to the
7956** [sqlite3_vtab_config()] interface that [virtual table] implementations
7957** can use to customize and optimize their behavior.
7958**
7959** <dl>
7960** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT
7961** <dd>Calls of the form
7962** [sqlite3_vtab_config](db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported,
7963** where X is an integer. If X is zero, then the [virtual table] whose
7964** [xCreate] or [xConnect] method invoked [sqlite3_vtab_config()] does not
7965** support constraints. In this configuration (which is the default) if
7966** a call to the [xUpdate] method returns [SQLITE_CONSTRAINT], then the entire
7967** statement is rolled back as if [ON CONFLICT | OR ABORT] had been
7968** specified as part of the users SQL statement, regardless of the actual
7969** ON CONFLICT mode specified.
7970**
7971** If X is non-zero, then the virtual table implementation guarantees
7972** that if [xUpdate] returns [SQLITE_CONSTRAINT], it will do so before
7973** any modifications to internal or persistent data structures have been made.
7974** If the [ON CONFLICT] mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite
7975** is able to roll back a statement or database transaction, and abandon
7976** or continue processing the current SQL statement as appropriate.
7977** If the ON CONFLICT mode is REPLACE and the [xUpdate] method returns
7978** [SQLITE_CONSTRAINT], SQLite handles this as if the ON CONFLICT mode
7979** had been ABORT.
7980**
7981** Virtual table implementations that are required to handle OR REPLACE
7982** must do so within the [xUpdate] method. If a call to the
7983** [sqlite3_vtab_on_conflict()] function indicates that the current ON
7984** CONFLICT policy is REPLACE, the virtual table implementation should
7985** silently replace the appropriate rows within the xUpdate callback and
7986** return SQLITE_OK. Or, if this is not possible, it may return
7987** SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT
7988** constraint handling.
7989** </dl>
7990*/
7991#define SQLITE_VTAB_CONSTRAINT_SUPPORT 1
7992
7993/*
7994** CAPI3REF: Determine The Virtual Table Conflict Policy
7995**
7996** This function may only be called from within a call to the [xUpdate] method
7997** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The
7998** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL],
7999** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode
8000** of the SQL statement that triggered the call to the [xUpdate] method of the
8001** [virtual table].
8002*/
8003SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
8004
8005/*
8006** CAPI3REF: Conflict resolution modes
8007** KEYWORDS: {conflict resolution mode}
8008**
8009** These constants are returned by [sqlite3_vtab_on_conflict()] to
8010** inform a [virtual table] implementation what the [ON CONFLICT] mode
8011** is for the SQL statement being evaluated.
8012**
8013** Note that the [SQLITE_IGNORE] constant is also used as a potential
8014** return value from the [sqlite3_set_authorizer()] callback and that
8015** [SQLITE_ABORT] is also a [result code].
8016*/
8017#define SQLITE_ROLLBACK 1
8018/* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */
8019#define SQLITE_FAIL 3
8020/* #define SQLITE_ABORT 4 // Also an error code */
8021#define SQLITE_REPLACE 5
8022
8023/*
8024** CAPI3REF: Prepared Statement Scan Status Opcodes
8025** KEYWORDS: {scanstatus options}
8026**
8027** The following constants can be used for the T parameter to the
8028** [sqlite3_stmt_scanstatus(S,X,T,V)] interface. Each constant designates a
8029** different metric for sqlite3_stmt_scanstatus() to return.
8030**
8031** When the value returned to V is a string, space to hold that string is
8032** managed by the prepared statement S and will be automatically freed when
8033** S is finalized.
8034**
8035** <dl>
8036** [[SQLITE_SCANSTAT_NLOOP]] <dt>SQLITE_SCANSTAT_NLOOP</dt>
8037** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be
8038** set to the total number of times that the X-th loop has run.</dd>
8039**
8040** [[SQLITE_SCANSTAT_NVISIT]] <dt>SQLITE_SCANSTAT_NVISIT</dt>
8041** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set
8042** to the total number of rows examined by all iterations of the X-th loop.</dd>
8043**
8044** [[SQLITE_SCANSTAT_EST]] <dt>SQLITE_SCANSTAT_EST</dt>
8045** <dd>^The "double" variable pointed to by the T parameter will be set to the
8046** query planner's estimate for the average number of rows output from each
8047** iteration of the X-th loop. If the query planner's estimates was accurate,
8048** then this value will approximate the quotient NVISIT/NLOOP and the
8049** product of this value for all prior loops with the same SELECTID will
8050** be the NLOOP value for the current loop.
8051**
8052** [[SQLITE_SCANSTAT_NAME]] <dt>SQLITE_SCANSTAT_NAME</dt>
8053** <dd>^The "const char *" variable pointed to by the T parameter will be set
8054** to a zero-terminated UTF-8 string containing the name of the index or table
8055** used for the X-th loop.
8056**
8057** [[SQLITE_SCANSTAT_EXPLAIN]] <dt>SQLITE_SCANSTAT_EXPLAIN</dt>
8058** <dd>^The "const char *" variable pointed to by the T parameter will be set
8059** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN]
8060** description for the X-th loop.
8061**
8062** [[SQLITE_SCANSTAT_SELECTID]] <dt>SQLITE_SCANSTAT_SELECT</dt>
8063** <dd>^The "int" variable pointed to by the T parameter will be set to the
8064** "select-id" for the X-th loop. The select-id identifies which query or
8065** subquery the loop is part of. The main query has a select-id of zero.
8066** The select-id is the same value as is output in the first column
8067** of an [EXPLAIN QUERY PLAN] query.
8068** </dl>
8069*/
8070#define SQLITE_SCANSTAT_NLOOP 0
8071#define SQLITE_SCANSTAT_NVISIT 1
8072#define SQLITE_SCANSTAT_EST 2
8073#define SQLITE_SCANSTAT_NAME 3
8074#define SQLITE_SCANSTAT_EXPLAIN 4
8075#define SQLITE_SCANSTAT_SELECTID 5
8076
8077/*
8078** CAPI3REF: Prepared Statement Scan Status
8079** METHOD: sqlite3_stmt
8080**
8081** This interface returns information about the predicted and measured
8082** performance for pStmt. Advanced applications can use this
8083** interface to compare the predicted and the measured performance and
8084** issue warnings and/or rerun [ANALYZE] if discrepancies are found.
8085**
8086** Since this interface is expected to be rarely used, it is only
8087** available if SQLite is compiled using the [SQLITE_ENABLE_STMT_SCANSTATUS]
8088** compile-time option.
8089**
8090** The "iScanStatusOp" parameter determines which status information to return.
8091** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior
8092** of this interface is undefined.
8093** ^The requested measurement is written into a variable pointed to by
8094** the "pOut" parameter.
8095** Parameter "idx" identifies the specific loop to retrieve statistics for.
8096** Loops are numbered starting from zero. ^If idx is out of range - less than
8097** zero or greater than or equal to the total number of loops used to implement
8098** the statement - a non-zero value is returned and the variable that pOut
8099** points to is unchanged.
8100**
8101** ^Statistics might not be available for all loops in all statements. ^In cases
8102** where there exist loops with no available statistics, this function behaves
8103** as if the loop did not exist - it returns non-zero and leave the variable
8104** that pOut points to unchanged.
8105**
8106** See also: [sqlite3_stmt_scanstatus_reset()]
8107*/
8108SQLITE_API int sqlite3_stmt_scanstatus(
8109 sqlite3_stmt *pStmt, /* Prepared statement for which info desired */
8110 int idx, /* Index of loop to report on */
8111 int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */
8112 void *pOut /* Result written here */
8113);
8114
8115/*
8116** CAPI3REF: Zero Scan-Status Counters
8117** METHOD: sqlite3_stmt
8118**
8119** ^Zero all [sqlite3_stmt_scanstatus()] related event counters.
8120**
8121** This API is only available if the library is built with pre-processor
8122** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined.
8123*/
8124SQLITE_API void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);
8125
8126/*
8127** CAPI3REF: Flush caches to disk mid-transaction
8128**
8129** ^If a write-transaction is open on [database connection] D when the
8130** [sqlite3_db_cacheflush(D)] interface invoked, any dirty
8131** pages in the pager-cache that are not currently in use are written out
8132** to disk. A dirty page may be in use if a database cursor created by an
8133** active SQL statement is reading from it, or if it is page 1 of a database
8134** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)]
8135** interface flushes caches for all schemas - "main", "temp", and
8136** any [attached] databases.
8137**
8138** ^If this function needs to obtain extra database locks before dirty pages
8139** can be flushed to disk, it does so. ^If those locks cannot be obtained
8140** immediately and there is a busy-handler callback configured, it is invoked
8141** in the usual manner. ^If the required lock still cannot be obtained, then
8142** the database is skipped and an attempt made to flush any dirty pages
8143** belonging to the next (if any) database. ^If any databases are skipped
8144** because locks cannot be obtained, but no other error occurs, this
8145** function returns SQLITE_BUSY.
8146**
8147** ^If any other error occurs while flushing dirty pages to disk (for
8148** example an IO error or out-of-memory condition), then processing is
8149** abandoned and an SQLite [error code] is returned to the caller immediately.
8150**
8151** ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK.
8152**
8153** ^This function does not set the database handle error code or message
8154** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions.
8155*/
8156SQLITE_API int sqlite3_db_cacheflush(sqlite3*);
8157
8158/*
8159** CAPI3REF: The pre-update hook.
8160**
8161** ^These interfaces are only available if SQLite is compiled using the
8162** [SQLITE_ENABLE_PREUPDATE_HOOK] compile-time option.
8163**
8164** ^The [sqlite3_preupdate_hook()] interface registers a callback function
8165** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation
8166** on a [rowid table].
8167** ^At most one preupdate hook may be registered at a time on a single
8168** [database connection]; each call to [sqlite3_preupdate_hook()] overrides
8169** the previous setting.
8170** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()]
8171** with a NULL pointer as the second parameter.
8172** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as
8173** the first parameter to callbacks.
8174**
8175** ^The preupdate hook only fires for changes to [rowid tables]; the preupdate
8176** hook is not invoked for changes to [virtual tables] or [WITHOUT ROWID]
8177** tables.
8178**
8179** ^The second parameter to the preupdate callback is a pointer to
8180** the [database connection] that registered the preupdate hook.
8181** ^The third parameter to the preupdate callback is one of the constants
8182** [SQLITE_INSERT], [SQLITE_DELETE], or [SQLITE_UPDATE] to identify the
8183** kind of update operation that is about to occur.
8184** ^(The fourth parameter to the preupdate callback is the name of the
8185** database within the database connection that is being modified. This
8186** will be "main" for the main database or "temp" for TEMP tables or
8187** the name given after the AS keyword in the [ATTACH] statement for attached
8188** databases.)^
8189** ^The fifth parameter to the preupdate callback is the name of the
8190** table that is being modified.
8191** ^The sixth parameter to the preupdate callback is the initial [rowid] of the
8192** row being changes for SQLITE_UPDATE and SQLITE_DELETE changes and is
8193** undefined for SQLITE_INSERT changes.
8194** ^The seventh parameter to the preupdate callback is the final [rowid] of
8195** the row being changed for SQLITE_UPDATE and SQLITE_INSERT changes and is
8196** undefined for SQLITE_DELETE changes.
8197**
8198** The [sqlite3_preupdate_old()], [sqlite3_preupdate_new()],
8199** [sqlite3_preupdate_count()], and [sqlite3_preupdate_depth()] interfaces
8200** provide additional information about a preupdate event. These routines
8201** may only be called from within a preupdate callback. Invoking any of
8202** these routines from outside of a preupdate callback or with a
8203** [database connection] pointer that is different from the one supplied
8204** to the preupdate callback results in undefined and probably undesirable
8205** behavior.
8206**
8207** ^The [sqlite3_preupdate_count(D)] interface returns the number of columns
8208** in the row that is being inserted, updated, or deleted.
8209**
8210** ^The [sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to
8211** a [protected sqlite3_value] that contains the value of the Nth column of
8212** the table row before it is updated. The N parameter must be between 0
8213** and one less than the number of columns or the behavior will be
8214** undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE
8215** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the
8216** behavior is undefined. The [sqlite3_value] that P points to
8217** will be destroyed when the preupdate callback returns.
8218**
8219** ^The [sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to
8220** a [protected sqlite3_value] that contains the value of the Nth column of
8221** the table row after it is updated. The N parameter must be between 0
8222** and one less than the number of columns or the behavior will be
8223** undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE
8224** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the
8225** behavior is undefined. The [sqlite3_value] that P points to
8226** will be destroyed when the preupdate callback returns.
8227**
8228** ^The [sqlite3_preupdate_depth(D)] interface returns 0 if the preupdate
8229** callback was invoked as a result of a direct insert, update, or delete
8230** operation; or 1 for inserts, updates, or deletes invoked by top-level
8231** triggers; or 2 for changes resulting from triggers called by top-level
8232** triggers; and so forth.
8233**
8234** See also: [sqlite3_update_hook()]
8235*/
8236#if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
8237SQLITE_API void *sqlite3_preupdate_hook(
8238 sqlite3 *db,
8239 void(*xPreUpdate)(
8240 void *pCtx, /* Copy of third arg to preupdate_hook() */
8241 sqlite3 *db, /* Database handle */
8242 int op, /* SQLITE_UPDATE, DELETE or INSERT */
8243 char const *zDb, /* Database name */
8244 char const *zName, /* Table name */
8245 sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */
8246 sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */
8247 ),
8248 void*
8249);
8250SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
8251SQLITE_API int sqlite3_preupdate_count(sqlite3 *);
8252SQLITE_API int sqlite3_preupdate_depth(sqlite3 *);
8253SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
8254#endif
8255
8256/*
8257** CAPI3REF: Low-level system error code
8258**
8259** ^Attempt to return the underlying operating system error code or error
8260** number that caused the most recent I/O error or failure to open a file.
8261** The return value is OS-dependent. For example, on unix systems, after
8262** [sqlite3_open_v2()] returns [SQLITE_CANTOPEN], this interface could be
8263** called to get back the underlying "errno" that caused the problem, such
8264** as ENOSPC, EAUTH, EISDIR, and so forth.
8265*/
8266SQLITE_API int sqlite3_system_errno(sqlite3*);
8267
8268/*
8269** CAPI3REF: Database Snapshot
8270** KEYWORDS: {snapshot} {sqlite3_snapshot}
8271** EXPERIMENTAL
8272**
8273** An instance of the snapshot object records the state of a [WAL mode]
8274** database for some specific point in history.
8275**
8276** In [WAL mode], multiple [database connections] that are open on the
8277** same database file can each be reading a different historical version
8278** of the database file. When a [database connection] begins a read
8279** transaction, that connection sees an unchanging copy of the database
8280** as it existed for the point in time when the transaction first started.
8281** Subsequent changes to the database from other connections are not seen
8282** by the reader until a new read transaction is started.
8283**
8284** The sqlite3_snapshot object records state information about an historical
8285** version of the database file so that it is possible to later open a new read
8286** transaction that sees that historical version of the database rather than
8287** the most recent version.
8288**
8289** The constructor for this object is [sqlite3_snapshot_get()]. The
8290** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer
8291** to an historical snapshot (if possible). The destructor for
8292** sqlite3_snapshot objects is [sqlite3_snapshot_free()].
8293*/
8294typedef struct sqlite3_snapshot {
8295 unsigned char hidden[48];
8296} sqlite3_snapshot;
8297
8298/*
8299** CAPI3REF: Record A Database Snapshot
8300** EXPERIMENTAL
8301**
8302** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a
8303** new [sqlite3_snapshot] object that records the current state of
8304** schema S in database connection D. ^On success, the
8305** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly
8306** created [sqlite3_snapshot] object into *P and returns SQLITE_OK.
8307** If there is not already a read-transaction open on schema S when
8308** this function is called, one is opened automatically.
8309**
8310** The following must be true for this function to succeed. If any of
8311** the following statements are false when sqlite3_snapshot_get() is
8312** called, SQLITE_ERROR is returned. The final value of *P is undefined
8313** in this case.
8314**
8315** <ul>
8316** <li> The database handle must be in [autocommit mode].
8317**
8318** <li> Schema S of [database connection] D must be a [WAL mode] database.
8319**
8320** <li> There must not be a write transaction open on schema S of database
8321** connection D.
8322**
8323** <li> One or more transactions must have been written to the current wal
8324** file since it was created on disk (by any connection). This means
8325** that a snapshot cannot be taken on a wal mode database with no wal
8326** file immediately after it is first opened. At least one transaction
8327** must be written to it first.
8328** </ul>
8329**
8330** This function may also return SQLITE_NOMEM. If it is called with the
8331** database handle in autocommit mode but fails for some other reason,
8332** whether or not a read transaction is opened on schema S is undefined.
8333**
8334** The [sqlite3_snapshot] object returned from a successful call to
8335** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()]
8336** to avoid a memory leak.
8337**
8338** The [sqlite3_snapshot_get()] interface is only available when the
8339** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
8340*/
8341SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get(
8342 sqlite3 *db,
8343 const char *zSchema,
8344 sqlite3_snapshot **ppSnapshot
8345);
8346
8347/*
8348** CAPI3REF: Start a read transaction on an historical snapshot
8349** EXPERIMENTAL
8350**
8351** ^The [sqlite3_snapshot_open(D,S,P)] interface starts a
8352** read transaction for schema S of
8353** [database connection] D such that the read transaction
8354** refers to historical [snapshot] P, rather than the most
8355** recent change to the database.
8356** ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success
8357** or an appropriate [error code] if it fails.
8358**
8359** ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be
8360** the first operation following the [BEGIN] that takes the schema S
8361** out of [autocommit mode].
8362** ^In other words, schema S must not currently be in
8363** a transaction for [sqlite3_snapshot_open(D,S,P)] to work, but the
8364** database connection D must be out of [autocommit mode].
8365** ^A [snapshot] will fail to open if it has been overwritten by a
8366** [checkpoint].
8367** ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the
8368** database connection D does not know that the database file for
8369** schema S is in [WAL mode]. A database connection might not know
8370** that the database file is in [WAL mode] if there has been no prior
8371** I/O on that database connection, or if the database entered [WAL mode]
8372** after the most recent I/O on the database connection.)^
8373** (Hint: Run "[PRAGMA application_id]" against a newly opened
8374** database connection in order to make it ready to use snapshots.)
8375**
8376** The [sqlite3_snapshot_open()] interface is only available when the
8377** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
8378*/
8379SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(
8380 sqlite3 *db,
8381 const char *zSchema,
8382 sqlite3_snapshot *pSnapshot
8383);
8384
8385/*
8386** CAPI3REF: Destroy a snapshot
8387** EXPERIMENTAL
8388**
8389** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P.
8390** The application must eventually free every [sqlite3_snapshot] object
8391** using this routine to avoid a memory leak.
8392**
8393** The [sqlite3_snapshot_free()] interface is only available when the
8394** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
8395*/
8396SQLITE_API SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*);
8397
8398/*
8399** CAPI3REF: Compare the ages of two snapshot handles.
8400** EXPERIMENTAL
8401**
8402** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
8403** of two valid snapshot handles.
8404**
8405** If the two snapshot handles are not associated with the same database
8406** file, the result of the comparison is undefined.
8407**
8408** Additionally, the result of the comparison is only valid if both of the
8409** snapshot handles were obtained by calling sqlite3_snapshot_get() since the
8410** last time the wal file was deleted. The wal file is deleted when the
8411** database is changed back to rollback mode or when the number of database
8412** clients drops to zero. If either snapshot handle was obtained before the
8413** wal file was last deleted, the value returned by this function
8414** is undefined.
8415**
8416** Otherwise, this API returns a negative value if P1 refers to an older
8417** snapshot than P2, zero if the two handles refer to the same database
8418** snapshot, and a positive value if P1 is a newer snapshot than P2.
8419*/
8420SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp(
8421 sqlite3_snapshot *p1,
8422 sqlite3_snapshot *p2
8423);
8424
8425/*
8426** CAPI3REF: Recover snapshots from a wal file
8427** EXPERIMENTAL
8428**
8429** If all connections disconnect from a database file but do not perform
8430** a checkpoint, the existing wal file is opened along with the database
8431** file the next time the database is opened. At this point it is only
8432** possible to successfully call sqlite3_snapshot_open() to open the most
8433** recent snapshot of the database (the one at the head of the wal file),
8434** even though the wal file may contain other valid snapshots for which
8435** clients have sqlite3_snapshot handles.
8436**
8437** This function attempts to scan the wal file associated with database zDb
8438** of database handle db and make all valid snapshots available to
8439** sqlite3_snapshot_open(). It is an error if there is already a read
8440** transaction open on the database, or if the database is not a wal mode
8441** database.
8442**
8443** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
8444*/
8445SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);
8446
8447/*
8448** Undo the hack that converts floating point types to integer for
8449** builds on processors without floating point support.
8450*/
8451#ifdef SQLITE_OMIT_FLOATING_POINT
8452# undef double
8453#endif
8454
8455#ifdef __cplusplus
8456} /* End of the 'extern "C"' block */
8457#endif
8458#endif /* SQLITE3_H */
8459
8460/******** Begin file sqlite3rtree.h *********/
8461/*
8462** 2010 August 30
8463**
8464** The author disclaims copyright to this source code. In place of
8465** a legal notice, here is a blessing:
8466**
8467** May you do good and not evil.
8468** May you find forgiveness for yourself and forgive others.
8469** May you share freely, never taking more than you give.
8470**
8471*************************************************************************
8472*/
8473
8474#ifndef _SQLITE3RTREE_H_
8475#define _SQLITE3RTREE_H_
8476
8477
8478#ifdef __cplusplus
8479extern "C" {
8480#endif
8481
8482typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
8483typedef struct sqlite3_rtree_query_info sqlite3_rtree_query_info;
8484
8485/* The double-precision datatype used by RTree depends on the
8486** SQLITE_RTREE_INT_ONLY compile-time option.
8487*/
8488#ifdef SQLITE_RTREE_INT_ONLY
8489 typedef sqlite3_int64 sqlite3_rtree_dbl;
8490#else
8491 typedef double sqlite3_rtree_dbl;
8492#endif
8493
8494/*
8495** Register a geometry callback named zGeom that can be used as part of an
8496** R-Tree geometry query as follows:
8497**
8498** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...)
8499*/
8500SQLITE_API int sqlite3_rtree_geometry_callback(
8501 sqlite3 *db,
8502 const char *zGeom,
8503 int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*),
8504 void *pContext
8505);
8506
8507
8508/*
8509** A pointer to a structure of the following type is passed as the first
8510** argument to callbacks registered using rtree_geometry_callback().
8511*/
8512struct sqlite3_rtree_geometry {
8513 void *pContext; /* Copy of pContext passed to s_r_g_c() */
8514 int nParam; /* Size of array aParam[] */
8515 sqlite3_rtree_dbl *aParam; /* Parameters passed to SQL geom function */
8516 void *pUser; /* Callback implementation user data */
8517 void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */
8518};
8519
8520/*
8521** Register a 2nd-generation geometry callback named zScore that can be
8522** used as part of an R-Tree geometry query as follows:
8523**
8524** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...)
8525*/
8526SQLITE_API int sqlite3_rtree_query_callback(
8527 sqlite3 *db,
8528 const char *zQueryFunc,
8529 int (*xQueryFunc)(sqlite3_rtree_query_info*),
8530 void *pContext,
8531 void (*xDestructor)(void*)
8532);
8533
8534
8535/*
8536** A pointer to a structure of the following type is passed as the
8537** argument to scored geometry callback registered using
8538** sqlite3_rtree_query_callback().
8539**
8540** Note that the first 5 fields of this structure are identical to
8541** sqlite3_rtree_geometry. This structure is a subclass of
8542** sqlite3_rtree_geometry.
8543*/
8544struct sqlite3_rtree_query_info {
8545 void *pContext; /* pContext from when function registered */
8546 int nParam; /* Number of function parameters */
8547 sqlite3_rtree_dbl *aParam; /* value of function parameters */
8548 void *pUser; /* callback can use this, if desired */
8549 void (*xDelUser)(void*); /* function to free pUser */
8550 sqlite3_rtree_dbl *aCoord; /* Coordinates of node or entry to check */
8551 unsigned int *anQueue; /* Number of pending entries in the queue */
8552 int nCoord; /* Number of coordinates */
8553 int iLevel; /* Level of current node or entry */
8554 int mxLevel; /* The largest iLevel value in the tree */
8555 sqlite3_int64 iRowid; /* Rowid for current entry */
8556 sqlite3_rtree_dbl rParentScore; /* Score of parent node */
8557 int eParentWithin; /* Visibility of parent node */
8558 int eWithin; /* OUT: Visiblity */
8559 sqlite3_rtree_dbl rScore; /* OUT: Write the score here */
8560 /* The following fields are only available in 3.8.11 and later */
8561 sqlite3_value **apSqlParam; /* Original SQL values of parameters */
8562};
8563
8564/*
8565** Allowed values for sqlite3_rtree_query.eWithin and .eParentWithin.
8566*/
8567#define NOT_WITHIN 0 /* Object completely outside of query region */
8568#define PARTLY_WITHIN 1 /* Object partially overlaps query region */
8569#define FULLY_WITHIN 2 /* Object fully contained within query region */
8570
8571
8572#ifdef __cplusplus
8573} /* end of the 'extern "C"' block */
8574#endif
8575
8576#endif /* ifndef _SQLITE3RTREE_H_ */
8577
8578/******** End of sqlite3rtree.h *********/
8579/******** Begin file sqlite3session.h *********/
8580
8581#if !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION)
8582#define __SQLITESESSION_H_ 1
8583
8584/*
8585** Make sure we can call this stuff from C++.
8586*/
8587#ifdef __cplusplus
8588extern "C" {
8589#endif
8590
8591
8592/*
8593** CAPI3REF: Session Object Handle
8594*/
8595typedef struct sqlite3_session sqlite3_session;
8596
8597/*
8598** CAPI3REF: Changeset Iterator Handle
8599*/
8600typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
8601
8602/*
8603** CAPI3REF: Create A New Session Object
8604**
8605** Create a new session object attached to database handle db. If successful,
8606** a pointer to the new object is written to *ppSession and SQLITE_OK is
8607** returned. If an error occurs, *ppSession is set to NULL and an SQLite
8608** error code (e.g. SQLITE_NOMEM) is returned.
8609**
8610** It is possible to create multiple session objects attached to a single
8611** database handle.
8612**
8613** Session objects created using this function should be deleted using the
8614** [sqlite3session_delete()] function before the database handle that they
8615** are attached to is itself closed. If the database handle is closed before
8616** the session object is deleted, then the results of calling any session
8617** module function, including [sqlite3session_delete()] on the session object
8618** are undefined.
8619**
8620** Because the session module uses the [sqlite3_preupdate_hook()] API, it
8621** is not possible for an application to register a pre-update hook on a
8622** database handle that has one or more session objects attached. Nor is
8623** it possible to create a session object attached to a database handle for
8624** which a pre-update hook is already defined. The results of attempting
8625** either of these things are undefined.
8626**
8627** The session object will be used to create changesets for tables in
8628** database zDb, where zDb is either "main", or "temp", or the name of an
8629** attached database. It is not an error if database zDb is not attached
8630** to the database when the session object is created.
8631*/
8632int sqlite3session_create(
8633 sqlite3 *db, /* Database handle */
8634 const char *zDb, /* Name of db (e.g. "main") */
8635 sqlite3_session **ppSession /* OUT: New session object */
8636);
8637
8638/*
8639** CAPI3REF: Delete A Session Object
8640**
8641** Delete a session object previously allocated using
8642** [sqlite3session_create()]. Once a session object has been deleted, the
8643** results of attempting to use pSession with any other session module
8644** function are undefined.
8645**
8646** Session objects must be deleted before the database handle to which they
8647** are attached is closed. Refer to the documentation for
8648** [sqlite3session_create()] for details.
8649*/
8650void sqlite3session_delete(sqlite3_session *pSession);
8651
8652
8653/*
8654** CAPI3REF: Enable Or Disable A Session Object
8655**
8656** Enable or disable the recording of changes by a session object. When
8657** enabled, a session object records changes made to the database. When
8658** disabled - it does not. A newly created session object is enabled.
8659** Refer to the documentation for [sqlite3session_changeset()] for further
8660** details regarding how enabling and disabling a session object affects
8661** the eventual changesets.
8662**
8663** Passing zero to this function disables the session. Passing a value
8664** greater than zero enables it. Passing a value less than zero is a
8665** no-op, and may be used to query the current state of the session.
8666**
8667** The return value indicates the final state of the session object: 0 if
8668** the session is disabled, or 1 if it is enabled.
8669*/
8670int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
8671
8672/*
8673** CAPI3REF: Set Or Clear the Indirect Change Flag
8674**
8675** Each change recorded by a session object is marked as either direct or
8676** indirect. A change is marked as indirect if either:
8677**
8678** <ul>
8679** <li> The session object "indirect" flag is set when the change is
8680** made, or
8681** <li> The change is made by an SQL trigger or foreign key action
8682** instead of directly as a result of a users SQL statement.
8683** </ul>
8684**
8685** If a single row is affected by more than one operation within a session,
8686** then the change is considered indirect if all operations meet the criteria
8687** for an indirect change above, or direct otherwise.
8688**
8689** This function is used to set, clear or query the session object indirect
8690** flag. If the second argument passed to this function is zero, then the
8691** indirect flag is cleared. If it is greater than zero, the indirect flag
8692** is set. Passing a value less than zero does not modify the current value
8693** of the indirect flag, and may be used to query the current state of the
8694** indirect flag for the specified session object.
8695**
8696** The return value indicates the final state of the indirect flag: 0 if
8697** it is clear, or 1 if it is set.
8698*/
8699int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);
8700
8701/*
8702** CAPI3REF: Attach A Table To A Session Object
8703**
8704** If argument zTab is not NULL, then it is the name of a table to attach
8705** to the session object passed as the first argument. All subsequent changes
8706** made to the table while the session object is enabled will be recorded. See
8707** documentation for [sqlite3session_changeset()] for further details.
8708**
8709** Or, if argument zTab is NULL, then changes are recorded for all tables
8710** in the database. If additional tables are added to the database (by
8711** executing "CREATE TABLE" statements) after this call is made, changes for
8712** the new tables are also recorded.
8713**
8714** Changes can only be recorded for tables that have a PRIMARY KEY explicitly
8715** defined as part of their CREATE TABLE statement. It does not matter if the
8716** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
8717** KEY may consist of a single column, or may be a composite key.
8718**
8719** It is not an error if the named table does not exist in the database. Nor
8720** is it an error if the named table does not have a PRIMARY KEY. However,
8721** no changes will be recorded in either of these scenarios.
8722**
8723** Changes are not recorded for individual rows that have NULL values stored
8724** in one or more of their PRIMARY KEY columns.
8725**
8726** SQLITE_OK is returned if the call completes without error. Or, if an error
8727** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.
8728*/
8729int sqlite3session_attach(
8730 sqlite3_session *pSession, /* Session object */
8731 const char *zTab /* Table name */
8732);
8733
8734/*
8735** CAPI3REF: Set a table filter on a Session Object.
8736**
8737** The second argument (xFilter) is the "filter callback". For changes to rows
8738** in tables that are not attached to the Session object, the filter is called
8739** to determine whether changes to the table's rows should be tracked or not.
8740** If xFilter returns 0, changes is not tracked. Note that once a table is
8741** attached, xFilter will not be called again.
8742*/
8743void sqlite3session_table_filter(
8744 sqlite3_session *pSession, /* Session object */
8745 int(*xFilter)(
8746 void *pCtx, /* Copy of third arg to _filter_table() */
8747 const char *zTab /* Table name */
8748 ),
8749 void *pCtx /* First argument passed to xFilter */
8750);
8751
8752/*
8753** CAPI3REF: Generate A Changeset From A Session Object
8754**
8755** Obtain a changeset containing changes to the tables attached to the
8756** session object passed as the first argument. If successful,
8757** set *ppChangeset to point to a buffer containing the changeset
8758** and *pnChangeset to the size of the changeset in bytes before returning
8759** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
8760** zero and return an SQLite error code.
8761**
8762** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
8763** each representing a change to a single row of an attached table. An INSERT
8764** change contains the values of each field of a new database row. A DELETE
8765** contains the original values of each field of a deleted database row. An
8766** UPDATE change contains the original values of each field of an updated
8767** database row along with the updated values for each updated non-primary-key
8768** column. It is not possible for an UPDATE change to represent a change that
8769** modifies the values of primary key columns. If such a change is made, it
8770** is represented in a changeset as a DELETE followed by an INSERT.
8771**
8772** Changes are not recorded for rows that have NULL values stored in one or
8773** more of their PRIMARY KEY columns. If such a row is inserted or deleted,
8774** no corresponding change is present in the changesets returned by this
8775** function. If an existing row with one or more NULL values stored in
8776** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
8777** only an INSERT is appears in the changeset. Similarly, if an existing row
8778** with non-NULL PRIMARY KEY values is updated so that one or more of its
8779** PRIMARY KEY columns are set to NULL, the resulting changeset contains a
8780** DELETE change only.
8781**
8782** The contents of a changeset may be traversed using an iterator created
8783** using the [sqlite3changeset_start()] API. A changeset may be applied to
8784** a database with a compatible schema using the [sqlite3changeset_apply()]
8785** API.
8786**
8787** Within a changeset generated by this function, all changes related to a
8788** single table are grouped together. In other words, when iterating through
8789** a changeset or when applying a changeset to a database, all changes related
8790** to a single table are processed before moving on to the next table. Tables
8791** are sorted in the same order in which they were attached (or auto-attached)
8792** to the sqlite3_session object. The order in which the changes related to
8793** a single table are stored is undefined.
8794**
8795** Following a successful call to this function, it is the responsibility of
8796** the caller to eventually free the buffer that *ppChangeset points to using
8797** [sqlite3_free()].
8798**
8799** <h3>Changeset Generation</h3>
8800**
8801** Once a table has been attached to a session object, the session object
8802** records the primary key values of all new rows inserted into the table.
8803** It also records the original primary key and other column values of any
8804** deleted or updated rows. For each unique primary key value, data is only
8805** recorded once - the first time a row with said primary key is inserted,
8806** updated or deleted in the lifetime of the session.
8807**
8808** There is one exception to the previous paragraph: when a row is inserted,
8809** updated or deleted, if one or more of its primary key columns contain a
8810** NULL value, no record of the change is made.
8811**
8812** The session object therefore accumulates two types of records - those
8813** that consist of primary key values only (created when the user inserts
8814** a new record) and those that consist of the primary key values and the
8815** original values of other table columns (created when the users deletes
8816** or updates a record).
8817**
8818** When this function is called, the requested changeset is created using
8819** both the accumulated records and the current contents of the database
8820** file. Specifically:
8821**
8822** <ul>
8823** <li> For each record generated by an insert, the database is queried
8824** for a row with a matching primary key. If one is found, an INSERT
8825** change is added to the changeset. If no such row is found, no change
8826** is added to the changeset.
8827**
8828** <li> For each record generated by an update or delete, the database is
8829** queried for a row with a matching primary key. If such a row is
8830** found and one or more of the non-primary key fields have been
8831** modified from their original values, an UPDATE change is added to
8832** the changeset. Or, if no such row is found in the table, a DELETE
8833** change is added to the changeset. If there is a row with a matching
8834** primary key in the database, but all fields contain their original
8835** values, no change is added to the changeset.
8836** </ul>
8837**
8838** This means, amongst other things, that if a row is inserted and then later
8839** deleted while a session object is active, neither the insert nor the delete
8840** will be present in the changeset. Or if a row is deleted and then later a
8841** row with the same primary key values inserted while a session object is
8842** active, the resulting changeset will contain an UPDATE change instead of
8843** a DELETE and an INSERT.
8844**
8845** When a session object is disabled (see the [sqlite3session_enable()] API),
8846** it does not accumulate records when rows are inserted, updated or deleted.
8847** This may appear to have some counter-intuitive effects if a single row
8848** is written to more than once during a session. For example, if a row
8849** is inserted while a session object is enabled, then later deleted while
8850** the same session object is disabled, no INSERT record will appear in the
8851** changeset, even though the delete took place while the session was disabled.
8852** Or, if one field of a row is updated while a session is disabled, and
8853** another field of the same row is updated while the session is enabled, the
8854** resulting changeset will contain an UPDATE change that updates both fields.
8855*/
8856int sqlite3session_changeset(
8857 sqlite3_session *pSession, /* Session object */
8858 int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */
8859 void **ppChangeset /* OUT: Buffer containing changeset */
8860);
8861
8862/*
8863** CAPI3REF: Load The Difference Between Tables Into A Session
8864**
8865** If it is not already attached to the session object passed as the first
8866** argument, this function attaches table zTbl in the same manner as the
8867** [sqlite3session_attach()] function. If zTbl does not exist, or if it
8868** does not have a primary key, this function is a no-op (but does not return
8869** an error).
8870**
8871** Argument zFromDb must be the name of a database ("main", "temp" etc.)
8872** attached to the same database handle as the session object that contains
8873** a table compatible with the table attached to the session by this function.
8874** A table is considered compatible if it:
8875**
8876** <ul>
8877** <li> Has the same name,
8878** <li> Has the same set of columns declared in the same order, and
8879** <li> Has the same PRIMARY KEY definition.
8880** </ul>
8881**
8882** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables
8883** are compatible but do not have any PRIMARY KEY columns, it is not an error
8884** but no changes are added to the session object. As with other session
8885** APIs, tables without PRIMARY KEYs are simply ignored.
8886**
8887** This function adds a set of changes to the session object that could be
8888** used to update the table in database zFrom (call this the "from-table")
8889** so that its content is the same as the table attached to the session
8890** object (call this the "to-table"). Specifically:
8891**
8892** <ul>
8893** <li> For each row (primary key) that exists in the to-table but not in
8894** the from-table, an INSERT record is added to the session object.
8895**
8896** <li> For each row (primary key) that exists in the to-table but not in
8897** the from-table, a DELETE record is added to the session object.
8898**
8899** <li> For each row (primary key) that exists in both tables, but features
8900** different in each, an UPDATE record is added to the session.
8901** </ul>
8902**
8903** To clarify, if this function is called and then a changeset constructed
8904** using [sqlite3session_changeset()], then after applying that changeset to
8905** database zFrom the contents of the two compatible tables would be
8906** identical.
8907**
8908** It an error if database zFrom does not exist or does not contain the
8909** required compatible table.
8910**
8911** If the operation successful, SQLITE_OK is returned. Otherwise, an SQLite
8912** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg
8913** may be set to point to a buffer containing an English language error
8914** message. It is the responsibility of the caller to free this buffer using
8915** sqlite3_free().
8916*/
8917int sqlite3session_diff(
8918 sqlite3_session *pSession,
8919 const char *zFromDb,
8920 const char *zTbl,
8921 char **pzErrMsg
8922);
8923
8924
8925/*
8926** CAPI3REF: Generate A Patchset From A Session Object
8927**
8928** The differences between a patchset and a changeset are that:
8929**
8930** <ul>
8931** <li> DELETE records consist of the primary key fields only. The
8932** original values of other fields are omitted.
8933** <li> The original values of any modified fields are omitted from
8934** UPDATE records.
8935** </ul>
8936**
8937** A patchset blob may be used with up to date versions of all
8938** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(),
8939** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,
8940** attempting to use a patchset blob with old versions of the
8941** sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error.
8942**
8943** Because the non-primary key "old.*" fields are omitted, no
8944** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset
8945** is passed to the sqlite3changeset_apply() API. Other conflict types work
8946** in the same way as for changesets.
8947**
8948** Changes within a patchset are ordered in the same way as for changesets
8949** generated by the sqlite3session_changeset() function (i.e. all changes for
8950** a single table are grouped together, tables appear in the order in which
8951** they were attached to the session object).
8952*/
8953int sqlite3session_patchset(
8954 sqlite3_session *pSession, /* Session object */
8955 int *pnPatchset, /* OUT: Size of buffer at *ppChangeset */
8956 void **ppPatchset /* OUT: Buffer containing changeset */
8957);
8958
8959/*
8960** CAPI3REF: Test if a changeset has recorded any changes.
8961**
8962** Return non-zero if no changes to attached tables have been recorded by
8963** the session object passed as the first argument. Otherwise, if one or
8964** more changes have been recorded, return zero.
8965**
8966** Even if this function returns zero, it is possible that calling
8967** [sqlite3session_changeset()] on the session handle may still return a
8968** changeset that contains no changes. This can happen when a row in
8969** an attached table is modified and then later on the original values
8970** are restored. However, if this function returns non-zero, then it is
8971** guaranteed that a call to sqlite3session_changeset() will return a
8972** changeset containing zero changes.
8973*/
8974int sqlite3session_isempty(sqlite3_session *pSession);
8975
8976/*
8977** CAPI3REF: Create An Iterator To Traverse A Changeset
8978**
8979** Create an iterator used to iterate through the contents of a changeset.
8980** If successful, *pp is set to point to the iterator handle and SQLITE_OK
8981** is returned. Otherwise, if an error occurs, *pp is set to zero and an
8982** SQLite error code is returned.
8983**
8984** The following functions can be used to advance and query a changeset
8985** iterator created by this function:
8986**
8987** <ul>
8988** <li> [sqlite3changeset_next()]
8989** <li> [sqlite3changeset_op()]
8990** <li> [sqlite3changeset_new()]
8991** <li> [sqlite3changeset_old()]
8992** </ul>
8993**
8994** It is the responsibility of the caller to eventually destroy the iterator
8995** by passing it to [sqlite3changeset_finalize()]. The buffer containing the
8996** changeset (pChangeset) must remain valid until after the iterator is
8997** destroyed.
8998**
8999** Assuming the changeset blob was created by one of the
9000** [sqlite3session_changeset()], [sqlite3changeset_concat()] or
9001** [sqlite3changeset_invert()] functions, all changes within the changeset
9002** that apply to a single table are grouped together. This means that when
9003** an application iterates through a changeset using an iterator created by
9004** this function, all changes that relate to a single table are visited
9005** consecutively. There is no chance that the iterator will visit a change
9006** the applies to table X, then one for table Y, and then later on visit
9007** another change for table X.
9008*/
9009int sqlite3changeset_start(
9010 sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */
9011 int nChangeset, /* Size of changeset blob in bytes */
9012 void *pChangeset /* Pointer to blob containing changeset */
9013);
9014
9015
9016/*
9017** CAPI3REF: Advance A Changeset Iterator
9018**
9019** This function may only be used with iterators created by function
9020** [sqlite3changeset_start()]. If it is called on an iterator passed to
9021** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
9022** is returned and the call has no effect.
9023**
9024** Immediately after an iterator is created by sqlite3changeset_start(), it
9025** does not point to any change in the changeset. Assuming the changeset
9026** is not empty, the first call to this function advances the iterator to
9027** point to the first change in the changeset. Each subsequent call advances
9028** the iterator to point to the next change in the changeset (if any). If
9029** no error occurs and the iterator points to a valid change after a call
9030** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.
9031** Otherwise, if all changes in the changeset have already been visited,
9032** SQLITE_DONE is returned.
9033**
9034** If an error occurs, an SQLite error code is returned. Possible error
9035** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or
9036** SQLITE_NOMEM.
9037*/
9038int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
9039
9040/*
9041** CAPI3REF: Obtain The Current Operation From A Changeset Iterator
9042**
9043** The pIter argument passed to this function may either be an iterator
9044** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
9045** created by [sqlite3changeset_start()]. In the latter case, the most recent
9046** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this
9047** is not the case, this function returns [SQLITE_MISUSE].
9048**
9049** If argument pzTab is not NULL, then *pzTab is set to point to a
9050** nul-terminated utf-8 encoded string containing the name of the table
9051** affected by the current change. The buffer remains valid until either
9052** sqlite3changeset_next() is called on the iterator or until the
9053** conflict-handler function returns. If pnCol is not NULL, then *pnCol is
9054** set to the number of columns in the table affected by the change. If
9055** pbIncorrect is not NULL, then *pbIndirect is set to true (1) if the change
9056** is an indirect change, or false (0) otherwise. See the documentation for
9057** [sqlite3session_indirect()] for a description of direct and indirect
9058** changes. Finally, if pOp is not NULL, then *pOp is set to one of
9059** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the
9060** type of change that the iterator currently points to.
9061**
9062** If no error occurs, SQLITE_OK is returned. If an error does occur, an
9063** SQLite error code is returned. The values of the output variables may not
9064** be trusted in this case.
9065*/
9066int sqlite3changeset_op(
9067 sqlite3_changeset_iter *pIter, /* Iterator object */
9068 const char **pzTab, /* OUT: Pointer to table name */
9069 int *pnCol, /* OUT: Number of columns in table */
9070 int *pOp, /* OUT: SQLITE_INSERT, DELETE or UPDATE */
9071 int *pbIndirect /* OUT: True for an 'indirect' change */
9072);
9073
9074/*
9075** CAPI3REF: Obtain The Primary Key Definition Of A Table
9076**
9077** For each modified table, a changeset includes the following:
9078**
9079** <ul>
9080** <li> The number of columns in the table, and
9081** <li> Which of those columns make up the tables PRIMARY KEY.
9082** </ul>
9083**
9084** This function is used to find which columns comprise the PRIMARY KEY of
9085** the table modified by the change that iterator pIter currently points to.
9086** If successful, *pabPK is set to point to an array of nCol entries, where
9087** nCol is the number of columns in the table. Elements of *pabPK are set to
9088** 0x01 if the corresponding column is part of the tables primary key, or
9089** 0x00 if it is not.
9090**
9091** If argument pnCol is not NULL, then *pnCol is set to the number of columns
9092** in the table.
9093**
9094** If this function is called when the iterator does not point to a valid
9095** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,
9096** SQLITE_OK is returned and the output variables populated as described
9097** above.
9098*/
9099int sqlite3changeset_pk(
9100 sqlite3_changeset_iter *pIter, /* Iterator object */
9101 unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */
9102 int *pnCol /* OUT: Number of entries in output array */
9103);
9104
9105/*
9106** CAPI3REF: Obtain old.* Values From A Changeset Iterator
9107**
9108** The pIter argument passed to this function may either be an iterator
9109** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
9110** created by [sqlite3changeset_start()]. In the latter case, the most recent
9111** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
9112** Furthermore, it may only be called if the type of change that the iterator
9113** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,
9114** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
9115**
9116** Argument iVal must be greater than or equal to 0, and less than the number
9117** of columns in the table affected by the current change. Otherwise,
9118** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
9119**
9120** If successful, this function sets *ppValue to point to a protected
9121** sqlite3_value object containing the iVal'th value from the vector of
9122** original row values stored as part of the UPDATE or DELETE change and
9123** returns SQLITE_OK. The name of the function comes from the fact that this
9124** is similar to the "old.*" columns available to update or delete triggers.
9125**
9126** If some other error occurs (e.g. an OOM condition), an SQLite error code
9127** is returned and *ppValue is set to NULL.
9128*/
9129int sqlite3changeset_old(
9130 sqlite3_changeset_iter *pIter, /* Changeset iterator */
9131 int iVal, /* Column number */
9132 sqlite3_value **ppValue /* OUT: Old value (or NULL pointer) */
9133);
9134
9135/*
9136** CAPI3REF: Obtain new.* Values From A Changeset Iterator
9137**
9138** The pIter argument passed to this function may either be an iterator
9139** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
9140** created by [sqlite3changeset_start()]. In the latter case, the most recent
9141** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
9142** Furthermore, it may only be called if the type of change that the iterator
9143** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,
9144** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
9145**
9146** Argument iVal must be greater than or equal to 0, and less than the number
9147** of columns in the table affected by the current change. Otherwise,
9148** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
9149**
9150** If successful, this function sets *ppValue to point to a protected
9151** sqlite3_value object containing the iVal'th value from the vector of
9152** new row values stored as part of the UPDATE or INSERT change and
9153** returns SQLITE_OK. If the change is an UPDATE and does not include
9154** a new value for the requested column, *ppValue is set to NULL and
9155** SQLITE_OK returned. The name of the function comes from the fact that
9156** this is similar to the "new.*" columns available to update or delete
9157** triggers.
9158**
9159** If some other error occurs (e.g. an OOM condition), an SQLite error code
9160** is returned and *ppValue is set to NULL.
9161*/
9162int sqlite3changeset_new(
9163 sqlite3_changeset_iter *pIter, /* Changeset iterator */
9164 int iVal, /* Column number */
9165 sqlite3_value **ppValue /* OUT: New value (or NULL pointer) */
9166);
9167
9168/*
9169** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator
9170**
9171** This function should only be used with iterator objects passed to a
9172** conflict-handler callback by [sqlite3changeset_apply()] with either
9173** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function
9174** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue
9175** is set to NULL.
9176**
9177** Argument iVal must be greater than or equal to 0, and less than the number
9178** of columns in the table affected by the current change. Otherwise,
9179** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
9180**
9181** If successful, this function sets *ppValue to point to a protected
9182** sqlite3_value object containing the iVal'th value from the
9183** "conflicting row" associated with the current conflict-handler callback
9184** and returns SQLITE_OK.
9185**
9186** If some other error occurs (e.g. an OOM condition), an SQLite error code
9187** is returned and *ppValue is set to NULL.
9188*/
9189int sqlite3changeset_conflict(
9190 sqlite3_changeset_iter *pIter, /* Changeset iterator */
9191 int iVal, /* Column number */
9192 sqlite3_value **ppValue /* OUT: Value from conflicting row */
9193);
9194
9195/*
9196** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations
9197**
9198** This function may only be called with an iterator passed to an
9199** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case
9200** it sets the output variable to the total number of known foreign key
9201** violations in the destination database and returns SQLITE_OK.
9202**
9203** In all other cases this function returns SQLITE_MISUSE.
9204*/
9205int sqlite3changeset_fk_conflicts(
9206 sqlite3_changeset_iter *pIter, /* Changeset iterator */
9207 int *pnOut /* OUT: Number of FK violations */
9208);
9209
9210
9211/*
9212** CAPI3REF: Finalize A Changeset Iterator
9213**
9214** This function is used to finalize an iterator allocated with
9215** [sqlite3changeset_start()].
9216**
9217** This function should only be called on iterators created using the
9218** [sqlite3changeset_start()] function. If an application calls this
9219** function with an iterator passed to a conflict-handler by
9220** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the
9221** call has no effect.
9222**
9223** If an error was encountered within a call to an sqlite3changeset_xxx()
9224** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an
9225** [SQLITE_NOMEM] in [sqlite3changeset_new()]) then an error code corresponding
9226** to that error is returned by this function. Otherwise, SQLITE_OK is
9227** returned. This is to allow the following pattern (pseudo-code):
9228**
9229** sqlite3changeset_start();
9230** while( SQLITE_ROW==sqlite3changeset_next() ){
9231** // Do something with change.
9232** }
9233** rc = sqlite3changeset_finalize();
9234** if( rc!=SQLITE_OK ){
9235** // An error has occurred
9236** }
9237*/
9238int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
9239
9240/*
9241** CAPI3REF: Invert A Changeset
9242**
9243** This function is used to "invert" a changeset object. Applying an inverted
9244** changeset to a database reverses the effects of applying the uninverted
9245** changeset. Specifically:
9246**
9247** <ul>
9248** <li> Each DELETE change is changed to an INSERT, and
9249** <li> Each INSERT change is changed to a DELETE, and
9250** <li> For each UPDATE change, the old.* and new.* values are exchanged.
9251** </ul>
9252**
9253** This function does not change the order in which changes appear within
9254** the changeset. It merely reverses the sense of each individual change.
9255**
9256** If successful, a pointer to a buffer containing the inverted changeset
9257** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
9258** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
9259** zeroed and an SQLite error code returned.
9260**
9261** It is the responsibility of the caller to eventually call sqlite3_free()
9262** on the *ppOut pointer to free the buffer allocation following a successful
9263** call to this function.
9264**
9265** WARNING/TODO: This function currently assumes that the input is a valid
9266** changeset. If it is not, the results are undefined.
9267*/
9268int sqlite3changeset_invert(
9269 int nIn, const void *pIn, /* Input changeset */
9270 int *pnOut, void **ppOut /* OUT: Inverse of input */
9271);
9272
9273/*
9274** CAPI3REF: Concatenate Two Changeset Objects
9275**
9276** This function is used to concatenate two changesets, A and B, into a
9277** single changeset. The result is a changeset equivalent to applying
9278** changeset A followed by changeset B.
9279**
9280** This function combines the two input changesets using an
9281** sqlite3_changegroup object. Calling it produces similar results as the
9282** following code fragment:
9283**
9284** sqlite3_changegroup *pGrp;
9285** rc = sqlite3_changegroup_new(&pGrp);
9286** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA);
9287** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB);
9288** if( rc==SQLITE_OK ){
9289** rc = sqlite3changegroup_output(pGrp, pnOut, ppOut);
9290** }else{
9291** *ppOut = 0;
9292** *pnOut = 0;
9293** }
9294**
9295** Refer to the sqlite3_changegroup documentation below for details.
9296*/
9297int sqlite3changeset_concat(
9298 int nA, /* Number of bytes in buffer pA */
9299 void *pA, /* Pointer to buffer containing changeset A */
9300 int nB, /* Number of bytes in buffer pB */
9301 void *pB, /* Pointer to buffer containing changeset B */
9302 int *pnOut, /* OUT: Number of bytes in output changeset */
9303 void **ppOut /* OUT: Buffer containing output changeset */
9304);
9305
9306
9307/*
9308** CAPI3REF: Changegroup Handle
9309*/
9310typedef struct sqlite3_changegroup sqlite3_changegroup;
9311
9312/*
9313** CAPI3REF: Create A New Changegroup Object
9314**
9315** An sqlite3_changegroup object is used to combine two or more changesets
9316** (or patchsets) into a single changeset (or patchset). A single changegroup
9317** object may combine changesets or patchsets, but not both. The output is
9318** always in the same format as the input.
9319**
9320** If successful, this function returns SQLITE_OK and populates (*pp) with
9321** a pointer to a new sqlite3_changegroup object before returning. The caller
9322** should eventually free the returned object using a call to
9323** sqlite3changegroup_delete(). If an error occurs, an SQLite error code
9324** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.
9325**
9326** The usual usage pattern for an sqlite3_changegroup object is as follows:
9327**
9328** <ul>
9329** <li> It is created using a call to sqlite3changegroup_new().
9330**
9331** <li> Zero or more changesets (or patchsets) are added to the object
9332** by calling sqlite3changegroup_add().
9333**
9334** <li> The result of combining all input changesets together is obtained
9335** by the application via a call to sqlite3changegroup_output().
9336**
9337** <li> The object is deleted using a call to sqlite3changegroup_delete().
9338** </ul>
9339**
9340** Any number of calls to add() and output() may be made between the calls to
9341** new() and delete(), and in any order.
9342**
9343** As well as the regular sqlite3changegroup_add() and
9344** sqlite3changegroup_output() functions, also available are the streaming
9345** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().
9346*/
9347int sqlite3changegroup_new(sqlite3_changegroup **pp);
9348
9349/*
9350** CAPI3REF: Add A Changeset To A Changegroup
9351**
9352** Add all changes within the changeset (or patchset) in buffer pData (size
9353** nData bytes) to the changegroup.
9354**
9355** If the buffer contains a patchset, then all prior calls to this function
9356** on the same changegroup object must also have specified patchsets. Or, if
9357** the buffer contains a changeset, so must have the earlier calls to this
9358** function. Otherwise, SQLITE_ERROR is returned and no changes are added
9359** to the changegroup.
9360**
9361** Rows within the changeset and changegroup are identified by the values in
9362** their PRIMARY KEY columns. A change in the changeset is considered to
9363** apply to the same row as a change already present in the changegroup if
9364** the two rows have the same primary key.
9365**
9366** Changes to rows that do not already appear in the changegroup are
9367** simply copied into it. Or, if both the new changeset and the changegroup
9368** contain changes that apply to a single row, the final contents of the
9369** changegroup depends on the type of each change, as follows:
9370**
9371** <table border=1 style="margin-left:8ex;margin-right:8ex">
9372** <tr><th style="white-space:pre">Existing Change </th>
9373** <th style="white-space:pre">New Change </th>
9374** <th>Output Change
9375** <tr><td>INSERT <td>INSERT <td>
9376** The new change is ignored. This case does not occur if the new
9377** changeset was recorded immediately after the changesets already
9378** added to the changegroup.
9379** <tr><td>INSERT <td>UPDATE <td>
9380** The INSERT change remains in the changegroup. The values in the
9381** INSERT change are modified as if the row was inserted by the
9382** existing change and then updated according to the new change.
9383** <tr><td>INSERT <td>DELETE <td>
9384** The existing INSERT is removed from the changegroup. The DELETE is
9385** not added.
9386** <tr><td>UPDATE <td>INSERT <td>
9387** The new change is ignored. This case does not occur if the new
9388** changeset was recorded immediately after the changesets already
9389** added to the changegroup.
9390** <tr><td>UPDATE <td>UPDATE <td>
9391** The existing UPDATE remains within the changegroup. It is amended
9392** so that the accompanying values are as if the row was updated once
9393** by the existing change and then again by the new change.
9394** <tr><td>UPDATE <td>DELETE <td>
9395** The existing UPDATE is replaced by the new DELETE within the
9396** changegroup.
9397** <tr><td>DELETE <td>INSERT <td>
9398** If one or more of the column values in the row inserted by the
9399** new change differ from those in the row deleted by the existing
9400** change, the existing DELETE is replaced by an UPDATE within the
9401** changegroup. Otherwise, if the inserted row is exactly the same
9402** as the deleted row, the existing DELETE is simply discarded.
9403** <tr><td>DELETE <td>UPDATE <td>
9404** The new change is ignored. This case does not occur if the new
9405** changeset was recorded immediately after the changesets already
9406** added to the changegroup.
9407** <tr><td>DELETE <td>DELETE <td>
9408** The new change is ignored. This case does not occur if the new
9409** changeset was recorded immediately after the changesets already
9410** added to the changegroup.
9411** </table>
9412**
9413** If the new changeset contains changes to a table that is already present
9414** in the changegroup, then the number of columns and the position of the
9415** primary key columns for the table must be consistent. If this is not the
9416** case, this function fails with SQLITE_SCHEMA. If the input changeset
9417** appears to be corrupt and the corruption is detected, SQLITE_CORRUPT is
9418** returned. Or, if an out-of-memory condition occurs during processing, this
9419** function returns SQLITE_NOMEM. In all cases, if an error occurs the
9420** final contents of the changegroup is undefined.
9421**
9422** If no error occurs, SQLITE_OK is returned.
9423*/
9424int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData);
9425
9426/*
9427** CAPI3REF: Obtain A Composite Changeset From A Changegroup
9428**
9429** Obtain a buffer containing a changeset (or patchset) representing the
9430** current contents of the changegroup. If the inputs to the changegroup
9431** were themselves changesets, the output is a changeset. Or, if the
9432** inputs were patchsets, the output is also a patchset.
9433**
9434** As with the output of the sqlite3session_changeset() and
9435** sqlite3session_patchset() functions, all changes related to a single
9436** table are grouped together in the output of this function. Tables appear
9437** in the same order as for the very first changeset added to the changegroup.
9438** If the second or subsequent changesets added to the changegroup contain
9439** changes for tables that do not appear in the first changeset, they are
9440** appended onto the end of the output changeset, again in the order in
9441** which they are first encountered.
9442**
9443** If an error occurs, an SQLite error code is returned and the output
9444** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK
9445** is returned and the output variables are set to the size of and a
9446** pointer to the output buffer, respectively. In this case it is the
9447** responsibility of the caller to eventually free the buffer using a
9448** call to sqlite3_free().
9449*/
9450int sqlite3changegroup_output(
9451 sqlite3_changegroup*,
9452 int *pnData, /* OUT: Size of output buffer in bytes */
9453 void **ppData /* OUT: Pointer to output buffer */
9454);
9455
9456/*
9457** CAPI3REF: Delete A Changegroup Object
9458*/
9459void sqlite3changegroup_delete(sqlite3_changegroup*);
9460
9461/*
9462** CAPI3REF: Apply A Changeset To A Database
9463**
9464** Apply a changeset to a database. This function attempts to update the
9465** "main" database attached to handle db with the changes found in the
9466** changeset passed via the second and third arguments.
9467**
9468** The fourth argument (xFilter) passed to this function is the "filter
9469** callback". If it is not NULL, then for each table affected by at least one
9470** change in the changeset, the filter callback is invoked with
9471** the table name as the second argument, and a copy of the context pointer
9472** passed as the sixth argument to this function as the first. If the "filter
9473** callback" returns zero, then no attempt is made to apply any changes to
9474** the table. Otherwise, if the return value is non-zero or the xFilter
9475** argument to this function is NULL, all changes related to the table are
9476** attempted.
9477**
9478** For each table that is not excluded by the filter callback, this function
9479** tests that the target database contains a compatible table. A table is
9480** considered compatible if all of the following are true:
9481**
9482** <ul>
9483** <li> The table has the same name as the name recorded in the
9484** changeset, and
9485** <li> The table has the same number of columns as recorded in the
9486** changeset, and
9487** <li> The table has primary key columns in the same position as
9488** recorded in the changeset.
9489** </ul>
9490**
9491** If there is no compatible table, it is not an error, but none of the
9492** changes associated with the table are applied. A warning message is issued
9493** via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most
9494** one such warning is issued for each table in the changeset.
9495**
9496** For each change for which there is a compatible table, an attempt is made
9497** to modify the table contents according to the UPDATE, INSERT or DELETE
9498** change. If a change cannot be applied cleanly, the conflict handler
9499** function passed as the fifth argument to sqlite3changeset_apply() may be
9500** invoked. A description of exactly when the conflict handler is invoked for
9501** each type of change is below.
9502**
9503** Unlike the xFilter argument, xConflict may not be passed NULL. The results
9504** of passing anything other than a valid function pointer as the xConflict
9505** argument are undefined.
9506**
9507** Each time the conflict handler function is invoked, it must return one
9508** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or
9509** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned
9510** if the second argument passed to the conflict handler is either
9511** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
9512** returns an illegal value, any changes already made are rolled back and
9513** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different
9514** actions are taken by sqlite3changeset_apply() depending on the value
9515** returned by each invocation of the conflict-handler function. Refer to
9516** the documentation for the three
9517** [SQLITE_CHANGESET_OMIT|available return values] for details.
9518**
9519** <dl>
9520** <dt>DELETE Changes<dd>
9521** For each DELETE change, this function checks if the target database
9522** contains a row with the same primary key value (or values) as the
9523** original row values stored in the changeset. If it does, and the values
9524** stored in all non-primary key columns also match the values stored in
9525** the changeset the row is deleted from the target database.
9526**
9527** If a row with matching primary key values is found, but one or more of
9528** the non-primary key fields contains a value different from the original
9529** row value stored in the changeset, the conflict-handler function is
9530** invoked with [SQLITE_CHANGESET_DATA] as the second argument.
9531**
9532** If no row with matching primary key values is found in the database,
9533** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
9534** passed as the second argument.
9535**
9536** If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
9537** (which can only happen if a foreign key constraint is violated), the
9538** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
9539** passed as the second argument. This includes the case where the DELETE
9540** operation is attempted because an earlier call to the conflict handler
9541** function returned [SQLITE_CHANGESET_REPLACE].
9542**
9543** <dt>INSERT Changes<dd>
9544** For each INSERT change, an attempt is made to insert the new row into
9545** the database.
9546**
9547** If the attempt to insert the row fails because the database already
9548** contains a row with the same primary key values, the conflict handler
9549** function is invoked with the second argument set to
9550** [SQLITE_CHANGESET_CONFLICT].
9551**
9552** If the attempt to insert the row fails because of some other constraint
9553** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
9554** invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT].
9555** This includes the case where the INSERT operation is re-attempted because
9556** an earlier call to the conflict handler function returned
9557** [SQLITE_CHANGESET_REPLACE].
9558**
9559** <dt>UPDATE Changes<dd>
9560** For each UPDATE change, this function checks if the target database
9561** contains a row with the same primary key value (or values) as the
9562** original row values stored in the changeset. If it does, and the values
9563** stored in all non-primary key columns also match the values stored in
9564** the changeset the row is updated within the target database.
9565**
9566** If a row with matching primary key values is found, but one or more of
9567** the non-primary key fields contains a value different from an original
9568** row value stored in the changeset, the conflict-handler function is
9569** invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since
9570** UPDATE changes only contain values for non-primary key fields that are
9571** to be modified, only those fields need to match the original values to
9572** avoid the SQLITE_CHANGESET_DATA conflict-handler callback.
9573**
9574** If no row with matching primary key values is found in the database,
9575** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
9576** passed as the second argument.
9577**
9578** If the UPDATE operation is attempted, but SQLite returns
9579** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
9580** [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument.
9581** This includes the case where the UPDATE operation is attempted after
9582** an earlier call to the conflict handler function returned
9583** [SQLITE_CHANGESET_REPLACE].
9584** </dl>
9585**
9586** It is safe to execute SQL statements, including those that write to the
9587** table that the callback related to, from within the xConflict callback.
9588** This can be used to further customize the applications conflict
9589** resolution strategy.
9590**
9591** All changes made by this function are enclosed in a savepoint transaction.
9592** If any other error (aside from a constraint failure when attempting to
9593** write to the target database) occurs, then the savepoint transaction is
9594** rolled back, restoring the target database to its original state, and an
9595** SQLite error code returned.
9596*/
9597int sqlite3changeset_apply(
9598 sqlite3 *db, /* Apply change to "main" db of this handle */
9599 int nChangeset, /* Size of changeset in bytes */
9600 void *pChangeset, /* Changeset blob */
9601 int(*xFilter)(
9602 void *pCtx, /* Copy of sixth arg to _apply() */
9603 const char *zTab /* Table name */
9604 ),
9605 int(*xConflict)(
9606 void *pCtx, /* Copy of sixth arg to _apply() */
9607 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
9608 sqlite3_changeset_iter *p /* Handle describing change and conflict */
9609 ),
9610 void *pCtx /* First argument passed to xConflict */
9611);
9612
9613/*
9614** CAPI3REF: Constants Passed To The Conflict Handler
9615**
9616** Values that may be passed as the second argument to a conflict-handler.
9617**
9618** <dl>
9619** <dt>SQLITE_CHANGESET_DATA<dd>
9620** The conflict handler is invoked with CHANGESET_DATA as the second argument
9621** when processing a DELETE or UPDATE change if a row with the required
9622** PRIMARY KEY fields is present in the database, but one or more other
9623** (non primary-key) fields modified by the update do not contain the
9624** expected "before" values.
9625**
9626** The conflicting row, in this case, is the database row with the matching
9627** primary key.
9628**
9629** <dt>SQLITE_CHANGESET_NOTFOUND<dd>
9630** The conflict handler is invoked with CHANGESET_NOTFOUND as the second
9631** argument when processing a DELETE or UPDATE change if a row with the
9632** required PRIMARY KEY fields is not present in the database.
9633**
9634** There is no conflicting row in this case. The results of invoking the
9635** sqlite3changeset_conflict() API are undefined.
9636**
9637** <dt>SQLITE_CHANGESET_CONFLICT<dd>
9638** CHANGESET_CONFLICT is passed as the second argument to the conflict
9639** handler while processing an INSERT change if the operation would result
9640** in duplicate primary key values.
9641**
9642** The conflicting row in this case is the database row with the matching
9643** primary key.
9644**
9645** <dt>SQLITE_CHANGESET_FOREIGN_KEY<dd>
9646** If foreign key handling is enabled, and applying a changeset leaves the
9647** database in a state containing foreign key violations, the conflict
9648** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument
9649** exactly once before the changeset is committed. If the conflict handler
9650** returns CHANGESET_OMIT, the changes, including those that caused the
9651** foreign key constraint violation, are committed. Or, if it returns
9652** CHANGESET_ABORT, the changeset is rolled back.
9653**
9654** No current or conflicting row information is provided. The only function
9655** it is possible to call on the supplied sqlite3_changeset_iter handle
9656** is sqlite3changeset_fk_conflicts().
9657**
9658** <dt>SQLITE_CHANGESET_CONSTRAINT<dd>
9659** If any other constraint violation occurs while applying a change (i.e.
9660** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
9661** invoked with CHANGESET_CONSTRAINT as the second argument.
9662**
9663** There is no conflicting row in this case. The results of invoking the
9664** sqlite3changeset_conflict() API are undefined.
9665**
9666** </dl>
9667*/
9668#define SQLITE_CHANGESET_DATA 1
9669#define SQLITE_CHANGESET_NOTFOUND 2
9670#define SQLITE_CHANGESET_CONFLICT 3
9671#define SQLITE_CHANGESET_CONSTRAINT 4
9672#define SQLITE_CHANGESET_FOREIGN_KEY 5
9673
9674/*
9675** CAPI3REF: Constants Returned By The Conflict Handler
9676**
9677** A conflict handler callback must return one of the following three values.
9678**
9679** <dl>
9680** <dt>SQLITE_CHANGESET_OMIT<dd>
9681** If a conflict handler returns this value no special action is taken. The
9682** change that caused the conflict is not applied. The session module
9683** continues to the next change in the changeset.
9684**
9685** <dt>SQLITE_CHANGESET_REPLACE<dd>
9686** This value may only be returned if the second argument to the conflict
9687** handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this
9688** is not the case, any changes applied so far are rolled back and the
9689** call to sqlite3changeset_apply() returns SQLITE_MISUSE.
9690**
9691** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict
9692** handler, then the conflicting row is either updated or deleted, depending
9693** on the type of change.
9694**
9695** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict
9696** handler, then the conflicting row is removed from the database and a
9697** second attempt to apply the change is made. If this second attempt fails,
9698** the original row is restored to the database before continuing.
9699**
9700** <dt>SQLITE_CHANGESET_ABORT<dd>
9701** If this value is returned, any changes applied so far are rolled back
9702** and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
9703** </dl>
9704*/
9705#define SQLITE_CHANGESET_OMIT 0
9706#define SQLITE_CHANGESET_REPLACE 1
9707#define SQLITE_CHANGESET_ABORT 2
9708
9709/*
9710** CAPI3REF: Streaming Versions of API functions.
9711**
9712** The six streaming API xxx_strm() functions serve similar purposes to the
9713** corresponding non-streaming API functions:
9714**
9715** <table border=1 style="margin-left:8ex;margin-right:8ex">
9716** <tr><th>Streaming function<th>Non-streaming equivalent</th>
9717** <tr><td>sqlite3changeset_apply_str<td>[sqlite3changeset_apply]
9718** <tr><td>sqlite3changeset_concat_str<td>[sqlite3changeset_concat]
9719** <tr><td>sqlite3changeset_invert_str<td>[sqlite3changeset_invert]
9720** <tr><td>sqlite3changeset_start_str<td>[sqlite3changeset_start]
9721** <tr><td>sqlite3session_changeset_str<td>[sqlite3session_changeset]
9722** <tr><td>sqlite3session_patchset_str<td>[sqlite3session_patchset]
9723** </table>
9724**
9725** Non-streaming functions that accept changesets (or patchsets) as input
9726** require that the entire changeset be stored in a single buffer in memory.
9727** Similarly, those that return a changeset or patchset do so by returning
9728** a pointer to a single large buffer allocated using sqlite3_malloc().
9729** Normally this is convenient. However, if an application running in a
9730** low-memory environment is required to handle very large changesets, the
9731** large contiguous memory allocations required can become onerous.
9732**
9733** In order to avoid this problem, instead of a single large buffer, input
9734** is passed to a streaming API functions by way of a callback function that
9735** the sessions module invokes to incrementally request input data as it is
9736** required. In all cases, a pair of API function parameters such as
9737**
9738** <pre>
9739** int nChangeset,
9740** void *pChangeset,
9741** </pre>
9742**
9743** Is replaced by:
9744**
9745** <pre>
9746** int (*xInput)(void *pIn, void *pData, int *pnData),
9747** void *pIn,
9748** </pre>
9749**
9750** Each time the xInput callback is invoked by the sessions module, the first
9751** argument passed is a copy of the supplied pIn context pointer. The second
9752** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no
9753** error occurs the xInput method should copy up to (*pnData) bytes of data
9754** into the buffer and set (*pnData) to the actual number of bytes copied
9755** before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
9756** should be set to zero to indicate this. Or, if an error occurs, an SQLite
9757** error code should be returned. In all cases, if an xInput callback returns
9758** an error, all processing is abandoned and the streaming API function
9759** returns a copy of the error code to the caller.
9760**
9761** In the case of sqlite3changeset_start_strm(), the xInput callback may be
9762** invoked by the sessions module at any point during the lifetime of the
9763** iterator. If such an xInput callback returns an error, the iterator enters
9764** an error state, whereby all subsequent calls to iterator functions
9765** immediately fail with the same error code as returned by xInput.
9766**
9767** Similarly, streaming API functions that return changesets (or patchsets)
9768** return them in chunks by way of a callback function instead of via a
9769** pointer to a single large buffer. In this case, a pair of parameters such
9770** as:
9771**
9772** <pre>
9773** int *pnChangeset,
9774** void **ppChangeset,
9775** </pre>
9776**
9777** Is replaced by:
9778**
9779** <pre>
9780** int (*xOutput)(void *pOut, const void *pData, int nData),
9781** void *pOut
9782** </pre>
9783**
9784** The xOutput callback is invoked zero or more times to return data to
9785** the application. The first parameter passed to each call is a copy of the
9786** pOut pointer supplied by the application. The second parameter, pData,
9787** points to a buffer nData bytes in size containing the chunk of output
9788** data being returned. If the xOutput callback successfully processes the
9789** supplied data, it should return SQLITE_OK to indicate success. Otherwise,
9790** it should return some other SQLite error code. In this case processing
9791** is immediately abandoned and the streaming API function returns a copy
9792** of the xOutput error code to the application.
9793**
9794** The sessions module never invokes an xOutput callback with the third
9795** parameter set to a value less than or equal to zero. Other than this,
9796** no guarantees are made as to the size of the chunks of data returned.
9797*/
9798int sqlite3changeset_apply_strm(
9799 sqlite3 *db, /* Apply change to "main" db of this handle */
9800 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
9801 void *pIn, /* First arg for xInput */
9802 int(*xFilter)(
9803 void *pCtx, /* Copy of sixth arg to _apply() */
9804 const char *zTab /* Table name */
9805 ),
9806 int(*xConflict)(
9807 void *pCtx, /* Copy of sixth arg to _apply() */
9808 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
9809 sqlite3_changeset_iter *p /* Handle describing change and conflict */
9810 ),
9811 void *pCtx /* First argument passed to xConflict */
9812);
9813int sqlite3changeset_concat_strm(
9814 int (*xInputA)(void *pIn, void *pData, int *pnData),
9815 void *pInA,
9816 int (*xInputB)(void *pIn, void *pData, int *pnData),
9817 void *pInB,
9818 int (*xOutput)(void *pOut, const void *pData, int nData),
9819 void *pOut
9820);
9821int sqlite3changeset_invert_strm(
9822 int (*xInput)(void *pIn, void *pData, int *pnData),
9823 void *pIn,
9824 int (*xOutput)(void *pOut, const void *pData, int nData),
9825 void *pOut
9826);
9827int sqlite3changeset_start_strm(
9828 sqlite3_changeset_iter **pp,
9829 int (*xInput)(void *pIn, void *pData, int *pnData),
9830 void *pIn
9831);
9832int sqlite3session_changeset_strm(
9833 sqlite3_session *pSession,
9834 int (*xOutput)(void *pOut, const void *pData, int nData),
9835 void *pOut
9836);
9837int sqlite3session_patchset_strm(
9838 sqlite3_session *pSession,
9839 int (*xOutput)(void *pOut, const void *pData, int nData),
9840 void *pOut
9841);
9842int sqlite3changegroup_add_strm(sqlite3_changegroup*,
9843 int (*xInput)(void *pIn, void *pData, int *pnData),
9844 void *pIn
9845);
9846int sqlite3changegroup_output_strm(sqlite3_changegroup*,
9847 int (*xOutput)(void *pOut, const void *pData, int nData),
9848 void *pOut
9849);
9850
9851
9852/*
9853** Make sure we can call this stuff from C++.
9854*/
9855#ifdef __cplusplus
9856}
9857#endif
9858
9859#endif /* !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) */
9860
9861/******** End of sqlite3session.h *********/
9862/******** Begin file fts5.h *********/
9863/*
9864** 2014 May 31
9865**
9866** The author disclaims copyright to this source code. In place of
9867** a legal notice, here is a blessing:
9868**
9869** May you do good and not evil.
9870** May you find forgiveness for yourself and forgive others.
9871** May you share freely, never taking more than you give.
9872**
9873******************************************************************************
9874**
9875** Interfaces to extend FTS5. Using the interfaces defined in this file,
9876** FTS5 may be extended with:
9877**
9878** * custom tokenizers, and
9879** * custom auxiliary functions.
9880*/
9881
9882
9883#ifndef _FTS5_H
9884#define _FTS5_H
9885
9886
9887#ifdef __cplusplus
9888extern "C" {
9889#endif
9890
9891/*************************************************************************
9892** CUSTOM AUXILIARY FUNCTIONS
9893**
9894** Virtual table implementations may overload SQL functions by implementing
9895** the sqlite3_module.xFindFunction() method.
9896*/
9897
9898typedef struct Fts5ExtensionApi Fts5ExtensionApi;
9899typedef struct Fts5Context Fts5Context;
9900typedef struct Fts5PhraseIter Fts5PhraseIter;
9901
9902typedef void (*fts5_extension_function)(
9903 const Fts5ExtensionApi *pApi, /* API offered by current FTS version */
9904 Fts5Context *pFts, /* First arg to pass to pApi functions */
9905 sqlite3_context *pCtx, /* Context for returning result/error */
9906 int nVal, /* Number of values in apVal[] array */
9907 sqlite3_value **apVal /* Array of trailing arguments */
9908);
9909
9910struct Fts5PhraseIter {
9911 const unsigned char *a;
9912 const unsigned char *b;
9913};
9914
9915/*
9916** EXTENSION API FUNCTIONS
9917**
9918** xUserData(pFts):
9919** Return a copy of the context pointer the extension function was
9920** registered with.
9921**
9922** xColumnTotalSize(pFts, iCol, pnToken):
9923** If parameter iCol is less than zero, set output variable *pnToken
9924** to the total number of tokens in the FTS5 table. Or, if iCol is
9925** non-negative but less than the number of columns in the table, return
9926** the total number of tokens in column iCol, considering all rows in
9927** the FTS5 table.
9928**
9929** If parameter iCol is greater than or equal to the number of columns
9930** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
9931** an OOM condition or IO error), an appropriate SQLite error code is
9932** returned.
9933**
9934** xColumnCount(pFts):
9935** Return the number of columns in the table.
9936**
9937** xColumnSize(pFts, iCol, pnToken):
9938** If parameter iCol is less than zero, set output variable *pnToken
9939** to the total number of tokens in the current row. Or, if iCol is
9940** non-negative but less than the number of columns in the table, set
9941** *pnToken to the number of tokens in column iCol of the current row.
9942**
9943** If parameter iCol is greater than or equal to the number of columns
9944** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
9945** an OOM condition or IO error), an appropriate SQLite error code is
9946** returned.
9947**
9948** This function may be quite inefficient if used with an FTS5 table
9949** created with the "columnsize=0" option.
9950**
9951** xColumnText:
9952** This function attempts to retrieve the text of column iCol of the
9953** current document. If successful, (*pz) is set to point to a buffer
9954** containing the text in utf-8 encoding, (*pn) is set to the size in bytes
9955** (not characters) of the buffer and SQLITE_OK is returned. Otherwise,
9956** if an error occurs, an SQLite error code is returned and the final values
9957** of (*pz) and (*pn) are undefined.
9958**
9959** xPhraseCount:
9960** Returns the number of phrases in the current query expression.
9961**
9962** xPhraseSize:
9963** Returns the number of tokens in phrase iPhrase of the query. Phrases
9964** are numbered starting from zero.
9965**
9966** xInstCount:
9967** Set *pnInst to the total number of occurrences of all phrases within
9968** the query within the current row. Return SQLITE_OK if successful, or
9969** an error code (i.e. SQLITE_NOMEM) if an error occurs.
9970**
9971** This API can be quite slow if used with an FTS5 table created with the
9972** "detail=none" or "detail=column" option. If the FTS5 table is created
9973** with either "detail=none" or "detail=column" and "content=" option
9974** (i.e. if it is a contentless table), then this API always returns 0.
9975**
9976** xInst:
9977** Query for the details of phrase match iIdx within the current row.
9978** Phrase matches are numbered starting from zero, so the iIdx argument
9979** should be greater than or equal to zero and smaller than the value
9980** output by xInstCount().
9981**
9982** Usually, output parameter *piPhrase is set to the phrase number, *piCol
9983** to the column in which it occurs and *piOff the token offset of the
9984** first token of the phrase. The exception is if the table was created
9985** with the offsets=0 option specified. In this case *piOff is always
9986** set to -1.
9987**
9988** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM)
9989** if an error occurs.
9990**
9991** This API can be quite slow if used with an FTS5 table created with the
9992** "detail=none" or "detail=column" option.
9993**
9994** xRowid:
9995** Returns the rowid of the current row.
9996**
9997** xTokenize:
9998** Tokenize text using the tokenizer belonging to the FTS5 table.
9999**
10000** xQueryPhrase(pFts5, iPhrase, pUserData, xCallback):
10001** This API function is used to query the FTS table for phrase iPhrase
10002** of the current query. Specifically, a query equivalent to:
10003**
10004** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid
10005**
10006** with $p set to a phrase equivalent to the phrase iPhrase of the
10007** current query is executed. Any column filter that applies to
10008** phrase iPhrase of the current query is included in $p. For each
10009** row visited, the callback function passed as the fourth argument
10010** is invoked. The context and API objects passed to the callback
10011** function may be used to access the properties of each matched row.
10012** Invoking Api.xUserData() returns a copy of the pointer passed as
10013** the third argument to pUserData.
10014**
10015** If the callback function returns any value other than SQLITE_OK, the
10016** query is abandoned and the xQueryPhrase function returns immediately.
10017** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK.
10018** Otherwise, the error code is propagated upwards.
10019**
10020** If the query runs to completion without incident, SQLITE_OK is returned.
10021** Or, if some error occurs before the query completes or is aborted by
10022** the callback, an SQLite error code is returned.
10023**
10024**
10025** xSetAuxdata(pFts5, pAux, xDelete)
10026**
10027** Save the pointer passed as the second argument as the extension functions
10028** "auxiliary data". The pointer may then be retrieved by the current or any
10029** future invocation of the same fts5 extension function made as part of
10030** of the same MATCH query using the xGetAuxdata() API.
10031**
10032** Each extension function is allocated a single auxiliary data slot for
10033** each FTS query (MATCH expression). If the extension function is invoked
10034** more than once for a single FTS query, then all invocations share a
10035** single auxiliary data context.
10036**
10037** If there is already an auxiliary data pointer when this function is
10038** invoked, then it is replaced by the new pointer. If an xDelete callback
10039** was specified along with the original pointer, it is invoked at this
10040** point.
10041**
10042** The xDelete callback, if one is specified, is also invoked on the
10043** auxiliary data pointer after the FTS5 query has finished.
10044**
10045** If an error (e.g. an OOM condition) occurs within this function, an
10046** the auxiliary data is set to NULL and an error code returned. If the
10047** xDelete parameter was not NULL, it is invoked on the auxiliary data
10048** pointer before returning.
10049**
10050**
10051** xGetAuxdata(pFts5, bClear)
10052**
10053** Returns the current auxiliary data pointer for the fts5 extension
10054** function. See the xSetAuxdata() method for details.
10055**
10056** If the bClear argument is non-zero, then the auxiliary data is cleared
10057** (set to NULL) before this function returns. In this case the xDelete,
10058** if any, is not invoked.
10059**
10060**
10061** xRowCount(pFts5, pnRow)
10062**
10063** This function is used to retrieve the total number of rows in the table.
10064** In other words, the same value that would be returned by:
10065**
10066** SELECT count(*) FROM ftstable;
10067**
10068** xPhraseFirst()
10069** This function is used, along with type Fts5PhraseIter and the xPhraseNext
10070** method, to iterate through all instances of a single query phrase within
10071** the current row. This is the same information as is accessible via the
10072** xInstCount/xInst APIs. While the xInstCount/xInst APIs are more convenient
10073** to use, this API may be faster under some circumstances. To iterate
10074** through instances of phrase iPhrase, use the following code:
10075**
10076** Fts5PhraseIter iter;
10077** int iCol, iOff;
10078** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff);
10079** iCol>=0;
10080** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff)
10081** ){
10082** // An instance of phrase iPhrase at offset iOff of column iCol
10083** }
10084**
10085** The Fts5PhraseIter structure is defined above. Applications should not
10086** modify this structure directly - it should only be used as shown above
10087** with the xPhraseFirst() and xPhraseNext() API methods (and by
10088** xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below).
10089**
10090** This API can be quite slow if used with an FTS5 table created with the
10091** "detail=none" or "detail=column" option. If the FTS5 table is created
10092** with either "detail=none" or "detail=column" and "content=" option
10093** (i.e. if it is a contentless table), then this API always iterates
10094** through an empty set (all calls to xPhraseFirst() set iCol to -1).
10095**
10096** xPhraseNext()
10097** See xPhraseFirst above.
10098**
10099** xPhraseFirstColumn()
10100** This function and xPhraseNextColumn() are similar to the xPhraseFirst()
10101** and xPhraseNext() APIs described above. The difference is that instead
10102** of iterating through all instances of a phrase in the current row, these
10103** APIs are used to iterate through the set of columns in the current row
10104** that contain one or more instances of a specified phrase. For example:
10105**
10106** Fts5PhraseIter iter;
10107** int iCol;
10108** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol);
10109** iCol>=0;
10110** pApi->xPhraseNextColumn(pFts, &iter, &iCol)
10111** ){
10112** // Column iCol contains at least one instance of phrase iPhrase
10113** }
10114**
10115** This API can be quite slow if used with an FTS5 table created with the
10116** "detail=none" option. If the FTS5 table is created with either
10117** "detail=none" "content=" option (i.e. if it is a contentless table),
10118** then this API always iterates through an empty set (all calls to
10119** xPhraseFirstColumn() set iCol to -1).
10120**
10121** The information accessed using this API and its companion
10122** xPhraseFirstColumn() may also be obtained using xPhraseFirst/xPhraseNext
10123** (or xInst/xInstCount). The chief advantage of this API is that it is
10124** significantly more efficient than those alternatives when used with
10125** "detail=column" tables.
10126**
10127** xPhraseNextColumn()
10128** See xPhraseFirstColumn above.
10129*/
10130struct Fts5ExtensionApi {
10131 int iVersion; /* Currently always set to 3 */
10132
10133 void *(*xUserData)(Fts5Context*);
10134
10135 int (*xColumnCount)(Fts5Context*);
10136 int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow);
10137 int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken);
10138
10139 int (*xTokenize)(Fts5Context*,
10140 const char *pText, int nText, /* Text to tokenize */
10141 void *pCtx, /* Context passed to xToken() */
10142 int (*xToken)(void*, int, const char*, int, int, int) /* Callback */
10143 );
10144
10145 int (*xPhraseCount)(Fts5Context*);
10146 int (*xPhraseSize)(Fts5Context*, int iPhrase);
10147
10148 int (*xInstCount)(Fts5Context*, int *pnInst);
10149 int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff);
10150
10151 sqlite3_int64 (*xRowid)(Fts5Context*);
10152 int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn);
10153 int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken);
10154
10155 int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData,
10156 int(*)(const Fts5ExtensionApi*,Fts5Context*,void*)
10157 );
10158 int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*));
10159 void *(*xGetAuxdata)(Fts5Context*, int bClear);
10160
10161 int (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*);
10162 void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff);
10163
10164 int (*xPhraseFirstColumn)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*);
10165 void (*xPhraseNextColumn)(Fts5Context*, Fts5PhraseIter*, int *piCol);
10166};
10167
10168/*
10169** CUSTOM AUXILIARY FUNCTIONS
10170*************************************************************************/
10171
10172/*************************************************************************
10173** CUSTOM TOKENIZERS
10174**
10175** Applications may also register custom tokenizer types. A tokenizer
10176** is registered by providing fts5 with a populated instance of the
10177** following structure. All structure methods must be defined, setting
10178** any member of the fts5_tokenizer struct to NULL leads to undefined
10179** behaviour. The structure methods are expected to function as follows:
10180**
10181** xCreate:
10182** This function is used to allocate and initialize a tokenizer instance.
10183** A tokenizer instance is required to actually tokenize text.
10184**
10185** The first argument passed to this function is a copy of the (void*)
10186** pointer provided by the application when the fts5_tokenizer object
10187** was registered with FTS5 (the third argument to xCreateTokenizer()).
10188** The second and third arguments are an array of nul-terminated strings
10189** containing the tokenizer arguments, if any, specified following the
10190** tokenizer name as part of the CREATE VIRTUAL TABLE statement used
10191** to create the FTS5 table.
10192**
10193** The final argument is an output variable. If successful, (*ppOut)
10194** should be set to point to the new tokenizer handle and SQLITE_OK
10195** returned. If an error occurs, some value other than SQLITE_OK should
10196** be returned. In this case, fts5 assumes that the final value of *ppOut
10197** is undefined.
10198**
10199** xDelete:
10200** This function is invoked to delete a tokenizer handle previously
10201** allocated using xCreate(). Fts5 guarantees that this function will
10202** be invoked exactly once for each successful call to xCreate().
10203**
10204** xTokenize:
10205** This function is expected to tokenize the nText byte string indicated
10206** by argument pText. pText may or may not be nul-terminated. The first
10207** argument passed to this function is a pointer to an Fts5Tokenizer object
10208** returned by an earlier call to xCreate().
10209**
10210** The second argument indicates the reason that FTS5 is requesting
10211** tokenization of the supplied text. This is always one of the following
10212** four values:
10213**
10214** <ul><li> <b>FTS5_TOKENIZE_DOCUMENT</b> - A document is being inserted into
10215** or removed from the FTS table. The tokenizer is being invoked to
10216** determine the set of tokens to add to (or delete from) the
10217** FTS index.
10218**
10219** <li> <b>FTS5_TOKENIZE_QUERY</b> - A MATCH query is being executed
10220** against the FTS index. The tokenizer is being called to tokenize
10221** a bareword or quoted string specified as part of the query.
10222**
10223** <li> <b>(FTS5_TOKENIZE_QUERY | FTS5_TOKENIZE_PREFIX)</b> - Same as
10224** FTS5_TOKENIZE_QUERY, except that the bareword or quoted string is
10225** followed by a "*" character, indicating that the last token
10226** returned by the tokenizer will be treated as a token prefix.
10227**
10228** <li> <b>FTS5_TOKENIZE_AUX</b> - The tokenizer is being invoked to
10229** satisfy an fts5_api.xTokenize() request made by an auxiliary
10230** function. Or an fts5_api.xColumnSize() request made by the same
10231** on a columnsize=0 database.
10232** </ul>
10233**
10234** For each token in the input string, the supplied callback xToken() must
10235** be invoked. The first argument to it should be a copy of the pointer
10236** passed as the second argument to xTokenize(). The third and fourth
10237** arguments are a pointer to a buffer containing the token text, and the
10238** size of the token in bytes. The 4th and 5th arguments are the byte offsets
10239** of the first byte of and first byte immediately following the text from
10240** which the token is derived within the input.
10241**
10242** The second argument passed to the xToken() callback ("tflags") should
10243** normally be set to 0. The exception is if the tokenizer supports
10244** synonyms. In this case see the discussion below for details.
10245**
10246** FTS5 assumes the xToken() callback is invoked for each token in the
10247** order that they occur within the input text.
10248**
10249** If an xToken() callback returns any value other than SQLITE_OK, then
10250** the tokenization should be abandoned and the xTokenize() method should
10251** immediately return a copy of the xToken() return value. Or, if the
10252** input buffer is exhausted, xTokenize() should return SQLITE_OK. Finally,
10253** if an error occurs with the xTokenize() implementation itself, it
10254** may abandon the tokenization and return any error code other than
10255** SQLITE_OK or SQLITE_DONE.
10256**
10257** SYNONYM SUPPORT
10258**
10259** Custom tokenizers may also support synonyms. Consider a case in which a
10260** user wishes to query for a phrase such as "first place". Using the
10261** built-in tokenizers, the FTS5 query 'first + place' will match instances
10262** of "first place" within the document set, but not alternative forms
10263** such as "1st place". In some applications, it would be better to match
10264** all instances of "first place" or "1st place" regardless of which form
10265** the user specified in the MATCH query text.
10266**
10267** There are several ways to approach this in FTS5:
10268**
10269** <ol><li> By mapping all synonyms to a single token. In this case, the
10270** In the above example, this means that the tokenizer returns the
10271** same token for inputs "first" and "1st". Say that token is in
10272** fact "first", so that when the user inserts the document "I won
10273** 1st place" entries are added to the index for tokens "i", "won",
10274** "first" and "place". If the user then queries for '1st + place',
10275** the tokenizer substitutes "first" for "1st" and the query works
10276** as expected.
10277**
10278** <li> By adding multiple synonyms for a single term to the FTS index.
10279** In this case, when tokenizing query text, the tokenizer may
10280** provide multiple synonyms for a single term within the document.
10281** FTS5 then queries the index for each synonym individually. For
10282** example, faced with the query:
10283**
10284** <codeblock>
10285** ... MATCH 'first place'</codeblock>
10286**
10287** the tokenizer offers both "1st" and "first" as synonyms for the
10288** first token in the MATCH query and FTS5 effectively runs a query
10289** similar to:
10290**
10291** <codeblock>
10292** ... MATCH '(first OR 1st) place'</codeblock>
10293**
10294** except that, for the purposes of auxiliary functions, the query
10295** still appears to contain just two phrases - "(first OR 1st)"
10296** being treated as a single phrase.
10297**
10298** <li> By adding multiple synonyms for a single term to the FTS index.
10299** Using this method, when tokenizing document text, the tokenizer
10300** provides multiple synonyms for each token. So that when a
10301** document such as "I won first place" is tokenized, entries are
10302** added to the FTS index for "i", "won", "first", "1st" and
10303** "place".
10304**
10305** This way, even if the tokenizer does not provide synonyms
10306** when tokenizing query text (it should not - to do would be
10307** inefficient), it doesn't matter if the user queries for
10308** 'first + place' or '1st + place', as there are entires in the
10309** FTS index corresponding to both forms of the first token.
10310** </ol>
10311**
10312** Whether it is parsing document or query text, any call to xToken that
10313** specifies a <i>tflags</i> argument with the FTS5_TOKEN_COLOCATED bit
10314** is considered to supply a synonym for the previous token. For example,
10315** when parsing the document "I won first place", a tokenizer that supports
10316** synonyms would call xToken() 5 times, as follows:
10317**
10318** <codeblock>
10319** xToken(pCtx, 0, "i", 1, 0, 1);
10320** xToken(pCtx, 0, "won", 3, 2, 5);
10321** xToken(pCtx, 0, "first", 5, 6, 11);
10322** xToken(pCtx, FTS5_TOKEN_COLOCATED, "1st", 3, 6, 11);
10323** xToken(pCtx, 0, "place", 5, 12, 17);
10324**</codeblock>
10325**
10326** It is an error to specify the FTS5_TOKEN_COLOCATED flag the first time
10327** xToken() is called. Multiple synonyms may be specified for a single token
10328** by making multiple calls to xToken(FTS5_TOKEN_COLOCATED) in sequence.
10329** There is no limit to the number of synonyms that may be provided for a
10330** single token.
10331**
10332** In many cases, method (1) above is the best approach. It does not add
10333** extra data to the FTS index or require FTS5 to query for multiple terms,
10334** so it is efficient in terms of disk space and query speed. However, it
10335** does not support prefix queries very well. If, as suggested above, the
10336** token "first" is subsituted for "1st" by the tokenizer, then the query:
10337**
10338** <codeblock>
10339** ... MATCH '1s*'</codeblock>
10340**
10341** will not match documents that contain the token "1st" (as the tokenizer
10342** will probably not map "1s" to any prefix of "first").
10343**
10344** For full prefix support, method (3) may be preferred. In this case,
10345** because the index contains entries for both "first" and "1st", prefix
10346** queries such as 'fi*' or '1s*' will match correctly. However, because
10347** extra entries are added to the FTS index, this method uses more space
10348** within the database.
10349**
10350** Method (2) offers a midpoint between (1) and (3). Using this method,
10351** a query such as '1s*' will match documents that contain the literal
10352** token "1st", but not "first" (assuming the tokenizer is not able to
10353** provide synonyms for prefixes). However, a non-prefix query like '1st'
10354** will match against "1st" and "first". This method does not require
10355** extra disk space, as no extra entries are added to the FTS index.
10356** On the other hand, it may require more CPU cycles to run MATCH queries,
10357** as separate queries of the FTS index are required for each synonym.
10358**
10359** When using methods (2) or (3), it is important that the tokenizer only
10360** provide synonyms when tokenizing document text (method (2)) or query
10361** text (method (3)), not both. Doing so will not cause any errors, but is
10362** inefficient.
10363*/
10364typedef struct Fts5Tokenizer Fts5Tokenizer;
10365typedef struct fts5_tokenizer fts5_tokenizer;
10366struct fts5_tokenizer {
10367 int (*xCreate)(void*, const char **azArg, int nArg, Fts5Tokenizer **ppOut);
10368 void (*xDelete)(Fts5Tokenizer*);
10369 int (*xTokenize)(Fts5Tokenizer*,
10370 void *pCtx,
10371 int flags, /* Mask of FTS5_TOKENIZE_* flags */
10372 const char *pText, int nText,
10373 int (*xToken)(
10374 void *pCtx, /* Copy of 2nd argument to xTokenize() */
10375 int tflags, /* Mask of FTS5_TOKEN_* flags */
10376 const char *pToken, /* Pointer to buffer containing token */
10377 int nToken, /* Size of token in bytes */
10378 int iStart, /* Byte offset of token within input text */
10379 int iEnd /* Byte offset of end of token within input text */
10380 )
10381 );
10382};
10383
10384/* Flags that may be passed as the third argument to xTokenize() */
10385#define FTS5_TOKENIZE_QUERY 0x0001
10386#define FTS5_TOKENIZE_PREFIX 0x0002
10387#define FTS5_TOKENIZE_DOCUMENT 0x0004
10388#define FTS5_TOKENIZE_AUX 0x0008
10389
10390/* Flags that may be passed by the tokenizer implementation back to FTS5
10391** as the third argument to the supplied xToken callback. */
10392#define FTS5_TOKEN_COLOCATED 0x0001 /* Same position as prev. token */
10393
10394/*
10395** END OF CUSTOM TOKENIZERS
10396*************************************************************************/
10397
10398/*************************************************************************
10399** FTS5 EXTENSION REGISTRATION API
10400*/
10401typedef struct fts5_api fts5_api;
10402struct fts5_api {
10403 int iVersion; /* Currently always set to 2 */
10404
10405 /* Create a new tokenizer */
10406 int (*xCreateTokenizer)(
10407 fts5_api *pApi,
10408 const char *zName,
10409 void *pContext,
10410 fts5_tokenizer *pTokenizer,
10411 void (*xDestroy)(void*)
10412 );
10413
10414 /* Find an existing tokenizer */
10415 int (*xFindTokenizer)(
10416 fts5_api *pApi,
10417 const char *zName,
10418 void **ppContext,
10419 fts5_tokenizer *pTokenizer
10420 );
10421
10422 /* Create a new auxiliary function */
10423 int (*xCreateFunction)(
10424 fts5_api *pApi,
10425 const char *zName,
10426 void *pContext,
10427 fts5_extension_function xFunction,
10428 void (*xDestroy)(void*)
10429 );
10430};
10431
10432/*
10433** END OF REGISTRATION API
10434*************************************************************************/
10435
10436#ifdef __cplusplus
10437} /* end of the 'extern "C"' block */
10438#endif
10439
10440#endif /* _FTS5_H */
10441
10442/******** End of fts5.h *********/