sqlite3.h · cryptotaxi247/netdata-1

Code Commits Issues Pulls Sessions CI/CD

master

h 13,775 lines 646 KB

Raw

Large file — syntax highlighting disabled.

1	/*
2	** 2001-09-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
41	extern "C" {
42	#endif
43
44
45	/*
46	** Facilitate override of interface linkage and calling conventions.
47	** Be aware that these macros may not be used within this particular
48	** translation of the amalgamation and its associated header file.
49	**
50	** The SQLITE_EXTERN and SQLITE_API macros are used to instruct the
51	** compiler that the target identifier should have external linkage.
52	**
53	** The SQLITE_CDECL macro is used to set the calling convention for
54	** public functions that accept a variable number of arguments.
55	**
56	** The SQLITE_APICALL macro is used to set the calling convention for
57	** public functions that accept a fixed number of arguments.
58	**
59	** The SQLITE_STDCALL macro is no longer used and is now deprecated.
60	**
61	** The SQLITE_CALLBACK macro is used to set the calling convention for
62	** function pointers.
63	**
64	** The SQLITE_SYSAPI macro is used to set the calling convention for
65	** functions provided by the operating system.
66	**
67	** Currently, the SQLITE_CDECL, SQLITE_APICALL, SQLITE_CALLBACK, and
68	** SQLITE_SYSAPI macros are used only when building for environments
69	** that require non-default calling conventions.
70	*/
71	#ifndef SQLITE_EXTERN
72	# define SQLITE_EXTERN extern
73	#endif
74	#ifndef SQLITE_API
75	# define SQLITE_API
76	#endif
77	#ifndef SQLITE_CDECL
78	# define SQLITE_CDECL
79	#endif
80	#ifndef SQLITE_APICALL
81	# define SQLITE_APICALL
82	#endif
83	#ifndef SQLITE_STDCALL
84	# define SQLITE_STDCALL SQLITE_APICALL
85	#endif
86	#ifndef SQLITE_CALLBACK
87	# define SQLITE_CALLBACK
88	#endif
89	#ifndef SQLITE_SYSAPI
90	# define SQLITE_SYSAPI
91	#endif
92
93	/*
94	** These no-op macros are used in front of interfaces to mark those
95	** interfaces as either deprecated or experimental. New applications
96	** should not use deprecated interfaces - they are supported for backwards
97	** compatibility only. Application writers should be aware that
98	** experimental interfaces are subject to change in point releases.
99	**
100	** These macros used to resolve to various kinds of compiler magic that
101	** would generate warning messages when they were used. But that
102	** compiler magic ended up generating such a flurry of bug reports
103	** that we have taken it all out and gone back to using simple
104	** noop macros.
105	*/
106	#define SQLITE_DEPRECATED
107	#define SQLITE_EXPERIMENTAL
108
109	/*
110	** Ensure these symbols were not defined by some previous header file.
111	*/
112	#ifdef SQLITE_VERSION
113	# undef SQLITE_VERSION
114	#endif
115	#ifdef SQLITE_VERSION_NUMBER
116	# undef SQLITE_VERSION_NUMBER
117	#endif
118
119	/*
120	** CAPI3REF: Compile-Time Library Version Numbers
121	**
122	** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
123	** evaluates to a string literal that is the SQLite version in the
124	** format "X.Y.Z" where X is the major version number (always 3 for
125	** SQLite3) and Y is the minor version number and Z is the release number.)^
126	** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
127	** with the value (X1000000 + Y1000 + Z) where X, Y, and Z are the same
128	** numbers used in [SQLITE_VERSION].)^
129	** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
130	** be larger than the release from which it is derived. Either Y will
131	** be held constant and Z will be incremented or else Y will be incremented
132	** and Z will be reset to zero.
133	**
134	** Since [version 3.6.18] ([dateof:3.6.18]),
135	** SQLite source code has been stored in the
136	** <a href="http://fossil-scm.org/">Fossil configuration management
137	** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to
138	** a string which identifies a particular check-in of SQLite
139	** within its configuration management system. ^The SQLITE_SOURCE_ID
140	** string contains the date and time of the check-in (UTC) and a SHA1
141	** or SHA3-256 hash of the entire source tree. If the source code has
142	** been edited in any way since it was last checked in, then the last
143	** four hexadecimal digits of the hash may be modified.
144	**
145	** See also: [sqlite3_libversion()],
146	** [sqlite3_libversion_number()], [sqlite3_sourceid()],
147	** [sqlite_version()] and [sqlite_source_id()].
148	*/
149	#define SQLITE_VERSION "3.50.4"
150	#define SQLITE_VERSION_NUMBER 3050004
151	#define SQLITE_SOURCE_ID "2025-07-30 19:33:53 4d8adfb30e03f9cf27f800a2c1ba3c48fb4ca1b08b0f5ed59a4d5ecbf45e20a3"
152
153	/*
154	** CAPI3REF: Run-Time Library Version Numbers
155	** KEYWORDS: sqlite3_version sqlite3_sourceid
156	**
157	** These interfaces provide the same information as the [SQLITE_VERSION],
158	** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
159	** but are associated with the library instead of the header file. ^(Cautious
160	** programmers might include assert() statements in their application to
161	** verify that values returned by these interfaces match the macros in
162	** the header, and thus ensure that the application is
163	** compiled with matching library and header files.
164	**
165	** <blockquote><pre>
166	** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
167	** assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );
168	** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
169	** </pre></blockquote>)^
170	**
171	** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
172	** macro. ^The sqlite3_libversion() function returns a pointer to the
173	** to the sqlite3_version[] string constant. The sqlite3_libversion()
174	** function is provided for use in DLLs since DLL users usually do not have
175	** direct access to string constants within the DLL. ^The
176	** sqlite3_libversion_number() function returns an integer equal to
177	** [SQLITE_VERSION_NUMBER]. ^(The sqlite3_sourceid() function returns
178	** a pointer to a string constant whose value is the same as the
179	** [SQLITE_SOURCE_ID] C preprocessor macro. Except if SQLite is built
180	** using an edited copy of [the amalgamation], then the last four characters
181	** of the hash might be different from [SQLITE_SOURCE_ID].)^
182	**
183	** See also: [sqlite_version()] and [sqlite_source_id()].
184	*/
185	SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
186	SQLITE_API const char *sqlite3_libversion(void);
187	SQLITE_API const char *sqlite3_sourceid(void);
188	SQLITE_API int sqlite3_libversion_number(void);
189
190	/*
191	** CAPI3REF: Run-Time Library Compilation Options Diagnostics
192	**
193	** ^The sqlite3_compileoption_used() function returns 0 or 1
194	** indicating whether the specified option was defined at
195	** compile time. ^The SQLITE_ prefix may be omitted from the
196	** option name passed to sqlite3_compileoption_used().
197	**
198	** ^The sqlite3_compileoption_get() function allows iterating
199	** over the list of options that were defined at compile time by
200	** returning the N-th compile time option string. ^If N is out of range,
201	** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_
202	** prefix is omitted from any strings returned by
203	** sqlite3_compileoption_get().
204	**
205	** ^Support for the diagnostic functions sqlite3_compileoption_used()
206	** and sqlite3_compileoption_get() may be omitted by specifying the
207	** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
208	**
209	** See also: SQL functions [sqlite_compileoption_used()] and
210	** [sqlite_compileoption_get()] and the [compile_options pragma].
211	*/
212	#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
213	SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
214	SQLITE_API const char *sqlite3_compileoption_get(int N);
215	#else
216	# define sqlite3_compileoption_used(X) 0
217	# define sqlite3_compileoption_get(X) ((void*)0)
218	#endif
219
220	/*
221	** CAPI3REF: Test To See If The Library Is Threadsafe
222	**
223	** ^The sqlite3_threadsafe() function returns zero if and only if
224	** SQLite was compiled with mutexing code omitted due to the
225	** [SQLITE_THREADSAFE] compile-time option being set to 0.
226	**
227	** SQLite can be compiled with or without mutexes. When
228	** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
229	** are enabled and SQLite is threadsafe. When the
230	** [SQLITE_THREADSAFE] macro is 0,
231	** the mutexes are omitted. Without the mutexes, it is not safe
232	** to use SQLite concurrently from more than one thread.
233	**
234	** Enabling mutexes incurs a measurable performance penalty.
235	** So if speed is of utmost importance, it makes sense to disable
236	** the mutexes. But for maximum safety, mutexes should be enabled.
237	** ^The default behavior is for mutexes to be enabled.
238	**
239	** This interface can be used by an application to make sure that the
240	** version of SQLite that it is linking against was compiled with
241	** the desired setting of the [SQLITE_THREADSAFE] macro.
242	**
243	** This interface only reports on the compile-time mutex setting
244	** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
245	** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
246	** can be fully or partially disabled using a call to [sqlite3_config()]
247	** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
248	** or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the
249	** sqlite3_threadsafe() function shows only the compile-time setting of
250	** thread safety, not any run-time changes to that setting made by
251	** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
252	** is unchanged by calls to sqlite3_config().)^
253	**
254	** See the [threading mode] documentation for additional information.
255	*/
256	SQLITE_API int sqlite3_threadsafe(void);
257
258	/*
259	** CAPI3REF: Database Connection Handle
260	** KEYWORDS: {database connection} {database connections}
261	**
262	** Each open SQLite database is represented by a pointer to an instance of
263	** the opaque structure named "sqlite3". It is useful to think of an sqlite3
264	** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
265	** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
266	** and [sqlite3_close_v2()] are its destructors. There are many other
267	** interfaces (such as
268	** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
269	** [sqlite3_busy_timeout()] to name but three) that are methods on an
270	** sqlite3 object.
271	*/
272	typedef struct sqlite3 sqlite3;
273
274	/*
275	** CAPI3REF: 64-Bit Integer Types
276	** KEYWORDS: sqlite_int64 sqlite_uint64
277	**
278	** Because there is no cross-platform way to specify 64-bit integer types
279	** SQLite includes typedefs for 64-bit signed and unsigned integers.
280	**
281	** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
282	** The sqlite_int64 and sqlite_uint64 types are supported for backwards
283	** compatibility only.
284	**
285	** ^The sqlite3_int64 and sqlite_int64 types can store integer values
286	** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
287	** sqlite3_uint64 and sqlite_uint64 types can store integer values
288	** between 0 and +18446744073709551615 inclusive.
289	*/
290	#ifdef SQLITE_INT64_TYPE
291	typedef SQLITE_INT64_TYPE sqlite_int64;
292	# ifdef SQLITE_UINT64_TYPE
293	typedef SQLITE_UINT64_TYPE sqlite_uint64;
294	# else
295	typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
296	# endif
297	#elif defined(_MSC_VER) \|\| defined(__BORLANDC__)
298	typedef __int64 sqlite_int64;
299	typedef unsigned __int64 sqlite_uint64;
300	#else
301	typedef long long int sqlite_int64;
302	typedef unsigned long long int sqlite_uint64;
303	#endif
304	typedef sqlite_int64 sqlite3_int64;
305	typedef sqlite_uint64 sqlite3_uint64;
306
307	/*
308	** If compiling for a processor that lacks floating point support,
309	** substitute integer for floating-point.
310	*/
311	#ifdef SQLITE_OMIT_FLOATING_POINT
312	# define double sqlite3_int64
313	#endif
314
315	/*
316	** CAPI3REF: Closing A Database Connection
317	** DESTRUCTOR: sqlite3
318	**
319	** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
320	** for the [sqlite3] object.
321	** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
322	** the [sqlite3] object is successfully destroyed and all associated
323	** resources are deallocated.
324	**
325	** Ideally, applications should [sqlite3_finalize \| finalize] all
326	** [prepared statements], [sqlite3_blob_close \| close] all [BLOB handles], and
327	** [sqlite3_backup_finish \| finish] all [sqlite3_backup] objects associated
328	** with the [sqlite3] object prior to attempting to close the object.
329	** ^If the database connection is associated with unfinalized prepared
330	** statements, BLOB handlers, and/or unfinished sqlite3_backup objects then
331	** sqlite3_close() will leave the database connection open and return
332	** [SQLITE_BUSY]. ^If sqlite3_close_v2() is called with unfinalized prepared
333	** statements, unclosed BLOB handlers, and/or unfinished sqlite3_backups,
334	** it returns [SQLITE_OK] regardless, but instead of deallocating the database
335	** connection immediately, it marks the database connection as an unusable
336	** "zombie" and makes arrangements to automatically deallocate the database
337	** connection after all prepared statements are finalized, all BLOB handles
338	** are closed, and all backups have finished. The sqlite3_close_v2() interface
339	** is intended for use with host languages that are garbage collected, and
340	** where the order in which destructors are called is arbitrary.
341	**
342	** ^If an [sqlite3] object is destroyed while a transaction is open,
343	** the transaction is automatically rolled back.
344	**
345	** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
346	** must be either a NULL
347	** pointer or an [sqlite3] object pointer obtained
348	** from [sqlite3_open()], [sqlite3_open16()], or
349	** [sqlite3_open_v2()], and not previously closed.
350	** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
351	** argument is a harmless no-op.
352	*/
353	SQLITE_API int sqlite3_close(sqlite3*);
354	SQLITE_API int sqlite3_close_v2(sqlite3*);
355
356	/*
357	** The type for a callback function.
358	** This is legacy and deprecated. It is included for historical
359	** compatibility and is not documented.
360	*/
361	typedef int (sqlite3_callback)(void,int,char, char);
362
363	/*
364	** CAPI3REF: One-Step Query Execution Interface
365	** METHOD: sqlite3
366	**
367	** The sqlite3_exec() interface is a convenience wrapper around
368	** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
369	** that allows an application to run multiple statements of SQL
370	** without having to use a lot of C code.
371	**
372	** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
373	** semicolon-separate SQL statements passed into its 2nd argument,
374	** in the context of the [database connection] passed in as its 1st
375	** argument. ^If the callback function of the 3rd argument to
376	** sqlite3_exec() is not NULL, then it is invoked for each result row
377	** coming out of the evaluated SQL statements. ^The 4th argument to
378	** sqlite3_exec() is relayed through to the 1st argument of each
379	** callback invocation. ^If the callback pointer to sqlite3_exec()
380	** is NULL, then no callback is ever invoked and result rows are
381	** ignored.
382	**
383	** ^If an error occurs while evaluating the SQL statements passed into
384	** sqlite3_exec(), then execution of the current statement stops and
385	** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec()
386	** is not NULL then any error message is written into memory obtained
387	** from [sqlite3_malloc()] and passed back through the 5th parameter.
388	** To avoid memory leaks, the application should invoke [sqlite3_free()]
389	** on error message strings returned through the 5th parameter of
390	** sqlite3_exec() after the error message string is no longer needed.
391	** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
392	** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
393	** NULL before returning.
394	**
395	** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
396	** routine returns SQLITE_ABORT without invoking the callback again and
397	** without running any subsequent SQL statements.
398	**
399	** ^The 2nd argument to the sqlite3_exec() callback function is the
400	** number of columns in the result. ^The 3rd argument to the sqlite3_exec()
401	** callback is an array of pointers to strings obtained as if from
402	** [sqlite3_column_text()], one for each column. ^If an element of a
403	** result row is NULL then the corresponding string pointer for the
404	** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
405	** sqlite3_exec() callback is an array of pointers to strings where each
406	** entry represents the name of corresponding result column as obtained
407	** from [sqlite3_column_name()].
408	**
409	** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
410	** to an empty string, or a pointer that contains only whitespace and/or
411	** SQL comments, then no SQL statements are evaluated and the database
412	** is not changed.
413	**
414	** Restrictions:
415	**
416	** <ul>
417	** <li> The application must ensure that the 1st parameter to sqlite3_exec()
418	** is a valid and open [database connection].
419	** <li> The application must not close the [database connection] specified by
420	** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
421	** <li> The application must not modify the SQL statement text passed into
422	** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
423	** <li> The application must not dereference the arrays or string pointers
424	** passed as the 3rd and 4th callback parameters after it returns.
425	** </ul>
426	*/
427	SQLITE_API int sqlite3_exec(
428	sqlite3, / An open database */
429	const char sql, / SQL to be evaluated */
430	int (callback)(void,int,char,char), /* Callback function */
431	void , / 1st argument to callback */
432	char *errmsg / Error msg written here */
433	);
434
435	/*
436	** CAPI3REF: Result Codes
437	** KEYWORDS: {result code definitions}
438	**
439	** Many SQLite functions return an integer result code from the set shown
440	** here in order to indicate success or failure.
441	**
442	** New error codes may be added in future versions of SQLite.
443	**
444	** See also: [extended result code definitions]
445	*/
446	#define SQLITE_OK 0 /* Successful result */
447	/* beginning-of-error-codes */
448	#define SQLITE_ERROR 1 /* Generic error */
449	#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
450	#define SQLITE_PERM 3 /* Access permission denied */
451	#define SQLITE_ABORT 4 /* Callback routine requested an abort */
452	#define SQLITE_BUSY 5 /* The database file is locked */
453	#define SQLITE_LOCKED 6 /* A table in the database is locked */
454	#define SQLITE_NOMEM 7 /* A malloc() failed */
455	#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
456	#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
457	#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
458	#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
459	#define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */
460	#define SQLITE_FULL 13 /* Insertion failed because database is full */
461	#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
462	#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
463	#define SQLITE_EMPTY 16 /* Internal use only */
464	#define SQLITE_SCHEMA 17 /* The database schema changed */
465	#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
466	#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
467	#define SQLITE_MISMATCH 20 /* Data type mismatch */
468	#define SQLITE_MISUSE 21 /* Library used incorrectly */
469	#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
470	#define SQLITE_AUTH 23 /* Authorization denied */
471	#define SQLITE_FORMAT 24 /* Not used */
472	#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
473	#define SQLITE_NOTADB 26 /* File opened that is not a database file */
474	#define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */
475	#define SQLITE_WARNING 28 /* Warnings from sqlite3_log() */
476	#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
477	#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
478	/* end-of-error-codes */
479
480	/*
481	** CAPI3REF: Extended Result Codes
482	** KEYWORDS: {extended result code definitions}
483	**
484	** In its default configuration, SQLite API routines return one of 30 integer
485	** [result codes]. However, experience has shown that many of
486	** these result codes are too coarse-grained. They do not provide as
487	** much information about problems as programmers might like. In an effort to
488	** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8]
489	** and later) include
490	** support for additional result codes that provide more detailed information
491	** about errors. These [extended result codes] are enabled or disabled
492	** on a per database connection basis using the
493	** [sqlite3_extended_result_codes()] API. Or, the extended code for
494	** the most recent error can be obtained using
495	** [sqlite3_extended_errcode()].
496	*/
497	#define SQLITE_ERROR_MISSING_COLLSEQ (SQLITE_ERROR \| (1<<8))
498	#define SQLITE_ERROR_RETRY (SQLITE_ERROR \| (2<<8))
499	#define SQLITE_ERROR_SNAPSHOT (SQLITE_ERROR \| (3<<8))
500	#define SQLITE_IOERR_READ (SQLITE_IOERR \| (1<<8))
501	#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR \| (2<<8))
502	#define SQLITE_IOERR_WRITE (SQLITE_IOERR \| (3<<8))
503	#define SQLITE_IOERR_FSYNC (SQLITE_IOERR \| (4<<8))
504	#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR \| (5<<8))
505	#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR \| (6<<8))
506	#define SQLITE_IOERR_FSTAT (SQLITE_IOERR \| (7<<8))
507	#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR \| (8<<8))
508	#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR \| (9<<8))
509	#define SQLITE_IOERR_DELETE (SQLITE_IOERR \| (10<<8))
510	#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR \| (11<<8))
511	#define SQLITE_IOERR_NOMEM (SQLITE_IOERR \| (12<<8))
512	#define SQLITE_IOERR_ACCESS (SQLITE_IOERR \| (13<<8))
513	#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR \| (14<<8))
514	#define SQLITE_IOERR_LOCK (SQLITE_IOERR \| (15<<8))
515	#define SQLITE_IOERR_CLOSE (SQLITE_IOERR \| (16<<8))
516	#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR \| (17<<8))
517	#define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR \| (18<<8))
518	#define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR \| (19<<8))
519	#define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR \| (20<<8))
520	#define SQLITE_IOERR_SHMMAP (SQLITE_IOERR \| (21<<8))
521	#define SQLITE_IOERR_SEEK (SQLITE_IOERR \| (22<<8))
522	#define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR \| (23<<8))
523	#define SQLITE_IOERR_MMAP (SQLITE_IOERR \| (24<<8))
524	#define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR \| (25<<8))
525	#define SQLITE_IOERR_CONVPATH (SQLITE_IOERR \| (26<<8))
526	#define SQLITE_IOERR_VNODE (SQLITE_IOERR \| (27<<8))
527	#define SQLITE_IOERR_AUTH (SQLITE_IOERR \| (28<<8))
528	#define SQLITE_IOERR_BEGIN_ATOMIC (SQLITE_IOERR \| (29<<8))
529	#define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR \| (30<<8))
530	#define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR \| (31<<8))
531	#define SQLITE_IOERR_DATA (SQLITE_IOERR \| (32<<8))
532	#define SQLITE_IOERR_CORRUPTFS (SQLITE_IOERR \| (33<<8))
533	#define SQLITE_IOERR_IN_PAGE (SQLITE_IOERR \| (34<<8))
534	#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED \| (1<<8))
535	#define SQLITE_LOCKED_VTAB (SQLITE_LOCKED \| (2<<8))
536	#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY \| (1<<8))
537	#define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY \| (2<<8))
538	#define SQLITE_BUSY_TIMEOUT (SQLITE_BUSY \| (3<<8))
539	#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN \| (1<<8))
540	#define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN \| (2<<8))
541	#define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN \| (3<<8))
542	#define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN \| (4<<8))
543	#define SQLITE_CANTOPEN_DIRTYWAL (SQLITE_CANTOPEN \| (5<<8)) /* Not Used */
544	#define SQLITE_CANTOPEN_SYMLINK (SQLITE_CANTOPEN \| (6<<8))
545	#define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT \| (1<<8))
546	#define SQLITE_CORRUPT_SEQUENCE (SQLITE_CORRUPT \| (2<<8))
547	#define SQLITE_CORRUPT_INDEX (SQLITE_CORRUPT \| (3<<8))
548	#define SQLITE_READONLY_RECOVERY (SQLITE_READONLY \| (1<<8))
549	#define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY \| (2<<8))
550	#define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY \| (3<<8))
551	#define SQLITE_READONLY_DBMOVED (SQLITE_READONLY \| (4<<8))
552	#define SQLITE_READONLY_CANTINIT (SQLITE_READONLY \| (5<<8))
553	#define SQLITE_READONLY_DIRECTORY (SQLITE_READONLY \| (6<<8))
554	#define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT \| (2<<8))
555	#define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT \| (1<<8))
556	#define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT \| (2<<8))
557	#define SQLITE_CONSTRAINT_FOREIGNKEY (SQLITE_CONSTRAINT \| (3<<8))
558	#define SQLITE_CONSTRAINT_FUNCTION (SQLITE_CONSTRAINT \| (4<<8))
559	#define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT \| (5<<8))
560	#define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT \| (6<<8))
561	#define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT \| (7<<8))
562	#define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT \| (8<<8))
563	#define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT \| (9<<8))
564	#define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT \|(10<<8))
565	#define SQLITE_CONSTRAINT_PINNED (SQLITE_CONSTRAINT \|(11<<8))
566	#define SQLITE_CONSTRAINT_DATATYPE (SQLITE_CONSTRAINT \|(12<<8))
567	#define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE \| (1<<8))
568	#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE \| (2<<8))
569	#define SQLITE_NOTICE_RBU (SQLITE_NOTICE \| (3<<8))
570	#define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING \| (1<<8))
571	#define SQLITE_AUTH_USER (SQLITE_AUTH \| (1<<8))
572	#define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK \| (1<<8))
573	#define SQLITE_OK_SYMLINK (SQLITE_OK \| (2<<8)) /* internal use only */
574
575	/*
576	** CAPI3REF: Flags For File Open Operations
577	**
578	** These bit values are intended for use in the
579	** 3rd parameter to the [sqlite3_open_v2()] interface and
580	** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
581	**
582	** Only those flags marked as "Ok for sqlite3_open_v2()" may be
583	** used as the third argument to the [sqlite3_open_v2()] interface.
584	** The other flags have historically been ignored by sqlite3_open_v2(),
585	** though future versions of SQLite might change so that an error is
586	** raised if any of the disallowed bits are passed into sqlite3_open_v2().
587	** Applications should not depend on the historical behavior.
588	**
589	** Note in particular that passing the SQLITE_OPEN_EXCLUSIVE flag into
590	** [sqlite3_open_v2()] does not cause the underlying database file
591	** to be opened using O_EXCL. Passing SQLITE_OPEN_EXCLUSIVE into
592	** [sqlite3_open_v2()] has historically be a no-op and might become an
593	** error in future versions of SQLite.
594	*/
595	#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
596	#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
597	#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */
598	#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */
599	#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */
600	#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */
601	#define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */
602	#define SQLITE_OPEN_MEMORY 0x00000080 /* Ok for sqlite3_open_v2() */
603	#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */
604	#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */
605	#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */
606	#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */
607	#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */
608	#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */
609	#define SQLITE_OPEN_SUPER_JOURNAL 0x00004000 /* VFS only */
610	#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
611	#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
612	#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */
613	#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
614	#define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
615	#define SQLITE_OPEN_NOFOLLOW 0x01000000 /* Ok for sqlite3_open_v2() */
616	#define SQLITE_OPEN_EXRESCODE 0x02000000 /* Extended result codes */
617
618	/* Reserved: 0x00F00000 */
619	/* Legacy compatibility: */
620	#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */
621
622
623	/*
624	** CAPI3REF: Device Characteristics
625	**
626	** The xDeviceCharacteristics method of the [sqlite3_io_methods]
627	** object returns an integer which is a vector of these
628	** bit values expressing I/O characteristics of the mass storage
629	** device that holds the file that the [sqlite3_io_methods]
630	** refers to.
631	**
632	** The SQLITE_IOCAP_ATOMIC property means that all writes of
633	** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
634	** mean that writes of blocks that are nnn bytes in size and
635	** are aligned to an address which is an integer multiple of
636	** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
637	** that when data is appended to a file, the data is appended
638	** first then the size of the file is extended, never the other
639	** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
640	** information is written to disk in the same order as calls
641	** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
642	** after reboot following a crash or power loss, the only bytes in a
643	** file that were written at the application level might have changed
644	** and that adjacent bytes, even bytes within the same sector are
645	** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
646	** flag indicates that a file cannot be deleted when open. The
647	** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
648	** read-only media and cannot be changed even by processes with
649	** elevated privileges.
650	**
651	** The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying
652	** filesystem supports doing multiple write operations atomically when those
653	** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and
654	** [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].
655	**
656	** The SQLITE_IOCAP_SUBPAGE_READ property means that it is ok to read
657	** from the database file in amounts that are not a multiple of the
658	** page size and that do not begin at a page boundary. Without this
659	** property, SQLite is careful to only do full-page reads and write
660	** on aligned pages, with the one exception that it will do a sub-page
661	** read of the first page to access the database header.
662	*/
663	#define SQLITE_IOCAP_ATOMIC 0x00000001
664	#define SQLITE_IOCAP_ATOMIC512 0x00000002
665	#define SQLITE_IOCAP_ATOMIC1K 0x00000004
666	#define SQLITE_IOCAP_ATOMIC2K 0x00000008
667	#define SQLITE_IOCAP_ATOMIC4K 0x00000010
668	#define SQLITE_IOCAP_ATOMIC8K 0x00000020
669	#define SQLITE_IOCAP_ATOMIC16K 0x00000040
670	#define SQLITE_IOCAP_ATOMIC32K 0x00000080
671	#define SQLITE_IOCAP_ATOMIC64K 0x00000100
672	#define SQLITE_IOCAP_SAFE_APPEND 0x00000200
673	#define SQLITE_IOCAP_SEQUENTIAL 0x00000400
674	#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
675	#define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000
676	#define SQLITE_IOCAP_IMMUTABLE 0x00002000
677	#define SQLITE_IOCAP_BATCH_ATOMIC 0x00004000
678	#define SQLITE_IOCAP_SUBPAGE_READ 0x00008000
679
680	/*
681	** CAPI3REF: File Locking Levels
682	**
683	** SQLite uses one of these integer values as the second
684	** argument to calls it makes to the xLock() and xUnlock() methods
685	** of an [sqlite3_io_methods] object. These values are ordered from
686	** lest restrictive to most restrictive.
687	**
688	** The argument to xLock() is always SHARED or higher. The argument to
689	** xUnlock is either SHARED or NONE.
690	*/
691	#define SQLITE_LOCK_NONE 0 /* xUnlock() only */
692	#define SQLITE_LOCK_SHARED 1 /* xLock() or xUnlock() */
693	#define SQLITE_LOCK_RESERVED 2 /* xLock() only */
694	#define SQLITE_LOCK_PENDING 3 /* xLock() only */
695	#define SQLITE_LOCK_EXCLUSIVE 4 /* xLock() only */
696
697	/*
698	** CAPI3REF: Synchronization Type Flags
699	**
700	** When SQLite invokes the xSync() method of an
701	** [sqlite3_io_methods] object it uses a combination of
702	** these integer values as the second argument.
703	**
704	** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
705	** sync operation only needs to flush data to mass storage. Inode
706	** information need not be flushed. If the lower four bits of the flag
707	** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
708	** If the lower four bits equal SQLITE_SYNC_FULL, that means
709	** to use Mac OS X style fullsync instead of fsync().
710	**
711	** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
712	** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
713	** settings. The [synchronous pragma] determines when calls to the
714	** xSync VFS method occur and applies uniformly across all platforms.
715	** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
716	** energetic or rigorous or forceful the sync operations are and
717	** only make a difference on Mac OSX for the default SQLite code.
718	** (Third-party VFS implementations might also make the distinction
719	** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
720	** operating systems natively supported by SQLite, only Mac OSX
721	** cares about the difference.)
722	*/
723	#define SQLITE_SYNC_NORMAL 0x00002
724	#define SQLITE_SYNC_FULL 0x00003
725	#define SQLITE_SYNC_DATAONLY 0x00010
726
727	/*
728	** CAPI3REF: OS Interface Open File Handle
729	**
730	** An [sqlite3_file] object represents an open file in the
731	** [sqlite3_vfs \| OS interface layer]. Individual OS interface
732	** implementations will
733	** want to subclass this object by appending additional fields
734	** for their own use. The pMethods entry is a pointer to an
735	** [sqlite3_io_methods] object that defines methods for performing
736	** I/O operations on the open file.
737	*/
738	typedef struct sqlite3_file sqlite3_file;
739	struct sqlite3_file {
740	const struct sqlite3_io_methods pMethods; / Methods for an open file */
741	};
742
743	/*
744	** CAPI3REF: OS Interface File Virtual Methods Object
745	**
746	** Every file opened by the [sqlite3_vfs.xOpen] method populates an
747	** [sqlite3_file] object (or, more commonly, a subclass of the
748	** [sqlite3_file] object) with a pointer to an instance of this object.
749	** This object defines the methods used to perform various operations
750	** against the open file represented by the [sqlite3_file] object.
751	**
752	** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element
753	** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
754	** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed. The
755	** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
756	** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
757	** to NULL.
758	**
759	** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
760	** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
761	** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
762	** flag may be ORed in to indicate that only the data of the file
763	** and not its inode needs to be synced.
764	**
765	** The integer values to xLock() and xUnlock() are one of
766	** <ul>
767	** <li> [SQLITE_LOCK_NONE],
768	** <li> [SQLITE_LOCK_SHARED],
769	** <li> [SQLITE_LOCK_RESERVED],
770	** <li> [SQLITE_LOCK_PENDING], or
771	** <li> [SQLITE_LOCK_EXCLUSIVE].
772	** </ul>
773	** xLock() upgrades the database file lock. In other words, xLock() moves the
774	** database file lock in the direction NONE toward EXCLUSIVE. The argument to
775	** xLock() is always one of SHARED, RESERVED, PENDING, or EXCLUSIVE, never
776	** SQLITE_LOCK_NONE. If the database file lock is already at or above the
777	** requested lock, then the call to xLock() is a no-op.
778	** xUnlock() downgrades the database file lock to either SHARED or NONE.
779	** If the lock is already at or below the requested lock state, then the call
780	** to xUnlock() is a no-op.
781	** The xCheckReservedLock() method checks whether any database connection,
782	** either in this process or in some other process, is holding a RESERVED,
783	** PENDING, or EXCLUSIVE lock on the file. It returns, via its output
784	** pointer parameter, true if such a lock exists and false otherwise.
785	**
786	** The xFileControl() method is a generic interface that allows custom
787	** VFS implementations to directly control an open file using the
788	** [sqlite3_file_control()] interface. The second "op" argument is an
789	** integer opcode. The third argument is a generic pointer intended to
790	** point to a structure that may contain arguments or space in which to
791	** write return values. Potential uses for xFileControl() might be
792	** functions to enable blocking locks with timeouts, to change the
793	** locking strategy (for example to use dot-file locks), to inquire
794	** about the status of a lock, or to break stale locks. The SQLite
795	** core reserves all opcodes less than 100 for its own use.
796	** A [file control opcodes \| list of opcodes] less than 100 is available.
797	** Applications that define a custom xFileControl method should use opcodes
798	** greater than 100 to avoid conflicts. VFS implementations should
799	** return [SQLITE_NOTFOUND] for file control opcodes that they do not
800	** recognize.
801	**
802	** The xSectorSize() method returns the sector size of the
803	** device that underlies the file. The sector size is the
804	** minimum write that can be performed without disturbing
805	** other bytes in the file. The xDeviceCharacteristics()
806	** method returns a bit vector describing behaviors of the
807	** underlying device:
808	**
809	** <ul>
810	** <li> [SQLITE_IOCAP_ATOMIC]
811	** <li> [SQLITE_IOCAP_ATOMIC512]
812	** <li> [SQLITE_IOCAP_ATOMIC1K]
813	** <li> [SQLITE_IOCAP_ATOMIC2K]
814	** <li> [SQLITE_IOCAP_ATOMIC4K]
815	** <li> [SQLITE_IOCAP_ATOMIC8K]
816	** <li> [SQLITE_IOCAP_ATOMIC16K]
817	** <li> [SQLITE_IOCAP_ATOMIC32K]
818	** <li> [SQLITE_IOCAP_ATOMIC64K]
819	** <li> [SQLITE_IOCAP_SAFE_APPEND]
820	** <li> [SQLITE_IOCAP_SEQUENTIAL]
821	** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN]
822	** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE]
823	** <li> [SQLITE_IOCAP_IMMUTABLE]
824	** <li> [SQLITE_IOCAP_BATCH_ATOMIC]
825	** <li> [SQLITE_IOCAP_SUBPAGE_READ]
826	** </ul>
827	**
828	** The SQLITE_IOCAP_ATOMIC property means that all writes of
829	** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
830	** mean that writes of blocks that are nnn bytes in size and
831	** are aligned to an address which is an integer multiple of
832	** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
833	** that when data is appended to a file, the data is appended
834	** first then the size of the file is extended, never the other
835	** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
836	** information is written to disk in the same order as calls
837	** to xWrite().
838	**
839	** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
840	** in the unread portions of the buffer with zeros. A VFS that
841	** fails to zero-fill short reads might seem to work. However,
842	** failure to zero-fill short reads will eventually lead to
843	** database corruption.
844	*/
845	typedef struct sqlite3_io_methods sqlite3_io_methods;
846	struct sqlite3_io_methods {
847	int iVersion;
848	int (xClose)(sqlite3_file);
849	int (xRead)(sqlite3_file, void*, int iAmt, sqlite3_int64 iOfst);
850	int (xWrite)(sqlite3_file, const void*, int iAmt, sqlite3_int64 iOfst);
851	int (xTruncate)(sqlite3_file, sqlite3_int64 size);
852	int (xSync)(sqlite3_file, int flags);
853	int (xFileSize)(sqlite3_file, sqlite3_int64 *pSize);
854	int (xLock)(sqlite3_file, int);
855	int (xUnlock)(sqlite3_file, int);
856	int (xCheckReservedLock)(sqlite3_file, int *pResOut);
857	int (xFileControl)(sqlite3_file, int op, void *pArg);
858	int (xSectorSize)(sqlite3_file);
859	int (xDeviceCharacteristics)(sqlite3_file);
860	/* Methods above are valid for version 1 */
861	int (xShmMap)(sqlite3_file, int iPg, int pgsz, int, void volatile**);
862	int (xShmLock)(sqlite3_file, int offset, int n, int flags);
863	void (xShmBarrier)(sqlite3_file);
864	int (xShmUnmap)(sqlite3_file, int deleteFlag);
865	/* Methods above are valid for version 2 */
866	int (xFetch)(sqlite3_file, sqlite3_int64 iOfst, int iAmt, void **pp);
867	int (xUnfetch)(sqlite3_file, sqlite3_int64 iOfst, void *p);
868	/* Methods above are valid for version 3 */
869	/* Additional methods may be added in future releases */
870	};
871
872	/*
873	** CAPI3REF: Standard File Control Opcodes
874	** KEYWORDS: {file control opcodes} {file control opcode}
875	**
876	** These integer constants are opcodes for the xFileControl method
877	** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
878	** interface.
879	**
880	** <ul>
881	** <li>[[SQLITE_FCNTL_LOCKSTATE]]
882	** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
883	** opcode causes the xFileControl method to write the current state of
884	** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
885	** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
886	** into an integer that the pArg argument points to.
887	** This capability is only available if SQLite is compiled with [SQLITE_DEBUG].
888	**
889	** <li>[[SQLITE_FCNTL_SIZE_HINT]]
890	** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
891	** layer a hint of how large the database file will grow to be during the
892	** current transaction. This hint is not guaranteed to be accurate but it
893	** is often close. The underlying VFS might choose to preallocate database
894	** file space based on this hint in order to help writes to the database
895	** file run faster.
896	**
897	** <li>[[SQLITE_FCNTL_SIZE_LIMIT]]
898	** The [SQLITE_FCNTL_SIZE_LIMIT] opcode is used by in-memory VFS that
899	** implements [sqlite3_deserialize()] to set an upper bound on the size
900	** of the in-memory database. The argument is a pointer to a [sqlite3_int64].
901	** If the integer pointed to is negative, then it is filled in with the
902	** current limit. Otherwise the limit is set to the larger of the value
903	** of the integer pointed to and the current database size. The integer
904	** pointed to is set to the new limit.
905	**
906	** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]
907	** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
908	** extends and truncates the database file in chunks of a size specified
909	** by the user. The fourth argument to [sqlite3_file_control()] should
910	** point to an integer (type int) containing the new chunk-size to use
911	** for the nominated database. Allocating database file space in large
912	** chunks (say 1MB at a time), may reduce file-system fragmentation and
913	** improve performance on some systems.
914	**
915	** <li>[[SQLITE_FCNTL_FILE_POINTER]]
916	** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
917	** to the [sqlite3_file] object associated with a particular database
918	** connection. See also [SQLITE_FCNTL_JOURNAL_POINTER].
919	**
920	** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]
921	** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
922	** to the [sqlite3_file] object associated with the journal file (either
923	** the [rollback journal] or the [write-ahead log]) for a particular database
924	** connection. See also [SQLITE_FCNTL_FILE_POINTER].
925	**
926	** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
927	** No longer in use.
928	**
929	** <li>[[SQLITE_FCNTL_SYNC]]
930	** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
931	** sent to the VFS immediately before the xSync method is invoked on a
932	** database file descriptor. Or, if the xSync method is not invoked
933	** because the user has configured SQLite with
934	** [PRAGMA synchronous \| PRAGMA synchronous=OFF] it is invoked in place
935	** of the xSync method. In most cases, the pointer argument passed with
936	** this file-control is NULL. However, if the database file is being synced
937	** as part of a multi-database commit, the argument points to a nul-terminated
938	** string containing the transactions super-journal file name. VFSes that
939	** do not need this signal should silently ignore this opcode. Applications
940	** should not call [sqlite3_file_control()] with this opcode as doing so may
941	** disrupt the operation of the specialized VFSes that do require it.
942	**
943	** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]
944	** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
945	** and sent to the VFS after a transaction has been committed immediately
946	** but before the database is unlocked. VFSes that do not need this signal
947	** should silently ignore this opcode. Applications should not call
948	** [sqlite3_file_control()] with this opcode as doing so may disrupt the
949	** operation of the specialized VFSes that do require it.
950	**
951	** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
952	** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
953	** retry counts and intervals for certain disk I/O operations for the
954	** windows [VFS] in order to provide robustness in the presence of
955	** anti-virus programs. By default, the windows VFS will retry file read,
956	** file write, and file delete operations up to 10 times, with a delay
957	** of 25 milliseconds before the first retry and with the delay increasing
958	** by an additional 25 milliseconds with each subsequent retry. This
959	** opcode allows these two values (10 retries and 25 milliseconds of delay)
960	** to be adjusted. The values are changed for all database connections
961	** within the same process. The argument is a pointer to an array of two
962	** integers where the first integer is the new retry count and the second
963	** integer is the delay. If either integer is negative, then the setting
964	** is not changed but instead the prior value of that setting is written
965	** into the array entry, allowing the current retry settings to be
966	** interrogated. The zDbName parameter is ignored.
967	**
968	** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
969	** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
970	** persistent [WAL \| Write Ahead Log] setting. By default, the auxiliary
971	** write ahead log ([WAL file]) and shared memory
972	** files used for transaction control
973	** are automatically deleted when the latest connection to the database
974	** closes. Setting persistent WAL mode causes those files to persist after
975	** close. Persisting the files is useful when other processes that do not
976	** have write permission on the directory containing the database file want
977	** to read the database file, as the WAL and shared memory files must exist
978	** in order for the database to be readable. The fourth parameter to
979	** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
980	** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
981	** WAL mode. If the integer is -1, then it is overwritten with the current
982	** WAL persistence setting.
983	**
984	** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]
985	** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
986	** persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
987	** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the
988	** xDeviceCharacteristics methods. The fourth parameter to
989	** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
990	** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
991	** mode. If the integer is -1, then it is overwritten with the current
992	** zero-damage mode setting.
993	**
994	** <li>[[SQLITE_FCNTL_OVERWRITE]]
995	** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
996	** a write transaction to indicate that, unless it is rolled back for some
997	** reason, the entire database file will be overwritten by the current
998	** transaction. This is used by VACUUM operations.
999	**
1000	** <li>[[SQLITE_FCNTL_VFSNAME]]
1001	** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
1002	** all [VFSes] in the VFS stack. The names are of all VFS shims and the
1003	** final bottom-level VFS are written into memory obtained from
1004	** [sqlite3_malloc()] and the result is stored in the char* variable
1005	** that the fourth parameter of [sqlite3_file_control()] points to.
1006	** The caller is responsible for freeing the memory when done. As with
1007	** all file-control actions, there is no guarantee that this will actually
1008	** do anything. Callers should initialize the char* variable to a NULL
1009	** pointer in case this file-control is not implemented. This file-control
1010	** is intended for diagnostic use only.
1011	**
1012	** <li>[[SQLITE_FCNTL_VFS_POINTER]]
1013	** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
1014	** [VFSes] currently in use. ^(The argument X in
1015	** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
1016	of type "[sqlite3_vfs] ". This opcodes will set *X
1017	** to a pointer to the top-level VFS.)^
1018	** ^When there are multiple VFS shims in the stack, this opcode finds the
1019	** upper-most shim only.
1020	**
1021	** <li>[[SQLITE_FCNTL_PRAGMA]]
1022	** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
1023	** file control is sent to the open [sqlite3_file] object corresponding
1024	** to the database file to which the pragma statement refers. ^The argument
1025	** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
1026	pointers to strings (char) in which the second element of the array
1027	** is the name of the pragma and the third element is the argument to the
1028	** pragma or NULL if the pragma has no argument. ^The handler for an
1029	** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element
1030	of the char argument point to a string obtained from [sqlite3_mprintf()]
1031	** or the equivalent and that string will become the result of the pragma or
1032	** the error message if the pragma fails. ^If the
1033	** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal
1034	** [PRAGMA] processing continues. ^If the [SQLITE_FCNTL_PRAGMA]
1035	** file control returns [SQLITE_OK], then the parser assumes that the
1036	** VFS has handled the PRAGMA itself and the parser generates a no-op
1037	** prepared statement if result string is NULL, or that returns a copy
1038	** of the result string if the string is non-NULL.
1039	** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
1040	** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
1041	** that the VFS encountered an error while handling the [PRAGMA] and the
1042	** compilation of the PRAGMA fails with an error. ^The [SQLITE_FCNTL_PRAGMA]
1043	** file control occurs at the beginning of pragma statement analysis and so
1044	** it is able to override built-in [PRAGMA] statements.
1045	**
1046	** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
1047	** ^The [SQLITE_FCNTL_BUSYHANDLER]
1048	** file-control may be invoked by SQLite on the database file handle
1049	** shortly after it is opened in order to provide a custom VFS with access
1050	to the connection's busy-handler callback. The argument is of type (void)
1051	** - an array of two (void ) values. The first (void ) actually points
1052	** to a function of type (int ()(void )). In order to invoke the connection's
1053	** busy-handler, this function should be invoked with the second (void *) in
1054	** the array as the only argument. If it returns non-zero, then the operation
1055	** should be retried. If it returns zero, the custom VFS should abandon the
1056	** current operation.
1057	**
1058	** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
1059	** ^Applications can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
1060	** to have SQLite generate a
1061	** temporary filename using the same algorithm that is followed to generate
1062	** temporary filenames for TEMP tables and other internal uses. The
1063	argument should be a char which will be filled with the filename
1064	** written into memory obtained from [sqlite3_malloc()]. The caller should
1065	** invoke [sqlite3_free()] on the result to avoid a memory leak.
1066	**
1067	** <li>[[SQLITE_FCNTL_MMAP_SIZE]]
1068	** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
1069	** maximum number of bytes that will be used for memory-mapped I/O.
1070	** The argument is a pointer to a value of type sqlite3_int64 that
1071	** is an advisory maximum number of bytes in the file to memory map. The
1072	** pointer is overwritten with the old value. The limit is not changed if
1073	** the value originally pointed to is negative, and so the current limit
1074	** can be queried by passing in a pointer to a negative number. This
1075	** file-control is used internally to implement [PRAGMA mmap_size].
1076	**
1077	** <li>[[SQLITE_FCNTL_TRACE]]
1078	** The [SQLITE_FCNTL_TRACE] file control provides advisory information
1079	** to the VFS about what the higher layers of the SQLite stack are doing.
1080	** This file control is used by some VFS activity tracing [shims].
1081	** The argument is a zero-terminated string. Higher layers in the
1082	** SQLite stack may generate instances of this file control if
1083	** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
1084	**
1085	** <li>[[SQLITE_FCNTL_HAS_MOVED]]
1086	** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
1087	** pointer to an integer and it writes a boolean into that integer depending
1088	** on whether or not the file has been renamed, moved, or deleted since it
1089	** was first opened.
1090	**
1091	** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]]
1092	** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the
1093	** underlying native file handle associated with a file handle. This file
1094	** control interprets its argument as a pointer to a native file handle and
1095	** writes the resulting value there.
1096	**
1097	** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
1098	** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This
1099	** opcode causes the xFileControl method to swap the file handle with the one
1100	** pointed to by the pArg argument. This capability is used during testing
1101	** and only needs to be supported when SQLITE_TEST is defined.
1102	**
1103	** <li>[[SQLITE_FCNTL_NULL_IO]]
1104	** The [SQLITE_FCNTL_NULL_IO] opcode sets the low-level file descriptor
1105	** or file handle for the [sqlite3_file] object such that it will no longer
1106	** read or write to the database file.
1107	**
1108	** <li>[[SQLITE_FCNTL_WAL_BLOCK]]
1109	** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
1110	** be advantageous to block on the next WAL lock if the lock is not immediately
1111	** available. The WAL subsystem issues this signal during rare
1112	** circumstances in order to fix a problem with priority inversion.
1113	** Applications should <em>not</em> use this file-control.
1114	**
1115	** <li>[[SQLITE_FCNTL_ZIPVFS]]
1116	** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
1117	** VFS should return SQLITE_NOTFOUND for this opcode.
1118	**
1119	** <li>[[SQLITE_FCNTL_RBU]]
1120	** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
1121	** the RBU extension only. All other VFS should return SQLITE_NOTFOUND for
1122	** this opcode.
1123	**
1124	** <li>[[SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]]
1125	** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, then
1126	** the file descriptor is placed in "batch write mode", which
1127	** means all subsequent write operations will be deferred and done
1128	** atomically at the next [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]. Systems
1129	** that do not support batch atomic writes will return SQLITE_NOTFOUND.
1130	** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
1131	** the closing [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] or
1132	** [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE], SQLite will make
1133	** no VFS interface calls on the same [sqlite3_file] file descriptor
1134	** except for calls to the xWrite method and the xFileControl method
1135	** with [SQLITE_FCNTL_SIZE_HINT].
1136	**
1137	** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]
1138	** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write
1139	** operations since the previous successful call to
1140	** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.
1141	** This file control returns [SQLITE_OK] if and only if the writes were
1142	** all performed successfully and have been committed to persistent storage.
1143	** ^Regardless of whether or not it is successful, this file control takes
1144	** the file descriptor out of batch write mode so that all subsequent
1145	** write operations are independent.
1146	** ^SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
1147	** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
1148	**
1149	** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]
1150	** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write
1151	** operations since the previous successful call to
1152	** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.
1153	** ^This file control takes the file descriptor out of batch write mode
1154	** so that all subsequent write operations are independent.
1155	** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
1156	** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
1157	**
1158	** <li>[[SQLITE_FCNTL_LOCK_TIMEOUT]]
1159	** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode is used to configure a VFS
1160	** to block for up to M milliseconds before failing when attempting to
1161	** obtain a file lock using the xLock or xShmLock methods of the VFS.
1162	** The parameter is a pointer to a 32-bit signed integer that contains
1163	** the value that M is to be set to. Before returning, the 32-bit signed
1164	** integer is overwritten with the previous value of M.
1165	**
1166	** <li>[[SQLITE_FCNTL_BLOCK_ON_CONNECT]]
1167	** The [SQLITE_FCNTL_BLOCK_ON_CONNECT] opcode is used to configure the
1168	** VFS to block when taking a SHARED lock to connect to a wal mode database.
1169	** This is used to implement the functionality associated with
1170	** SQLITE_SETLK_BLOCK_ON_CONNECT.
1171	**
1172	** <li>[[SQLITE_FCNTL_DATA_VERSION]]
1173	** The [SQLITE_FCNTL_DATA_VERSION] opcode is used to detect changes to
1174	** a database file. The argument is a pointer to a 32-bit unsigned integer.
1175	** The "data version" for the pager is written into the pointer. The
1176	** "data version" changes whenever any change occurs to the corresponding
1177	** database file, either through SQL statements on the same database
1178	** connection or through transactions committed by separate database
1179	** connections possibly in other processes. The [sqlite3_total_changes()]
1180	** interface can be used to find if any database on the connection has changed,
1181	** but that interface responds to changes on TEMP as well as MAIN and does
1182	** not provide a mechanism to detect changes to MAIN only. Also, the
1183	** [sqlite3_total_changes()] interface responds to internal changes only and
1184	** omits changes made by other database connections. The
1185	** [PRAGMA data_version] command provides a mechanism to detect changes to
1186	** a single attached database that occur due to other database connections,
1187	** but omits changes implemented by the database connection on which it is
1188	** called. This file control is the only mechanism to detect changes that
1189	** happen either internally or externally and that are associated with
1190	** a particular attached database.
1191	**
1192	** <li>[[SQLITE_FCNTL_CKPT_START]]
1193	** The [SQLITE_FCNTL_CKPT_START] opcode is invoked from within a checkpoint
1194	** in wal mode before the client starts to copy pages from the wal
1195	** file to the database file.
1196	**
1197	** <li>[[SQLITE_FCNTL_CKPT_DONE]]
1198	** The [SQLITE_FCNTL_CKPT_DONE] opcode is invoked from within a checkpoint
1199	** in wal mode after the client has finished copying pages from the wal
1200	** file to the database file, but before the *-shm file is updated to
1201	** record the fact that the pages have been checkpointed.
1202	**
1203	** <li>[[SQLITE_FCNTL_EXTERNAL_READER]]
1204	** The EXPERIMENTAL [SQLITE_FCNTL_EXTERNAL_READER] opcode is used to detect
1205	** whether or not there is a database client in another process with a wal-mode
1206	** transaction open on the database or not. It is only available on unix.The
1207	** (void*) argument passed with this file-control should be a pointer to a
1208	** value of type (int). The integer value is set to 1 if the database is a wal
1209	** mode database and there exists at least one client in another process that
1210	** currently has an SQL transaction open on the database. It is set to 0 if
1211	** the database is not a wal-mode db, or if there is no such connection in any
1212	** other process. This opcode cannot be used to detect transactions opened
1213	** by clients within the current process, only within other processes.
1214	**
1215	** <li>[[SQLITE_FCNTL_CKSM_FILE]]
1216	** The [SQLITE_FCNTL_CKSM_FILE] opcode is for use internally by the
1217	** [checksum VFS shim] only.
1218	**
1219	** <li>[[SQLITE_FCNTL_RESET_CACHE]]
1220	** If there is currently no transaction open on the database, and the
1221	** database is not a temp db, then the [SQLITE_FCNTL_RESET_CACHE] file-control
1222	** purges the contents of the in-memory page cache. If there is an open
1223	** transaction, or if the db is a temp-db, this opcode is a no-op, not an error.
1224	** </ul>
1225	*/
1226	#define SQLITE_FCNTL_LOCKSTATE 1
1227	#define SQLITE_FCNTL_GET_LOCKPROXYFILE 2
1228	#define SQLITE_FCNTL_SET_LOCKPROXYFILE 3
1229	#define SQLITE_FCNTL_LAST_ERRNO 4
1230	#define SQLITE_FCNTL_SIZE_HINT 5
1231	#define SQLITE_FCNTL_CHUNK_SIZE 6
1232	#define SQLITE_FCNTL_FILE_POINTER 7
1233	#define SQLITE_FCNTL_SYNC_OMITTED 8
1234	#define SQLITE_FCNTL_WIN32_AV_RETRY 9
1235	#define SQLITE_FCNTL_PERSIST_WAL 10
1236	#define SQLITE_FCNTL_OVERWRITE 11
1237	#define SQLITE_FCNTL_VFSNAME 12
1238	#define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13
1239	#define SQLITE_FCNTL_PRAGMA 14
1240	#define SQLITE_FCNTL_BUSYHANDLER 15
1241	#define SQLITE_FCNTL_TEMPFILENAME 16
1242	#define SQLITE_FCNTL_MMAP_SIZE 18
1243	#define SQLITE_FCNTL_TRACE 19
1244	#define SQLITE_FCNTL_HAS_MOVED 20
1245	#define SQLITE_FCNTL_SYNC 21
1246	#define SQLITE_FCNTL_COMMIT_PHASETWO 22
1247	#define SQLITE_FCNTL_WIN32_SET_HANDLE 23
1248	#define SQLITE_FCNTL_WAL_BLOCK 24
1249	#define SQLITE_FCNTL_ZIPVFS 25
1250	#define SQLITE_FCNTL_RBU 26
1251	#define SQLITE_FCNTL_VFS_POINTER 27
1252	#define SQLITE_FCNTL_JOURNAL_POINTER 28
1253	#define SQLITE_FCNTL_WIN32_GET_HANDLE 29
1254	#define SQLITE_FCNTL_PDB 30
1255	#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31
1256	#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32
1257	#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33
1258	#define SQLITE_FCNTL_LOCK_TIMEOUT 34
1259	#define SQLITE_FCNTL_DATA_VERSION 35
1260	#define SQLITE_FCNTL_SIZE_LIMIT 36
1261	#define SQLITE_FCNTL_CKPT_DONE 37
1262	#define SQLITE_FCNTL_RESERVE_BYTES 38
1263	#define SQLITE_FCNTL_CKPT_START 39
1264	#define SQLITE_FCNTL_EXTERNAL_READER 40
1265	#define SQLITE_FCNTL_CKSM_FILE 41
1266	#define SQLITE_FCNTL_RESET_CACHE 42
1267	#define SQLITE_FCNTL_NULL_IO 43
1268	#define SQLITE_FCNTL_BLOCK_ON_CONNECT 44
1269
1270	/* deprecated names */
1271	#define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE
1272	#define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE
1273	#define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO
1274
1275
1276	/*
1277	** CAPI3REF: Mutex Handle
1278	**
1279	** The mutex module within SQLite defines [sqlite3_mutex] to be an
1280	** abstract type for a mutex object. The SQLite core never looks
1281	** at the internal representation of an [sqlite3_mutex]. It only
1282	** deals with pointers to the [sqlite3_mutex] object.
1283	**
1284	** Mutexes are created using [sqlite3_mutex_alloc()].
1285	*/
1286	typedef struct sqlite3_mutex sqlite3_mutex;
1287
1288	/*
1289	** CAPI3REF: Loadable Extension Thunk
1290	**
1291	** A pointer to the opaque sqlite3_api_routines structure is passed as
1292	** the third parameter to entry points of [loadable extensions]. This
1293	** structure must be typedefed in order to work around compiler warnings
1294	** on some platforms.
1295	*/
1296	typedef struct sqlite3_api_routines sqlite3_api_routines;
1297
1298	/*
1299	** CAPI3REF: File Name
1300	**
1301	** Type [sqlite3_filename] is used by SQLite to pass filenames to the
1302	** xOpen method of a [VFS]. It may be cast to (const char*) and treated
1303	** as a normal, nul-terminated, UTF-8 buffer containing the filename, but
1304	** may also be passed to special APIs such as:
1305	**
1306	** <ul>
1307	** <li> sqlite3_filename_database()
1308	** <li> sqlite3_filename_journal()
1309	** <li> sqlite3_filename_wal()
1310	** <li> sqlite3_uri_parameter()
1311	** <li> sqlite3_uri_boolean()
1312	** <li> sqlite3_uri_int64()
1313	** <li> sqlite3_uri_key()
1314	** </ul>
1315	*/
1316	typedef const char *sqlite3_filename;
1317
1318	/*
1319	** CAPI3REF: OS Interface Object
1320	**
1321	** An instance of the sqlite3_vfs object defines the interface between
1322	** the SQLite core and the underlying operating system. The "vfs"
1323	** in the name of the object stands for "virtual file system". See
1324	** the [VFS \| VFS documentation] for further information.
1325	**
1326	** The VFS interface is sometimes extended by adding new methods onto
1327	** the end. Each time such an extension occurs, the iVersion field
1328	** is incremented. The iVersion value started out as 1 in
1329	** SQLite [version 3.5.0] on [dateof:3.5.0], then increased to 2
1330	** with SQLite [version 3.7.0] on [dateof:3.7.0], and then increased
1331	** to 3 with SQLite [version 3.7.6] on [dateof:3.7.6]. Additional fields
1332	** may be appended to the sqlite3_vfs object and the iVersion value
1333	** may increase again in future versions of SQLite.
1334	** Note that due to an oversight, the structure
1335	** of the sqlite3_vfs object changed in the transition from
1336	** SQLite [version 3.5.9] to [version 3.6.0] on [dateof:3.6.0]
1337	** and yet the iVersion field was not increased.
1338	**
1339	** The szOsFile field is the size of the subclassed [sqlite3_file]
1340	** structure used by this VFS. mxPathname is the maximum length of
1341	** a pathname in this VFS.
1342	**
1343	** Registered sqlite3_vfs objects are kept on a linked list formed by
1344	** the pNext pointer. The [sqlite3_vfs_register()]
1345	** and [sqlite3_vfs_unregister()] interfaces manage this list
1346	** in a thread-safe way. The [sqlite3_vfs_find()] interface
1347	** searches the list. Neither the application code nor the VFS
1348	** implementation should use the pNext pointer.
1349	**
1350	** The pNext field is the only field in the sqlite3_vfs
1351	** structure that SQLite will ever modify. SQLite will only access
1352	** or modify this field while holding a particular static mutex.
1353	** The application should never modify anything within the sqlite3_vfs
1354	** object once the object has been registered.
1355	**
1356	** The zName field holds the name of the VFS module. The name must
1357	** be unique across all VFS modules.
1358	**
1359	** [[sqlite3_vfs.xOpen]]
1360	** ^SQLite guarantees that the zFilename parameter to xOpen
1361	** is either a NULL pointer or string obtained
1362	** from xFullPathname() with an optional suffix added.
1363	** ^If a suffix is added to the zFilename parameter, it will
1364	** consist of a single "-" character followed by no more than
1365	** 11 alphanumeric and/or "-" characters.
1366	** ^SQLite further guarantees that
1367	** the string will be valid and unchanged until xClose() is
1368	** called. Because of the previous sentence,
1369	** the [sqlite3_file] can safely store a pointer to the
1370	** filename if it needs to remember the filename for some reason.
1371	** If the zFilename parameter to xOpen is a NULL pointer then xOpen
1372	** must invent its own temporary name for the file. ^Whenever the
1373	** xFilename parameter is NULL it will also be the case that the
1374	** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
1375	**
1376	** The flags argument to xOpen() includes all bits set in
1377	** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
1378	** or [sqlite3_open16()] is used, then flags includes at least
1379	** [SQLITE_OPEN_READWRITE] \| [SQLITE_OPEN_CREATE].
1380	** If xOpen() opens a file read-only then it sets *pOutFlags to
1381	** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set.
1382	**
1383	** ^(SQLite will also add one of the following flags to the xOpen()
1384	** call, depending on the object being opened:
1385	**
1386	** <ul>
1387	** <li> [SQLITE_OPEN_MAIN_DB]
1388	** <li> [SQLITE_OPEN_MAIN_JOURNAL]
1389	** <li> [SQLITE_OPEN_TEMP_DB]
1390	** <li> [SQLITE_OPEN_TEMP_JOURNAL]
1391	** <li> [SQLITE_OPEN_TRANSIENT_DB]
1392	** <li> [SQLITE_OPEN_SUBJOURNAL]
1393	** <li> [SQLITE_OPEN_SUPER_JOURNAL]
1394	** <li> [SQLITE_OPEN_WAL]
1395	** </ul>)^
1396	**
1397	** The file I/O implementation can use the object type flags to
1398	** change the way it deals with files. For example, an application
1399	** that does not care about crash recovery or rollback might make
1400	** the open of a journal file a no-op. Writes to this journal would
1401	** also be no-ops, and any attempt to read the journal would return
1402	** SQLITE_IOERR. Or the implementation might recognize that a database
1403	** file will be doing page-aligned sector reads and writes in a random
1404	** order and set up its I/O subsystem accordingly.
1405	**
1406	** SQLite might also add one of the following flags to the xOpen method:
1407	**
1408	** <ul>
1409	** <li> [SQLITE_OPEN_DELETEONCLOSE]
1410	** <li> [SQLITE_OPEN_EXCLUSIVE]
1411	** </ul>
1412	**
1413	** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
1414	** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE]
1415	** will be set for TEMP databases and their journals, transient
1416	** databases, and subjournals.
1417	**
1418	** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
1419	** with the [SQLITE_OPEN_CREATE] flag, which are both directly
1420	** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
1421	** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
1422	** SQLITE_OPEN_CREATE, is used to indicate that file should always
1423	** be created, and that it is an error if it already exists.
1424	** It is <i>not</i> used to indicate the file should be opened
1425	** for exclusive access.
1426	**
1427	** ^At least szOsFile bytes of memory are allocated by SQLite
1428	** to hold the [sqlite3_file] structure passed as the third
1429	** argument to xOpen. The xOpen method does not have to
1430	** allocate the structure; it should just fill it in. Note that
1431	** the xOpen method must set the sqlite3_file.pMethods to either
1432	** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
1433	** this even if the open fails. SQLite expects that the sqlite3_file.pMethods
1434	** element will be valid after xOpen returns regardless of the success
1435	** or failure of the xOpen call.
1436	**
1437	** [[sqlite3_vfs.xAccess]]
1438	** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
1439	** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
1440	** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
1441	** to test whether a file is at least readable. The SQLITE_ACCESS_READ
1442	** flag is never actually used and is not implemented in the built-in
1443	** VFSes of SQLite. The file is named by the second argument and can be a
1444	** directory. The xAccess method returns [SQLITE_OK] on success or some
1445	** non-zero error code if there is an I/O error or if the name of
1446	** the file given in the second argument is illegal. If SQLITE_OK
1447	** is returned, then non-zero or zero is written into *pResOut to indicate
1448	** whether or not the file is accessible.
1449	**
1450	** ^SQLite will always allocate at least mxPathname+1 bytes for the
1451	** output buffer xFullPathname. The exact size of the output buffer
1452	** is also passed as a parameter to both methods. If the output buffer
1453	** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
1454	** handled as a fatal error by SQLite, vfs implementations should endeavor
1455	** to prevent this by setting mxPathname to a sufficiently large value.
1456	**
1457	** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
1458	** interfaces are not strictly a part of the filesystem, but they are
1459	** included in the VFS structure for completeness.
1460	** The xRandomness() function attempts to return nBytes bytes
1461	** of good-quality randomness into zOut. The return value is
1462	** the actual number of bytes of randomness obtained.
1463	** The xSleep() method causes the calling thread to sleep for at
1464	** least the number of microseconds given. ^The xCurrentTime()
1465	** method returns a Julian Day Number for the current date and time as
1466	** a floating point value.
1467	** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
1468	** Day Number multiplied by 86400000 (the number of milliseconds in
1469	** a 24-hour day).
1470	** ^SQLite will use the xCurrentTimeInt64() method to get the current
1471	** date and time if that method is available (if iVersion is 2 or
1472	** greater and the function pointer is not NULL) and will fall back
1473	** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
1474	**
1475	** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
1476	** are not used by the SQLite core. These optional interfaces are provided
1477	** by some VFSes to facilitate testing of the VFS code. By overriding
1478	** system calls with functions under its control, a test program can
1479	** simulate faults and error conditions that would otherwise be difficult
1480	** or impossible to induce. The set of system calls that can be overridden
1481	** varies from one VFS to another, and from one version of the same VFS to the
1482	** next. Applications that use these interfaces must be prepared for any
1483	** or all of these interfaces to be NULL or for their behavior to change
1484	** from one release to the next. Applications must not attempt to access
1485	** any of these methods if the iVersion of the VFS is less than 3.
1486	*/
1487	typedef struct sqlite3_vfs sqlite3_vfs;
1488	typedef void (*sqlite3_syscall_ptr)(void);
1489	struct sqlite3_vfs {
1490	int iVersion; /* Structure version number (currently 3) */
1491	int szOsFile; /* Size of subclassed sqlite3_file */
1492	int mxPathname; /* Maximum file pathname length */
1493	sqlite3_vfs pNext; / Next registered VFS */
1494	const char zName; / Name of this virtual file system */
1495	void pAppData; / Pointer to application-specific data */
1496	int (xOpen)(sqlite3_vfs, sqlite3_filename zName, sqlite3_file*,
1497	int flags, int *pOutFlags);
1498	int (xDelete)(sqlite3_vfs, const char *zName, int syncDir);
1499	int (xAccess)(sqlite3_vfs, const char zName, int flags, int pResOut);
1500	int (xFullPathname)(sqlite3_vfs, const char zName, int nOut, char zOut);
1501	void (xDlOpen)(sqlite3_vfs, const char zFilename);
1502	void (xDlError)(sqlite3_vfs, int nByte, char *zErrMsg);
1503	void ((xDlSym)(sqlite3_vfs,void, const char *zSymbol))(void);
1504	void (xDlClose)(sqlite3_vfs, void*);
1505	int (xRandomness)(sqlite3_vfs, int nByte, char *zOut);
1506	int (xSleep)(sqlite3_vfs, int microseconds);
1507	int (xCurrentTime)(sqlite3_vfs, double*);
1508	int (xGetLastError)(sqlite3_vfs, int, char *);
1509	/*
1510	** The methods above are in version 1 of the sqlite_vfs object
1511	** definition. Those that follow are added in version 2 or later
1512	*/
1513	int (xCurrentTimeInt64)(sqlite3_vfs, sqlite3_int64*);
1514	/*
1515	** The methods above are in versions 1 and 2 of the sqlite_vfs object.
1516	** Those below are for version 3 and greater.
1517	*/
1518	int (xSetSystemCall)(sqlite3_vfs, const char *zName, sqlite3_syscall_ptr);
1519	sqlite3_syscall_ptr (xGetSystemCall)(sqlite3_vfs, const char *zName);
1520	const char (xNextSystemCall)(sqlite3_vfs, const char zName);
1521	/*
1522	** The methods above are in versions 1 through 3 of the sqlite_vfs object.
1523	** New fields may be appended in future versions. The iVersion
1524	** value will increment whenever this happens.
1525	*/
1526	};
1527
1528	/*
1529	** CAPI3REF: Flags for the xAccess VFS method
1530	**
1531	** These integer constants can be used as the third parameter to
1532	** the xAccess method of an [sqlite3_vfs] object. They determine
1533	** what kind of permissions the xAccess method is looking for.
1534	** With SQLITE_ACCESS_EXISTS, the xAccess method
1535	** simply checks whether the file exists.
1536	** With SQLITE_ACCESS_READWRITE, the xAccess method
1537	** checks whether the named directory is both readable and writable
1538	** (in other words, if files can be added, removed, and renamed within
1539	** the directory).
1540	** The SQLITE_ACCESS_READWRITE constant is currently used only by the
1541	** [temp_store_directory pragma], though this could change in a future
1542	** release of SQLite.
1543	** With SQLITE_ACCESS_READ, the xAccess method
1544	** checks whether the file is readable. The SQLITE_ACCESS_READ constant is
1545	** currently unused, though it might be used in a future release of
1546	** SQLite.
1547	*/
1548	#define SQLITE_ACCESS_EXISTS 0
1549	#define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */
1550	#define SQLITE_ACCESS_READ 2 /* Unused */
1551
1552	/*
1553	** CAPI3REF: Flags for the xShmLock VFS method
1554	**
1555	** These integer constants define the various locking operations
1556	** allowed by the xShmLock method of [sqlite3_io_methods]. The
1557	** following are the only legal combinations of flags to the
1558	** xShmLock method:
1559	**
1560	** <ul>
1561	** <li> SQLITE_SHM_LOCK \| SQLITE_SHM_SHARED
1562	** <li> SQLITE_SHM_LOCK \| SQLITE_SHM_EXCLUSIVE
1563	** <li> SQLITE_SHM_UNLOCK \| SQLITE_SHM_SHARED
1564	** <li> SQLITE_SHM_UNLOCK \| SQLITE_SHM_EXCLUSIVE
1565	** </ul>
1566	**
1567	** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
1568	** was given on the corresponding lock.
1569	**
1570	** The xShmLock method can transition between unlocked and SHARED or
1571	** between unlocked and EXCLUSIVE. It cannot transition between SHARED
1572	** and EXCLUSIVE.
1573	*/
1574	#define SQLITE_SHM_UNLOCK 1
1575	#define SQLITE_SHM_LOCK 2
1576	#define SQLITE_SHM_SHARED 4
1577	#define SQLITE_SHM_EXCLUSIVE 8
1578
1579	/*
1580	** CAPI3REF: Maximum xShmLock index
1581	**
1582	** The xShmLock method on [sqlite3_io_methods] may use values
1583	** between 0 and this upper bound as its "offset" argument.
1584	** The SQLite core will never attempt to acquire or release a
1585	** lock outside of this range
1586	*/
1587	#define SQLITE_SHM_NLOCK 8
1588
1589
1590	/*
1591	** CAPI3REF: Initialize The SQLite Library
1592	**
1593	** ^The sqlite3_initialize() routine initializes the
1594	** SQLite library. ^The sqlite3_shutdown() routine
1595	** deallocates any resources that were allocated by sqlite3_initialize().
1596	** These routines are designed to aid in process initialization and
1597	** shutdown on embedded systems. Workstation applications using
1598	** SQLite normally do not need to invoke either of these routines.
1599	**
1600	** A call to sqlite3_initialize() is an "effective" call if it is
1601	** the first time sqlite3_initialize() is invoked during the lifetime of
1602	** the process, or if it is the first time sqlite3_initialize() is invoked
1603	** following a call to sqlite3_shutdown(). ^(Only an effective call
1604	** of sqlite3_initialize() does any initialization. All other calls
1605	** are harmless no-ops.)^
1606	**
1607	** A call to sqlite3_shutdown() is an "effective" call if it is the first
1608	** call to sqlite3_shutdown() since the last sqlite3_initialize(). ^(Only
1609	** an effective call to sqlite3_shutdown() does any deinitialization.
1610	** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
1611	**
1612	** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
1613	** is not. The sqlite3_shutdown() interface must only be called from a
1614	** single thread. All open [database connections] must be closed and all
1615	** other SQLite resources must be deallocated prior to invoking
1616	** sqlite3_shutdown().
1617	**
1618	** Among other things, ^sqlite3_initialize() will invoke
1619	** sqlite3_os_init(). Similarly, ^sqlite3_shutdown()
1620	** will invoke sqlite3_os_end().
1621	**
1622	** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
1623	** ^If for some reason, sqlite3_initialize() is unable to initialize
1624	** the library (perhaps it is unable to allocate a needed resource such
1625	** as a mutex) it returns an [error code] other than [SQLITE_OK].
1626	**
1627	** ^The sqlite3_initialize() routine is called internally by many other
1628	** SQLite interfaces so that an application usually does not need to
1629	** invoke sqlite3_initialize() directly. For example, [sqlite3_open()]
1630	** calls sqlite3_initialize() so the SQLite library will be automatically
1631	** initialized when [sqlite3_open()] is called if it has not be initialized
1632	** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
1633	** compile-time option, then the automatic calls to sqlite3_initialize()
1634	** are omitted and the application must call sqlite3_initialize() directly
1635	** prior to using any other SQLite interface. For maximum portability,
1636	** it is recommended that applications always invoke sqlite3_initialize()
1637	** directly prior to using any other SQLite interface. Future releases
1638	** of SQLite may require this. In other words, the behavior exhibited
1639	** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
1640	** default behavior in some future release of SQLite.
1641	**
1642	** The sqlite3_os_init() routine does operating-system specific
1643	** initialization of the SQLite library. The sqlite3_os_end()
1644	** routine undoes the effect of sqlite3_os_init(). Typical tasks
1645	** performed by these routines include allocation or deallocation
1646	** of static resources, initialization of global variables,
1647	** setting up a default [sqlite3_vfs] module, or setting up
1648	** a default configuration using [sqlite3_config()].
1649	**
1650	** The application should never invoke either sqlite3_os_init()
1651	** or sqlite3_os_end() directly. The application should only invoke
1652	** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()
1653	** interface is called automatically by sqlite3_initialize() and
1654	** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
1655	** implementations for sqlite3_os_init() and sqlite3_os_end()
1656	** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
1657	** When [custom builds \| built for other platforms]
1658	** (using the [SQLITE_OS_OTHER=1] compile-time
1659	** option) the application must supply a suitable implementation for
1660	** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
1661	** implementation of sqlite3_os_init() or sqlite3_os_end()
1662	** must return [SQLITE_OK] on success and some other [error code] upon
1663	** failure.
1664	*/
1665	SQLITE_API int sqlite3_initialize(void);
1666	SQLITE_API int sqlite3_shutdown(void);
1667	SQLITE_API int sqlite3_os_init(void);
1668	SQLITE_API int sqlite3_os_end(void);
1669
1670	/*
1671	** CAPI3REF: Configuring The SQLite Library
1672	**
1673	** The sqlite3_config() interface is used to make global configuration
1674	** changes to SQLite in order to tune SQLite to the specific needs of
1675	** the application. The default configuration is recommended for most
1676	** applications and so this routine is usually not necessary. It is
1677	** provided to support rare applications with unusual needs.
1678	**
1679	** <b>The sqlite3_config() interface is not threadsafe. The application
1680	** must ensure that no other SQLite interfaces are invoked by other
1681	** threads while sqlite3_config() is running.</b>
1682	**
1683	** The first argument to sqlite3_config() is an integer
1684	** [configuration option] that determines
1685	** what property of SQLite is to be configured. Subsequent arguments
1686	** vary depending on the [configuration option]
1687	** in the first argument.
1688	**
1689	** For most configuration options, the sqlite3_config() interface
1690	** may only be invoked prior to library initialization using
1691	** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
1692	** The exceptional configuration options that may be invoked at any time
1693	** are called "anytime configuration options".
1694	** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
1695	** [sqlite3_shutdown()] with a first argument that is not an anytime
1696	** configuration option, then the sqlite3_config() call will return SQLITE_MISUSE.
1697	** Note, however, that ^sqlite3_config() can be called as part of the
1698	** implementation of an application-defined [sqlite3_os_init()].
1699	**
1700	** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
1701	** ^If the option is unknown or SQLite is unable to set the option
1702	** then this routine returns a non-zero [error code].
1703	*/
1704	SQLITE_API int sqlite3_config(int, ...);
1705
1706	/*
1707	** CAPI3REF: Configure database connections
1708	** METHOD: sqlite3
1709	**
1710	** The sqlite3_db_config() interface is used to make configuration
1711	** changes to a [database connection]. The interface is similar to
1712	** [sqlite3_config()] except that the changes apply to a single
1713	** [database connection] (specified in the first argument).
1714	**
1715	** The second argument to sqlite3_db_config(D,V,...) is the
1716	** [SQLITE_DBCONFIG_LOOKASIDE \| configuration verb] - an integer code
1717	** that indicates what aspect of the [database connection] is being configured.
1718	** Subsequent arguments vary depending on the configuration verb.
1719	**
1720	** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
1721	** the call is considered successful.
1722	*/
1723	SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
1724
1725	/*
1726	** CAPI3REF: Memory Allocation Routines
1727	**
1728	** An instance of this object defines the interface between SQLite
1729	** and low-level memory allocation routines.
1730	**
1731	** This object is used in only one place in the SQLite interface.
1732	** A pointer to an instance of this object is the argument to
1733	** [sqlite3_config()] when the configuration option is
1734	** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
1735	** By creating an instance of this object
1736	** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
1737	** during configuration, an application can specify an alternative
1738	** memory allocation subsystem for SQLite to use for all of its
1739	** dynamic memory needs.
1740	**
1741	** Note that SQLite comes with several [built-in memory allocators]
1742	** that are perfectly adequate for the overwhelming majority of applications
1743	** and that this object is only useful to a tiny minority of applications
1744	** with specialized memory allocation requirements. This object is
1745	** also used during testing of SQLite in order to specify an alternative
1746	** memory allocator that simulates memory out-of-memory conditions in
1747	** order to verify that SQLite recovers gracefully from such
1748	** conditions.
1749	**
1750	** The xMalloc, xRealloc, and xFree methods must work like the
1751	** malloc(), realloc() and free() functions from the standard C library.
1752	** ^SQLite guarantees that the second argument to
1753	** xRealloc is always a value returned by a prior call to xRoundup.
1754	**
1755	** xSize should return the allocated size of a memory allocation
1756	** previously obtained from xMalloc or xRealloc. The allocated size
1757	** is always at least as big as the requested size but may be larger.
1758	**
1759	** The xRoundup method returns what would be the allocated size of
1760	** a memory allocation given a particular requested size. Most memory
1761	** allocators round up memory allocations at least to the next multiple
1762	** of 8. Some allocators round up to a larger multiple or to a power of 2.
1763	** Every memory allocation request coming in through [sqlite3_malloc()]
1764	** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
1765	** that causes the corresponding memory allocation to fail.
1766	**
1767	** The xInit method initializes the memory allocator. For example,
1768	** it might allocate any required mutexes or initialize internal data
1769	** structures. The xShutdown method is invoked (indirectly) by
1770	** [sqlite3_shutdown()] and should deallocate any resources acquired
1771	** by xInit. The pAppData pointer is used as the only parameter to
1772	** xInit and xShutdown.
1773	**
1774	** SQLite holds the [SQLITE_MUTEX_STATIC_MAIN] mutex when it invokes
1775	** the xInit method, so the xInit method need not be threadsafe. The
1776	** xShutdown method is only called from [sqlite3_shutdown()] so it does
1777	** not need to be threadsafe either. For all other methods, SQLite
1778	** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
1779	** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
1780	** it is by default) and so the methods are automatically serialized.
1781	** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
1782	** methods must be threadsafe or else make their own arrangements for
1783	** serialization.
1784	**
1785	** SQLite will never invoke xInit() more than once without an intervening
1786	** call to xShutdown().
1787	*/
1788	typedef struct sqlite3_mem_methods sqlite3_mem_methods;
1789	struct sqlite3_mem_methods {
1790	void (xMalloc)(int); /* Memory allocation function */
1791	void (xFree)(void); /* Free a prior allocation */
1792	void (xRealloc)(void,int); / Resize an allocation */
1793	int (xSize)(void); /* Return the size of an allocation */
1794	int (xRoundup)(int); / Round up request size to allocation size */
1795	int (xInit)(void); /* Initialize the memory allocator */
1796	void (xShutdown)(void); /* Deinitialize the memory allocator */
1797	void pAppData; / Argument to xInit() and xShutdown() */
1798	};
1799
1800	/*
1801	** CAPI3REF: Configuration Options
1802	** KEYWORDS: {configuration option}
1803	**
1804	** These constants are the available integer configuration options that
1805	** can be passed as the first argument to the [sqlite3_config()] interface.
1806	**
1807	** Most of the configuration options for sqlite3_config()
1808	** will only work if invoked prior to [sqlite3_initialize()] or after
1809	** [sqlite3_shutdown()]. The few exceptions to this rule are called
1810	** "anytime configuration options".
1811	** ^Calling [sqlite3_config()] with a first argument that is not an
1812	** anytime configuration option in between calls to [sqlite3_initialize()] and
1813	** [sqlite3_shutdown()] is a no-op that returns SQLITE_MISUSE.
1814	**
1815	** The set of anytime configuration options can change (by insertions
1816	** and/or deletions) from one release of SQLite to the next.
1817	** As of SQLite version 3.42.0, the complete set of anytime configuration
1818	** options is:
1819	** <ul>
1820	** <li> SQLITE_CONFIG_LOG
1821	** <li> SQLITE_CONFIG_PCACHE_HDRSZ
1822	** </ul>
1823	**
1824	** New configuration options may be added in future releases of SQLite.
1825	** Existing configuration options might be discontinued. Applications
1826	** should check the return code from [sqlite3_config()] to make sure that
1827	** the call worked. The [sqlite3_config()] interface will return a
1828	** non-zero [error code] if a discontinued or unsupported configuration option
1829	** is invoked.
1830	**
1831	** <dl>
1832	** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
1833	** <dd>There are no arguments to this option. ^This option sets the
1834	** [threading mode] to Single-thread. In other words, it disables
1835	** all mutexing and puts SQLite into a mode where it can only be used
1836	** by a single thread. ^If SQLite is compiled with
1837	** the [SQLITE_THREADSAFE \| SQLITE_THREADSAFE=0] compile-time option then
1838	** it is not possible to change the [threading mode] from its default
1839	** value of Single-thread and so [sqlite3_config()] will return
1840	** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
1841	** configuration option.</dd>
1842	**
1843	** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
1844	** <dd>There are no arguments to this option. ^This option sets the
1845	** [threading mode] to Multi-thread. In other words, it disables
1846	** mutexing on [database connection] and [prepared statement] objects.
1847	** The application is responsible for serializing access to
1848	** [database connections] and [prepared statements]. But other mutexes
1849	** are enabled so that SQLite will be safe to use in a multi-threaded
1850	** environment as long as no two threads attempt to use the same
1851	** [database connection] at the same time. ^If SQLite is compiled with
1852	** the [SQLITE_THREADSAFE \| SQLITE_THREADSAFE=0] compile-time option then
1853	** it is not possible to set the Multi-thread [threading mode] and
1854	** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1855	** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
1856	**
1857	** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
1858	** <dd>There are no arguments to this option. ^This option sets the
1859	** [threading mode] to Serialized. In other words, this option enables
1860	** all mutexes including the recursive
1861	** mutexes on [database connection] and [prepared statement] objects.
1862	** In this mode (which is the default when SQLite is compiled with
1863	** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
1864	** to [database connections] and [prepared statements] so that the
1865	** application is free to use the same [database connection] or the
1866	** same [prepared statement] in different threads at the same time.
1867	** ^If SQLite is compiled with
1868	** the [SQLITE_THREADSAFE \| SQLITE_THREADSAFE=0] compile-time option then
1869	** it is not possible to set the Serialized [threading mode] and
1870	** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1871	** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
1872	**
1873	** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
1874	** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is
1875	** a pointer to an instance of the [sqlite3_mem_methods] structure.
1876	** The argument specifies
1877	** alternative low-level memory allocation routines to be used in place of
1878	** the memory allocation routines built into SQLite.)^ ^SQLite makes
1879	** its own private copy of the content of the [sqlite3_mem_methods] structure
1880	** before the [sqlite3_config()] call returns.</dd>
1881	**
1882	** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
1883	** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which
1884	** is a pointer to an instance of the [sqlite3_mem_methods] structure.
1885	** The [sqlite3_mem_methods]
1886	** structure is filled with the currently defined memory allocation routines.)^
1887	** This option can be used to overload the default memory allocation
1888	** routines with a wrapper that simulations memory allocation failure or
1889	** tracks memory usage, for example. </dd>
1890	**
1891	** [[SQLITE_CONFIG_SMALL_MALLOC]] <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>
1892	** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of
1893	** type int, interpreted as a boolean, which if true provides a hint to
1894	** SQLite that it should avoid large memory allocations if possible.
1895	** SQLite will run faster if it is free to make large memory allocations,
1896	** but some application might prefer to run slower in exchange for
1897	** guarantees about memory fragmentation that are possible if large
1898	** allocations are avoided. This hint is normally off.
1899	** </dd>
1900	**
1901	** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
1902	** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
1903	** interpreted as a boolean, which enables or disables the collection of
1904	** memory allocation statistics. ^(When memory allocation statistics are
1905	** disabled, the following SQLite interfaces become non-operational:
1906	** <ul>
1907	** <li> [sqlite3_hard_heap_limit64()]
1908	** <li> [sqlite3_memory_used()]
1909	** <li> [sqlite3_memory_highwater()]
1910	** <li> [sqlite3_soft_heap_limit64()]
1911	** <li> [sqlite3_status64()]
1912	** </ul>)^
1913	** ^Memory allocation statistics are enabled by default unless SQLite is
1914	** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
1915	** allocation statistics are disabled by default.
1916	** </dd>
1917	**
1918	** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
1919	** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
1920	** </dd>
1921	**
1922	** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
1923	** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
1924	** that SQLite can use for the database page cache with the default page
1925	** cache implementation.
1926	** This configuration option is a no-op if an application-defined page
1927	** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
1928	** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
1929	** 8-byte aligned memory (pMem), the size of each page cache line (sz),
1930	** and the number of cache lines (N).
1931	** The sz argument should be the size of the largest database page
1932	** (a power of two between 512 and 65536) plus some extra bytes for each
1933	** page header. ^The number of extra bytes needed by the page header
1934	** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
1935	** ^It is harmless, apart from the wasted memory,
1936	** for the sz parameter to be larger than necessary. The pMem
1937	** argument must be either a NULL pointer or a pointer to an 8-byte
1938	** aligned block of memory of at least sz*N bytes, otherwise
1939	** subsequent behavior is undefined.
1940	** ^When pMem is not NULL, SQLite will strive to use the memory provided
1941	** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
1942	** a page cache line is larger than sz bytes or if all of the pMem buffer
1943	** is exhausted.
1944	** ^If pMem is NULL and N is non-zero, then each database connection
1945	** does an initial bulk allocation for page cache memory
1946	** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
1947	** of -1024*N bytes if N is negative, . ^If additional
1948	** page cache memory is needed beyond what is provided by the initial
1949	** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
1950	** additional cache line. </dd>
1951	**
1952	** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
1953	** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer
1954	** that SQLite will use for all of its dynamic memory allocation needs
1955	** beyond those provided for by [SQLITE_CONFIG_PAGECACHE].
1956	** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
1957	** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
1958	** [SQLITE_ERROR] if invoked otherwise.
1959	** ^There are three arguments to SQLITE_CONFIG_HEAP:
1960	** An 8-byte aligned pointer to the memory,
1961	** the number of bytes in the memory buffer, and the minimum allocation size.
1962	** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
1963	** to using its default memory allocator (the system malloc() implementation),
1964	** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the
1965	** memory pointer is not NULL then the alternative memory
1966	** allocator is engaged to handle all of SQLites memory allocation needs.
1967	** The first pointer (the memory pointer) must be aligned to an 8-byte
1968	** boundary or subsequent behavior of SQLite will be undefined.
1969	The minimum allocation size is capped at 212. Reasonable values
1970	for the minimum allocation size are 25 through 2**8.</dd>
1971	**
1972	** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
1973	** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
1974	** pointer to an instance of the [sqlite3_mutex_methods] structure.
1975	** The argument specifies alternative low-level mutex routines to be used
1976	** in place the mutex routines built into SQLite.)^ ^SQLite makes a copy of
1977	** the content of the [sqlite3_mutex_methods] structure before the call to
1978	** [sqlite3_config()] returns. ^If SQLite is compiled with
1979	** the [SQLITE_THREADSAFE \| SQLITE_THREADSAFE=0] compile-time option then
1980	** the entire mutexing subsystem is omitted from the build and hence calls to
1981	** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
1982	** return [SQLITE_ERROR].</dd>
1983	**
1984	** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
1985	** <dd> ^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which
1986	** is a pointer to an instance of the [sqlite3_mutex_methods] structure. The
1987	** [sqlite3_mutex_methods]
1988	** structure is filled with the currently defined mutex routines.)^
1989	** This option can be used to overload the default mutex allocation
1990	** routines with a wrapper used to track mutex usage for performance
1991	** profiling or testing, for example. ^If SQLite is compiled with
1992	** the [SQLITE_THREADSAFE \| SQLITE_THREADSAFE=0] compile-time option then
1993	** the entire mutexing subsystem is omitted from the build and hence calls to
1994	** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
1995	** return [SQLITE_ERROR].</dd>
1996	**
1997	** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
1998	** <dd> ^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
1999	** the default size of [lookaside memory] on each [database connection].
2000	** The first argument is the
2001	** size of each lookaside buffer slot ("sz") and the second is the number of
2002	** slots allocated to each database connection ("cnt").)^
2003	** ^(SQLITE_CONFIG_LOOKASIDE sets the <i>default</i> lookaside size.
2004	** The [SQLITE_DBCONFIG_LOOKASIDE] option to [sqlite3_db_config()] can
2005	** be used to change the lookaside configuration on individual connections.)^
2006	** The [-DSQLITE_DEFAULT_LOOKASIDE] option can be used to change the
2007	** default lookaside configuration at compile-time.
2008	** </dd>
2009	**
2010	** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
2011	** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
2012	** a pointer to an [sqlite3_pcache_methods2] object. This object specifies
2013	** the interface to a custom page cache implementation.)^
2014	** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
2015	**
2016	** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
2017	** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
2018	** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of
2019	** the current page cache implementation into that object.)^ </dd>
2020	**
2021	** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
2022	** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
2023	** global [error log].
2024	** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
2025	** function with a call signature of void()(void,int,const char*),
2026	** and a pointer to void. ^If the function pointer is not NULL, it is
2027	** invoked by [sqlite3_log()] to process each logging event. ^If the
2028	** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
2029	** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
2030	** passed through as the first parameter to the application-defined logger
2031	** function whenever that function is invoked. ^The second parameter to
2032	** the logger function is a copy of the first parameter to the corresponding
2033	** [sqlite3_log()] call and is intended to be a [result code] or an
2034	** [extended result code]. ^The third parameter passed to the logger is
2035	** log message after formatting via [sqlite3_snprintf()].
2036	** The SQLite logging interface is not reentrant; the logger function
2037	** supplied by the application must not invoke any SQLite interface.
2038	** In a multi-threaded application, the application-defined logger
2039	** function must be threadsafe. </dd>
2040	**
2041	** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
2042	** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
2043	** If non-zero, then URI handling is globally enabled. If the parameter is zero,
2044	** then URI handling is globally disabled.)^ ^If URI handling is globally
2045	** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
2046	** [sqlite3_open16()] or
2047	** specified as part of [ATTACH] commands are interpreted as URIs, regardless
2048	** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
2049	** connection is opened. ^If it is globally disabled, filenames are
2050	** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
2051	** database connection is opened. ^(By default, URI handling is globally
2052	** disabled. The default value may be changed by compiling with the
2053	** [SQLITE_USE_URI] symbol defined.)^
2054	**
2055	** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
2056	** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
2057	** argument which is interpreted as a boolean in order to enable or disable
2058	** the use of covering indices for full table scans in the query optimizer.
2059	** ^The default setting is determined
2060	** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
2061	** if that compile-time option is omitted.
2062	** The ability to disable the use of covering indices for full table scans
2063	** is because some incorrectly coded legacy applications might malfunction
2064	** when the optimization is enabled. Providing the ability to
2065	** disable the optimization allows the older, buggy application code to work
2066	** without change even with newer versions of SQLite.
2067	**
2068	** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
2069	** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
2070	** <dd> These options are obsolete and should not be used by new code.
2071	** They are retained for backwards compatibility but are now no-ops.
2072	** </dd>
2073	**
2074	** [[SQLITE_CONFIG_SQLLOG]]
2075	** <dt>SQLITE_CONFIG_SQLLOG
2076	** <dd>This option is only available if sqlite is compiled with the
2077	** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
2078	** be a pointer to a function of type void()(void,sqlite3,const char, int).
2079	** The second should be of type (void*). The callback is invoked by the library
2080	** in three separate circumstances, identified by the value passed as the
2081	** fourth parameter. If the fourth parameter is 0, then the database connection
2082	** passed as the second argument has just been opened. The third argument
2083	** points to a buffer containing the name of the main database file. If the
2084	** fourth parameter is 1, then the SQL statement that the third parameter
2085	** points to has just been executed. Or, if the fourth parameter is 2, then
2086	** the connection being passed as the second parameter is being closed. The
2087	** third parameter is passed NULL In this case. An example of using this
2088	** configuration option can be seen in the "test_sqllog.c" source file in
2089	** the canonical SQLite source tree.</dd>
2090	**
2091	** [[SQLITE_CONFIG_MMAP_SIZE]]
2092	** <dt>SQLITE_CONFIG_MMAP_SIZE
2093	** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
2094	** that are the default mmap size limit (the default setting for
2095	** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
2096	** ^The default setting can be overridden by each database connection using
2097	** either the [PRAGMA mmap_size] command, or by using the
2098	** [SQLITE_FCNTL_MMAP_SIZE] file control. ^(The maximum allowed mmap size
2099	** will be silently truncated if necessary so that it does not exceed the
2100	** compile-time maximum mmap size set by the
2101	** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
2102	** ^If either argument to this option is negative, then that argument is
2103	** changed to its compile-time default.
2104	**
2105	** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
2106	** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
2107	** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
2108	** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
2109	** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
2110	** that specifies the maximum size of the created heap.
2111	**
2112	** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
2113	** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
2114	** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
2115	** is a pointer to an integer and writes into that integer the number of extra
2116	** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].
2117	** The amount of extra space required can change depending on the compiler,
2118	** target platform, and SQLite version.
2119	**
2120	** [[SQLITE_CONFIG_PMASZ]]
2121	** <dt>SQLITE_CONFIG_PMASZ
2122	** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which
2123	** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
2124	** sorter to that integer. The default minimum PMA Size is set by the
2125	** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched
2126	** to help with sort operations when multithreaded sorting
2127	** is enabled (using the [PRAGMA threads] command) and the amount of content
2128	** to be sorted exceeds the page size times the minimum of the
2129	** [PRAGMA cache_size] setting and this value.
2130	**
2131	** [[SQLITE_CONFIG_STMTJRNL_SPILL]]
2132	** <dt>SQLITE_CONFIG_STMTJRNL_SPILL
2133	** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
2134	** becomes the [statement journal] spill-to-disk threshold.
2135	** [Statement journals] are held in memory until their size (in bytes)
2136	** exceeds this threshold, at which point they are written to disk.
2137	** Or if the threshold is -1, statement journals are always held
2138	** exclusively in memory.
2139	** Since many statement journals never become large, setting the spill
2140	** threshold to a value such as 64KiB can greatly reduce the amount of
2141	** I/O required to support statement rollback.
2142	** The default value for this setting is controlled by the
2143	** [SQLITE_STMTJRNL_SPILL] compile-time option.
2144	**
2145	** [[SQLITE_CONFIG_SORTERREF_SIZE]]
2146	** <dt>SQLITE_CONFIG_SORTERREF_SIZE
2147	** <dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter
2148	** of type (int) - the new value of the sorter-reference size threshold.
2149	** Usually, when SQLite uses an external sort to order records according
2150	** to an ORDER BY clause, all fields required by the caller are present in the
2151	** sorted records. However, if SQLite determines based on the declared type
2152	** of a table column that its values are likely to be very large - larger
2153	** than the configured sorter-reference size threshold - then a reference
2154	** is stored in each sorted record and the required column values loaded
2155	** from the database as records are returned in sorted order. The default
2156	** value for this option is to never use this optimization. Specifying a
2157	** negative value for this option restores the default behavior.
2158	** This option is only available if SQLite is compiled with the
2159	** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option.
2160	**
2161	** [[SQLITE_CONFIG_MEMDB_MAXSIZE]]
2162	** <dt>SQLITE_CONFIG_MEMDB_MAXSIZE
2163	** <dd>The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter
2164	** [sqlite3_int64] parameter which is the default maximum size for an in-memory
2165	** database created using [sqlite3_deserialize()]. This default maximum
2166	** size can be adjusted up or down for individual databases using the
2167	** [SQLITE_FCNTL_SIZE_LIMIT] [sqlite3_file_control\|file-control]. If this
2168	** configuration setting is never used, then the default maximum is determined
2169	** by the [SQLITE_MEMDB_DEFAULT_MAXSIZE] compile-time option. If that
2170	** compile-time option is not set, then the default maximum is 1073741824.
2171	**
2172	** [[SQLITE_CONFIG_ROWID_IN_VIEW]]
2173	** <dt>SQLITE_CONFIG_ROWID_IN_VIEW
2174	** <dd>The SQLITE_CONFIG_ROWID_IN_VIEW option enables or disables the ability
2175	** for VIEWs to have a ROWID. The capability can only be enabled if SQLite is
2176	** compiled with -DSQLITE_ALLOW_ROWID_IN_VIEW, in which case the capability
2177	** defaults to on. This configuration option queries the current setting or
2178	** changes the setting to off or on. The argument is a pointer to an integer.
2179	** If that integer initially holds a value of 1, then the ability for VIEWs to
2180	** have ROWIDs is activated. If the integer initially holds zero, then the
2181	** ability is deactivated. Any other initial value for the integer leaves the
2182	** setting unchanged. After changes, if any, the integer is written with
2183	** a 1 or 0, if the ability for VIEWs to have ROWIDs is on or off. If SQLite
2184	** is compiled without -DSQLITE_ALLOW_ROWID_IN_VIEW (which is the usual and
2185	** recommended case) then the integer is always filled with zero, regardless
2186	** if its initial value.
2187	** </dl>
2188	*/
2189	#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
2190	#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
2191	#define SQLITE_CONFIG_SERIALIZED 3 /* nil */
2192	#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
2193	#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
2194	#define SQLITE_CONFIG_SCRATCH 6 /* No longer used */
2195	#define SQLITE_CONFIG_PAGECACHE 7 /* void, int sz, int N /
2196	#define SQLITE_CONFIG_HEAP 8 /* void, int nByte, int min /
2197	#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
2198	#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
2199	#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
2200	/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
2201	#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
2202	#define SQLITE_CONFIG_PCACHE 14 /* no-op */
2203	#define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
2204	#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
2205	#define SQLITE_CONFIG_URI 17 /* int */
2206	#define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
2207	#define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
2208	#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
2209	#define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
2210	#define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
2211	#define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
2212	#define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int psz /
2213	#define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
2214	#define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
2215	#define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */
2216	#define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */
2217	#define SQLITE_CONFIG_MEMDB_MAXSIZE 29 /* sqlite3_int64 */
2218	#define SQLITE_CONFIG_ROWID_IN_VIEW 30 /* int* */
2219
2220	/*
2221	** CAPI3REF: Database Connection Configuration Options
2222	**
2223	** These constants are the available integer configuration options that
2224	** can be passed as the second parameter to the [sqlite3_db_config()] interface.
2225	**
2226	** The [sqlite3_db_config()] interface is a var-args functions. It takes a
2227	** variable number of parameters, though always at least two. The number of
2228	** parameters passed into sqlite3_db_config() depends on which of these
2229	** constants is given as the second parameter. This documentation page
2230	** refers to parameters beyond the second as "arguments". Thus, when this
2231	** page says "the N-th argument" it means "the N-th parameter past the
2232	** configuration option" or "the (N+2)-th parameter to sqlite3_db_config()".
2233	**
2234	** New configuration options may be added in future releases of SQLite.
2235	** Existing configuration options might be discontinued. Applications
2236	** should check the return code from [sqlite3_db_config()] to make sure that
2237	** the call worked. ^The [sqlite3_db_config()] interface will return a
2238	** non-zero [error code] if a discontinued or unsupported configuration option
2239	** is invoked.
2240	**
2241	** <dl>
2242	** [[SQLITE_DBCONFIG_LOOKASIDE]]
2243	** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
2244	** <dd> The SQLITE_DBCONFIG_LOOKASIDE option is used to adjust the
2245	** configuration of the [lookaside memory allocator] within a database
2246	** connection.
2247	** The arguments to the SQLITE_DBCONFIG_LOOKASIDE option are <i>not</i>
2248	** in the [DBCONFIG arguments\|usual format].
2249	** The SQLITE_DBCONFIG_LOOKASIDE option takes three arguments, not two,
2250	** so that a call to [sqlite3_db_config()] that uses SQLITE_DBCONFIG_LOOKASIDE
2251	** should have a total of five parameters.
2252	** <ol>
2253	** <li><p>The first argument ("buf") is a
2254	** pointer to a memory buffer to use for lookaside memory.
2255	** The first argument may be NULL in which case SQLite will allocate the
2256	** lookaside buffer itself using [sqlite3_malloc()].
2257	** <li><P>The second argument ("sz") is the
2258	** size of each lookaside buffer slot. Lookaside is disabled if "sz"
2259	** is less than 8. The "sz" argument should be a multiple of 8 less than
2260	** 65536. If "sz" does not meet this constraint, it is reduced in size until
2261	** it does.
2262	** <li><p>The third argument ("cnt") is the number of slots. Lookaside is disabled
2263	** if "cnt"is less than 1. The "cnt" value will be reduced, if necessary, so
2264	** that the product of "sz" and "cnt" does not exceed 2,147,418,112. The "cnt"
2265	** parameter is usually chosen so that the product of "sz" and "cnt" is less
2266	** than 1,000,000.
2267	** </ol>
2268	** <p>If the "buf" argument is not NULL, then it must
2269	** point to a memory buffer with a size that is greater than
2270	** or equal to the product of "sz" and "cnt".
2271	** The buffer must be aligned to an 8-byte boundary.
2272	** The lookaside memory
2273	** configuration for a database connection can only be changed when that
2274	** connection is not currently using lookaside memory, or in other words
2275	** when the value returned by [SQLITE_DBSTATUS_LOOKASIDE_USED] is zero.
2276	** Any attempt to change the lookaside memory configuration when lookaside
2277	** memory is in use leaves the configuration unchanged and returns
2278	** [SQLITE_BUSY].
2279	** If the "buf" argument is NULL and an attempt
2280	** to allocate memory based on "sz" and "cnt" fails, then
2281	** lookaside is silently disabled.
2282	** <p>
2283	** The [SQLITE_CONFIG_LOOKASIDE] configuration option can be used to set the
2284	** default lookaside configuration at initialization. The
2285	** [-DSQLITE_DEFAULT_LOOKASIDE] option can be used to set the default lookaside
2286	** configuration at compile-time. Typical values for lookaside are 1200 for
2287	** "sz" and 40 to 100 for "cnt".
2288	** </dd>
2289	**
2290	** [[SQLITE_DBCONFIG_ENABLE_FKEY]]
2291	** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
2292	** <dd> ^This option is used to enable or disable the enforcement of
2293	** [foreign key constraints]. This is the same setting that is
2294	** enabled or disabled by the [PRAGMA foreign_keys] statement.
2295	** The first argument is an integer which is 0 to disable FK enforcement,
2296	** positive to enable FK enforcement or negative to leave FK enforcement
2297	** unchanged. The second parameter is a pointer to an integer into which
2298	** is written 0 or 1 to indicate whether FK enforcement is off or on
2299	** following this call. The second parameter may be a NULL pointer, in
2300	** which case the FK enforcement setting is not reported back. </dd>
2301	**
2302	** [[SQLITE_DBCONFIG_ENABLE_TRIGGER]]
2303	** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
2304	** <dd> ^This option is used to enable or disable [CREATE TRIGGER \| triggers].
2305	** There should be two additional arguments.
2306	** The first argument is an integer which is 0 to disable triggers,
2307	** positive to enable triggers or negative to leave the setting unchanged.
2308	** The second parameter is a pointer to an integer into which
2309	** is written 0 or 1 to indicate whether triggers are disabled or enabled
2310	** following this call. The second parameter may be a NULL pointer, in
2311	** which case the trigger setting is not reported back.
2312	**
2313	** <p>Originally this option disabled all triggers. ^(However, since
2314	** SQLite version 3.35.0, TEMP triggers are still allowed even if
2315	** this option is off. So, in other words, this option now only disables
2316	** triggers in the main database schema or in the schemas of [ATTACH]-ed
2317	** databases.)^ </dd>
2318	**
2319	** [[SQLITE_DBCONFIG_ENABLE_VIEW]]
2320	** <dt>SQLITE_DBCONFIG_ENABLE_VIEW</dt>
2321	** <dd> ^This option is used to enable or disable [CREATE VIEW \| views].
2322	** There must be two additional arguments.
2323	** The first argument is an integer which is 0 to disable views,
2324	** positive to enable views or negative to leave the setting unchanged.
2325	** The second parameter is a pointer to an integer into which
2326	** is written 0 or 1 to indicate whether views are disabled or enabled
2327	** following this call. The second parameter may be a NULL pointer, in
2328	** which case the view setting is not reported back.
2329	**
2330	** <p>Originally this option disabled all views. ^(However, since
2331	** SQLite version 3.35.0, TEMP views are still allowed even if
2332	** this option is off. So, in other words, this option now only disables
2333	** views in the main database schema or in the schemas of ATTACH-ed
2334	** databases.)^ </dd>
2335	**
2336	** [[SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER]]
2337	** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
2338	** <dd> ^This option is used to enable or disable the
2339	** [fts3_tokenizer()] function which is part of the
2340	** [FTS3] full-text search engine extension.
2341	** There must be two additional arguments.
2342	** The first argument is an integer which is 0 to disable fts3_tokenizer() or
2343	** positive to enable fts3_tokenizer() or negative to leave the setting
2344	** unchanged.
2345	** The second parameter is a pointer to an integer into which
2346	** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
2347	** following this call. The second parameter may be a NULL pointer, in
2348	** which case the new setting is not reported back. </dd>
2349	**
2350	** [[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION]]
2351	** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt>
2352	** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
2353	** interface independently of the [load_extension()] SQL function.
2354	** The [sqlite3_enable_load_extension()] API enables or disables both the
2355	** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].
2356	** There must be two additional arguments.
2357	** When the first argument to this interface is 1, then only the C-API is
2358	** enabled and the SQL function remains disabled. If the first argument to
2359	** this interface is 0, then both the C-API and the SQL function are disabled.
2360	** If the first argument is -1, then no changes are made to state of either the
2361	** C-API or the SQL function.
2362	** The second parameter is a pointer to an integer into which
2363	** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface
2364	** is disabled or enabled following this call. The second parameter may
2365	** be a NULL pointer, in which case the new setting is not reported back.
2366	** </dd>
2367	**
2368	** [[SQLITE_DBCONFIG_MAINDBNAME]] <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>
2369	** <dd> ^This option is used to change the name of the "main" database
2370	** schema. This option does not follow the
2371	** [DBCONFIG arguments\|usual SQLITE_DBCONFIG argument format].
2372	** This option takes exactly one additional argument so that the
2373	** [sqlite3_db_config()] call has a total of three parameters. The
2374	** extra argument must be a pointer to a constant UTF8 string which
2375	** will become the new schema name in place of "main". ^SQLite does
2376	** not make a copy of the new main schema name string, so the application
2377	** must ensure that the argument passed into SQLITE_DBCONFIG MAINDBNAME
2378	** is unchanged until after the database connection closes.
2379	** </dd>
2380	**
2381	** [[SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE]]
2382	** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>
2383	** <dd> Usually, when a database in [WAL mode] is closed or detached from a
2384	** database handle, SQLite checks if if there are other connections to the
2385	** same database, and if there are no other database connection (if the
2386	** connection being closed is the last open connection to the database),
2387	** then SQLite performs a [checkpoint] before closing the connection and
2388	** deletes the WAL file. The SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE option can
2389	** be used to override that behavior. The first argument passed to this
2390	** operation (the third parameter to [sqlite3_db_config()]) is an integer
2391	** which is positive to disable checkpoints-on-close, or zero (the default)
2392	** to enable them, and negative to leave the setting unchanged.
2393	** The second argument (the fourth parameter) is a pointer to an integer
2394	** into which is written 0 or 1 to indicate whether checkpoints-on-close
2395	** have been disabled - 0 if they are not disabled, 1 if they are.
2396	** </dd>
2397	**
2398	** [[SQLITE_DBCONFIG_ENABLE_QPSG]] <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>
2399	** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates
2400	** the [query planner stability guarantee] (QPSG). When the QPSG is active,
2401	** a single SQL query statement will always use the same algorithm regardless
2402	** of values of [bound parameters].)^ The QPSG disables some query optimizations
2403	** that look at the values of bound parameters, which can make some queries
2404	** slower. But the QPSG has the advantage of more predictable behavior. With
2405	** the QPSG active, SQLite will always use the same query plan in the field as
2406	** was used during testing in the lab.
2407	** The first argument to this setting is an integer which is 0 to disable
2408	** the QPSG, positive to enable QPSG, or negative to leave the setting
2409	** unchanged. The second parameter is a pointer to an integer into which
2410	** is written 0 or 1 to indicate whether the QPSG is disabled or enabled
2411	** following this call.
2412	** </dd>
2413	**
2414	** [[SQLITE_DBCONFIG_TRIGGER_EQP]] <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt>
2415	** <dd> By default, the output of EXPLAIN QUERY PLAN commands does not
2416	** include output for any operations performed by trigger programs. This
2417	** option is used to set or clear (the default) a flag that governs this
2418	** behavior. The first parameter passed to this operation is an integer -
2419	** positive to enable output for trigger programs, or zero to disable it,
2420	** or negative to leave the setting unchanged.
2421	** The second parameter is a pointer to an integer into which is written
2422	** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if
2423	** it is not disabled, 1 if it is.
2424	** </dd>
2425	**
2426	** [[SQLITE_DBCONFIG_RESET_DATABASE]] <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt>
2427	** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run
2428	** [VACUUM] in order to reset a database back to an empty database
2429	** with no schema and no content. The following process works even for
2430	** a badly corrupted database file:
2431	** <ol>
2432	** <li> If the database connection is newly opened, make sure it has read the
2433	** database schema by preparing then discarding some query against the
2434	** database, or calling sqlite3_table_column_metadata(), ignoring any
2435	** errors. This step is only necessary if the application desires to keep
2436	** the database in WAL mode after the reset if it was in WAL mode before
2437	** the reset.
2438	** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);
2439	** <li> [sqlite3_exec](db, "[VACUUM]", 0, 0, 0);
2440	** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);
2441	** </ol>
2442	** Because resetting a database is destructive and irreversible, the
2443	** process requires the use of this obscure API and multiple steps to
2444	** help ensure that it does not happen by accident. Because this
2445	** feature must be capable of resetting corrupt databases, and
2446	** shutting down virtual tables may require access to that corrupt
2447	** storage, the library must abandon any installed virtual tables
2448	** without calling their xDestroy() methods.
2449	**
2450	** [[SQLITE_DBCONFIG_DEFENSIVE]] <dt>SQLITE_DBCONFIG_DEFENSIVE</dt>
2451	** <dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the
2452	** "defensive" flag for a database connection. When the defensive
2453	** flag is enabled, language features that allow ordinary SQL to
2454	** deliberately corrupt the database file are disabled. The disabled
2455	** features include but are not limited to the following:
2456	** <ul>
2457	** <li> The [PRAGMA writable_schema=ON] statement.
2458	** <li> The [PRAGMA journal_mode=OFF] statement.
2459	** <li> The [PRAGMA schema_version=N] statement.
2460	** <li> Writes to the [sqlite_dbpage] virtual table.
2461	** <li> Direct writes to [shadow tables].
2462	** </ul>
2463	** </dd>
2464	**
2465	** [[SQLITE_DBCONFIG_WRITABLE_SCHEMA]] <dt>SQLITE_DBCONFIG_WRITABLE_SCHEMA</dt>
2466	** <dd>The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the
2467	** "writable_schema" flag. This has the same effect and is logically equivalent
2468	** to setting [PRAGMA writable_schema=ON] or [PRAGMA writable_schema=OFF].
2469	** The first argument to this setting is an integer which is 0 to disable
2470	** the writable_schema, positive to enable writable_schema, or negative to
2471	** leave the setting unchanged. The second parameter is a pointer to an
2472	** integer into which is written 0 or 1 to indicate whether the writable_schema
2473	** is enabled or disabled following this call.
2474	** </dd>
2475	**
2476	** [[SQLITE_DBCONFIG_LEGACY_ALTER_TABLE]]
2477	** <dt>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</dt>
2478	** <dd>The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates
2479	** the legacy behavior of the [ALTER TABLE RENAME] command such it
2480	** behaves as it did prior to [version 3.24.0] (2018-06-04). See the
2481	** "Compatibility Notice" on the [ALTER TABLE RENAME documentation] for
2482	** additional information. This feature can also be turned on and off
2483	** using the [PRAGMA legacy_alter_table] statement.
2484	** </dd>
2485	**
2486	** [[SQLITE_DBCONFIG_DQS_DML]]
2487	** <dt>SQLITE_DBCONFIG_DQS_DML</dt>
2488	** <dd>The SQLITE_DBCONFIG_DQS_DML option activates or deactivates
2489	** the legacy [double-quoted string literal] misfeature for DML statements
2490	** only, that is DELETE, INSERT, SELECT, and UPDATE statements. The
2491	** default value of this setting is determined by the [-DSQLITE_DQS]
2492	** compile-time option.
2493	** </dd>
2494	**
2495	** [[SQLITE_DBCONFIG_DQS_DDL]]
2496	** <dt>SQLITE_DBCONFIG_DQS_DDL</dt>
2497	** <dd>The SQLITE_DBCONFIG_DQS option activates or deactivates
2498	** the legacy [double-quoted string literal] misfeature for DDL statements,
2499	** such as CREATE TABLE and CREATE INDEX. The
2500	** default value of this setting is determined by the [-DSQLITE_DQS]
2501	** compile-time option.
2502	** </dd>
2503	**
2504	** [[SQLITE_DBCONFIG_TRUSTED_SCHEMA]]
2505	** <dt>SQLITE_DBCONFIG_TRUSTED_SCHEMA</dt>
2506	** <dd>The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to
2507	** assume that database schemas are untainted by malicious content.
2508	** When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite
2509	** takes additional defensive steps to protect the application from harm
2510	** including:
2511	** <ul>
2512	** <li> Prohibit the use of SQL functions inside triggers, views,
2513	** CHECK constraints, DEFAULT clauses, expression indexes,
2514	** partial indexes, or generated columns
2515	** unless those functions are tagged with [SQLITE_INNOCUOUS].
2516	** <li> Prohibit the use of virtual tables inside of triggers or views
2517	** unless those virtual tables are tagged with [SQLITE_VTAB_INNOCUOUS].
2518	** </ul>
2519	** This setting defaults to "on" for legacy compatibility, however
2520	** all applications are advised to turn it off if possible. This setting
2521	** can also be controlled using the [PRAGMA trusted_schema] statement.
2522	** </dd>
2523	**
2524	** [[SQLITE_DBCONFIG_LEGACY_FILE_FORMAT]]
2525	** <dt>SQLITE_DBCONFIG_LEGACY_FILE_FORMAT</dt>
2526	** <dd>The SQLITE_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates
2527	** the legacy file format flag. When activated, this flag causes all newly
2528	** created database file to have a schema format version number (the 4-byte
2529	** integer found at offset 44 into the database header) of 1. This in turn
2530	** means that the resulting database file will be readable and writable by
2531	** any SQLite version back to 3.0.0 ([dateof:3.0.0]). Without this setting,
2532	** newly created databases are generally not understandable by SQLite versions
2533	** prior to 3.3.0 ([dateof:3.3.0]). As these words are written, there
2534	** is now scarcely any need to generate database files that are compatible
2535	** all the way back to version 3.0.0, and so this setting is of little
2536	** practical use, but is provided so that SQLite can continue to claim the
2537	** ability to generate new database files that are compatible with version
2538	** 3.0.0.
2539	** <p>Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on,
2540	** the [VACUUM] command will fail with an obscure error when attempting to
2541	** process a table with generated columns and a descending index. This is
2542	** not considered a bug since SQLite versions 3.3.0 and earlier do not support
2543	** either generated columns or descending indexes.
2544	** </dd>
2545	**
2546	** [[SQLITE_DBCONFIG_STMT_SCANSTATUS]]
2547	** <dt>SQLITE_DBCONFIG_STMT_SCANSTATUS</dt>
2548	** <dd>The SQLITE_DBCONFIG_STMT_SCANSTATUS option is only useful in
2549	** SQLITE_ENABLE_STMT_SCANSTATUS builds. In this case, it sets or clears
2550	** a flag that enables collection of the sqlite3_stmt_scanstatus_v2()
2551	** statistics. For statistics to be collected, the flag must be set on
2552	** the database handle both when the SQL statement is prepared and when it
2553	** is stepped. The flag is set (collection of statistics is enabled)
2554	** by default. <p>This option takes two arguments: an integer and a pointer to
2555	** an integer.. The first argument is 1, 0, or -1 to enable, disable, or
2556	** leave unchanged the statement scanstatus option. If the second argument
2557	** is not NULL, then the value of the statement scanstatus setting after
2558	** processing the first argument is written into the integer that the second
2559	** argument points to.
2560	** </dd>
2561	**
2562	** [[SQLITE_DBCONFIG_REVERSE_SCANORDER]]
2563	** <dt>SQLITE_DBCONFIG_REVERSE_SCANORDER</dt>
2564	** <dd>The SQLITE_DBCONFIG_REVERSE_SCANORDER option changes the default order
2565	** in which tables and indexes are scanned so that the scans start at the end
2566	** and work toward the beginning rather than starting at the beginning and
2567	** working toward the end. Setting SQLITE_DBCONFIG_REVERSE_SCANORDER is the
2568	** same as setting [PRAGMA reverse_unordered_selects]. <p>This option takes
2569	** two arguments which are an integer and a pointer to an integer. The first
2570	** argument is 1, 0, or -1 to enable, disable, or leave unchanged the
2571	** reverse scan order flag, respectively. If the second argument is not NULL,
2572	** then 0 or 1 is written into the integer that the second argument points to
2573	** depending on if the reverse scan order flag is set after processing the
2574	** first argument.
2575	** </dd>
2576	**
2577	** [[SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE]]
2578	** <dt>SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE</dt>
2579	** <dd>The SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE option enables or disables
2580	** the ability of the [ATTACH DATABASE] SQL command to create a new database
2581	** file if the database filed named in the ATTACH command does not already
2582	** exist. This ability of ATTACH to create a new database is enabled by
2583	** default. Applications can disable or reenable the ability for ATTACH to
2584	** create new database files using this DBCONFIG option.<p>
2585	** This option takes two arguments which are an integer and a pointer
2586	** to an integer. The first argument is 1, 0, or -1 to enable, disable, or
2587	** leave unchanged the attach-create flag, respectively. If the second
2588	** argument is not NULL, then 0 or 1 is written into the integer that the
2589	** second argument points to depending on if the attach-create flag is set
2590	** after processing the first argument.
2591	** </dd>
2592	**
2593	** [[SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE]]
2594	** <dt>SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE</dt>
2595	** <dd>The SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE option enables or disables the
2596	** ability of the [ATTACH DATABASE] SQL command to open a database for writing.
2597	** This capability is enabled by default. Applications can disable or
2598	** reenable this capability using the current DBCONFIG option. If the
2599	** the this capability is disabled, the [ATTACH] command will still work,
2600	** but the database will be opened read-only. If this option is disabled,
2601	** then the ability to create a new database using [ATTACH] is also disabled,
2602	** regardless of the value of the [SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE]
2603	** option.<p>
2604	** This option takes two arguments which are an integer and a pointer
2605	** to an integer. The first argument is 1, 0, or -1 to enable, disable, or
2606	** leave unchanged the ability to ATTACH another database for writing,
2607	** respectively. If the second argument is not NULL, then 0 or 1 is written
2608	** into the integer to which the second argument points, depending on whether
2609	** the ability to ATTACH a read/write database is enabled or disabled
2610	** after processing the first argument.
2611	** </dd>
2612	**
2613	** [[SQLITE_DBCONFIG_ENABLE_COMMENTS]]
2614	** <dt>SQLITE_DBCONFIG_ENABLE_COMMENTS</dt>
2615	** <dd>The SQLITE_DBCONFIG_ENABLE_COMMENTS option enables or disables the
2616	** ability to include comments in SQL text. Comments are enabled by default.
2617	** An application can disable or reenable comments in SQL text using this
2618	** DBCONFIG option.<p>
2619	** This option takes two arguments which are an integer and a pointer
2620	** to an integer. The first argument is 1, 0, or -1 to enable, disable, or
2621	** leave unchanged the ability to use comments in SQL text,
2622	** respectively. If the second argument is not NULL, then 0 or 1 is written
2623	** into the integer that the second argument points to depending on if
2624	** comments are allowed in SQL text after processing the first argument.
2625	** </dd>
2626	**
2627	** </dl>
2628	**
2629	** [[DBCONFIG arguments]] <h3>Arguments To SQLITE_DBCONFIG Options</h3>
2630	**
2631	** <p>Most of the SQLITE_DBCONFIG options take two arguments, so that the
2632	** overall call to [sqlite3_db_config()] has a total of four parameters.
2633	** The first argument (the third parameter to sqlite3_db_config()) is a integer.
2634	** The second argument is a pointer to an integer. If the first argument is 1,
2635	** then the option becomes enabled. If the first integer argument is 0, then the
2636	** option is disabled. If the first argument is -1, then the option setting
2637	** is unchanged. The second argument, the pointer to an integer, may be NULL.
2638	** If the second argument is not NULL, then a value of 0 or 1 is written into
2639	** the integer to which the second argument points, depending on whether the
2640	** setting is disabled or enabled after applying any changes specified by
2641	** the first argument.
2642	**
2643	** <p>While most SQLITE_DBCONFIG options use the argument format
2644	** described in the previous paragraph, the [SQLITE_DBCONFIG_MAINDBNAME]
2645	** and [SQLITE_DBCONFIG_LOOKASIDE] options are different. See the
2646	** documentation of those exceptional options for details.
2647	*/
2648	#define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */
2649	#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
2650	#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
2651	#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
2652	#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
2653	#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
2654	#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */
2655	#define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */
2656	#define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */
2657	#define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */
2658	#define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */
2659	#define SQLITE_DBCONFIG_WRITABLE_SCHEMA 1011 /* int int* */
2660	#define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 1012 /* int int* */
2661	#define SQLITE_DBCONFIG_DQS_DML 1013 /* int int* */
2662	#define SQLITE_DBCONFIG_DQS_DDL 1014 /* int int* */
2663	#define SQLITE_DBCONFIG_ENABLE_VIEW 1015 /* int int* */
2664	#define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 1016 /* int int* */
2665	#define SQLITE_DBCONFIG_TRUSTED_SCHEMA 1017 /* int int* */
2666	#define SQLITE_DBCONFIG_STMT_SCANSTATUS 1018 /* int int* */
2667	#define SQLITE_DBCONFIG_REVERSE_SCANORDER 1019 /* int int* */
2668	#define SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE 1020 /* int int* */
2669	#define SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE 1021 /* int int* */
2670	#define SQLITE_DBCONFIG_ENABLE_COMMENTS 1022 /* int int* */
2671	#define SQLITE_DBCONFIG_MAX 1022 /* Largest DBCONFIG */
2672
2673	/*
2674	** CAPI3REF: Enable Or Disable Extended Result Codes
2675	** METHOD: sqlite3
2676	**
2677	** ^The sqlite3_extended_result_codes() routine enables or disables the
2678	** [extended result codes] feature of SQLite. ^The extended result
2679	** codes are disabled by default for historical compatibility.
2680	*/
2681	SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
2682
2683	/*
2684	** CAPI3REF: Last Insert Rowid
2685	** METHOD: sqlite3
2686	**
2687	** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
2688	** has a unique 64-bit signed
2689	** integer key called the [ROWID \| "rowid"]. ^The rowid is always available
2690	** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
2691	** names are not also used by explicitly declared columns. ^If
2692	** the table has a column of type [INTEGER PRIMARY KEY] then that column
2693	** is another alias for the rowid.
2694	**
2695	** ^The sqlite3_last_insert_rowid(D) interface usually returns the [rowid] of
2696	** the most recent successful [INSERT] into a rowid table or [virtual table]
2697	** on database connection D. ^Inserts into [WITHOUT ROWID] tables are not
2698	** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred
2699	** on the database connection D, then sqlite3_last_insert_rowid(D) returns
2700	** zero.
2701	**
2702	** As well as being set automatically as rows are inserted into database
2703	** tables, the value returned by this function may be set explicitly by
2704	** [sqlite3_set_last_insert_rowid()]
2705	**
2706	** Some virtual table implementations may INSERT rows into rowid tables as
2707	** part of committing a transaction (e.g. to flush data accumulated in memory
2708	** to disk). In this case subsequent calls to this function return the rowid
2709	** associated with these internal INSERT operations, which leads to
2710	** unintuitive results. Virtual table implementations that do write to rowid
2711	** tables in this way can avoid this problem by restoring the original
2712	** rowid value using [sqlite3_set_last_insert_rowid()] before returning
2713	** control to the user.
2714	**
2715	** ^(If an [INSERT] occurs within a trigger then this routine will
2716	** return the [rowid] of the inserted row as long as the trigger is
2717	** running. Once the trigger program ends, the value returned
2718	** by this routine reverts to what it was before the trigger was fired.)^
2719	**
2720	** ^An [INSERT] that fails due to a constraint violation is not a
2721	** successful [INSERT] and does not change the value returned by this
2722	** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
2723	** and INSERT OR ABORT make no changes to the return value of this
2724	** routine when their insertion fails. ^(When INSERT OR REPLACE
2725	** encounters a constraint violation, it does not fail. The
2726	** INSERT continues to completion after deleting rows that caused
2727	** the constraint problem so INSERT OR REPLACE will always change
2728	** the return value of this interface.)^
2729	**
2730	** ^For the purposes of this routine, an [INSERT] is considered to
2731	** be successful even if it is subsequently rolled back.
2732	**
2733	** This function is accessible to SQL statements via the
2734	** [last_insert_rowid() SQL function].
2735	**
2736	** If a separate thread performs a new [INSERT] on the same
2737	** database connection while the [sqlite3_last_insert_rowid()]
2738	** function is running and thus changes the last insert [rowid],
2739	** then the value returned by [sqlite3_last_insert_rowid()] is
2740	** unpredictable and might not equal either the old or the new
2741	** last insert [rowid].
2742	*/
2743	SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
2744
2745	/*
2746	** CAPI3REF: Set the Last Insert Rowid value.
2747	** METHOD: sqlite3
2748	**
2749	** The sqlite3_set_last_insert_rowid(D, R) method allows the application to
2750	** set the value returned by calling sqlite3_last_insert_rowid(D) to R
2751	** without inserting a row into the database.
2752	*/
2753	SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
2754
2755	/*
2756	** CAPI3REF: Count The Number Of Rows Modified
2757	** METHOD: sqlite3
2758	**
2759	** ^These functions return the number of rows modified, inserted or
2760	** deleted by the most recently completed INSERT, UPDATE or DELETE
2761	** statement on the database connection specified by the only parameter.
2762	** The two functions are identical except for the type of the return value
2763	** and that if the number of rows modified by the most recent INSERT, UPDATE,
2764	** or DELETE is greater than the maximum value supported by type "int", then
2765	** the return value of sqlite3_changes() is undefined. ^Executing any other
2766	** type of SQL statement does not modify the value returned by these functions.
2767	** For the purposes of this interface, a CREATE TABLE AS SELECT statement
2768	** does not count as an INSERT, UPDATE or DELETE statement and hence the rows
2769	** added to the new table by the CREATE TABLE AS SELECT statement are not
2770	** counted.
2771	**
2772	** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
2773	** considered - auxiliary changes caused by [CREATE TRIGGER \| triggers],
2774	** [foreign key actions] or [REPLACE] constraint resolution are not counted.
2775	**
2776	** Changes to a view that are intercepted by
2777	** [INSTEAD OF trigger \| INSTEAD OF triggers] are not counted. ^The value
2778	** returned by sqlite3_changes() immediately after an INSERT, UPDATE or
2779	** DELETE statement run on a view is always zero. Only changes made to real
2780	** tables are counted.
2781	**
2782	** Things are more complicated if the sqlite3_changes() function is
2783	** executed while a trigger program is running. This may happen if the
2784	** program uses the [changes() SQL function], or if some other callback
2785	** function invokes sqlite3_changes() directly. Essentially:
2786	**
2787	** <ul>
2788	** <li> ^(Before entering a trigger program the value returned by
2789	** sqlite3_changes() function is saved. After the trigger program
2790	** has finished, the original value is restored.)^
2791	**
2792	** <li> ^(Within a trigger program each INSERT, UPDATE and DELETE
2793	** statement sets the value returned by sqlite3_changes()
2794	** upon completion as normal. Of course, this value will not include
2795	** any changes performed by sub-triggers, as the sqlite3_changes()
2796	** value will be saved and restored after each sub-trigger has run.)^
2797	** </ul>
2798	**
2799	** ^This means that if the changes() SQL function (or similar) is used
2800	** by the first INSERT, UPDATE or DELETE statement within a trigger, it
2801	** returns the value as set when the calling statement began executing.
2802	** ^If it is used by the second or subsequent such statement within a trigger
2803	** program, the value returned reflects the number of rows modified by the
2804	** previous INSERT, UPDATE or DELETE statement within the same trigger.
2805	**
2806	** If a separate thread makes changes on the same database connection
2807	** while [sqlite3_changes()] is running then the value returned
2808	** is unpredictable and not meaningful.
2809	**
2810	** See also:
2811	** <ul>
2812	** <li> the [sqlite3_total_changes()] interface
2813	** <li> the [count_changes pragma]
2814	** <li> the [changes() SQL function]
2815	** <li> the [data_version pragma]
2816	** </ul>
2817	*/
2818	SQLITE_API int sqlite3_changes(sqlite3*);
2819	SQLITE_API sqlite3_int64 sqlite3_changes64(sqlite3*);
2820
2821	/*
2822	** CAPI3REF: Total Number Of Rows Modified
2823	** METHOD: sqlite3
2824	**
2825	** ^These functions return the total number of rows inserted, modified or
2826	** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed
2827	** since the database connection was opened, including those executed as
2828	** part of trigger programs. The two functions are identical except for the
2829	** type of the return value and that if the number of rows modified by the
2830	** connection exceeds the maximum value supported by type "int", then
2831	** the return value of sqlite3_total_changes() is undefined. ^Executing
2832	** any other type of SQL statement does not affect the value returned by
2833	** sqlite3_total_changes().
2834	**
2835	** ^Changes made as part of [foreign key actions] are included in the
2836	** count, but those made as part of REPLACE constraint resolution are
2837	** not. ^Changes to a view that are intercepted by INSTEAD OF triggers
2838	** are not counted.
2839	**
2840	** The [sqlite3_total_changes(D)] interface only reports the number
2841	** of rows that changed due to SQL statement run against database
2842	** connection D. Any changes by other database connections are ignored.
2843	** To detect changes against a database file from other database
2844	** connections use the [PRAGMA data_version] command or the
2845	** [SQLITE_FCNTL_DATA_VERSION] [file control].
2846	**
2847	** If a separate thread makes changes on the same database connection
2848	** while [sqlite3_total_changes()] is running then the value
2849	** returned is unpredictable and not meaningful.
2850	**
2851	** See also:
2852	** <ul>
2853	** <li> the [sqlite3_changes()] interface
2854	** <li> the [count_changes pragma]
2855	** <li> the [changes() SQL function]
2856	** <li> the [data_version pragma]
2857	** <li> the [SQLITE_FCNTL_DATA_VERSION] [file control]
2858	** </ul>
2859	*/
2860	SQLITE_API int sqlite3_total_changes(sqlite3*);
2861	SQLITE_API sqlite3_int64 sqlite3_total_changes64(sqlite3*);
2862
2863	/*
2864	** CAPI3REF: Interrupt A Long-Running Query
2865	** METHOD: sqlite3
2866	**
2867	** ^This function causes any pending database operation to abort and
2868	** return at its earliest opportunity. This routine is typically
2869	** called in response to a user action such as pressing "Cancel"
2870	** or Ctrl-C where the user wants a long query operation to halt
2871	** immediately.
2872	**
2873	** ^It is safe to call this routine from a thread different from the
2874	** thread that is currently running the database operation. But it
2875	** is not safe to call this routine with a [database connection] that
2876	** is closed or might close before sqlite3_interrupt() returns.
2877	**
2878	** ^If an SQL operation is very nearly finished at the time when
2879	** sqlite3_interrupt() is called, then it might not have an opportunity
2880	** to be interrupted and might continue to completion.
2881	**
2882	** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
2883	** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
2884	** that is inside an explicit transaction, then the entire transaction
2885	** will be rolled back automatically.
2886	**
2887	** ^The sqlite3_interrupt(D) call is in effect until all currently running
2888	** SQL statements on [database connection] D complete. ^Any new SQL statements
2889	** that are started after the sqlite3_interrupt() call and before the
2890	** running statement count reaches zero are interrupted as if they had been
2891	** running prior to the sqlite3_interrupt() call. ^New SQL statements
2892	** that are started after the running statement count reaches zero are
2893	** not effected by the sqlite3_interrupt().
2894	** ^A call to sqlite3_interrupt(D) that occurs when there are no running
2895	** SQL statements is a no-op and has no effect on SQL statements
2896	** that are started after the sqlite3_interrupt() call returns.
2897	**
2898	** ^The [sqlite3_is_interrupted(D)] interface can be used to determine whether
2899	** or not an interrupt is currently in effect for [database connection] D.
2900	** It returns 1 if an interrupt is currently in effect, or 0 otherwise.
2901	*/
2902	SQLITE_API void sqlite3_interrupt(sqlite3*);
2903	SQLITE_API int sqlite3_is_interrupted(sqlite3*);
2904
2905	/*
2906	** CAPI3REF: Determine If An SQL Statement Is Complete
2907	**
2908	** These routines are useful during command-line input to determine if the
2909	** currently entered text seems to form a complete SQL statement or
2910	** if additional input is needed before sending the text into
2911	** SQLite for parsing. ^These routines return 1 if the input string
2912	** appears to be a complete SQL statement. ^A statement is judged to be
2913	** complete if it ends with a semicolon token and is not a prefix of a
2914	** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within
2915	** string literals or quoted identifier names or comments are not
2916	** independent tokens (they are part of the token in which they are
2917	** embedded) and thus do not count as a statement terminator. ^Whitespace
2918	** and comments that follow the final semicolon are ignored.
2919	**
2920	** ^These routines return 0 if the statement is incomplete. ^If a
2921	** memory allocation fails, then SQLITE_NOMEM is returned.
2922	**
2923	** ^These routines do not parse the SQL statements thus
2924	** will not detect syntactically incorrect SQL.
2925	**
2926	** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior
2927	** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
2928	** automatically by sqlite3_complete16(). If that initialization fails,
2929	** then the return value from sqlite3_complete16() will be non-zero
2930	** regardless of whether or not the input SQL is complete.)^
2931	**
2932	** The input to [sqlite3_complete()] must be a zero-terminated
2933	** UTF-8 string.
2934	**
2935	** The input to [sqlite3_complete16()] must be a zero-terminated
2936	** UTF-16 string in native byte order.
2937	*/
2938	SQLITE_API int sqlite3_complete(const char *sql);
2939	SQLITE_API int sqlite3_complete16(const void *sql);
2940
2941	/*
2942	** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
2943	** KEYWORDS: {busy-handler callback} {busy handler}
2944	** METHOD: sqlite3
2945	**
2946	** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
2947	** that might be invoked with argument P whenever
2948	** an attempt is made to access a database table associated with
2949	** [database connection] D when another thread
2950	** or process has the table locked.
2951	** The sqlite3_busy_handler() interface is used to implement
2952	** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
2953	**
2954	** ^If the busy callback is NULL, then [SQLITE_BUSY]
2955	** is returned immediately upon encountering the lock. ^If the busy callback
2956	** is not NULL, then the callback might be invoked with two arguments.
2957	**
2958	** ^The first argument to the busy handler is a copy of the void* pointer which
2959	** is the third argument to sqlite3_busy_handler(). ^The second argument to
2960	** the busy handler callback is the number of times that the busy handler has
2961	** been invoked previously for the same locking event. ^If the
2962	** busy callback returns 0, then no additional attempts are made to
2963	** access the database and [SQLITE_BUSY] is returned
2964	** to the application.
2965	** ^If the callback returns non-zero, then another attempt
2966	** is made to access the database and the cycle repeats.
2967	**
2968	** The presence of a busy handler does not guarantee that it will be invoked
2969	** when there is lock contention. ^If SQLite determines that invoking the busy
2970	** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
2971	** to the application instead of invoking the
2972	** busy handler.
2973	** Consider a scenario where one process is holding a read lock that
2974	** it is trying to promote to a reserved lock and
2975	** a second process is holding a reserved lock that it is trying
2976	** to promote to an exclusive lock. The first process cannot proceed
2977	** because it is blocked by the second and the second process cannot
2978	** proceed because it is blocked by the first. If both processes
2979	** invoke the busy handlers, neither will make any progress. Therefore,
2980	** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
2981	** will induce the first process to release its read lock and allow
2982	** the second process to proceed.
2983	**
2984	** ^The default busy callback is NULL.
2985	**
2986	** ^(There can only be a single busy handler defined for each
2987	** [database connection]. Setting a new busy handler clears any
2988	** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
2989	** or evaluating [PRAGMA busy_timeout=N] will change the
2990	** busy handler and thus clear any previously set busy handler.
2991	**
2992	** The busy callback should not take any actions which modify the
2993	** database connection that invoked the busy handler. In other words,
2994	** the busy handler is not reentrant. Any such actions
2995	** result in undefined behavior.
2996	**
2997	** A busy handler must not close the database connection
2998	** or [prepared statement] that invoked the busy handler.
2999	*/
3000	SQLITE_API int sqlite3_busy_handler(sqlite3,int()(void,int),void);
3001
3002	/*
3003	** CAPI3REF: Set A Busy Timeout
3004	** METHOD: sqlite3
3005	**
3006	** ^This routine sets a [sqlite3_busy_handler \| busy handler] that sleeps
3007	** for a specified amount of time when a table is locked. ^The handler
3008	** will sleep multiple times until at least "ms" milliseconds of sleeping
3009	** have accumulated. ^After at least "ms" milliseconds of sleeping,
3010	** the handler returns 0 which causes [sqlite3_step()] to return
3011	** [SQLITE_BUSY].
3012	**
3013	** ^Calling this routine with an argument less than or equal to zero
3014	** turns off all busy handlers.
3015	**
3016	** ^(There can only be a single busy handler for a particular
3017	** [database connection] at any given moment. If another busy handler
3018	** was defined (using [sqlite3_busy_handler()]) prior to calling
3019	** this routine, that other busy handler is cleared.)^
3020	**
3021	** See also: [PRAGMA busy_timeout]
3022	*/
3023	SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
3024
3025	/*
3026	** CAPI3REF: Set the Setlk Timeout
3027	** METHOD: sqlite3
3028	**
3029	** This routine is only useful in SQLITE_ENABLE_SETLK_TIMEOUT builds. If
3030	** the VFS supports blocking locks, it sets the timeout in ms used by
3031	** eligible locks taken on wal mode databases by the specified database
3032	** handle. In non-SQLITE_ENABLE_SETLK_TIMEOUT builds, or if the VFS does
3033	** not support blocking locks, this function is a no-op.
3034	**
3035	** Passing 0 to this function disables blocking locks altogether. Passing
3036	** -1 to this function requests that the VFS blocks for a long time -
3037	** indefinitely if possible. The results of passing any other negative value
3038	** are undefined.
3039	**
3040	** Internally, each SQLite database handle store two timeout values - the
3041	** busy-timeout (used for rollback mode databases, or if the VFS does not
3042	** support blocking locks) and the setlk-timeout (used for blocking locks
3043	** on wal-mode databases). The sqlite3_busy_timeout() method sets both
3044	** values, this function sets only the setlk-timeout value. Therefore,
3045	** to configure separate busy-timeout and setlk-timeout values for a single
3046	** database handle, call sqlite3_busy_timeout() followed by this function.
3047	**
3048	** Whenever the number of connections to a wal mode database falls from
3049	** 1 to 0, the last connection takes an exclusive lock on the database,
3050	** then checkpoints and deletes the wal file. While it is doing this, any
3051	** new connection that tries to read from the database fails with an
3052	** SQLITE_BUSY error. Or, if the SQLITE_SETLK_BLOCK_ON_CONNECT flag is
3053	** passed to this API, the new connection blocks until the exclusive lock
3054	** has been released.
3055	*/
3056	SQLITE_API int sqlite3_setlk_timeout(sqlite3*, int ms, int flags);
3057
3058	/*
3059	** CAPI3REF: Flags for sqlite3_setlk_timeout()
3060	*/
3061	#define SQLITE_SETLK_BLOCK_ON_CONNECT 0x01
3062
3063	/*
3064	** CAPI3REF: Convenience Routines For Running Queries
3065	** METHOD: sqlite3
3066	**
3067	** This is a legacy interface that is preserved for backwards compatibility.
3068	** Use of this interface is not recommended.
3069	**
3070	** Definition: A <b>result table</b> is memory data structure created by the
3071	** [sqlite3_get_table()] interface. A result table records the
3072	** complete query results from one or more queries.
3073	**
3074	** The table conceptually has a number of rows and columns. But
3075	** these numbers are not part of the result table itself. These
3076	** numbers are obtained separately. Let N be the number of rows
3077	** and M be the number of columns.
3078	**
3079	** A result table is an array of pointers to zero-terminated UTF-8 strings.
3080	** There are (N+1)*M elements in the array. The first M pointers point
3081	** to zero-terminated strings that contain the names of the columns.
3082	** The remaining entries all point to query results. NULL values result
3083	** in NULL pointers. All other values are in their UTF-8 zero-terminated
3084	** string representation as returned by [sqlite3_column_text()].
3085	**
3086	** A result table might consist of one or more memory allocations.
3087	** It is not safe to pass a result table directly to [sqlite3_free()].
3088	** A result table should be deallocated using [sqlite3_free_table()].
3089	**
3090	** ^(As an example of the result table format, suppose a query result
3091	** is as follows:
3092	**
3093	** <blockquote><pre>
3094	** Name \| Age
3095	** -----------------------
3096	** Alice \| 43
3097	** Bob \| 28
3098	** Cindy \| 21
3099	** </pre></blockquote>
3100	**
3101	** There are two columns (M==2) and three rows (N==3). Thus the
3102	** result table has 8 entries. Suppose the result table is stored
3103	** in an array named azResult. Then azResult holds this content:
3104	**
3105	** <blockquote><pre>
3106	** azResult[0] = "Name";
3107	** azResult[1] = "Age";
3108	** azResult[2] = "Alice";
3109	** azResult[3] = "43";
3110	** azResult[4] = "Bob";
3111	** azResult[5] = "28";
3112	** azResult[6] = "Cindy";
3113	** azResult[7] = "21";
3114	** </pre></blockquote>)^
3115	**
3116	** ^The sqlite3_get_table() function evaluates one or more
3117	** semicolon-separated SQL statements in the zero-terminated UTF-8
3118	** string of its 2nd parameter and returns a result table to the
3119	** pointer given in its 3rd parameter.
3120	**
3121	** After the application has finished with the result from sqlite3_get_table(),
3122	** it must pass the result table pointer to sqlite3_free_table() in order to
3123	** release the memory that was malloced. Because of the way the
3124	** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
3125	** function must not try to call [sqlite3_free()] directly. Only
3126	** [sqlite3_free_table()] is able to release the memory properly and safely.
3127	**
3128	** The sqlite3_get_table() interface is implemented as a wrapper around
3129	** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
3130	** to any internal data structures of SQLite. It uses only the public
3131	** interface defined here. As a consequence, errors that occur in the
3132	** wrapper layer outside of the internal [sqlite3_exec()] call are not
3133	** reflected in subsequent calls to [sqlite3_errcode()] or
3134	** [sqlite3_errmsg()].
3135	*/
3136	SQLITE_API int sqlite3_get_table(
3137	sqlite3 db, / An open database */
3138	const char zSql, / SQL to be evaluated */
3139	char **pazResult, / Results of the query */
3140	int pnRow, / Number of result rows written here */
3141	int pnColumn, / Number of result columns written here */
3142	char *pzErrmsg / Error msg written here */
3143	);
3144	SQLITE_API void sqlite3_free_table(char **result);
3145
3146	/*
3147	** CAPI3REF: Formatted String Printing Functions
3148	**
3149	** These routines are work-alikes of the "printf()" family of functions
3150	** from the standard C library.
3151	** These routines understand most of the common formatting options from
3152	** the standard library printf()
3153	** plus some additional non-standard formats ([%q], [%Q], [%w], and [%z]).
3154	** See the [built-in printf()] documentation for details.
3155	**
3156	** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
3157	** results into memory obtained from [sqlite3_malloc64()].
3158	** The strings returned by these two routines should be
3159	** released by [sqlite3_free()]. ^Both routines return a
3160	** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough
3161	** memory to hold the resulting string.
3162	**
3163	** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
3164	** the standard C library. The result is written into the
3165	** buffer supplied as the second parameter whose size is given by
3166	** the first parameter. Note that the order of the
3167	** first two parameters is reversed from snprintf().)^ This is an
3168	** historical accident that cannot be fixed without breaking
3169	** backwards compatibility. ^(Note also that sqlite3_snprintf()
3170	** returns a pointer to its buffer instead of the number of
3171	** characters actually written into the buffer.)^ We admit that
3172	** the number of characters written would be a more useful return
3173	** value but we cannot change the implementation of sqlite3_snprintf()
3174	** now without breaking compatibility.
3175	**
3176	** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
3177	** guarantees that the buffer is always zero-terminated. ^The first
3178	** parameter "n" is the total size of the buffer, including space for
3179	** the zero terminator. So the longest string that can be completely
3180	** written will be n-1 characters.
3181	**
3182	** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
3183	**
3184	** See also: [built-in printf()], [printf() SQL function]
3185	*/
3186	SQLITE_API char sqlite3_mprintf(const char,...);
3187	SQLITE_API char sqlite3_vmprintf(const char, va_list);
3188	SQLITE_API char sqlite3_snprintf(int,char,const char*, ...);
3189	SQLITE_API char sqlite3_vsnprintf(int,char,const char*, va_list);
3190
3191	/*
3192	** CAPI3REF: Memory Allocation Subsystem
3193	**
3194	** The SQLite core uses these three routines for all of its own
3195	** internal memory allocation needs. "Core" in the previous sentence
3196	** does not include operating-system specific [VFS] implementation. The
3197	** Windows VFS uses native malloc() and free() for some operations.
3198	**
3199	** ^The sqlite3_malloc() routine returns a pointer to a block
3200	** of memory at least N bytes in length, where N is the parameter.
3201	** ^If sqlite3_malloc() is unable to obtain sufficient free
3202	** memory, it returns a NULL pointer. ^If the parameter N to
3203	** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
3204	** a NULL pointer.
3205	**
3206	** ^The sqlite3_malloc64(N) routine works just like
3207	** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
3208	** of a signed 32-bit integer.
3209	**
3210	** ^Calling sqlite3_free() with a pointer previously returned
3211	** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
3212	** that it might be reused. ^The sqlite3_free() routine is
3213	** a no-op if is called with a NULL pointer. Passing a NULL pointer
3214	** to sqlite3_free() is harmless. After being freed, memory
3215	** should neither be read nor written. Even reading previously freed
3216	** memory might result in a segmentation fault or other severe error.
3217	** Memory corruption, a segmentation fault, or other severe error
3218	** might result if sqlite3_free() is called with a non-NULL pointer that
3219	** was not obtained from sqlite3_malloc() or sqlite3_realloc().
3220	**
3221	** ^The sqlite3_realloc(X,N) interface attempts to resize a
3222	** prior memory allocation X to be at least N bytes.
3223	** ^If the X parameter to sqlite3_realloc(X,N)
3224	** is a NULL pointer then its behavior is identical to calling
3225	** sqlite3_malloc(N).
3226	** ^If the N parameter to sqlite3_realloc(X,N) is zero or
3227	** negative then the behavior is exactly the same as calling
3228	** sqlite3_free(X).
3229	** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
3230	** of at least N bytes in size or NULL if insufficient memory is available.
3231	** ^If M is the size of the prior allocation, then min(N,M) bytes
3232	** of the prior allocation are copied into the beginning of buffer returned
3233	** by sqlite3_realloc(X,N) and the prior allocation is freed.
3234	** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
3235	** prior allocation is not freed.
3236	**
3237	** ^The sqlite3_realloc64(X,N) interfaces works the same as
3238	** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
3239	** of a 32-bit signed integer.
3240	**
3241	** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
3242	** sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
3243	** sqlite3_msize(X) returns the size of that memory allocation in bytes.
3244	** ^The value returned by sqlite3_msize(X) might be larger than the number
3245	** of bytes requested when X was allocated. ^If X is a NULL pointer then
3246	** sqlite3_msize(X) returns zero. If X points to something that is not
3247	** the beginning of memory allocation, or if it points to a formerly
3248	** valid memory allocation that has now been freed, then the behavior
3249	** of sqlite3_msize(X) is undefined and possibly harmful.
3250	**
3251	** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(),
3252	** sqlite3_malloc64(), and sqlite3_realloc64()
3253	** is always aligned to at least an 8 byte boundary, or to a
3254	** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
3255	** option is used.
3256	**
3257	** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
3258	** must be either NULL or else pointers obtained from a prior
3259	** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
3260	** not yet been released.
3261	**
3262	** The application must not read or write any part of
3263	** a block of memory after it has been released using
3264	** [sqlite3_free()] or [sqlite3_realloc()].
3265	*/
3266	SQLITE_API void *sqlite3_malloc(int);
3267	SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);
3268	SQLITE_API void sqlite3_realloc(void, int);
3269	SQLITE_API void sqlite3_realloc64(void, sqlite3_uint64);
3270	SQLITE_API void sqlite3_free(void*);
3271	SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
3272
3273	/*
3274	** CAPI3REF: Memory Allocator Statistics
3275	**
3276	** SQLite provides these two interfaces for reporting on the status
3277	** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
3278	** routines, which form the built-in memory allocation subsystem.
3279	**
3280	** ^The [sqlite3_memory_used()] routine returns the number of bytes
3281	** of memory currently outstanding (malloced but not freed).
3282	** ^The [sqlite3_memory_highwater()] routine returns the maximum
3283	** value of [sqlite3_memory_used()] since the high-water mark
3284	** was last reset. ^The values returned by [sqlite3_memory_used()] and
3285	** [sqlite3_memory_highwater()] include any overhead
3286	** added by SQLite in its implementation of [sqlite3_malloc()],
3287	** but not overhead added by the any underlying system library
3288	** routines that [sqlite3_malloc()] may call.
3289	**
3290	** ^The memory high-water mark is reset to the current value of
3291	** [sqlite3_memory_used()] if and only if the parameter to
3292	** [sqlite3_memory_highwater()] is true. ^The value returned
3293	** by [sqlite3_memory_highwater(1)] is the high-water mark
3294	** prior to the reset.
3295	*/
3296	SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
3297	SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
3298
3299	/*
3300	** CAPI3REF: Pseudo-Random Number Generator
3301	**
3302	** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
3303	** select random [ROWID \| ROWIDs] when inserting new records into a table that
3304	** already uses the largest possible [ROWID]. The PRNG is also used for
3305	** the built-in random() and randomblob() SQL functions. This interface allows
3306	** applications to access the same PRNG for other purposes.
3307	**
3308	** ^A call to this routine stores N bytes of randomness into buffer P.
3309	** ^The P parameter can be a NULL pointer.
3310	**
3311	** ^If this routine has not been previously called or if the previous
3312	** call had N less than one or a NULL pointer for P, then the PRNG is
3313	** seeded using randomness obtained from the xRandomness method of
3314	** the default [sqlite3_vfs] object.
3315	** ^If the previous call to this routine had an N of 1 or more and a
3316	** non-NULL P then the pseudo-randomness is generated
3317	** internally and without recourse to the [sqlite3_vfs] xRandomness
3318	** method.
3319	*/
3320	SQLITE_API void sqlite3_randomness(int N, void *P);
3321
3322	/*
3323	** CAPI3REF: Compile-Time Authorization Callbacks
3324	** METHOD: sqlite3
3325	** KEYWORDS: {authorizer callback}
3326	**
3327	** ^This routine registers an authorizer callback with a particular
3328	** [database connection], supplied in the first argument.
3329	** ^The authorizer callback is invoked as SQL statements are being compiled
3330	** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
3331	** [sqlite3_prepare_v3()], [sqlite3_prepare16()], [sqlite3_prepare16_v2()],
3332	** and [sqlite3_prepare16_v3()]. ^At various
3333	** points during the compilation process, as logic is being created
3334	** to perform various actions, the authorizer callback is invoked to
3335	** see if those actions are allowed. ^The authorizer callback should
3336	** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
3337	** specific action but allow the SQL statement to continue to be
3338	** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
3339	** rejected with an error. ^If the authorizer callback returns
3340	** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
3341	** then the [sqlite3_prepare_v2()] or equivalent call that triggered
3342	** the authorizer will fail with an error message.
3343	**
3344	** When the callback returns [SQLITE_OK], that means the operation
3345	** requested is ok. ^When the callback returns [SQLITE_DENY], the
3346	** [sqlite3_prepare_v2()] or equivalent call that triggered the
3347	** authorizer will fail with an error message explaining that
3348	** access is denied.
3349	**
3350	** ^The first parameter to the authorizer callback is a copy of the third
3351	** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
3352	** to the callback is an integer [SQLITE_COPY \| action code] that specifies
3353	** the particular action to be authorized. ^The third through sixth parameters
3354	** to the callback are either NULL pointers or zero-terminated strings
3355	** that contain additional details about the action to be authorized.
3356	** Applications must always be prepared to encounter a NULL pointer in any
3357	** of the third through the sixth parameters of the authorization callback.
3358	**
3359	** ^If the action code is [SQLITE_READ]
3360	** and the callback returns [SQLITE_IGNORE] then the
3361	** [prepared statement] statement is constructed to substitute
3362	** a NULL value in place of the table column that would have
3363	** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
3364	** return can be used to deny an untrusted user access to individual
3365	** columns of a table.
3366	** ^When a table is referenced by a [SELECT] but no column values are
3367	** extracted from that table (for example in a query like
3368	** "SELECT count(*) FROM tab") then the [SQLITE_READ] authorizer callback
3369	** is invoked once for that table with a column name that is an empty string.
3370	** ^If the action code is [SQLITE_DELETE] and the callback returns
3371	** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
3372	** [truncate optimization] is disabled and all rows are deleted individually.
3373	**
3374	** An authorizer is used when [sqlite3_prepare \| preparing]
3375	** SQL statements from an untrusted source, to ensure that the SQL statements
3376	** do not try to access data they are not allowed to see, or that they do not
3377	** try to execute malicious statements that damage the database. For
3378	** example, an application may allow a user to enter arbitrary
3379	** SQL queries for evaluation by a database. But the application does
3380	** not want the user to be able to make arbitrary changes to the
3381	** database. An authorizer could then be put in place while the
3382	** user-entered SQL is being [sqlite3_prepare \| prepared] that
3383	** disallows everything except [SELECT] statements.
3384	**
3385	** Applications that need to process SQL from untrusted sources
3386	** might also consider lowering resource limits using [sqlite3_limit()]
3387	** and limiting database size using the [max_page_count] [PRAGMA]
3388	** in addition to using an authorizer.
3389	**
3390	** ^(Only a single authorizer can be in place on a database connection
3391	** at a time. Each call to sqlite3_set_authorizer overrides the
3392	** previous call.)^ ^Disable the authorizer by installing a NULL callback.
3393	** The authorizer is disabled by default.
3394	**
3395	** The authorizer callback must not do anything that will modify
3396	** the database connection that invoked the authorizer callback.
3397	** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
3398	** database connections for the meaning of "modify" in this paragraph.
3399	**
3400	** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
3401	** statement might be re-prepared during [sqlite3_step()] due to a
3402	** schema change. Hence, the application should ensure that the
3403	** correct authorizer callback remains in place during the [sqlite3_step()].
3404	**
3405	** ^Note that the authorizer callback is invoked only during
3406	** [sqlite3_prepare()] or its variants. Authorization is not
3407	** performed during statement evaluation in [sqlite3_step()], unless
3408	** as stated in the previous paragraph, sqlite3_step() invokes
3409	** sqlite3_prepare_v2() to reprepare a statement after a schema change.
3410	*/
3411	SQLITE_API int sqlite3_set_authorizer(
3412	sqlite3*,
3413	int (xAuth)(void,int,const char,const char,const char,const char),
3414	void *pUserData
3415	);
3416
3417	/*
3418	** CAPI3REF: Authorizer Return Codes
3419	**
3420	** The [sqlite3_set_authorizer \| authorizer callback function] must
3421	** return either [SQLITE_OK] or one of these two constants in order
3422	** to signal SQLite whether or not the action is permitted. See the
3423	** [sqlite3_set_authorizer \| authorizer documentation] for additional
3424	** information.
3425	**
3426	** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
3427	** returned from the [sqlite3_vtab_on_conflict()] interface.
3428	*/
3429	#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
3430	#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
3431
3432	/*
3433	** CAPI3REF: Authorizer Action Codes
3434	**
3435	** The [sqlite3_set_authorizer()] interface registers a callback function
3436	** that is invoked to authorize certain SQL statement actions. The
3437	** second parameter to the callback is an integer code that specifies
3438	** what action is being authorized. These are the integer action codes that
3439	** the authorizer callback may be passed.
3440	**
3441	** These action code values signify what kind of operation is to be
3442	** authorized. The 3rd and 4th parameters to the authorization
3443	** callback function will be parameters or NULL depending on which of these
3444	** codes is used as the second parameter. ^(The 5th parameter to the
3445	** authorizer callback is the name of the database ("main", "temp",
3446	** etc.) if applicable.)^ ^The 6th parameter to the authorizer callback
3447	** is the name of the inner-most trigger or view that is responsible for
3448	** the access attempt or NULL if this access attempt is directly from
3449	** top-level SQL code.
3450	*/
3451	/***************************************** 3rd ******** 4th *********/
3452	#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
3453	#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
3454	#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
3455	#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
3456	#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
3457	#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
3458	#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
3459	#define SQLITE_CREATE_VIEW 8 /* View Name NULL */
3460	#define SQLITE_DELETE 9 /* Table Name NULL */
3461	#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
3462	#define SQLITE_DROP_TABLE 11 /* Table Name NULL */
3463	#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
3464	#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
3465	#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
3466	#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
3467	#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
3468	#define SQLITE_DROP_VIEW 17 /* View Name NULL */
3469	#define SQLITE_INSERT 18 /* Table Name NULL */
3470	#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
3471	#define SQLITE_READ 20 /* Table Name Column Name */
3472	#define SQLITE_SELECT 21 /* NULL NULL */
3473	#define SQLITE_TRANSACTION 22 /* Operation NULL */
3474	#define SQLITE_UPDATE 23 /* Table Name Column Name */
3475	#define SQLITE_ATTACH 24 /* Filename NULL */
3476	#define SQLITE_DETACH 25 /* Database Name NULL */
3477	#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
3478	#define SQLITE_REINDEX 27 /* Index Name NULL */
3479	#define SQLITE_ANALYZE 28 /* Table Name NULL */
3480	#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
3481	#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
3482	#define SQLITE_FUNCTION 31 /* NULL Function Name */
3483	#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
3484	#define SQLITE_COPY 0 /* No longer used */
3485	#define SQLITE_RECURSIVE 33 /* NULL NULL */
3486
3487	/*
3488	** CAPI3REF: Deprecated Tracing And Profiling Functions
3489	** DEPRECATED
3490	**
3491	** These routines are deprecated. Use the [sqlite3_trace_v2()] interface
3492	** instead of the routines described here.
3493	**
3494	** These routines register callback functions that can be used for
3495	** tracing and profiling the execution of SQL statements.
3496	**
3497	** ^The callback function registered by sqlite3_trace() is invoked at
3498	** various times when an SQL statement is being run by [sqlite3_step()].
3499	** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
3500	** SQL statement text as the statement first begins executing.
3501	** ^(Additional sqlite3_trace() callbacks might occur
3502	** as each triggered subprogram is entered. The callbacks for triggers
3503	** contain a UTF-8 SQL comment that identifies the trigger.)^
3504	**
3505	** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
3506	** the length of [bound parameter] expansion in the output of sqlite3_trace().
3507	**
3508	** ^The callback function registered by sqlite3_profile() is invoked
3509	** as each SQL statement finishes. ^The profile callback contains
3510	** the original statement text and an estimate of wall-clock time
3511	** of how long that statement took to run. ^The profile callback
3512	** time is in units of nanoseconds, however the current implementation
3513	** is only capable of millisecond resolution so the six least significant
3514	** digits in the time are meaningless. Future versions of SQLite
3515	** might provide greater resolution on the profiler callback. Invoking
3516	** either [sqlite3_trace()] or [sqlite3_trace_v2()] will cancel the
3517	** profile callback.
3518	*/
3519	SQLITE_API SQLITE_DEPRECATED void sqlite3_trace(sqlite3,
3520	void(xTrace)(void,const char), void);
3521	SQLITE_API SQLITE_DEPRECATED void sqlite3_profile(sqlite3,
3522	void(xProfile)(void,const char,sqlite3_uint64), void);
3523
3524	/*
3525	** CAPI3REF: SQL Trace Event Codes
3526	** KEYWORDS: SQLITE_TRACE
3527	**
3528	** These constants identify classes of events that can be monitored
3529	** using the [sqlite3_trace_v2()] tracing logic. The M argument
3530	** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
3531	** the following constants. ^The first argument to the trace callback
3532	** is one of the following constants.
3533	**
3534	** New tracing constants may be added in future releases.
3535	**
3536	** ^A trace callback has four arguments: xCallback(T,C,P,X).
3537	** ^The T argument is one of the integer type codes above.
3538	** ^The C argument is a copy of the context pointer passed in as the
3539	** fourth argument to [sqlite3_trace_v2()].
3540	** The P and X arguments are pointers whose meanings depend on T.
3541	**
3542	** <dl>
3543	** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt>
3544	** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
3545	** first begins running and possibly at other times during the
3546	** execution of the prepared statement, such as at the start of each
3547	** trigger subprogram. ^The P argument is a pointer to the
3548	** [prepared statement]. ^The X argument is a pointer to a string which
3549	** is the unexpanded SQL text of the prepared statement or an SQL comment
3550	** that indicates the invocation of a trigger. ^The callback can compute
3551	** the same text that would have been returned by the legacy [sqlite3_trace()]
3552	** interface by using the X argument when X begins with "--" and invoking
3553	** [sqlite3_expanded_sql(P)] otherwise.
3554	**
3555	** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
3556	** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
3557	** information as is provided by the [sqlite3_profile()] callback.
3558	** ^The P argument is a pointer to the [prepared statement] and the
3559	** X argument points to a 64-bit integer which is approximately
3560	** the number of nanoseconds that the prepared statement took to run.
3561	** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
3562	**
3563	** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
3564	** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
3565	** statement generates a single row of result.
3566	** ^The P argument is a pointer to the [prepared statement] and the
3567	** X argument is unused.
3568	**
3569	** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt>
3570	** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
3571	** connection closes.
3572	** ^The P argument is a pointer to the [database connection] object
3573	** and the X argument is unused.
3574	** </dl>
3575	*/
3576	#define SQLITE_TRACE_STMT 0x01
3577	#define SQLITE_TRACE_PROFILE 0x02
3578	#define SQLITE_TRACE_ROW 0x04
3579	#define SQLITE_TRACE_CLOSE 0x08
3580
3581	/*
3582	** CAPI3REF: SQL Trace Hook
3583	** METHOD: sqlite3
3584	**
3585	** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
3586	** function X against [database connection] D, using property mask M
3587	** and context pointer P. ^If the X callback is
3588	** NULL or if the M mask is zero, then tracing is disabled. The
3589	** M argument should be the bitwise OR-ed combination of
3590	** zero or more [SQLITE_TRACE] constants.
3591	**
3592	** ^Each call to either sqlite3_trace(D,X,P) or sqlite3_trace_v2(D,M,X,P)
3593	** overrides (cancels) all prior calls to sqlite3_trace(D,X,P) or
3594	** sqlite3_trace_v2(D,M,X,P) for the [database connection] D. Each
3595	** database connection may have at most one trace callback.
3596	**
3597	** ^The X callback is invoked whenever any of the events identified by
3598	** mask M occur. ^The integer return value from the callback is currently
3599	** ignored, though this may change in future releases. Callback
3600	** implementations should return zero to ensure future compatibility.
3601	**
3602	** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
3603	** ^The T argument is one of the [SQLITE_TRACE]
3604	** constants to indicate why the callback was invoked.
3605	** ^The C argument is a copy of the context pointer.
3606	** The P and X arguments are pointers whose meanings depend on T.
3607	**
3608	** The sqlite3_trace_v2() interface is intended to replace the legacy
3609	** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which
3610	** are deprecated.
3611	*/
3612	SQLITE_API int sqlite3_trace_v2(
3613	sqlite3*,
3614	unsigned uMask,
3615	int(xCallback)(unsigned,void,void,void),
3616	void *pCtx
3617	);
3618
3619	/*
3620	** CAPI3REF: Query Progress Callbacks
3621	** METHOD: sqlite3
3622	**
3623	** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
3624	** function X to be invoked periodically during long running calls to
3625	** [sqlite3_step()] and [sqlite3_prepare()] and similar for
3626	** database connection D. An example use for this
3627	** interface is to keep a GUI updated during a large query.
3628	**
3629	** ^The parameter P is passed through as the only parameter to the
3630	** callback function X. ^The parameter N is the approximate number of
3631	** [virtual machine instructions] that are evaluated between successive
3632	** invocations of the callback X. ^If N is less than one then the progress
3633	** handler is disabled.
3634	**
3635	** ^Only a single progress handler may be defined at one time per
3636	** [database connection]; setting a new progress handler cancels the
3637	** old one. ^Setting parameter X to NULL disables the progress handler.
3638	** ^The progress handler is also disabled by setting N to a value less
3639	** than 1.
3640	**
3641	** ^If the progress callback returns non-zero, the operation is
3642	** interrupted. This feature can be used to implement a
3643	** "Cancel" button on a GUI progress dialog box.
3644	**
3645	** The progress handler callback must not do anything that will modify
3646	** the database connection that invoked the progress handler.
3647	** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
3648	** database connections for the meaning of "modify" in this paragraph.
3649	**
3650	** The progress handler callback would originally only be invoked from the
3651	** bytecode engine. It still might be invoked during [sqlite3_prepare()]
3652	** and similar because those routines might force a reparse of the schema
3653	** which involves running the bytecode engine. However, beginning with
3654	** SQLite version 3.41.0, the progress handler callback might also be
3655	** invoked directly from [sqlite3_prepare()] while analyzing and generating
3656	** code for complex queries.
3657	*/
3658	SQLITE_API void sqlite3_progress_handler(sqlite3, int, int()(void), void);
3659
3660	/*
3661	** CAPI3REF: Opening A New Database Connection
3662	** CONSTRUCTOR: sqlite3
3663	**
3664	** ^These routines open an SQLite database file as specified by the
3665	** filename argument. ^The filename argument is interpreted as UTF-8 for
3666	** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
3667	** order for sqlite3_open16(). ^(A [database connection] handle is usually
3668	** returned in *ppDb, even if an error occurs. The only exception is that
3669	** if SQLite is unable to allocate memory to hold the [sqlite3] object,
3670	** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
3671	** object.)^ ^(If the database is opened (and/or created) successfully, then
3672	** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The
3673	** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
3674	** an English language description of the error following a failure of any
3675	** of the sqlite3_open() routines.
3676	**
3677	** ^The default encoding will be UTF-8 for databases created using
3678	** sqlite3_open() or sqlite3_open_v2(). ^The default encoding for databases
3679	** created using sqlite3_open16() will be UTF-16 in the native byte order.
3680	**
3681	** Whether or not an error occurs when it is opened, resources
3682	** associated with the [database connection] handle should be released by
3683	** passing it to [sqlite3_close()] when it is no longer required.
3684	**
3685	** The sqlite3_open_v2() interface works like sqlite3_open()
3686	** except that it accepts two additional parameters for additional control
3687	** over the new database connection. ^(The flags parameter to
3688	** sqlite3_open_v2() must include, at a minimum, one of the following
3689	** three flag combinations:)^
3690	**
3691	** <dl>
3692	** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
3693	** <dd>The database is opened in read-only mode. If the database does
3694	** not already exist, an error is returned.</dd>)^
3695	**
3696	** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
3697	** <dd>The database is opened for reading and writing if possible, or
3698	** reading only if the file is write protected by the operating
3699	** system. In either case the database must already exist, otherwise
3700	** an error is returned. For historical reasons, if opening in
3701	** read-write mode fails due to OS-level permissions, an attempt is
3702	** made to open it in read-only mode. [sqlite3_db_readonly()] can be
3703	** used to determine whether the database is actually
3704	** read-write.</dd>)^
3705	**
3706	** ^(<dt>[SQLITE_OPEN_READWRITE] \| [SQLITE_OPEN_CREATE]</dt>
3707	** <dd>The database is opened for reading and writing, and is created if
3708	** it does not already exist. This is the behavior that is always used for
3709	** sqlite3_open() and sqlite3_open16().</dd>)^
3710	** </dl>
3711	**
3712	** In addition to the required flags, the following optional flags are
3713	** also supported:
3714	**
3715	** <dl>
3716	** ^(<dt>[SQLITE_OPEN_URI]</dt>
3717	** <dd>The filename can be interpreted as a URI if this flag is set.</dd>)^
3718	**
3719	** ^(<dt>[SQLITE_OPEN_MEMORY]</dt>
3720	** <dd>The database will be opened as an in-memory database. The database
3721	** is named by the "filename" argument for the purposes of cache-sharing,
3722	** if shared cache mode is enabled, but the "filename" is otherwise ignored.
3723	** </dd>)^
3724	**
3725	** ^(<dt>[SQLITE_OPEN_NOMUTEX]</dt>
3726	** <dd>The new database connection will use the "multi-thread"
3727	** [threading mode].)^ This means that separate threads are allowed
3728	** to use SQLite at the same time, as long as each thread is using
3729	** a different [database connection].
3730	**
3731	** ^(<dt>[SQLITE_OPEN_FULLMUTEX]</dt>
3732	** <dd>The new database connection will use the "serialized"
3733	** [threading mode].)^ This means the multiple threads can safely
3734	** attempt to use the same database connection at the same time.
3735	** (Mutexes will block any actual concurrency, but in this mode
3736	** there is no harm in trying.)
3737	**
3738	** ^(<dt>[SQLITE_OPEN_SHAREDCACHE]</dt>
3739	** <dd>The database is opened [shared cache] enabled, overriding
3740	** the default shared cache setting provided by
3741	** [sqlite3_enable_shared_cache()].)^
3742	** The [use of shared cache mode is discouraged] and hence shared cache
3743	** capabilities may be omitted from many builds of SQLite. In such cases,
3744	** this option is a no-op.
3745	**
3746	** ^(<dt>[SQLITE_OPEN_PRIVATECACHE]</dt>
3747	** <dd>The database is opened [shared cache] disabled, overriding
3748	** the default shared cache setting provided by
3749	** [sqlite3_enable_shared_cache()].)^
3750	**
3751	** [[OPEN_EXRESCODE]] ^(<dt>[SQLITE_OPEN_EXRESCODE]</dt>
3752	** <dd>The database connection comes up in "extended result code mode".
3753	** In other words, the database behaves as if
3754	** [sqlite3_extended_result_codes(db,1)] were called on the database
3755	** connection as soon as the connection is created. In addition to setting
3756	** the extended result code mode, this flag also causes [sqlite3_open_v2()]
3757	** to return an extended result code.</dd>
3758	**
3759	** [[OPEN_NOFOLLOW]] ^(<dt>[SQLITE_OPEN_NOFOLLOW]</dt>
3760	** <dd>The database filename is not allowed to contain a symbolic link</dd>
3761	** </dl>)^
3762	**
3763	** If the 3rd parameter to sqlite3_open_v2() is not one of the
3764	** required combinations shown above optionally combined with other
3765	** [SQLITE_OPEN_READONLY \| SQLITE_OPEN_* bits]
3766	** then the behavior is undefined. Historic versions of SQLite
3767	** have silently ignored surplus bits in the flags parameter to
3768	** sqlite3_open_v2(), however that behavior might not be carried through
3769	** into future versions of SQLite and so applications should not rely
3770	** upon it. Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op
3771	** for sqlite3_open_v2(). The SQLITE_OPEN_EXCLUSIVE does not cause
3772	** the open to fail if the database already exists. The SQLITE_OPEN_EXCLUSIVE
3773	** flag is intended for use by the [sqlite3_vfs\|VFS interface] only, and not
3774	** by sqlite3_open_v2().
3775	**
3776	** ^The fourth parameter to sqlite3_open_v2() is the name of the
3777	** [sqlite3_vfs] object that defines the operating system interface that
3778	** the new database connection should use. ^If the fourth parameter is
3779	** a NULL pointer then the default [sqlite3_vfs] object is used.
3780	**
3781	** ^If the filename is ":memory:", then a private, temporary in-memory database
3782	** is created for the connection. ^This in-memory database will vanish when
3783	** the database connection is closed. Future versions of SQLite might
3784	** make use of additional special filenames that begin with the ":" character.
3785	** It is recommended that when a database filename actually does begin with
3786	** a ":" character you should prefix the filename with a pathname such as
3787	** "./" to avoid ambiguity.
3788	**
3789	** ^If the filename is an empty string, then a private, temporary
3790	** on-disk database will be created. ^This private database will be
3791	** automatically deleted as soon as the database connection is closed.
3792	**
3793	** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
3794	**
3795	** ^If [URI filename] interpretation is enabled, and the filename argument
3796	** begins with "file:", then the filename is interpreted as a URI. ^URI
3797	** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
3798	** set in the third argument to sqlite3_open_v2(), or if it has
3799	** been enabled globally using the [SQLITE_CONFIG_URI] option with the
3800	** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
3801	** URI filename interpretation is turned off
3802	** by default, but future releases of SQLite might enable URI filename
3803	** interpretation by default. See "[URI filenames]" for additional
3804	** information.
3805	**
3806	** URI filenames are parsed according to RFC 3986. ^If the URI contains an
3807	** authority, then it must be either an empty string or the string
3808	** "localhost". ^If the authority is not an empty string or "localhost", an
3809	** error is returned to the caller. ^The fragment component of a URI, if
3810	** present, is ignored.
3811	**
3812	** ^SQLite uses the path component of the URI as the name of the disk file
3813	** which contains the database. ^If the path begins with a '/' character,
3814	** then it is interpreted as an absolute path. ^If the path does not begin
3815	** with a '/' (meaning that the authority section is omitted from the URI)
3816	** then the path is interpreted as a relative path.
3817	** ^(On windows, the first component of an absolute path
3818	** is a drive specification (e.g. "C:").)^
3819	**
3820	** [[core URI query parameters]]
3821	** The query component of a URI may contain parameters that are interpreted
3822	** either by SQLite itself, or by a [VFS \| custom VFS implementation].
3823	** SQLite and its built-in [VFSes] interpret the
3824	** following query parameters:
3825	**
3826	** <ul>
3827	** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
3828	** a VFS object that provides the operating system interface that should
3829	** be used to access the database file on disk. ^If this option is set to
3830	** an empty string the default VFS object is used. ^Specifying an unknown
3831	** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
3832	** present, then the VFS specified by the option takes precedence over
3833	** the value passed as the fourth parameter to sqlite3_open_v2().
3834	**
3835	** <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
3836	** "rwc", or "memory". Attempting to set it to any other value is
3837	** an error)^.
3838	** ^If "ro" is specified, then the database is opened for read-only
3839	** access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the
3840	** third argument to sqlite3_open_v2(). ^If the mode option is set to
3841	** "rw", then the database is opened for read-write (but not create)
3842	** access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
3843	** been set. ^Value "rwc" is equivalent to setting both
3844	** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If the mode option is
3845	** set to "memory" then a pure [in-memory database] that never reads
3846	** or writes from disk is used. ^It is an error to specify a value for
3847	** the mode parameter that is less restrictive than that specified by
3848	** the flags passed in the third parameter to sqlite3_open_v2().
3849	**
3850	** <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
3851	** "private". ^Setting it to "shared" is equivalent to setting the
3852	** SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
3853	** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
3854	** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
3855	** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
3856	** a URI filename, its value overrides any behavior requested by setting
3857	** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
3858	**
3859	** <li> <b>psow</b>: ^The psow parameter indicates whether or not the
3860	** [powersafe overwrite] property does or does not apply to the
3861	** storage media on which the database file resides.
3862	**
3863	** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
3864	** which if set disables file locking in rollback journal modes. This
3865	** is useful for accessing a database on a filesystem that does not
3866	** support locking. Caution: Database corruption might result if two
3867	** or more processes write to the same database and any one of those
3868	** processes uses nolock=1.
3869	**
3870	** <li> <b>immutable</b>: ^The immutable parameter is a boolean query
3871	** parameter that indicates that the database file is stored on
3872	** read-only media. ^When immutable is set, SQLite assumes that the
3873	** database file cannot be changed, even by a process with higher
3874	** privilege, and so the database is opened read-only and all locking
3875	** and change detection is disabled. Caution: Setting the immutable
3876	** property on a database file that does in fact change can result
3877	** in incorrect query results and/or [SQLITE_CORRUPT] errors.
3878	** See also: [SQLITE_IOCAP_IMMUTABLE].
3879	**
3880	** </ul>
3881	**
3882	** ^Specifying an unknown parameter in the query component of a URI is not an
3883	** error. Future versions of SQLite might understand additional query
3884	** parameters. See "[query parameters with special meaning to SQLite]" for
3885	** additional information.
3886	**
3887	** [[URI filename examples]] <h3>URI filename examples</h3>
3888	**
3889	** <table border="1" align=center cellpadding=5>
3890	** <tr><th> URI filenames <th> Results
3891	** <tr><td> file:data.db <td>
3892	** Open the file "data.db" in the current directory.
3893	** <tr><td> file:/home/fred/data.db<br>
3894	** file:///home/fred/data.db <br>
3895	** file://localhost/home/fred/data.db <br> <td>
3896	** Open the database file "/home/fred/data.db".
3897	** <tr><td> file://darkstar/home/fred/data.db <td>
3898	** An error. "darkstar" is not a recognized authority.
3899	** <tr><td style="white-space:nowrap">
3900	** file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
3901	** <td> Windows only: Open the file "data.db" on fred's desktop on drive
3902	** C:. Note that the %20 escaping in this example is not strictly
3903	** necessary - space characters can be used literally
3904	** in URI filenames.
3905	** <tr><td> file:data.db?mode=ro&cache=private <td>
3906	** Open file "data.db" in the current directory for read-only access.
3907	** Regardless of whether or not shared-cache mode is enabled by
3908	** default, use a private cache.
3909	** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
3910	** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
3911	** that uses dot-files in place of posix advisory locking.
3912	** <tr><td> file:data.db?mode=readonly <td>
3913	** An error. "readonly" is not a valid option for the "mode" parameter.
3914	** Use "ro" instead: "file:data.db?mode=ro".
3915	** </table>
3916	**
3917	** ^URI hexadecimal escape sequences (%HH) are supported within the path and
3918	** query components of a URI. A hexadecimal escape sequence consists of a
3919	** percent sign - "%" - followed by exactly two hexadecimal digits
3920	** specifying an octet value. ^Before the path or query components of a
3921	** URI filename are interpreted, they are encoded using UTF-8 and all
3922	** hexadecimal escape sequences replaced by a single byte containing the
3923	** corresponding octet. If this process generates an invalid UTF-8 encoding,
3924	** the results are undefined.
3925	**
3926	** <b>Note to Windows users:</b> The encoding used for the filename argument
3927	** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
3928	** codepage is currently defined. Filenames containing international
3929	** characters must be converted to UTF-8 prior to passing them into
3930	** sqlite3_open() or sqlite3_open_v2().
3931	**
3932	** <b>Note to Windows Runtime users:</b> The temporary directory must be set
3933	** prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various
3934	** features that require the use of temporary files may fail.
3935	**
3936	** See also: [sqlite3_temp_directory]
3937	*/
3938	SQLITE_API int sqlite3_open(
3939	const char filename, / Database filename (UTF-8) */
3940	sqlite3 *ppDb / OUT: SQLite db handle */
3941	);
3942	SQLITE_API int sqlite3_open16(
3943	const void filename, / Database filename (UTF-16) */
3944	sqlite3 *ppDb / OUT: SQLite db handle */
3945	);
3946	SQLITE_API int sqlite3_open_v2(
3947	const char filename, / Database filename (UTF-8) */
3948	sqlite3 *ppDb, / OUT: SQLite db handle */
3949	int flags, /* Flags */
3950	const char zVfs / Name of VFS module to use */
3951	);
3952
3953	/*
3954	** CAPI3REF: Obtain Values For URI Parameters
3955	**
3956	** These are utility routines, useful to [VFS\|custom VFS implementations],
3957	** that check if a database file was a URI that contained a specific query
3958	** parameter, and if so obtains the value of that query parameter.
3959	**
3960	** The first parameter to these interfaces (hereafter referred to
3961	** as F) must be one of:
3962	** <ul>
3963	** <li> A database filename pointer created by the SQLite core and
3964	** passed into the xOpen() method of a VFS implementation, or
3965	** <li> A filename obtained from [sqlite3_db_filename()], or
3966	** <li> A new filename constructed using [sqlite3_create_filename()].
3967	** </ul>
3968	** If the F parameter is not one of the above, then the behavior is
3969	** undefined and probably undesirable. Older versions of SQLite were
3970	** more tolerant of invalid F parameters than newer versions.
3971	**
3972	** If F is a suitable filename (as described in the previous paragraph)
3973	** and if P is the name of the query parameter, then
3974	** sqlite3_uri_parameter(F,P) returns the value of the P
3975	** parameter if it exists or a NULL pointer if P does not appear as a
3976	** query parameter on F. If P is a query parameter of F and it
3977	** has no explicit value, then sqlite3_uri_parameter(F,P) returns
3978	** a pointer to an empty string.
3979	**
3980	** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
3981	** parameter and returns true (1) or false (0) according to the value
3982	** of P. The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
3983	** value of query parameter P is one of "yes", "true", or "on" in any
3984	** case or if the value begins with a non-zero number. The
3985	** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
3986	** query parameter P is one of "no", "false", or "off" in any case or
3987	** if the value begins with a numeric zero. If P is not a query
3988	** parameter on F or if the value of P does not match any of the
3989	** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).
3990	**
3991	** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
3992	** 64-bit signed integer and returns that integer, or D if P does not
3993	** exist. If the value of P is something other than an integer, then
3994	** zero is returned.
3995	**
3996	** The sqlite3_uri_key(F,N) returns a pointer to the name (not
3997	** the value) of the N-th query parameter for filename F, or a NULL
3998	** pointer if N is less than zero or greater than the number of query
3999	** parameters minus 1. The N value is zero-based so N should be 0 to obtain
4000	** the name of the first query parameter, 1 for the second parameter, and
4001	** so forth.
4002	**
4003	** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
4004	** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
4005	** is not a database file pathname pointer that the SQLite core passed
4006	** into the xOpen VFS method, then the behavior of this routine is undefined
4007	** and probably undesirable.
4008	**
4009	** Beginning with SQLite [version 3.31.0] ([dateof:3.31.0]) the input F
4010	** parameter can also be the name of a rollback journal file or WAL file
4011	** in addition to the main database file. Prior to version 3.31.0, these
4012	** routines would only work if F was the name of the main database file.
4013	** When the F parameter is the name of the rollback journal or WAL file,
4014	** it has access to all the same query parameters as were found on the
4015	** main database file.
4016	**
4017	** See the [URI filename] documentation for additional information.
4018	*/
4019	SQLITE_API const char sqlite3_uri_parameter(sqlite3_filename z, const char zParam);
4020	SQLITE_API int sqlite3_uri_boolean(sqlite3_filename z, const char *zParam, int bDefault);
4021	SQLITE_API sqlite3_int64 sqlite3_uri_int64(sqlite3_filename, const char*, sqlite3_int64);
4022	SQLITE_API const char *sqlite3_uri_key(sqlite3_filename z, int N);
4023
4024	/*
4025	** CAPI3REF: Translate filenames
4026	**
4027	** These routines are available to [VFS\|custom VFS implementations] for
4028	** translating filenames between the main database file, the journal file,
4029	** and the WAL file.
4030	**
4031	** If F is the name of an sqlite database file, journal file, or WAL file
4032	** passed by the SQLite core into the VFS, then sqlite3_filename_database(F)
4033	** returns the name of the corresponding database file.
4034	**
4035	** If F is the name of an sqlite database file, journal file, or WAL file
4036	** passed by the SQLite core into the VFS, or if F is a database filename
4037	** obtained from [sqlite3_db_filename()], then sqlite3_filename_journal(F)
4038	** returns the name of the corresponding rollback journal file.
4039	**
4040	** If F is the name of an sqlite database file, journal file, or WAL file
4041	** that was passed by the SQLite core into the VFS, or if F is a database
4042	** filename obtained from [sqlite3_db_filename()], then
4043	** sqlite3_filename_wal(F) returns the name of the corresponding
4044	** WAL file.
4045	**
4046	** In all of the above, if F is not the name of a database, journal or WAL
4047	** filename passed into the VFS from the SQLite core and F is not the
4048	** return value from [sqlite3_db_filename()], then the result is
4049	** undefined and is likely a memory access violation.
4050	*/
4051	SQLITE_API const char *sqlite3_filename_database(sqlite3_filename);
4052	SQLITE_API const char *sqlite3_filename_journal(sqlite3_filename);
4053	SQLITE_API const char *sqlite3_filename_wal(sqlite3_filename);
4054
4055	/*
4056	** CAPI3REF: Database File Corresponding To A Journal
4057	**
4058	** ^If X is the name of a rollback or WAL-mode journal file that is
4059	** passed into the xOpen method of [sqlite3_vfs], then
4060	** sqlite3_database_file_object(X) returns a pointer to the [sqlite3_file]
4061	** object that represents the main database file.
4062	**
4063	** This routine is intended for use in custom [VFS] implementations
4064	** only. It is not a general-purpose interface.
4065	** The argument sqlite3_file_object(X) must be a filename pointer that
4066	** has been passed into [sqlite3_vfs].xOpen method where the
4067	** flags parameter to xOpen contains one of the bits
4068	** [SQLITE_OPEN_MAIN_JOURNAL] or [SQLITE_OPEN_WAL]. Any other use
4069	** of this routine results in undefined and probably undesirable
4070	** behavior.
4071	*/
4072	SQLITE_API sqlite3_file sqlite3_database_file_object(const char);
4073
4074	/*
4075	** CAPI3REF: Create and Destroy VFS Filenames
4076	**
4077	** These interfaces are provided for use by [VFS shim] implementations and
4078	** are not useful outside of that context.
4079	**
4080	** The sqlite3_create_filename(D,J,W,N,P) allocates memory to hold a version of
4081	** database filename D with corresponding journal file J and WAL file W and
4082	** an array P of N URI Key/Value pairs. The result from
4083	** sqlite3_create_filename(D,J,W,N,P) is a pointer to a database filename that
4084	** is safe to pass to routines like:
4085	** <ul>
4086	** <li> [sqlite3_uri_parameter()],
4087	** <li> [sqlite3_uri_boolean()],
4088	** <li> [sqlite3_uri_int64()],
4089	** <li> [sqlite3_uri_key()],
4090	** <li> [sqlite3_filename_database()],
4091	** <li> [sqlite3_filename_journal()], or
4092	** <li> [sqlite3_filename_wal()].
4093	** </ul>
4094	** If a memory allocation error occurs, sqlite3_create_filename() might
4095	** return a NULL pointer. The memory obtained from sqlite3_create_filename(X)
4096	** must be released by a corresponding call to sqlite3_free_filename(Y).
4097	**
4098	** The P parameter in sqlite3_create_filename(D,J,W,N,P) should be an array
4099	** of 2*N pointers to strings. Each pair of pointers in this array corresponds
4100	** to a key and value for a query parameter. The P parameter may be a NULL
4101	** pointer if N is zero. None of the 2*N pointers in the P array may be
4102	** NULL pointers and key pointers should not be empty strings.
4103	** None of the D, J, or W parameters to sqlite3_create_filename(D,J,W,N,P) may
4104	** be NULL pointers, though they can be empty strings.
4105	**
4106	** The sqlite3_free_filename(Y) routine releases a memory allocation
4107	** previously obtained from sqlite3_create_filename(). Invoking
4108	** sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless no-op.
4109	**
4110	** If the Y parameter to sqlite3_free_filename(Y) is anything other
4111	** than a NULL pointer or a pointer previously acquired from
4112	** sqlite3_create_filename(), then bad things such as heap
4113	** corruption or segfaults may occur. The value Y should not be
4114	** used again after sqlite3_free_filename(Y) has been called. This means
4115	** that if the [sqlite3_vfs.xOpen()] method of a VFS has been called using Y,
4116	** then the corresponding [sqlite3_module.xClose() method should also be
4117	** invoked prior to calling sqlite3_free_filename(Y).
4118	*/
4119	SQLITE_API sqlite3_filename sqlite3_create_filename(
4120	const char *zDatabase,
4121	const char *zJournal,
4122	const char *zWal,
4123	int nParam,
4124	const char **azParam
4125	);
4126	SQLITE_API void sqlite3_free_filename(sqlite3_filename);
4127
4128	/*
4129	** CAPI3REF: Error Codes And Messages
4130	** METHOD: sqlite3
4131	**
4132	** ^If the most recent sqlite3_* API call associated with
4133	** [database connection] D failed, then the sqlite3_errcode(D) interface
4134	** returns the numeric [result code] or [extended result code] for that
4135	** API call.
4136	** ^The sqlite3_extended_errcode()
4137	** interface is the same except that it always returns the
4138	** [extended result code] even when extended result codes are
4139	** disabled.
4140	**
4141	** The values returned by sqlite3_errcode() and/or
4142	** sqlite3_extended_errcode() might change with each API call.
4143	** Except, there are some interfaces that are guaranteed to never
4144	** change the value of the error code. The error-code preserving
4145	** interfaces include the following:
4146	**
4147	** <ul>
4148	** <li> sqlite3_errcode()
4149	** <li> sqlite3_extended_errcode()
4150	** <li> sqlite3_errmsg()
4151	** <li> sqlite3_errmsg16()
4152	** <li> sqlite3_error_offset()
4153	** </ul>
4154	**
4155	** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
4156	** text that describes the error, as either UTF-8 or UTF-16 respectively,
4157	** or NULL if no error message is available.
4158	** (See how SQLite handles [invalid UTF] for exceptions to this rule.)
4159	** ^(Memory to hold the error message string is managed internally.
4160	** The application does not need to worry about freeing the result.
4161	** However, the error string might be overwritten or deallocated by
4162	** subsequent calls to other SQLite interface functions.)^
4163	**
4164	** ^The sqlite3_errstr(E) interface returns the English-language text
4165	** that describes the [result code] E, as UTF-8, or NULL if E is not an
4166	** result code for which a text error message is available.
4167	** ^(Memory to hold the error message string is managed internally
4168	** and must not be freed by the application)^.
4169	**
4170	** ^If the most recent error references a specific token in the input
4171	** SQL, the sqlite3_error_offset() interface returns the byte offset
4172	** of the start of that token. ^The byte offset returned by
4173	** sqlite3_error_offset() assumes that the input SQL is UTF8.
4174	** ^If the most recent error does not reference a specific token in the input
4175	** SQL, then the sqlite3_error_offset() function returns -1.
4176	**
4177	** When the serialized [threading mode] is in use, it might be the
4178	** case that a second error occurs on a separate thread in between
4179	** the time of the first error and the call to these interfaces.
4180	** When that happens, the second error will be reported since these
4181	** interfaces always report the most recent result. To avoid
4182	** this, each thread can obtain exclusive use of the [database connection] D
4183	** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
4184	** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
4185	** all calls to the interfaces listed here are completed.
4186	**
4187	** If an interface fails with SQLITE_MISUSE, that means the interface
4188	** was invoked incorrectly by the application. In that case, the
4189	** error code and message may or may not be set.
4190	*/
4191	SQLITE_API int sqlite3_errcode(sqlite3 *db);
4192	SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
4193	SQLITE_API const char sqlite3_errmsg(sqlite3);
4194	SQLITE_API const void sqlite3_errmsg16(sqlite3);
4195	SQLITE_API const char *sqlite3_errstr(int);
4196	SQLITE_API int sqlite3_error_offset(sqlite3 *db);
4197
4198	/*
4199	** CAPI3REF: Prepared Statement Object
4200	** KEYWORDS: {prepared statement} {prepared statements}
4201	**
4202	** An instance of this object represents a single SQL statement that
4203	** has been compiled into binary form and is ready to be evaluated.
4204	**
4205	** Think of each SQL statement as a separate computer program. The
4206	** original SQL text is source code. A prepared statement object
4207	** is the compiled object code. All SQL must be converted into a
4208	** prepared statement before it can be run.
4209	**
4210	** The life-cycle of a prepared statement object usually goes like this:
4211	**
4212	** <ol>
4213	** <li> Create the prepared statement object using [sqlite3_prepare_v2()].
4214	** <li> Bind values to [parameters] using the sqlite3_bind_*()
4215	** interfaces.
4216	** <li> Run the SQL by calling [sqlite3_step()] one or more times.
4217	** <li> Reset the prepared statement using [sqlite3_reset()] then go back
4218	** to step 2. Do this zero or more times.
4219	** <li> Destroy the object using [sqlite3_finalize()].
4220	** </ol>
4221	*/
4222	typedef struct sqlite3_stmt sqlite3_stmt;
4223
4224	/*
4225	** CAPI3REF: Run-time Limits
4226	** METHOD: sqlite3
4227	**
4228	** ^(This interface allows the size of various constructs to be limited
4229	** on a connection by connection basis. The first parameter is the
4230	** [database connection] whose limit is to be set or queried. The
4231	** second parameter is one of the [limit categories] that define a
4232	** class of constructs to be size limited. The third parameter is the
4233	** new limit for that construct.)^
4234	**
4235	** ^If the new limit is a negative number, the limit is unchanged.
4236	** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
4237	** [limits \| hard upper bound]
4238	** set at compile-time by a C preprocessor macro called
4239	** [limits \| SQLITE_MAX_<i>NAME</i>].
4240	** (The "_LIMIT_" in the name is changed to "_MAX_".))^
4241	** ^Attempts to increase a limit above its hard upper bound are
4242	** silently truncated to the hard upper bound.
4243	**
4244	** ^Regardless of whether or not the limit was changed, the
4245	** [sqlite3_limit()] interface returns the prior value of the limit.
4246	** ^Hence, to find the current value of a limit without changing it,
4247	** simply invoke this interface with the third parameter set to -1.
4248	**
4249	** Run-time limits are intended for use in applications that manage
4250	** both their own internal database and also databases that are controlled
4251	** by untrusted external sources. An example application might be a
4252	** web browser that has its own databases for storing history and
4253	** separate databases controlled by JavaScript applications downloaded
4254	** off the Internet. The internal databases can be given the
4255	** large, default limits. Databases managed by external sources can
4256	** be given much smaller limits designed to prevent a denial of service
4257	** attack. Developers might also want to use the [sqlite3_set_authorizer()]
4258	** interface to further control untrusted SQL. The size of the database
4259	** created by an untrusted script can be contained using the
4260	** [max_page_count] [PRAGMA].
4261	**
4262	** New run-time limit categories may be added in future releases.
4263	*/
4264	SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
4265
4266	/*
4267	** CAPI3REF: Run-Time Limit Categories
4268	** KEYWORDS: {limit category} {*limit categories}
4269	**
4270	** These constants define various performance limits
4271	** that can be lowered at run-time using [sqlite3_limit()].
4272	** The synopsis of the meanings of the various limits is shown below.
4273	** Additional information is available at [limits \| Limits in SQLite].
4274	**
4275	** <dl>
4276	** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
4277	** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
4278	**
4279	** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
4280	** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
4281	**
4282	** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
4283	** <dd>The maximum number of columns in a table definition or in the
4284	** result set of a [SELECT] or the maximum number of columns in an index
4285	** or in an ORDER BY or GROUP BY clause.</dd>)^
4286	**
4287	** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
4288	** <dd>The maximum depth of the parse tree on any expression.</dd>)^
4289	**
4290	** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
4291	** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
4292	**
4293	** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
4294	** <dd>The maximum number of instructions in a virtual machine program
4295	** used to implement an SQL statement. If [sqlite3_prepare_v2()] or
4296	** the equivalent tries to allocate space for more than this many opcodes
4297	** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^
4298	**
4299	** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
4300	** <dd>The maximum number of arguments on a function.</dd>)^
4301	**
4302	** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
4303	** <dd>The maximum number of [ATTACH \| attached databases].)^</dd>
4304	**
4305	** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
4306	** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
4307	** <dd>The maximum length of the pattern argument to the [LIKE] or
4308	** [GLOB] operators.</dd>)^
4309	**
4310	** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
4311	** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
4312	** <dd>The maximum index number of any [parameter] in an SQL statement.)^
4313	**
4314	** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
4315	** <dd>The maximum depth of recursion for triggers.</dd>)^
4316	**
4317	** [[SQLITE_LIMIT_WORKER_THREADS]] ^(<dt>SQLITE_LIMIT_WORKER_THREADS</dt>
4318	** <dd>The maximum number of auxiliary worker threads that a single
4319	** [prepared statement] may start.</dd>)^
4320	** </dl>
4321	*/
4322	#define SQLITE_LIMIT_LENGTH 0
4323	#define SQLITE_LIMIT_SQL_LENGTH 1
4324	#define SQLITE_LIMIT_COLUMN 2
4325	#define SQLITE_LIMIT_EXPR_DEPTH 3
4326	#define SQLITE_LIMIT_COMPOUND_SELECT 4
4327	#define SQLITE_LIMIT_VDBE_OP 5
4328	#define SQLITE_LIMIT_FUNCTION_ARG 6
4329	#define SQLITE_LIMIT_ATTACHED 7
4330	#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8
4331	#define SQLITE_LIMIT_VARIABLE_NUMBER 9
4332	#define SQLITE_LIMIT_TRIGGER_DEPTH 10
4333	#define SQLITE_LIMIT_WORKER_THREADS 11
4334
4335	/*
4336	** CAPI3REF: Prepare Flags
4337	**
4338	** These constants define various flags that can be passed into
4339	** "prepFlags" parameter of the [sqlite3_prepare_v3()] and
4340	** [sqlite3_prepare16_v3()] interfaces.
4341	**
4342	** New flags may be added in future releases of SQLite.
4343	**
4344	** <dl>
4345	** [[SQLITE_PREPARE_PERSISTENT]] ^(<dt>SQLITE_PREPARE_PERSISTENT</dt>
4346	** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
4347	** that the prepared statement will be retained for a long time and
4348	** probably reused many times.)^ ^Without this flag, [sqlite3_prepare_v3()]
4349	** and [sqlite3_prepare16_v3()] assume that the prepared statement will
4350	** be used just once or at most a few times and then destroyed using
4351	** [sqlite3_finalize()] relatively soon. The current implementation acts
4352	** on this hint by avoiding the use of [lookaside memory] so as not to
4353	** deplete the limited store of lookaside memory. Future versions of
4354	** SQLite may act on this hint differently.
4355	**
4356	** [[SQLITE_PREPARE_NORMALIZE]] <dt>SQLITE_PREPARE_NORMALIZE</dt>
4357	** <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used
4358	** to be required for any prepared statement that wanted to use the
4359	** [sqlite3_normalized_sql()] interface. However, the
4360	** [sqlite3_normalized_sql()] interface is now available to all
4361	** prepared statements, regardless of whether or not they use this
4362	** flag.
4363	**
4364	** [[SQLITE_PREPARE_NO_VTAB]] <dt>SQLITE_PREPARE_NO_VTAB</dt>
4365	** <dd>The SQLITE_PREPARE_NO_VTAB flag causes the SQL compiler
4366	** to return an error (error code SQLITE_ERROR) if the statement uses
4367	** any virtual tables.
4368	**
4369	** [[SQLITE_PREPARE_DONT_LOG]] <dt>SQLITE_PREPARE_DONT_LOG</dt>
4370	** <dd>The SQLITE_PREPARE_DONT_LOG flag prevents SQL compiler
4371	** errors from being sent to the error log defined by
4372	** [SQLITE_CONFIG_LOG]. This can be used, for example, to do test
4373	** compiles to see if some SQL syntax is well-formed, without generating
4374	** messages on the global error log when it is not. If the test compile
4375	** fails, the sqlite3_prepare_v3() call returns the same error indications
4376	** with or without this flag; it just omits the call to [sqlite3_log()] that
4377	** logs the error.
4378	** </dl>
4379	*/
4380	#define SQLITE_PREPARE_PERSISTENT 0x01
4381	#define SQLITE_PREPARE_NORMALIZE 0x02
4382	#define SQLITE_PREPARE_NO_VTAB 0x04
4383	#define SQLITE_PREPARE_DONT_LOG 0x10
4384
4385	/*
4386	** CAPI3REF: Compiling An SQL Statement
4387	** KEYWORDS: {SQL statement compiler}
4388	** METHOD: sqlite3
4389	** CONSTRUCTOR: sqlite3_stmt
4390	**
4391	** To execute an SQL statement, it must first be compiled into a byte-code
4392	** program using one of these routines. Or, in other words, these routines
4393	** are constructors for the [prepared statement] object.
4394	**
4395	** The preferred routine to use is [sqlite3_prepare_v2()]. The
4396	** [sqlite3_prepare()] interface is legacy and should be avoided.
4397	** [sqlite3_prepare_v3()] has an extra "prepFlags" option that is used
4398	** for special purposes.
4399	**
4400	** The use of the UTF-8 interfaces is preferred, as SQLite currently
4401	** does all parsing using UTF-8. The UTF-16 interfaces are provided
4402	** as a convenience. The UTF-16 interfaces work by converting the
4403	** input text into UTF-8, then invoking the corresponding UTF-8 interface.
4404	**
4405	** The first argument, "db", is a [database connection] obtained from a
4406	** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
4407	** [sqlite3_open16()]. The database connection must not have been closed.
4408	**
4409	** The second argument, "zSql", is the statement to be compiled, encoded
4410	** as either UTF-8 or UTF-16. The sqlite3_prepare(), sqlite3_prepare_v2(),
4411	** and sqlite3_prepare_v3()
4412	** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
4413	** and sqlite3_prepare16_v3() use UTF-16.
4414	**
4415	** ^If the nByte argument is negative, then zSql is read up to the
4416	** first zero terminator. ^If nByte is positive, then it is the maximum
4417	** number of bytes read from zSql. When nByte is positive, zSql is read
4418	** up to the first zero terminator or until the nByte bytes have been read,
4419	** whichever comes first. ^If nByte is zero, then no prepared
4420	** statement is generated.
4421	** If the caller knows that the supplied string is nul-terminated, then
4422	** there is a small performance advantage to passing an nByte parameter that
4423	** is the number of bytes in the input string <i>including</i>
4424	** the nul-terminator.
4425	** Note that nByte measure the length of the input in bytes, not
4426	** characters, even for the UTF-16 interfaces.
4427	**
4428	** ^If pzTail is not NULL then *pzTail is made to point to the first byte
4429	** past the end of the first SQL statement in zSql. These routines only
4430	** compile the first statement in zSql, so *pzTail is left pointing to
4431	** what remains uncompiled.
4432	**
4433	** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
4434	** executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set
4435	** to NULL. ^If the input text contains no SQL (if the input is an empty
4436	** string or a comment) then *ppStmt is set to NULL.
4437	** The calling procedure is responsible for deleting the compiled
4438	** SQL statement using [sqlite3_finalize()] after it has finished with it.
4439	** ppStmt may not be NULL.
4440	**
4441	** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
4442	** otherwise an [error code] is returned.
4443	**
4444	** The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),
4445	** and sqlite3_prepare16_v3() interfaces are recommended for all new programs.
4446	** The older interfaces (sqlite3_prepare() and sqlite3_prepare16())
4447	** are retained for backwards compatibility, but their use is discouraged.
4448	** ^In the "vX" interfaces, the prepared statement
4449	** that is returned (the [sqlite3_stmt] object) contains a copy of the
4450	** original SQL text. This causes the [sqlite3_step()] interface to
4451	** behave differently in three ways:
4452	**
4453	** <ol>
4454	** <li>
4455	** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
4456	** always used to do, [sqlite3_step()] will automatically recompile the SQL
4457	** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
4458	** retries will occur before sqlite3_step() gives up and returns an error.
4459	** </li>
4460	**
4461	** <li>
4462	** ^When an error occurs, [sqlite3_step()] will return one of the detailed
4463	** [error codes] or [extended error codes]. ^The legacy behavior was that
4464	** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
4465	** and the application would have to make a second call to [sqlite3_reset()]
4466	** in order to find the underlying cause of the problem. With the "v2" prepare
4467	** interfaces, the underlying reason for the error is returned immediately.
4468	** </li>
4469	**
4470	** <li>
4471	** ^If the specific value bound to a [parameter \| host parameter] in the
4472	** WHERE clause might influence the choice of query plan for a statement,
4473	** then the statement will be automatically recompiled, as if there had been
4474	** a schema change, on the first [sqlite3_step()] call following any change
4475	** to the [sqlite3_bind_text \| bindings] of that [parameter].
4476	** ^The specific value of a WHERE-clause [parameter] might influence the
4477	** choice of query plan if the parameter is the left-hand side of a [LIKE]
4478	** or [GLOB] operator or if the parameter is compared to an indexed column
4479	** and the [SQLITE_ENABLE_STAT4] compile-time option is enabled.
4480	** </li>
4481	** </ol>
4482	**
4483	** <p>^sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having
4484	** the extra prepFlags parameter, which is a bit array consisting of zero or
4485	** more of the [SQLITE_PREPARE_PERSISTENT\|SQLITE_PREPARE_*] flags. ^The
4486	** sqlite3_prepare_v2() interface works exactly the same as
4487	** sqlite3_prepare_v3() with a zero prepFlags parameter.
4488	*/
4489	SQLITE_API int sqlite3_prepare(
4490	sqlite3 db, / Database handle */
4491	const char zSql, / SQL statement, UTF-8 encoded */
4492	int nByte, /* Maximum length of zSql in bytes. */
4493	sqlite3_stmt *ppStmt, / OUT: Statement handle */
4494	const char *pzTail / OUT: Pointer to unused portion of zSql */
4495	);
4496	SQLITE_API int sqlite3_prepare_v2(
4497	sqlite3 db, / Database handle */
4498	const char zSql, / SQL statement, UTF-8 encoded */
4499	int nByte, /* Maximum length of zSql in bytes. */
4500	sqlite3_stmt *ppStmt, / OUT: Statement handle */
4501	const char *pzTail / OUT: Pointer to unused portion of zSql */
4502	);
4503	SQLITE_API int sqlite3_prepare_v3(
4504	sqlite3 db, / Database handle */
4505	const char zSql, / SQL statement, UTF-8 encoded */
4506	int nByte, /* Maximum length of zSql in bytes. */
4507	unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
4508	sqlite3_stmt *ppStmt, / OUT: Statement handle */
4509	const char *pzTail / OUT: Pointer to unused portion of zSql */
4510	);
4511	SQLITE_API int sqlite3_prepare16(
4512	sqlite3 db, / Database handle */
4513	const void zSql, / SQL statement, UTF-16 encoded */
4514	int nByte, /* Maximum length of zSql in bytes. */
4515	sqlite3_stmt *ppStmt, / OUT: Statement handle */
4516	const void *pzTail / OUT: Pointer to unused portion of zSql */
4517	);
4518	SQLITE_API int sqlite3_prepare16_v2(
4519	sqlite3 db, / Database handle */
4520	const void zSql, / SQL statement, UTF-16 encoded */
4521	int nByte, /* Maximum length of zSql in bytes. */
4522	sqlite3_stmt *ppStmt, / OUT: Statement handle */
4523	const void *pzTail / OUT: Pointer to unused portion of zSql */
4524	);
4525	SQLITE_API int sqlite3_prepare16_v3(
4526	sqlite3 db, / Database handle */
4527	const void zSql, / SQL statement, UTF-16 encoded */
4528	int nByte, /* Maximum length of zSql in bytes. */
4529	unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
4530	sqlite3_stmt *ppStmt, / OUT: Statement handle */
4531	const void *pzTail / OUT: Pointer to unused portion of zSql */
4532	);
4533
4534	/*
4535	** CAPI3REF: Retrieving Statement SQL
4536	** METHOD: sqlite3_stmt
4537	**
4538	** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
4539	** SQL text used to create [prepared statement] P if P was
4540	** created by [sqlite3_prepare_v2()], [sqlite3_prepare_v3()],
4541	** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
4542	** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
4543	** string containing the SQL text of prepared statement P with
4544	** [bound parameters] expanded.
4545	** ^The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8
4546	** string containing the normalized SQL text of prepared statement P. The
4547	** semantics used to normalize a SQL statement are unspecified and subject
4548	** to change. At a minimum, literal values will be replaced with suitable
4549	** placeholders.
4550	**
4551	** ^(For example, if a prepared statement is created using the SQL
4552	** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
4553	** and parameter :xyz is unbound, then sqlite3_sql() will return
4554	** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()
4555	** will return "SELECT 2345,NULL".)^
4556	**
4557	** ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory
4558	** is available to hold the result, or if the result would exceed the
4559	** the maximum string length determined by the [SQLITE_LIMIT_LENGTH].
4560	**
4561	** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of
4562	** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time
4563	** option causes sqlite3_expanded_sql() to always return NULL.
4564	**
4565	** ^The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P)
4566	** are managed by SQLite and are automatically freed when the prepared
4567	** statement is finalized.
4568	** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
4569	** is obtained from [sqlite3_malloc()] and must be freed by the application
4570	** by passing it to [sqlite3_free()].
4571	**
4572	** ^The sqlite3_normalized_sql() interface is only available if
4573	** the [SQLITE_ENABLE_NORMALIZE] compile-time option is defined.
4574	*/
4575	SQLITE_API const char sqlite3_sql(sqlite3_stmt pStmt);
4576	SQLITE_API char sqlite3_expanded_sql(sqlite3_stmt pStmt);
4577	#ifdef SQLITE_ENABLE_NORMALIZE
4578	SQLITE_API const char sqlite3_normalized_sql(sqlite3_stmt pStmt);
4579	#endif
4580
4581	/*
4582	** CAPI3REF: Determine If An SQL Statement Writes The Database
4583	** METHOD: sqlite3_stmt
4584	**
4585	** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
4586	** and only if the [prepared statement] X makes no direct changes to
4587	** the content of the database file.
4588	**
4589	** Note that [application-defined SQL functions] or
4590	** [virtual tables] might change the database indirectly as a side effect.
4591	** ^(For example, if an application defines a function "eval()" that
4592	** calls [sqlite3_exec()], then the following SQL statement would
4593	** change the database file through side-effects:
4594	**
4595	** <blockquote><pre>
4596	** SELECT eval('DELETE FROM t1') FROM t2;
4597	** </pre></blockquote>
4598	**
4599	** But because the [SELECT] statement does not change the database file
4600	** directly, sqlite3_stmt_readonly() would still return true.)^
4601	**
4602	** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
4603	** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
4604	** since the statements themselves do not actually modify the database but
4605	** rather they control the timing of when other statements modify the
4606	** database. ^The [ATTACH] and [DETACH] statements also cause
4607	** sqlite3_stmt_readonly() to return true since, while those statements
4608	** change the configuration of a database connection, they do not make
4609	** changes to the content of the database files on disk.
4610	** ^The sqlite3_stmt_readonly() interface returns true for [BEGIN] since
4611	** [BEGIN] merely sets internal flags, but the [BEGIN\|BEGIN IMMEDIATE] and
4612	** [BEGIN\|BEGIN EXCLUSIVE] commands do touch the database and so
4613	** sqlite3_stmt_readonly() returns false for those commands.
4614	**
4615	** ^This routine returns false if there is any possibility that the
4616	** statement might change the database file. ^A false return does
4617	** not guarantee that the statement will change the database file.
4618	** ^For example, an UPDATE statement might have a WHERE clause that
4619	** makes it a no-op, but the sqlite3_stmt_readonly() result would still
4620	** be false. ^Similarly, a CREATE TABLE IF NOT EXISTS statement is a
4621	** read-only no-op if the table already exists, but
4622	** sqlite3_stmt_readonly() still returns false for such a statement.
4623	**
4624	** ^If prepared statement X is an [EXPLAIN] or [EXPLAIN QUERY PLAN]
4625	** statement, then sqlite3_stmt_readonly(X) returns the same value as
4626	** if the EXPLAIN or EXPLAIN QUERY PLAN prefix were omitted.
4627	*/
4628	SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
4629
4630	/*
4631	** CAPI3REF: Query The EXPLAIN Setting For A Prepared Statement
4632	** METHOD: sqlite3_stmt
4633	**
4634	** ^The sqlite3_stmt_isexplain(S) interface returns 1 if the
4635	** prepared statement S is an EXPLAIN statement, or 2 if the
4636	** statement S is an EXPLAIN QUERY PLAN.
4637	** ^The sqlite3_stmt_isexplain(S) interface returns 0 if S is
4638	** an ordinary statement or a NULL pointer.
4639	*/
4640	SQLITE_API int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt);
4641
4642	/*
4643	** CAPI3REF: Change The EXPLAIN Setting For A Prepared Statement
4644	** METHOD: sqlite3_stmt
4645	**
4646	** The sqlite3_stmt_explain(S,E) interface changes the EXPLAIN
4647	** setting for [prepared statement] S. If E is zero, then S becomes
4648	** a normal prepared statement. If E is 1, then S behaves as if
4649	** its SQL text began with "[EXPLAIN]". If E is 2, then S behaves as if
4650	** its SQL text began with "[EXPLAIN QUERY PLAN]".
4651	**
4652	** Calling sqlite3_stmt_explain(S,E) might cause S to be reprepared.
4653	** SQLite tries to avoid a reprepare, but a reprepare might be necessary
4654	** on the first transition into EXPLAIN or EXPLAIN QUERY PLAN mode.
4655	**
4656	** Because of the potential need to reprepare, a call to
4657	** sqlite3_stmt_explain(S,E) will fail with SQLITE_ERROR if S cannot be
4658	** reprepared because it was created using [sqlite3_prepare()] instead of
4659	** the newer [sqlite3_prepare_v2()] or [sqlite3_prepare_v3()] interfaces and
4660	** hence has no saved SQL text with which to reprepare.
4661	**
4662	** Changing the explain setting for a prepared statement does not change
4663	** the original SQL text for the statement. Hence, if the SQL text originally
4664	** began with EXPLAIN or EXPLAIN QUERY PLAN, but sqlite3_stmt_explain(S,0)
4665	** is called to convert the statement into an ordinary statement, the EXPLAIN
4666	** or EXPLAIN QUERY PLAN keywords will still appear in the sqlite3_sql(S)
4667	** output, even though the statement now acts like a normal SQL statement.
4668	**
4669	** This routine returns SQLITE_OK if the explain mode is successfully
4670	** changed, or an error code if the explain mode could not be changed.
4671	** The explain mode cannot be changed while a statement is active.
4672	** Hence, it is good practice to call [sqlite3_reset(S)]
4673	** immediately prior to calling sqlite3_stmt_explain(S,E).
4674	*/
4675	SQLITE_API int sqlite3_stmt_explain(sqlite3_stmt *pStmt, int eMode);
4676
4677	/*
4678	** CAPI3REF: Determine If A Prepared Statement Has Been Reset
4679	** METHOD: sqlite3_stmt
4680	**
4681	** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
4682	** [prepared statement] S has been stepped at least once using
4683	** [sqlite3_step(S)] but has neither run to completion (returned
4684	** [SQLITE_DONE] from [sqlite3_step(S)]) nor
4685	** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S)
4686	** interface returns false if S is a NULL pointer. If S is not a
4687	** NULL pointer and is not a pointer to a valid [prepared statement]
4688	** object, then the behavior is undefined and probably undesirable.
4689	**
4690	** This interface can be used in combination [sqlite3_next_stmt()]
4691	** to locate all prepared statements associated with a database
4692	** connection that are in need of being reset. This can be used,
4693	** for example, in diagnostic routines to search for prepared
4694	** statements that are holding a transaction open.
4695	*/
4696	SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
4697
4698	/*
4699	** CAPI3REF: Dynamically Typed Value Object
4700	** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
4701	**
4702	** SQLite uses the sqlite3_value object to represent all values
4703	** that can be stored in a database table. SQLite uses dynamic typing
4704	** for the values it stores. ^Values stored in sqlite3_value objects
4705	** can be integers, floating point values, strings, BLOBs, or NULL.
4706	**
4707	** An sqlite3_value object may be either "protected" or "unprotected".
4708	** Some interfaces require a protected sqlite3_value. Other interfaces
4709	** will accept either a protected or an unprotected sqlite3_value.
4710	** Every interface that accepts sqlite3_value arguments specifies
4711	** whether or not it requires a protected sqlite3_value. The
4712	** [sqlite3_value_dup()] interface can be used to construct a new
4713	** protected sqlite3_value from an unprotected sqlite3_value.
4714	**
4715	** The terms "protected" and "unprotected" refer to whether or not
4716	** a mutex is held. An internal mutex is held for a protected
4717	** sqlite3_value object but no mutex is held for an unprotected
4718	** sqlite3_value object. If SQLite is compiled to be single-threaded
4719	** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
4720	** or if SQLite is run in one of reduced mutex modes
4721	** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
4722	** then there is no distinction between protected and unprotected
4723	** sqlite3_value objects and they can be used interchangeably. However,
4724	** for maximum code portability it is recommended that applications
4725	** still make the distinction between protected and unprotected
4726	** sqlite3_value objects even when not strictly required.
4727	**
4728	** ^The sqlite3_value objects that are passed as parameters into the
4729	** implementation of [application-defined SQL functions] are protected.
4730	** ^The sqlite3_value objects returned by [sqlite3_vtab_rhs_value()]
4731	** are protected.
4732	** ^The sqlite3_value object returned by
4733	** [sqlite3_column_value()] is unprotected.
4734	** Unprotected sqlite3_value objects may only be used as arguments
4735	** to [sqlite3_result_value()], [sqlite3_bind_value()], and
4736	** [sqlite3_value_dup()].
4737	** The [sqlite3_value_blob \| sqlite3_value_type()] family of
4738	** interfaces require protected sqlite3_value objects.
4739	*/
4740	typedef struct sqlite3_value sqlite3_value;
4741
4742	/*
4743	** CAPI3REF: SQL Function Context Object
4744	**
4745	** The context in which an SQL function executes is stored in an
4746	** sqlite3_context object. ^A pointer to an sqlite3_context object
4747	** is always first parameter to [application-defined SQL functions].
4748	** The application-defined SQL function implementation will pass this
4749	** pointer through into calls to [sqlite3_result_int \| sqlite3_result()],
4750	** [sqlite3_aggregate_context()], [sqlite3_user_data()],
4751	** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
4752	** and/or [sqlite3_set_auxdata()].
4753	*/
4754	typedef struct sqlite3_context sqlite3_context;
4755
4756	/*
4757	** CAPI3REF: Binding Values To Prepared Statements
4758	** KEYWORDS: {host parameter} {host parameters} {host parameter name}
4759	** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
4760	** METHOD: sqlite3_stmt
4761	**
4762	** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
4763	** literals may be replaced by a [parameter] that matches one of the following
4764	** templates:
4765	**
4766	** <ul>
4767	** <li> ?
4768	** <li> ?NNN
4769	** <li> :VVV
4770	** <li> @VVV
4771	** <li> $VVV
4772	** </ul>
4773	**
4774	** In the templates above, NNN represents an integer literal,
4775	** and VVV represents an alphanumeric identifier.)^ ^The values of these
4776	** parameters (also called "host parameter names" or "SQL parameters")
4777	** can be set using the sqlite3_bind_*() routines defined here.
4778	**
4779	** ^The first argument to the sqlite3_bind_*() routines is always
4780	** a pointer to the [sqlite3_stmt] object returned from
4781	** [sqlite3_prepare_v2()] or its variants.
4782	**
4783	** ^The second argument is the index of the SQL parameter to be set.
4784	** ^The leftmost SQL parameter has an index of 1. ^When the same named
4785	** SQL parameter is used more than once, second and subsequent
4786	** occurrences have the same index as the first occurrence.
4787	** ^The index for named parameters can be looked up using the
4788	** [sqlite3_bind_parameter_index()] API if desired. ^The index
4789	** for "?NNN" parameters is the value of NNN.
4790	** ^The NNN value must be between 1 and the [sqlite3_limit()]
4791	** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 32766).
4792	**
4793	** ^The third argument is the value to bind to the parameter.
4794	** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
4795	** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
4796	** is ignored and the end result is the same as sqlite3_bind_null().
4797	** ^If the third parameter to sqlite3_bind_text() is not NULL, then
4798	** it should be a pointer to well-formed UTF8 text.
4799	** ^If the third parameter to sqlite3_bind_text16() is not NULL, then
4800	** it should be a pointer to well-formed UTF16 text.
4801	** ^If the third parameter to sqlite3_bind_text64() is not NULL, then
4802	** it should be a pointer to a well-formed unicode string that is
4803	** either UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16
4804	** otherwise.
4805	**
4806	** [[byte-order determination rules]] ^The byte-order of
4807	** UTF16 input text is determined by the byte-order mark (BOM, U+FEFF)
4808	** found in the first character, which is removed, or in the absence of a BOM
4809	** the byte order is the native byte order of the host
4810	** machine for sqlite3_bind_text16() or the byte order specified in
4811	** the 6th parameter for sqlite3_bind_text64().)^
4812	** ^If UTF16 input text contains invalid unicode
4813	** characters, then SQLite might change those invalid characters
4814	** into the unicode replacement character: U+FFFD.
4815	**
4816	** ^(In those routines that have a fourth argument, its value is the
4817	** number of bytes in the parameter. To be clear: the value is the
4818	** number of <u>bytes</u> in the value, not the number of characters.)^
4819	** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
4820	** is negative, then the length of the string is
4821	** the number of bytes up to the first zero terminator.
4822	** If the fourth parameter to sqlite3_bind_blob() is negative, then
4823	** the behavior is undefined.
4824	** If a non-negative fourth parameter is provided to sqlite3_bind_text()
4825	** or sqlite3_bind_text16() or sqlite3_bind_text64() then
4826	** that parameter must be the byte offset
4827	** where the NUL terminator would occur assuming the string were NUL
4828	** terminated. If any NUL characters occur at byte offsets less than
4829	** the value of the fourth parameter then the resulting string value will
4830	** contain embedded NULs. The result of expressions involving strings
4831	** with embedded NULs is undefined.
4832	**
4833	** ^The fifth argument to the BLOB and string binding interfaces controls
4834	** or indicates the lifetime of the object referenced by the third parameter.
4835	** These three options exist:
4836	** ^ (1) A destructor to dispose of the BLOB or string after SQLite has finished
4837	** with it may be passed. ^It is called to dispose of the BLOB or string even
4838	** if the call to the bind API fails, except the destructor is not called if
4839	** the third parameter is a NULL pointer or the fourth parameter is negative.
4840	** ^ (2) The special constant, [SQLITE_STATIC], may be passed to indicate that
4841	** the application remains responsible for disposing of the object. ^In this
4842	** case, the object and the provided pointer to it must remain valid until
4843	** either the prepared statement is finalized or the same SQL parameter is
4844	** bound to something else, whichever occurs sooner.
4845	** ^ (3) The constant, [SQLITE_TRANSIENT], may be passed to indicate that the
4846	** object is to be copied prior to the return from sqlite3_bind_*(). ^The
4847	** object and pointer to it must remain valid until then. ^SQLite will then
4848	** manage the lifetime of its private copy.
4849	**
4850	** ^The sixth argument to sqlite3_bind_text64() must be one of
4851	** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]
4852	** to specify the encoding of the text in the third parameter. If
4853	** the sixth argument to sqlite3_bind_text64() is not one of the
4854	** allowed values shown above, or if the text encoding is different
4855	** from the encoding specified by the sixth parameter, then the behavior
4856	** is undefined.
4857	**
4858	** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
4859	** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
4860	** (just an integer to hold its size) while it is being processed.
4861	** Zeroblobs are intended to serve as placeholders for BLOBs whose
4862	** content is later written using
4863	** [sqlite3_blob_open \| incremental BLOB I/O] routines.
4864	** ^A negative value for the zeroblob results in a zero-length BLOB.
4865	**
4866	** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
4867	** [prepared statement] S to have an SQL value of NULL, but to also be
4868	** associated with the pointer P of type T. ^D is either a NULL pointer or
4869	** a pointer to a destructor function for P. ^SQLite will invoke the
4870	** destructor D with a single argument of P when it is finished using
4871	** P. The T parameter should be a static string, preferably a string
4872	** literal. The sqlite3_bind_pointer() routine is part of the
4873	** [pointer passing interface] added for SQLite 3.20.0.
4874	**
4875	** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
4876	** for the [prepared statement] or with a prepared statement for which
4877	** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
4878	** then the call will return [SQLITE_MISUSE]. If any sqlite3_bind_()
4879	** routine is passed a [prepared statement] that has been finalized, the
4880	** result is undefined and probably harmful.
4881	**
4882	** ^Bindings are not cleared by the [sqlite3_reset()] routine.
4883	** ^Unbound parameters are interpreted as NULL.
4884	**
4885	** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
4886	** [error code] if anything goes wrong.
4887	** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB
4888	** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or
4889	** [SQLITE_MAX_LENGTH].
4890	** ^[SQLITE_RANGE] is returned if the parameter
4891	** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
4892	**
4893	** See also: [sqlite3_bind_parameter_count()],
4894	** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
4895	*/
4896	SQLITE_API int sqlite3_bind_blob(sqlite3_stmt, int, const void, int n, void()(void));
4897	SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt, int, const void, sqlite3_uint64,
4898	void()(void));
4899	SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
4900	SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
4901	SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
4902	SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
4903	SQLITE_API int sqlite3_bind_text(sqlite3_stmt,int,const char,int,void()(void));
4904	SQLITE_API int sqlite3_bind_text16(sqlite3_stmt, int, const void, int, void()(void));
4905	SQLITE_API int sqlite3_bind_text64(sqlite3_stmt, int, const char, sqlite3_uint64,
4906	void()(void), unsigned char encoding);
4907	SQLITE_API int sqlite3_bind_value(sqlite3_stmt, int, const sqlite3_value);
4908	SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt, int, void, const char,void()(void*));
4909	SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
4910	SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
4911
4912	/*
4913	** CAPI3REF: Number Of SQL Parameters
4914	** METHOD: sqlite3_stmt
4915	**
4916	** ^This routine can be used to find the number of [SQL parameters]
4917	** in a [prepared statement]. SQL parameters are tokens of the
4918	** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
4919	** placeholders for values that are [sqlite3_bind_blob \| bound]
4920	** to the parameters at a later time.
4921	**
4922	** ^(This routine actually returns the index of the largest (rightmost)
4923	** parameter. For all forms except ?NNN, this will correspond to the
4924	** number of unique parameters. If parameters of the ?NNN form are used,
4925	** there may be gaps in the list.)^
4926	**
4927	** See also: [sqlite3_bind_blob\|sqlite3_bind()],
4928	** [sqlite3_bind_parameter_name()], and
4929	** [sqlite3_bind_parameter_index()].
4930	*/
4931	SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
4932
4933	/*
4934	** CAPI3REF: Name Of A Host Parameter
4935	** METHOD: sqlite3_stmt
4936	**
4937	** ^The sqlite3_bind_parameter_name(P,N) interface returns
4938	** the name of the N-th [SQL parameter] in the [prepared statement] P.
4939	** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
4940	** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
4941	** respectively.
4942	** In other words, the initial ":" or "$" or "@" or "?"
4943	** is included as part of the name.)^
4944	** ^Parameters of the form "?" without a following integer have no name
4945	** and are referred to as "nameless" or "anonymous parameters".
4946	**
4947	** ^The first host parameter has an index of 1, not 0.
4948	**
4949	** ^If the value N is out of range or if the N-th parameter is
4950	** nameless, then NULL is returned. ^The returned string is
4951	** always in UTF-8 encoding even if the named parameter was
4952	** originally specified as UTF-16 in [sqlite3_prepare16()],
4953	** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
4954	**
4955	** See also: [sqlite3_bind_blob\|sqlite3_bind()],
4956	** [sqlite3_bind_parameter_count()], and
4957	** [sqlite3_bind_parameter_index()].
4958	*/
4959	SQLITE_API const char sqlite3_bind_parameter_name(sqlite3_stmt, int);
4960
4961	/*
4962	** CAPI3REF: Index Of A Parameter With A Given Name
4963	** METHOD: sqlite3_stmt
4964	**
4965	** ^Return the index of an SQL parameter given its name. ^The
4966	** index value returned is suitable for use as the second
4967	** parameter to [sqlite3_bind_blob\|sqlite3_bind()]. ^A zero
4968	** is returned if no matching parameter is found. ^The parameter
4969	** name must be given in UTF-8 even if the original statement
4970	** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or
4971	** [sqlite3_prepare16_v3()].
4972	**
4973	** See also: [sqlite3_bind_blob\|sqlite3_bind()],
4974	** [sqlite3_bind_parameter_count()], and
4975	** [sqlite3_bind_parameter_name()].
4976	*/
4977	SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt, const char zName);
4978
4979	/*
4980	** CAPI3REF: Reset All Bindings On A Prepared Statement
4981	** METHOD: sqlite3_stmt
4982	**
4983	** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
4984	** the [sqlite3_bind_blob \| bindings] on a [prepared statement].
4985	** ^Use this routine to reset all host parameters to NULL.
4986	*/
4987	SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
4988
4989	/*
4990	** CAPI3REF: Number Of Columns In A Result Set
4991	** METHOD: sqlite3_stmt
4992	**
4993	** ^Return the number of columns in the result set returned by the
4994	** [prepared statement]. ^If this routine returns 0, that means the
4995	** [prepared statement] returns no data (for example an [UPDATE]).
4996	** ^However, just because this routine returns a positive number does not
4997	** mean that one or more rows of data will be returned. ^A SELECT statement
4998	** will always have a positive sqlite3_column_count() but depending on the
4999	** WHERE clause constraints and the table content, it might return no rows.
5000	**

Showing first 5,000 of 13,775 lines. View raw