1/******************************************************************************
2** This file is an amalgamation of many separate C source files from SQLite
3** version 3.30.1.  By combining all the individual C code files into this
4** single large file, the entire code can be compiled as a single translation
5** unit.  This allows many compilers to do optimizations that would not be
6** possible if the files were compiled separately.  Performance improvements
7** of 5% or more are commonly seen when SQLite is compiled as a single
8** translation unit.
9**
10** This file is all you need to compile SQLite.  To use SQLite in other
11** programs, you need this file and the "sqlite3.h" header file that defines
12** the programming interface to the SQLite library.  (If you do not have
13** the "sqlite3.h" header file at hand, you will find a copy embedded within
14** the text of this file.  Search for "Begin file sqlite3.h" to find the start
15** of the embedded sqlite3.h header file.) Additional code files may be needed
16** if you want a wrapper to interface SQLite with your choice of programming
17** language. The code for the "sqlite3" command-line shell is also in a
18** separate file. This file contains only code for the core SQLite library.
19*/
20#define SQLITE_CORE 1
21#define SQLITE_AMALGAMATION 1
22#ifndef SQLITE_PRIVATE
23# define SQLITE_PRIVATE static
24#endif
25/************** Begin file ctime.c *******************************************/
26/*
27** 2010 February 23
28**
29** The author disclaims copyright to this source code.  In place of
30** a legal notice, here is a blessing:
31**
32**    May you do good and not evil.
33**    May you find forgiveness for yourself and forgive others.
34**    May you share freely, never taking more than you give.
35**
36*************************************************************************
37**
38** This file implements routines used to report what compile-time options
39** SQLite was built with.
40*/
41
42#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS /* IMP: R-16824-07538 */
43
44/*
45** Include the configuration header output by 'configure' if we're using the
46** autoconf-based build
47*/
48#if defined(_HAVE_SQLITE_CONFIG_H) && !defined(SQLITECONFIG_H)
49#include "config.h"
50#define SQLITECONFIG_H 1
51#endif
52
53/* These macros are provided to "stringify" the value of the define
54** for those options in which the value is meaningful. */
55#define CTIMEOPT_VAL_(opt) #opt
56#define CTIMEOPT_VAL(opt) CTIMEOPT_VAL_(opt)
57
58/* Like CTIMEOPT_VAL, but especially for SQLITE_DEFAULT_LOOKASIDE. This
59** option requires a separate macro because legal values contain a single
60** comma. e.g. (-DSQLITE_DEFAULT_LOOKASIDE="100,100") */
61#define CTIMEOPT_VAL2_(opt1,opt2) #opt1 "," #opt2
62#define CTIMEOPT_VAL2(opt) CTIMEOPT_VAL2_(opt)
63
64/*
65** An array of names of all compile-time options.  This array should
66** be sorted A-Z.
67**
68** This array looks large, but in a typical installation actually uses
69** only a handful of compile-time options, so most times this array is usually
70** rather short and uses little memory space.
71*/
72static const char * const sqlite3azCompileOpt[] = {
73
74/*
75** BEGIN CODE GENERATED BY tool/mkctime.tcl
76*/
77#if SQLITE_32BIT_ROWID
78  "32BIT_ROWID",
79#endif
80#if SQLITE_4_BYTE_ALIGNED_MALLOC
81  "4_BYTE_ALIGNED_MALLOC",
82#endif
83#if SQLITE_64BIT_STATS
84  "64BIT_STATS",
85#endif
86#if SQLITE_ALLOW_COVERING_INDEX_SCAN
87  "ALLOW_COVERING_INDEX_SCAN",
88#endif
89#if SQLITE_ALLOW_URI_AUTHORITY
90  "ALLOW_URI_AUTHORITY",
91#endif
92#ifdef SQLITE_BITMASK_TYPE
93  "BITMASK_TYPE=" CTIMEOPT_VAL(SQLITE_BITMASK_TYPE),
94#endif
95#if SQLITE_BUG_COMPATIBLE_20160819
96  "BUG_COMPATIBLE_20160819",
97#endif
98#if SQLITE_CASE_SENSITIVE_LIKE
99  "CASE_SENSITIVE_LIKE",
100#endif
101#if SQLITE_CHECK_PAGES
102  "CHECK_PAGES",
103#endif
104#if defined(__clang__) && defined(__clang_major__)
105  "COMPILER=clang-" CTIMEOPT_VAL(__clang_major__) "."
106                    CTIMEOPT_VAL(__clang_minor__) "."
107                    CTIMEOPT_VAL(__clang_patchlevel__),
108#elif defined(_MSC_VER)
109  "COMPILER=msvc-" CTIMEOPT_VAL(_MSC_VER),
110#elif defined(__GNUC__) && defined(__VERSION__)
111  "COMPILER=gcc-" __VERSION__,
112#endif
113#if SQLITE_COVERAGE_TEST
114  "COVERAGE_TEST",
115#endif
116#if SQLITE_DEBUG
117  "DEBUG",
118#endif
119#if SQLITE_DEFAULT_AUTOMATIC_INDEX
120  "DEFAULT_AUTOMATIC_INDEX",
121#endif
122#if SQLITE_DEFAULT_AUTOVACUUM
123  "DEFAULT_AUTOVACUUM",
124#endif
125#ifdef SQLITE_DEFAULT_CACHE_SIZE
126  "DEFAULT_CACHE_SIZE=" CTIMEOPT_VAL(SQLITE_DEFAULT_CACHE_SIZE),
127#endif
128#if SQLITE_DEFAULT_CKPTFULLFSYNC
129  "DEFAULT_CKPTFULLFSYNC",
130#endif
131#ifdef SQLITE_DEFAULT_FILE_FORMAT
132  "DEFAULT_FILE_FORMAT=" CTIMEOPT_VAL(SQLITE_DEFAULT_FILE_FORMAT),
133#endif
134#ifdef SQLITE_DEFAULT_FILE_PERMISSIONS
135  "DEFAULT_FILE_PERMISSIONS=" CTIMEOPT_VAL(SQLITE_DEFAULT_FILE_PERMISSIONS),
136#endif
137#if SQLITE_DEFAULT_FOREIGN_KEYS
138  "DEFAULT_FOREIGN_KEYS",
139#endif
140#ifdef SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT
141  "DEFAULT_JOURNAL_SIZE_LIMIT=" CTIMEOPT_VAL(SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT),
142#endif
143#ifdef SQLITE_DEFAULT_LOCKING_MODE
144  "DEFAULT_LOCKING_MODE=" CTIMEOPT_VAL(SQLITE_DEFAULT_LOCKING_MODE),
145#endif
146#ifdef SQLITE_DEFAULT_LOOKASIDE
147  "DEFAULT_LOOKASIDE=" CTIMEOPT_VAL2(SQLITE_DEFAULT_LOOKASIDE),
148#endif
149#if SQLITE_DEFAULT_MEMSTATUS
150  "DEFAULT_MEMSTATUS",
151#endif
152#ifdef SQLITE_DEFAULT_MMAP_SIZE
153  "DEFAULT_MMAP_SIZE=" CTIMEOPT_VAL(SQLITE_DEFAULT_MMAP_SIZE),
154#endif
155#ifdef SQLITE_DEFAULT_PAGE_SIZE
156  "DEFAULT_PAGE_SIZE=" CTIMEOPT_VAL(SQLITE_DEFAULT_PAGE_SIZE),
157#endif
158#ifdef SQLITE_DEFAULT_PCACHE_INITSZ
159  "DEFAULT_PCACHE_INITSZ=" CTIMEOPT_VAL(SQLITE_DEFAULT_PCACHE_INITSZ),
160#endif
161#ifdef SQLITE_DEFAULT_PROXYDIR_PERMISSIONS
162  "DEFAULT_PROXYDIR_PERMISSIONS=" CTIMEOPT_VAL(SQLITE_DEFAULT_PROXYDIR_PERMISSIONS),
163#endif
164#if SQLITE_DEFAULT_RECURSIVE_TRIGGERS
165  "DEFAULT_RECURSIVE_TRIGGERS",
166#endif
167#ifdef SQLITE_DEFAULT_ROWEST
168  "DEFAULT_ROWEST=" CTIMEOPT_VAL(SQLITE_DEFAULT_ROWEST),
169#endif
170#ifdef SQLITE_DEFAULT_SECTOR_SIZE
171  "DEFAULT_SECTOR_SIZE=" CTIMEOPT_VAL(SQLITE_DEFAULT_SECTOR_SIZE),
172#endif
173#ifdef SQLITE_DEFAULT_SYNCHRONOUS
174  "DEFAULT_SYNCHRONOUS=" CTIMEOPT_VAL(SQLITE_DEFAULT_SYNCHRONOUS),
175#endif
176#ifdef SQLITE_DEFAULT_WAL_AUTOCHECKPOINT
177  "DEFAULT_WAL_AUTOCHECKPOINT=" CTIMEOPT_VAL(SQLITE_DEFAULT_WAL_AUTOCHECKPOINT),
178#endif
179#ifdef SQLITE_DEFAULT_WAL_SYNCHRONOUS
180  "DEFAULT_WAL_SYNCHRONOUS=" CTIMEOPT_VAL(SQLITE_DEFAULT_WAL_SYNCHRONOUS),
181#endif
182#ifdef SQLITE_DEFAULT_WORKER_THREADS
183  "DEFAULT_WORKER_THREADS=" CTIMEOPT_VAL(SQLITE_DEFAULT_WORKER_THREADS),
184#endif
185#if SQLITE_DIRECT_OVERFLOW_READ
186  "DIRECT_OVERFLOW_READ",
187#endif
188#if SQLITE_DISABLE_DIRSYNC
189  "DISABLE_DIRSYNC",
190#endif
191#if SQLITE_DISABLE_FTS3_UNICODE
192  "DISABLE_FTS3_UNICODE",
193#endif
194#if SQLITE_DISABLE_FTS4_DEFERRED
195  "DISABLE_FTS4_DEFERRED",
196#endif
197#if SQLITE_DISABLE_INTRINSIC
198  "DISABLE_INTRINSIC",
199#endif
200#if SQLITE_DISABLE_LFS
201  "DISABLE_LFS",
202#endif
203#if SQLITE_DISABLE_PAGECACHE_OVERFLOW_STATS
204  "DISABLE_PAGECACHE_OVERFLOW_STATS",
205#endif
206#if SQLITE_DISABLE_SKIPAHEAD_DISTINCT
207  "DISABLE_SKIPAHEAD_DISTINCT",
208#endif
209#ifdef SQLITE_ENABLE_8_3_NAMES
210  "ENABLE_8_3_NAMES=" CTIMEOPT_VAL(SQLITE_ENABLE_8_3_NAMES),
211#endif
212#if SQLITE_ENABLE_API_ARMOR
213  "ENABLE_API_ARMOR",
214#endif
215#if SQLITE_ENABLE_ATOMIC_WRITE
216  "ENABLE_ATOMIC_WRITE",
217#endif
218#if SQLITE_ENABLE_BATCH_ATOMIC_WRITE
219  "ENABLE_BATCH_ATOMIC_WRITE",
220#endif
221#if SQLITE_ENABLE_CEROD
222  "ENABLE_CEROD=" CTIMEOPT_VAL(SQLITE_ENABLE_CEROD),
223#endif
224#if SQLITE_ENABLE_COLUMN_METADATA
225  "ENABLE_COLUMN_METADATA",
226#endif
227#if SQLITE_ENABLE_COLUMN_USED_MASK
228  "ENABLE_COLUMN_USED_MASK",
229#endif
230#if SQLITE_ENABLE_COSTMULT
231  "ENABLE_COSTMULT",
232#endif
233#if SQLITE_ENABLE_CURSOR_HINTS
234  "ENABLE_CURSOR_HINTS",
235#endif
236#if SQLITE_ENABLE_DBSTAT_VTAB
237  "ENABLE_DBSTAT_VTAB",
238#endif
239#if SQLITE_ENABLE_EXPENSIVE_ASSERT
240  "ENABLE_EXPENSIVE_ASSERT",
241#endif
242#if SQLITE_ENABLE_FTS1
243  "ENABLE_FTS1",
244#endif
245#if SQLITE_ENABLE_FTS2
246  "ENABLE_FTS2",
247#endif
248#if SQLITE_ENABLE_FTS3
249  "ENABLE_FTS3",
250#endif
251#if SQLITE_ENABLE_FTS3_PARENTHESIS
252  "ENABLE_FTS3_PARENTHESIS",
253#endif
254#if SQLITE_ENABLE_FTS3_TOKENIZER
255  "ENABLE_FTS3_TOKENIZER",
256#endif
257#if SQLITE_ENABLE_FTS4
258  "ENABLE_FTS4",
259#endif
260#if SQLITE_ENABLE_FTS5
261  "ENABLE_FTS5",
262#endif
263#if SQLITE_ENABLE_GEOPOLY
264  "ENABLE_GEOPOLY",
265#endif
266#if SQLITE_ENABLE_HIDDEN_COLUMNS
267  "ENABLE_HIDDEN_COLUMNS",
268#endif
269#if SQLITE_ENABLE_ICU
270  "ENABLE_ICU",
271#endif
272#if SQLITE_ENABLE_IOTRACE
273  "ENABLE_IOTRACE",
274#endif
275#if SQLITE_ENABLE_JSON1
276  "ENABLE_JSON1",
277#endif
278#if SQLITE_ENABLE_LOAD_EXTENSION
279  "ENABLE_LOAD_EXTENSION",
280#endif
281#ifdef SQLITE_ENABLE_LOCKING_STYLE
282  "ENABLE_LOCKING_STYLE=" CTIMEOPT_VAL(SQLITE_ENABLE_LOCKING_STYLE),
283#endif
284#if SQLITE_ENABLE_MEMORY_MANAGEMENT
285  "ENABLE_MEMORY_MANAGEMENT",
286#endif
287#if SQLITE_ENABLE_MEMSYS3
288  "ENABLE_MEMSYS3",
289#endif
290#if SQLITE_ENABLE_MEMSYS5
291  "ENABLE_MEMSYS5",
292#endif
293#if SQLITE_ENABLE_MULTIPLEX
294  "ENABLE_MULTIPLEX",
295#endif
296#if SQLITE_ENABLE_NORMALIZE
297  "ENABLE_NORMALIZE",
298#endif
299#if SQLITE_ENABLE_NULL_TRIM
300  "ENABLE_NULL_TRIM",
301#endif
302#if SQLITE_ENABLE_OVERSIZE_CELL_CHECK
303  "ENABLE_OVERSIZE_CELL_CHECK",
304#endif
305#if SQLITE_ENABLE_PREUPDATE_HOOK
306  "ENABLE_PREUPDATE_HOOK",
307#endif
308#if SQLITE_ENABLE_QPSG
309  "ENABLE_QPSG",
310#endif
311#if SQLITE_ENABLE_RBU
312  "ENABLE_RBU",
313#endif
314#if SQLITE_ENABLE_RTREE
315  "ENABLE_RTREE",
316#endif
317#if SQLITE_ENABLE_SELECTTRACE
318  "ENABLE_SELECTTRACE",
319#endif
320#if SQLITE_ENABLE_SESSION
321  "ENABLE_SESSION",
322#endif
323#if SQLITE_ENABLE_SNAPSHOT
324  "ENABLE_SNAPSHOT",
325#endif
326#if SQLITE_ENABLE_SORTER_REFERENCES
327  "ENABLE_SORTER_REFERENCES",
328#endif
329#if SQLITE_ENABLE_SQLLOG
330  "ENABLE_SQLLOG",
331#endif
332#if defined(SQLITE_ENABLE_STAT4)
333  "ENABLE_STAT4",
334#endif
335#if SQLITE_ENABLE_STMTVTAB
336  "ENABLE_STMTVTAB",
337#endif
338#if SQLITE_ENABLE_STMT_SCANSTATUS
339  "ENABLE_STMT_SCANSTATUS",
340#endif
341#if SQLITE_ENABLE_UNKNOWN_SQL_FUNCTION
342  "ENABLE_UNKNOWN_SQL_FUNCTION",
343#endif
344#if SQLITE_ENABLE_UNLOCK_NOTIFY
345  "ENABLE_UNLOCK_NOTIFY",
346#endif
347#if SQLITE_ENABLE_UPDATE_DELETE_LIMIT
348  "ENABLE_UPDATE_DELETE_LIMIT",
349#endif
350#if SQLITE_ENABLE_URI_00_ERROR
351  "ENABLE_URI_00_ERROR",
352#endif
353#if SQLITE_ENABLE_VFSTRACE
354  "ENABLE_VFSTRACE",
355#endif
356#if SQLITE_ENABLE_WHERETRACE
357  "ENABLE_WHERETRACE",
358#endif
359#if SQLITE_ENABLE_ZIPVFS
360  "ENABLE_ZIPVFS",
361#endif
362#if SQLITE_EXPLAIN_ESTIMATED_ROWS
363  "EXPLAIN_ESTIMATED_ROWS",
364#endif
365#if SQLITE_EXTRA_IFNULLROW
366  "EXTRA_IFNULLROW",
367#endif
368#ifdef SQLITE_EXTRA_INIT
369  "EXTRA_INIT=" CTIMEOPT_VAL(SQLITE_EXTRA_INIT),
370#endif
371#ifdef SQLITE_EXTRA_SHUTDOWN
372  "EXTRA_SHUTDOWN=" CTIMEOPT_VAL(SQLITE_EXTRA_SHUTDOWN),
373#endif
374#ifdef SQLITE_FTS3_MAX_EXPR_DEPTH
375  "FTS3_MAX_EXPR_DEPTH=" CTIMEOPT_VAL(SQLITE_FTS3_MAX_EXPR_DEPTH),
376#endif
377#if SQLITE_FTS5_ENABLE_TEST_MI
378  "FTS5_ENABLE_TEST_MI",
379#endif
380#if SQLITE_FTS5_NO_WITHOUT_ROWID
381  "FTS5_NO_WITHOUT_ROWID",
382#endif
383#if SQLITE_HAS_CODEC
384  "HAS_CODEC",
385#endif
386#if HAVE_ISNAN || SQLITE_HAVE_ISNAN
387  "HAVE_ISNAN",
388#endif
389#if SQLITE_HOMEGROWN_RECURSIVE_MUTEX
390  "HOMEGROWN_RECURSIVE_MUTEX",
391#endif
392#if SQLITE_IGNORE_AFP_LOCK_ERRORS
393  "IGNORE_AFP_LOCK_ERRORS",
394#endif
395#if SQLITE_IGNORE_FLOCK_LOCK_ERRORS
396  "IGNORE_FLOCK_LOCK_ERRORS",
397#endif
398#if SQLITE_INLINE_MEMCPY
399  "INLINE_MEMCPY",
400#endif
401#if SQLITE_INT64_TYPE
402  "INT64_TYPE",
403#endif
404#ifdef SQLITE_INTEGRITY_CHECK_ERROR_MAX
405  "INTEGRITY_CHECK_ERROR_MAX=" CTIMEOPT_VAL(SQLITE_INTEGRITY_CHECK_ERROR_MAX),
406#endif
407#if SQLITE_LIKE_DOESNT_MATCH_BLOBS
408  "LIKE_DOESNT_MATCH_BLOBS",
409#endif
410#if SQLITE_LOCK_TRACE
411  "LOCK_TRACE",
412#endif
413#if SQLITE_LOG_CACHE_SPILL
414  "LOG_CACHE_SPILL",
415#endif
416#ifdef SQLITE_MALLOC_SOFT_LIMIT
417  "MALLOC_SOFT_LIMIT=" CTIMEOPT_VAL(SQLITE_MALLOC_SOFT_LIMIT),
418#endif
419#ifdef SQLITE_MAX_ATTACHED
420  "MAX_ATTACHED=" CTIMEOPT_VAL(SQLITE_MAX_ATTACHED),
421#endif
422#ifdef SQLITE_MAX_COLUMN
423  "MAX_COLUMN=" CTIMEOPT_VAL(SQLITE_MAX_COLUMN),
424#endif
425#ifdef SQLITE_MAX_COMPOUND_SELECT
426  "MAX_COMPOUND_SELECT=" CTIMEOPT_VAL(SQLITE_MAX_COMPOUND_SELECT),
427#endif
428#ifdef SQLITE_MAX_DEFAULT_PAGE_SIZE
429  "MAX_DEFAULT_PAGE_SIZE=" CTIMEOPT_VAL(SQLITE_MAX_DEFAULT_PAGE_SIZE),
430#endif
431#ifdef SQLITE_MAX_EXPR_DEPTH
432  "MAX_EXPR_DEPTH=" CTIMEOPT_VAL(SQLITE_MAX_EXPR_DEPTH),
433#endif
434#ifdef SQLITE_MAX_FUNCTION_ARG
435  "MAX_FUNCTION_ARG=" CTIMEOPT_VAL(SQLITE_MAX_FUNCTION_ARG),
436#endif
437#ifdef SQLITE_MAX_LENGTH
438  "MAX_LENGTH=" CTIMEOPT_VAL(SQLITE_MAX_LENGTH),
439#endif
440#ifdef SQLITE_MAX_LIKE_PATTERN_LENGTH
441  "MAX_LIKE_PATTERN_LENGTH=" CTIMEOPT_VAL(SQLITE_MAX_LIKE_PATTERN_LENGTH),
442#endif
443#ifdef SQLITE_MAX_MEMORY
444  "MAX_MEMORY=" CTIMEOPT_VAL(SQLITE_MAX_MEMORY),
445#endif
446#ifdef SQLITE_MAX_MMAP_SIZE
447  "MAX_MMAP_SIZE=" CTIMEOPT_VAL(SQLITE_MAX_MMAP_SIZE),
448#endif
449#ifdef SQLITE_MAX_MMAP_SIZE_
450  "MAX_MMAP_SIZE_=" CTIMEOPT_VAL(SQLITE_MAX_MMAP_SIZE_),
451#endif
452#ifdef SQLITE_MAX_PAGE_COUNT
453  "MAX_PAGE_COUNT=" CTIMEOPT_VAL(SQLITE_MAX_PAGE_COUNT),
454#endif
455#ifdef SQLITE_MAX_PAGE_SIZE
456  "MAX_PAGE_SIZE=" CTIMEOPT_VAL(SQLITE_MAX_PAGE_SIZE),
457#endif
458#ifdef SQLITE_MAX_SCHEMA_RETRY
459  "MAX_SCHEMA_RETRY=" CTIMEOPT_VAL(SQLITE_MAX_SCHEMA_RETRY),
460#endif
461#ifdef SQLITE_MAX_SQL_LENGTH
462  "MAX_SQL_LENGTH=" CTIMEOPT_VAL(SQLITE_MAX_SQL_LENGTH),
463#endif
464#ifdef SQLITE_MAX_TRIGGER_DEPTH
465  "MAX_TRIGGER_DEPTH=" CTIMEOPT_VAL(SQLITE_MAX_TRIGGER_DEPTH),
466#endif
467#ifdef SQLITE_MAX_VARIABLE_NUMBER
468  "MAX_VARIABLE_NUMBER=" CTIMEOPT_VAL(SQLITE_MAX_VARIABLE_NUMBER),
469#endif
470#ifdef SQLITE_MAX_VDBE_OP
471  "MAX_VDBE_OP=" CTIMEOPT_VAL(SQLITE_MAX_VDBE_OP),
472#endif
473#ifdef SQLITE_MAX_WORKER_THREADS
474  "MAX_WORKER_THREADS=" CTIMEOPT_VAL(SQLITE_MAX_WORKER_THREADS),
475#endif
476#if SQLITE_MEMDEBUG
477  "MEMDEBUG",
478#endif
479#if SQLITE_MIXED_ENDIAN_64BIT_FLOAT
480  "MIXED_ENDIAN_64BIT_FLOAT",
481#endif
482#if SQLITE_MMAP_READWRITE
483  "MMAP_READWRITE",
484#endif
485#if SQLITE_MUTEX_NOOP
486  "MUTEX_NOOP",
487#endif
488#if SQLITE_MUTEX_NREF
489  "MUTEX_NREF",
490#endif
491#if SQLITE_MUTEX_OMIT
492  "MUTEX_OMIT",
493#endif
494#if SQLITE_MUTEX_PTHREADS
495  "MUTEX_PTHREADS",
496#endif
497#if SQLITE_MUTEX_W32
498  "MUTEX_W32",
499#endif
500#if SQLITE_NEED_ERR_NAME
501  "NEED_ERR_NAME",
502#endif
503#if SQLITE_NOINLINE
504  "NOINLINE",
505#endif
506#if SQLITE_NO_SYNC
507  "NO_SYNC",
508#endif
509#if SQLITE_OMIT_ALTERTABLE
510  "OMIT_ALTERTABLE",
511#endif
512#if SQLITE_OMIT_ANALYZE
513  "OMIT_ANALYZE",
514#endif
515#if SQLITE_OMIT_ATTACH
516  "OMIT_ATTACH",
517#endif
518#if SQLITE_OMIT_AUTHORIZATION
519  "OMIT_AUTHORIZATION",
520#endif
521#if SQLITE_OMIT_AUTOINCREMENT
522  "OMIT_AUTOINCREMENT",
523#endif
524#if SQLITE_OMIT_AUTOINIT
525  "OMIT_AUTOINIT",
526#endif
527#if SQLITE_OMIT_AUTOMATIC_INDEX
528  "OMIT_AUTOMATIC_INDEX",
529#endif
530#if SQLITE_OMIT_AUTORESET
531  "OMIT_AUTORESET",
532#endif
533#if SQLITE_OMIT_AUTOVACUUM
534  "OMIT_AUTOVACUUM",
535#endif
536#if SQLITE_OMIT_BETWEEN_OPTIMIZATION
537  "OMIT_BETWEEN_OPTIMIZATION",
538#endif
539#if SQLITE_OMIT_BLOB_LITERAL
540  "OMIT_BLOB_LITERAL",
541#endif
542#if SQLITE_OMIT_BTREECOUNT
543  "OMIT_BTREECOUNT",
544#endif
545#if SQLITE_OMIT_CAST
546  "OMIT_CAST",
547#endif
548#if SQLITE_OMIT_CHECK
549  "OMIT_CHECK",
550#endif
551#if SQLITE_OMIT_COMPLETE
552  "OMIT_COMPLETE",
553#endif
554#if SQLITE_OMIT_COMPOUND_SELECT
555  "OMIT_COMPOUND_SELECT",
556#endif
557#if SQLITE_OMIT_CONFLICT_CLAUSE
558  "OMIT_CONFLICT_CLAUSE",
559#endif
560#if SQLITE_OMIT_CTE
561  "OMIT_CTE",
562#endif
563#if SQLITE_OMIT_DATETIME_FUNCS
564  "OMIT_DATETIME_FUNCS",
565#endif
566#if SQLITE_OMIT_DECLTYPE
567  "OMIT_DECLTYPE",
568#endif
569#if SQLITE_OMIT_DEPRECATED
570  "OMIT_DEPRECATED",
571#endif
572#if SQLITE_OMIT_DISKIO
573  "OMIT_DISKIO",
574#endif
575#if SQLITE_OMIT_EXPLAIN
576  "OMIT_EXPLAIN",
577#endif
578#if SQLITE_OMIT_FLAG_PRAGMAS
579  "OMIT_FLAG_PRAGMAS",
580#endif
581#if SQLITE_OMIT_FLOATING_POINT
582  "OMIT_FLOATING_POINT",
583#endif
584#if SQLITE_OMIT_FOREIGN_KEY
585  "OMIT_FOREIGN_KEY",
586#endif
587#if SQLITE_OMIT_GET_TABLE
588  "OMIT_GET_TABLE",
589#endif
590#if SQLITE_OMIT_HEX_INTEGER
591  "OMIT_HEX_INTEGER",
592#endif
593#if SQLITE_OMIT_INCRBLOB
594  "OMIT_INCRBLOB",
595#endif
596#if SQLITE_OMIT_INTEGRITY_CHECK
597  "OMIT_INTEGRITY_CHECK",
598#endif
599#if SQLITE_OMIT_LIKE_OPTIMIZATION
600  "OMIT_LIKE_OPTIMIZATION",
601#endif
602#if SQLITE_OMIT_LOAD_EXTENSION
603  "OMIT_LOAD_EXTENSION",
604#endif
605#if SQLITE_OMIT_LOCALTIME
606  "OMIT_LOCALTIME",
607#endif
608#if SQLITE_OMIT_LOOKASIDE
609  "OMIT_LOOKASIDE",
610#endif
611#if SQLITE_OMIT_MEMORYDB
612  "OMIT_MEMORYDB",
613#endif
614#if SQLITE_OMIT_OR_OPTIMIZATION
615  "OMIT_OR_OPTIMIZATION",
616#endif
617#if SQLITE_OMIT_PAGER_PRAGMAS
618  "OMIT_PAGER_PRAGMAS",
619#endif
620#if SQLITE_OMIT_PARSER_TRACE
621  "OMIT_PARSER_TRACE",
622#endif
623#if SQLITE_OMIT_POPEN
624  "OMIT_POPEN",
625#endif
626#if SQLITE_OMIT_PRAGMA
627  "OMIT_PRAGMA",
628#endif
629#if SQLITE_OMIT_PROGRESS_CALLBACK
630  "OMIT_PROGRESS_CALLBACK",
631#endif
632#if SQLITE_OMIT_QUICKBALANCE
633  "OMIT_QUICKBALANCE",
634#endif
635#if SQLITE_OMIT_REINDEX
636  "OMIT_REINDEX",
637#endif
638#if SQLITE_OMIT_SCHEMA_PRAGMAS
639  "OMIT_SCHEMA_PRAGMAS",
640#endif
641#if SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS
642  "OMIT_SCHEMA_VERSION_PRAGMAS",
643#endif
644#if SQLITE_OMIT_SHARED_CACHE
645  "OMIT_SHARED_CACHE",
646#endif
647#if SQLITE_OMIT_SHUTDOWN_DIRECTORIES
648  "OMIT_SHUTDOWN_DIRECTORIES",
649#endif
650#if SQLITE_OMIT_SUBQUERY
651  "OMIT_SUBQUERY",
652#endif
653#if SQLITE_OMIT_TCL_VARIABLE
654  "OMIT_TCL_VARIABLE",
655#endif
656#if SQLITE_OMIT_TEMPDB
657  "OMIT_TEMPDB",
658#endif
659#if SQLITE_OMIT_TEST_CONTROL
660  "OMIT_TEST_CONTROL",
661#endif
662#if SQLITE_OMIT_TRACE
663  "OMIT_TRACE",
664#endif
665#if SQLITE_OMIT_TRIGGER
666  "OMIT_TRIGGER",
667#endif
668#if SQLITE_OMIT_TRUNCATE_OPTIMIZATION
669  "OMIT_TRUNCATE_OPTIMIZATION",
670#endif
671#if SQLITE_OMIT_UTF16
672  "OMIT_UTF16",
673#endif
674#if SQLITE_OMIT_VACUUM
675  "OMIT_VACUUM",
676#endif
677#if SQLITE_OMIT_VIEW
678  "OMIT_VIEW",
679#endif
680#if SQLITE_OMIT_VIRTUALTABLE
681  "OMIT_VIRTUALTABLE",
682#endif
683#if SQLITE_OMIT_WAL
684  "OMIT_WAL",
685#endif
686#if SQLITE_OMIT_WSD
687  "OMIT_WSD",
688#endif
689#if SQLITE_OMIT_XFER_OPT
690  "OMIT_XFER_OPT",
691#endif
692#if SQLITE_PCACHE_SEPARATE_HEADER
693  "PCACHE_SEPARATE_HEADER",
694#endif
695#if SQLITE_PERFORMANCE_TRACE
696  "PERFORMANCE_TRACE",
697#endif
698#if SQLITE_POWERSAFE_OVERWRITE
699  "POWERSAFE_OVERWRITE",
700#endif
701#if SQLITE_PREFER_PROXY_LOCKING
702  "PREFER_PROXY_LOCKING",
703#endif
704#if SQLITE_PROXY_DEBUG
705  "PROXY_DEBUG",
706#endif
707#if SQLITE_REVERSE_UNORDERED_SELECTS
708  "REVERSE_UNORDERED_SELECTS",
709#endif
710#if SQLITE_RTREE_INT_ONLY
711  "RTREE_INT_ONLY",
712#endif
713#if SQLITE_SECURE_DELETE
714  "SECURE_DELETE",
715#endif
716#if SQLITE_SMALL_STACK
717  "SMALL_STACK",
718#endif
719#ifdef SQLITE_SORTER_PMASZ
720  "SORTER_PMASZ=" CTIMEOPT_VAL(SQLITE_SORTER_PMASZ),
721#endif
722#if SQLITE_SOUNDEX
723  "SOUNDEX",
724#endif
725#ifdef SQLITE_STAT4_SAMPLES
726  "STAT4_SAMPLES=" CTIMEOPT_VAL(SQLITE_STAT4_SAMPLES),
727#endif
728#ifdef SQLITE_STMTJRNL_SPILL
729  "STMTJRNL_SPILL=" CTIMEOPT_VAL(SQLITE_STMTJRNL_SPILL),
730#endif
731#if SQLITE_SUBSTR_COMPATIBILITY
732  "SUBSTR_COMPATIBILITY",
733#endif
734#if SQLITE_SYSTEM_MALLOC
735  "SYSTEM_MALLOC",
736#endif
737#if SQLITE_TCL
738  "TCL",
739#endif
740#ifdef SQLITE_TEMP_STORE
741  "TEMP_STORE=" CTIMEOPT_VAL(SQLITE_TEMP_STORE),
742#endif
743#if SQLITE_TEST
744  "TEST",
745#endif
746#if defined(SQLITE_THREADSAFE)
747  "THREADSAFE=" CTIMEOPT_VAL(SQLITE_THREADSAFE),
748#elif defined(THREADSAFE)
749  "THREADSAFE=" CTIMEOPT_VAL(THREADSAFE),
750#else
751  "THREADSAFE=1",
752#endif
753#if SQLITE_UNLINK_AFTER_CLOSE
754  "UNLINK_AFTER_CLOSE",
755#endif
756#if SQLITE_UNTESTABLE
757  "UNTESTABLE",
758#endif
759#if SQLITE_USER_AUTHENTICATION
760  "USER_AUTHENTICATION",
761#endif
762#if SQLITE_USE_ALLOCA
763  "USE_ALLOCA",
764#endif
765#if SQLITE_USE_FCNTL_TRACE
766  "USE_FCNTL_TRACE",
767#endif
768#if SQLITE_USE_URI
769  "USE_URI",
770#endif
771#if SQLITE_VDBE_COVERAGE
772  "VDBE_COVERAGE",
773#endif
774#if SQLITE_WIN32_MALLOC
775  "WIN32_MALLOC",
776#endif
777#if SQLITE_ZERO_MALLOC
778  "ZERO_MALLOC",
779#endif
780/*
781** END CODE GENERATED BY tool/mkctime.tcl
782*/
783};
784
785SQLITE_PRIVATE const char **sqlite3CompileOptions(int *pnOpt){
786  *pnOpt = sizeof(sqlite3azCompileOpt) / sizeof(sqlite3azCompileOpt[0]);
787  return (const char**)sqlite3azCompileOpt;
788}
789
790#endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */
791
792/************** End of ctime.c ***********************************************/
793/************** Begin file sqliteInt.h ***************************************/
794/*
795** 2001 September 15
796**
797** The author disclaims copyright to this source code.  In place of
798** a legal notice, here is a blessing:
799**
800**    May you do good and not evil.
801**    May you find forgiveness for yourself and forgive others.
802**    May you share freely, never taking more than you give.
803**
804*************************************************************************
805** Internal interface definitions for SQLite.
806**
807*/
808#ifndef SQLITEINT_H
809#define SQLITEINT_H
810
811/* Special Comments:
812**
813** Some comments have special meaning to the tools that measure test
814** coverage:
815**
816**    NO_TEST                     - The branches on this line are not
817**                                  measured by branch coverage.  This is
818**                                  used on lines of code that actually
819**                                  implement parts of coverage testing.
820**
821**    OPTIMIZATION-IF-TRUE        - This branch is allowed to alway be false
822**                                  and the correct answer is still obtained,
823**                                  though perhaps more slowly.
824**
825**    OPTIMIZATION-IF-FALSE       - This branch is allowed to alway be true
826**                                  and the correct answer is still obtained,
827**                                  though perhaps more slowly.
828**
829**    PREVENTS-HARMLESS-OVERREAD  - This branch prevents a buffer overread
830**                                  that would be harmless and undetectable
831**                                  if it did occur.
832**
833** In all cases, the special comment must be enclosed in the usual
834** slash-asterisk...asterisk-slash comment marks, with no spaces between the
835** asterisks and the comment text.
836*/
837
838/*
839** Make sure the Tcl calling convention macro is defined.  This macro is
840** only used by test code and Tcl integration code.
841*/
842#ifndef SQLITE_TCLAPI
843#  define SQLITE_TCLAPI
844#endif
845
846/*
847** Include the header file used to customize the compiler options for MSVC.
848** This should be done first so that it can successfully prevent spurious
849** compiler warnings due to subsequent content in this file and other files
850** that are included by this file.
851*/
852/************** Include msvc.h in the middle of sqliteInt.h ******************/
853/************** Begin file msvc.h ********************************************/
854/*
855** 2015 January 12
856**
857** The author disclaims copyright to this source code.  In place of
858** a legal notice, here is a blessing:
859**
860**    May you do good and not evil.
861**    May you find forgiveness for yourself and forgive others.
862**    May you share freely, never taking more than you give.
863**
864******************************************************************************
865**
866** This file contains code that is specific to MSVC.
867*/
868#ifndef SQLITE_MSVC_H
869#define SQLITE_MSVC_H
870
871#if defined(_MSC_VER)
872#pragma warning(disable : 4054)
873#pragma warning(disable : 4055)
874#pragma warning(disable : 4100)
875#pragma warning(disable : 4127)
876#pragma warning(disable : 4130)
877#pragma warning(disable : 4152)
878#pragma warning(disable : 4189)
879#pragma warning(disable : 4206)
880#pragma warning(disable : 4210)
881#pragma warning(disable : 4232)
882#pragma warning(disable : 4244)
883#pragma warning(disable : 4305)
884#pragma warning(disable : 4306)
885#pragma warning(disable : 4702)
886#pragma warning(disable : 4706)
887#endif /* defined(_MSC_VER) */
888
889#if defined(_MSC_VER) && !defined(_WIN64)
890#undef SQLITE_4_BYTE_ALIGNED_MALLOC
891#define SQLITE_4_BYTE_ALIGNED_MALLOC
892#endif /* defined(_MSC_VER) && !defined(_WIN64) */
893
894#endif /* SQLITE_MSVC_H */
895
896/************** End of msvc.h ************************************************/
897/************** Continuing where we left off in sqliteInt.h ******************/
898
899/*
900** Special setup for VxWorks
901*/
902/************** Include vxworks.h in the middle of sqliteInt.h ***************/
903/************** Begin file vxworks.h *****************************************/
904/*
905** 2015-03-02
906**
907** The author disclaims copyright to this source code.  In place of
908** a legal notice, here is a blessing:
909**
910**    May you do good and not evil.
911**    May you find forgiveness for yourself and forgive others.
912**    May you share freely, never taking more than you give.
913**
914******************************************************************************
915**
916** This file contains code that is specific to Wind River's VxWorks
917*/
918#if defined(__RTP__) || defined(_WRS_KERNEL)
919/* This is VxWorks.  Set up things specially for that OS
920*/
921#include <vxWorks.h>
922#include <pthread.h>  /* amalgamator: dontcache */
923#define OS_VXWORKS 1
924#define SQLITE_OS_OTHER 0
925#define SQLITE_HOMEGROWN_RECURSIVE_MUTEX 1
926#define SQLITE_OMIT_LOAD_EXTENSION 1
927#define SQLITE_ENABLE_LOCKING_STYLE 0
928#define HAVE_UTIME 1
929#else
930/* This is not VxWorks. */
931#define OS_VXWORKS 0
932#define HAVE_FCHOWN 1
933#define HAVE_READLINK 1
934#define HAVE_LSTAT 1
935#endif /* defined(_WRS_KERNEL) */
936
937/************** End of vxworks.h *********************************************/
938/************** Continuing where we left off in sqliteInt.h ******************/
939
940/*
941** These #defines should enable >2GB file support on POSIX if the
942** underlying operating system supports it.  If the OS lacks
943** large file support, or if the OS is windows, these should be no-ops.
944**
945** Ticket #2739:  The _LARGEFILE_SOURCE macro must appear before any
946** system #includes.  Hence, this block of code must be the very first
947** code in all source files.
948**
949** Large file support can be disabled using the -DSQLITE_DISABLE_LFS switch
950** on the compiler command line.  This is necessary if you are compiling
951** on a recent machine (ex: Red Hat 7.2) but you want your code to work
952** on an older machine (ex: Red Hat 6.0).  If you compile on Red Hat 7.2
953** without this option, LFS is enable.  But LFS does not exist in the kernel
954** in Red Hat 6.0, so the code won't work.  Hence, for maximum binary
955** portability you should omit LFS.
956**
957** The previous paragraph was written in 2005.  (This paragraph is written
958** on 2008-11-28.) These days, all Linux kernels support large files, so
959** you should probably leave LFS enabled.  But some embedded platforms might
960** lack LFS in which case the SQLITE_DISABLE_LFS macro might still be useful.
961**
962** Similar is true for Mac OS X.  LFS is only supported on Mac OS X 9 and later.
963*/
964#ifndef SQLITE_DISABLE_LFS
965# define _LARGE_FILE       1
966# ifndef _FILE_OFFSET_BITS
967#   define _FILE_OFFSET_BITS 64
968# endif
969# define _LARGEFILE_SOURCE 1
970#endif
971
972/* The GCC_VERSION and MSVC_VERSION macros are used to
973** conditionally include optimizations for each of these compilers.  A
974** value of 0 means that compiler is not being used.  The
975** SQLITE_DISABLE_INTRINSIC macro means do not use any compiler-specific
976** optimizations, and hence set all compiler macros to 0
977**
978** There was once also a CLANG_VERSION macro.  However, we learn that the
979** version numbers in clang are for "marketing" only and are inconsistent
980** and unreliable.  Fortunately, all versions of clang also recognize the
981** gcc version numbers and have reasonable settings for gcc version numbers,
982** so the GCC_VERSION macro will be set to a correct non-zero value even
983** when compiling with clang.
984*/
985#if defined(__GNUC__) && !defined(SQLITE_DISABLE_INTRINSIC)
986# define GCC_VERSION (__GNUC__*1000000+__GNUC_MINOR__*1000+__GNUC_PATCHLEVEL__)
987#else
988# define GCC_VERSION 0
989#endif
990#if defined(_MSC_VER) && !defined(SQLITE_DISABLE_INTRINSIC)
991# define MSVC_VERSION _MSC_VER
992#else
993# define MSVC_VERSION 0
994#endif
995
996/* Needed for various definitions... */
997#if defined(__GNUC__) && !defined(_GNU_SOURCE)
998# define _GNU_SOURCE
999#endif
1000
1001#if defined(__OpenBSD__) && !defined(_BSD_SOURCE)
1002# define _BSD_SOURCE
1003#endif
1004
1005/*
1006** For MinGW, check to see if we can include the header file containing its
1007** version information, among other things.  Normally, this internal MinGW
1008** header file would [only] be included automatically by other MinGW header
1009** files; however, the contained version information is now required by this
1010** header file to work around binary compatibility issues (see below) and
1011** this is the only known way to reliably obtain it.  This entire #if block
1012** would be completely unnecessary if there was any other way of detecting
1013** MinGW via their preprocessor (e.g. if they customized their GCC to define
1014** some MinGW-specific macros).  When compiling for MinGW, either the
1015** _HAVE_MINGW_H or _HAVE__MINGW_H (note the extra underscore) macro must be
1016** defined; otherwise, detection of conditions specific to MinGW will be
1017** disabled.
1018*/
1019#if defined(_HAVE_MINGW_H)
1020# include "mingw.h"
1021#elif defined(_HAVE__MINGW_H)
1022# include "_mingw.h"
1023#endif
1024
1025/*
1026** For MinGW version 4.x (and higher), check to see if the _USE_32BIT_TIME_T
1027** define is required to maintain binary compatibility with the MSVC runtime
1028** library in use (e.g. for Windows XP).
1029*/
1030#if !defined(_USE_32BIT_TIME_T) && !defined(_USE_64BIT_TIME_T) && \
1031    defined(_WIN32) && !defined(_WIN64) && \
1032    defined(__MINGW_MAJOR_VERSION) && __MINGW_MAJOR_VERSION >= 4 && \
1033    defined(__MSVCRT__)
1034# define _USE_32BIT_TIME_T
1035#endif
1036
1037/* The public SQLite interface.  The _FILE_OFFSET_BITS macro must appear
1038** first in QNX.  Also, the _USE_32BIT_TIME_T macro must appear first for
1039** MinGW.
1040*/
1041/************** Include sqlite3.h in the middle of sqliteInt.h ***************/
1042/************** Begin file sqlite3.h *****************************************/
1043/*
1044** 2001-09-15
1045**
1046** The author disclaims copyright to this source code.  In place of
1047** a legal notice, here is a blessing:
1048**
1049**    May you do good and not evil.
1050**    May you find forgiveness for yourself and forgive others.
1051**    May you share freely, never taking more than you give.
1052**
1053*************************************************************************
1054** This header file defines the interface that the SQLite library
1055** presents to client programs.  If a C-function, structure, datatype,
1056** or constant definition does not appear in this file, then it is
1057** not a published API of SQLite, is subject to change without
1058** notice, and should not be referenced by programs that use SQLite.
1059**
1060** Some of the definitions that are in this file are marked as
1061** "experimental".  Experimental interfaces are normally new
1062** features recently added to SQLite.  We do not anticipate changes
1063** to experimental interfaces but reserve the right to make minor changes
1064** if experience from use "in the wild" suggest such changes are prudent.
1065**
1066** The official C-language API documentation for SQLite is derived
1067** from comments in this file.  This file is the authoritative source
1068** on how SQLite interfaces are supposed to operate.
1069**
1070** The name of this file under configuration management is "sqlite.h.in".
1071** The makefile makes some minor changes to this file (such as inserting
1072** the version number) and changes its name to "sqlite3.h" as
1073** part of the build process.
1074*/
1075#ifndef SQLITE3_H
1076#define SQLITE3_H
1077#include <stdarg.h>     /* Needed for the definition of va_list */
1078
1079/*
1080** Make sure we can call this stuff from C++.
1081*/
1082#if 0
1083extern "C" {
1084#endif
1085
1086
1087/*
1088** Provide the ability to override linkage features of the interface.
1089*/
1090#ifndef SQLITE_EXTERN
1091# define SQLITE_EXTERN extern
1092#endif
1093#ifndef SQLITE_API
1094# define SQLITE_API
1095#endif
1096#ifndef SQLITE_CDECL
1097# define SQLITE_CDECL
1098#endif
1099#ifndef SQLITE_APICALL
1100# define SQLITE_APICALL
1101#endif
1102#ifndef SQLITE_STDCALL
1103# define SQLITE_STDCALL SQLITE_APICALL
1104#endif
1105#ifndef SQLITE_CALLBACK
1106# define SQLITE_CALLBACK
1107#endif
1108#ifndef SQLITE_SYSAPI
1109# define SQLITE_SYSAPI
1110#endif
1111
1112/*
1113** These no-op macros are used in front of interfaces to mark those
1114** interfaces as either deprecated or experimental.  New applications
1115** should not use deprecated interfaces - they are supported for backwards
1116** compatibility only.  Application writers should be aware that
1117** experimental interfaces are subject to change in point releases.
1118**
1119** These macros used to resolve to various kinds of compiler magic that
1120** would generate warning messages when they were used.  But that
1121** compiler magic ended up generating such a flurry of bug reports
1122** that we have taken it all out and gone back to using simple
1123** noop macros.
1124*/
1125#define SQLITE_DEPRECATED
1126#define SQLITE_EXPERIMENTAL
1127
1128/*
1129** Ensure these symbols were not defined by some previous header file.
1130*/
1131#ifdef SQLITE_VERSION
1132# undef SQLITE_VERSION
1133#endif
1134#ifdef SQLITE_VERSION_NUMBER
1135# undef SQLITE_VERSION_NUMBER
1136#endif
1137
1138/*
1139** CAPI3REF: Compile-Time Library Version Numbers
1140**
1141** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
1142** evaluates to a string literal that is the SQLite version in the
1143** format "X.Y.Z" where X is the major version number (always 3 for
1144** SQLite3) and Y is the minor version number and Z is the release number.)^
1145** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
1146** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
1147** numbers used in [SQLITE_VERSION].)^
1148** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
1149** be larger than the release from which it is derived.  Either Y will
1150** be held constant and Z will be incremented or else Y will be incremented
1151** and Z will be reset to zero.
1152**
1153** Since [version 3.6.18] ([dateof:3.6.18]),
1154** SQLite source code has been stored in the
1155** <a href="http://www.fossil-scm.org/">Fossil configuration management
1156** system</a>.  ^The SQLITE_SOURCE_ID macro evaluates to
1157** a string which identifies a particular check-in of SQLite
1158** within its configuration management system.  ^The SQLITE_SOURCE_ID
1159** string contains the date and time of the check-in (UTC) and a SHA1
1160** or SHA3-256 hash of the entire source tree.  If the source code has
1161** been edited in any way since it was last checked in, then the last
1162** four hexadecimal digits of the hash may be modified.
1163**
1164** See also: [sqlite3_libversion()],
1165** [sqlite3_libversion_number()], [sqlite3_sourceid()],
1166** [sqlite_version()] and [sqlite_source_id()].
1167*/
1168#define SQLITE_VERSION        "3.30.1"
1169#define SQLITE_VERSION_NUMBER 3030001
1170#define SQLITE_SOURCE_ID      "2019-10-10 20:19:45 18db032d058f1436ce3dea84081f4ee5a0f2259ad97301d43c426bc7f3df1b0b"
1171
1172/*
1173** CAPI3REF: Run-Time Library Version Numbers
1174** KEYWORDS: sqlite3_version sqlite3_sourceid
1175**
1176** These interfaces provide the same information as the [SQLITE_VERSION],
1177** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
1178** but are associated with the library instead of the header file.  ^(Cautious
1179** programmers might include assert() statements in their application to
1180** verify that values returned by these interfaces match the macros in
1181** the header, and thus ensure that the application is
1182** compiled with matching library and header files.
1183**
1184** <blockquote><pre>
1185** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
1186** assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );
1187** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
1188** </pre></blockquote>)^
1189**
1190** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
1191** macro.  ^The sqlite3_libversion() function returns a pointer to the
1192** to the sqlite3_version[] string constant.  The sqlite3_libversion()
1193** function is provided for use in DLLs since DLL users usually do not have
1194** direct access to string constants within the DLL.  ^The
1195** sqlite3_libversion_number() function returns an integer equal to
1196** [SQLITE_VERSION_NUMBER].  ^(The sqlite3_sourceid() function returns
1197** a pointer to a string constant whose value is the same as the
1198** [SQLITE_SOURCE_ID] C preprocessor macro.  Except if SQLite is built
1199** using an edited copy of [the amalgamation], then the last four characters
1200** of the hash might be different from [SQLITE_SOURCE_ID].)^
1201**
1202** See also: [sqlite_version()] and [sqlite_source_id()].
1203*/
1204SQLITE_API const char sqlite3_version[] = SQLITE_VERSION;
1205SQLITE_API const char *sqlite3_libversion(void);
1206SQLITE_API const char *sqlite3_sourceid(void);
1207SQLITE_API int sqlite3_libversion_number(void);
1208
1209/*
1210** CAPI3REF: Run-Time Library Compilation Options Diagnostics
1211**
1212** ^The sqlite3_compileoption_used() function returns 0 or 1
1213** indicating whether the specified option was defined at
1214** compile time.  ^The SQLITE_ prefix may be omitted from the
1215** option name passed to sqlite3_compileoption_used().
1216**
1217** ^The sqlite3_compileoption_get() function allows iterating
1218** over the list of options that were defined at compile time by
1219** returning the N-th compile time option string.  ^If N is out of range,
1220** sqlite3_compileoption_get() returns a NULL pointer.  ^The SQLITE_
1221** prefix is omitted from any strings returned by
1222** sqlite3_compileoption_get().
1223**
1224** ^Support for the diagnostic functions sqlite3_compileoption_used()
1225** and sqlite3_compileoption_get() may be omitted by specifying the
1226** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
1227**
1228** See also: SQL functions [sqlite_compileoption_used()] and
1229** [sqlite_compileoption_get()] and the [compile_options pragma].
1230*/
1231#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
1232SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
1233SQLITE_API const char *sqlite3_compileoption_get(int N);
1234#else
1235# define sqlite3_compileoption_used(X) 0
1236# define sqlite3_compileoption_get(X)  ((void*)0)
1237#endif
1238
1239/*
1240** CAPI3REF: Test To See If The Library Is Threadsafe
1241**
1242** ^The sqlite3_threadsafe() function returns zero if and only if
1243** SQLite was compiled with mutexing code omitted due to the
1244** [SQLITE_THREADSAFE] compile-time option being set to 0.
1245**
1246** SQLite can be compiled with or without mutexes.  When
1247** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
1248** are enabled and SQLite is threadsafe.  When the
1249** [SQLITE_THREADSAFE] macro is 0,
1250** the mutexes are omitted.  Without the mutexes, it is not safe
1251** to use SQLite concurrently from more than one thread.
1252**
1253** Enabling mutexes incurs a measurable performance penalty.
1254** So if speed is of utmost importance, it makes sense to disable
1255** the mutexes.  But for maximum safety, mutexes should be enabled.
1256** ^The default behavior is for mutexes to be enabled.
1257**
1258** This interface can be used by an application to make sure that the
1259** version of SQLite that it is linking against was compiled with
1260** the desired setting of the [SQLITE_THREADSAFE] macro.
1261**
1262** This interface only reports on the compile-time mutex setting
1263** of the [SQLITE_THREADSAFE] flag.  If SQLite is compiled with
1264** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
1265** can be fully or partially disabled using a call to [sqlite3_config()]
1266** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
1267** or [SQLITE_CONFIG_SERIALIZED].  ^(The return value of the
1268** sqlite3_threadsafe() function shows only the compile-time setting of
1269** thread safety, not any run-time changes to that setting made by
1270** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
1271** is unchanged by calls to sqlite3_config().)^
1272**
1273** See the [threading mode] documentation for additional information.
1274*/
1275SQLITE_API int sqlite3_threadsafe(void);
1276
1277/*
1278** CAPI3REF: Database Connection Handle
1279** KEYWORDS: {database connection} {database connections}
1280**
1281** Each open SQLite database is represented by a pointer to an instance of
1282** the opaque structure named "sqlite3".  It is useful to think of an sqlite3
1283** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and
1284** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
1285** and [sqlite3_close_v2()] are its destructors.  There are many other
1286** interfaces (such as
1287** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
1288** [sqlite3_busy_timeout()] to name but three) that are methods on an
1289** sqlite3 object.
1290*/
1291typedef struct sqlite3 sqlite3;
1292
1293/*
1294** CAPI3REF: 64-Bit Integer Types
1295** KEYWORDS: sqlite_int64 sqlite_uint64
1296**
1297** Because there is no cross-platform way to specify 64-bit integer types
1298** SQLite includes typedefs for 64-bit signed and unsigned integers.
1299**
1300** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
1301** The sqlite_int64 and sqlite_uint64 types are supported for backwards
1302** compatibility only.
1303**
1304** ^The sqlite3_int64 and sqlite_int64 types can store integer values
1305** between -9223372036854775808 and +9223372036854775807 inclusive.  ^The
1306** sqlite3_uint64 and sqlite_uint64 types can store integer values
1307** between 0 and +18446744073709551615 inclusive.
1308*/
1309#ifdef SQLITE_INT64_TYPE
1310  typedef SQLITE_INT64_TYPE sqlite_int64;
1311# ifdef SQLITE_UINT64_TYPE
1312    typedef SQLITE_UINT64_TYPE sqlite_uint64;
1313# else
1314    typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
1315# endif
1316#elif defined(_MSC_VER) || defined(__BORLANDC__)
1317  typedef __int64 sqlite_int64;
1318  typedef unsigned __int64 sqlite_uint64;
1319#else
1320  typedef long long int sqlite_int64;
1321  typedef unsigned long long int sqlite_uint64;
1322#endif
1323typedef sqlite_int64 sqlite3_int64;
1324typedef sqlite_uint64 sqlite3_uint64;
1325
1326/*
1327** If compiling for a processor that lacks floating point support,
1328** substitute integer for floating-point.
1329*/
1330#ifdef SQLITE_OMIT_FLOATING_POINT
1331# define double sqlite3_int64
1332#endif
1333
1334/*
1335** CAPI3REF: Closing A Database Connection
1336** DESTRUCTOR: sqlite3
1337**
1338** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
1339** for the [sqlite3] object.
1340** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
1341** the [sqlite3] object is successfully destroyed and all associated
1342** resources are deallocated.
1343**
1344** ^If the database connection is associated with unfinalized prepared
1345** statements or unfinished sqlite3_backup objects then sqlite3_close()
1346** will leave the database connection open and return [SQLITE_BUSY].
1347** ^If sqlite3_close_v2() is called with unfinalized prepared statements
1348** and/or unfinished sqlite3_backups, then the database connection becomes
1349** an unusable "zombie" which will automatically be deallocated when the
1350** last prepared statement is finalized or the last sqlite3_backup is
1351** finished.  The sqlite3_close_v2() interface is intended for use with
1352** host languages that are garbage collected, and where the order in which
1353** destructors are called is arbitrary.
1354**
1355** Applications should [sqlite3_finalize | finalize] all [prepared statements],
1356** [sqlite3_blob_close | close] all [BLOB handles], and
1357** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
1358** with the [sqlite3] object prior to attempting to close the object.  ^If
1359** sqlite3_close_v2() is called on a [database connection] that still has
1360** outstanding [prepared statements], [BLOB handles], and/or
1361** [sqlite3_backup] objects then it returns [SQLITE_OK] and the deallocation
1362** of resources is deferred until all [prepared statements], [BLOB handles],
1363** and [sqlite3_backup] objects are also destroyed.
1364**
1365** ^If an [sqlite3] object is destroyed while a transaction is open,
1366** the transaction is automatically rolled back.
1367**
1368** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
1369** must be either a NULL
1370** pointer or an [sqlite3] object pointer obtained
1371** from [sqlite3_open()], [sqlite3_open16()], or
1372** [sqlite3_open_v2()], and not previously closed.
1373** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
1374** argument is a harmless no-op.
1375*/
1376SQLITE_API int sqlite3_close(sqlite3*);
1377SQLITE_API int sqlite3_close_v2(sqlite3*);
1378
1379/*
1380** The type for a callback function.
1381** This is legacy and deprecated.  It is included for historical
1382** compatibility and is not documented.
1383*/
1384typedef int (*sqlite3_callback)(void*,int,char**, char**);
1385
1386/*
1387** CAPI3REF: One-Step Query Execution Interface
1388** METHOD: sqlite3
1389**
1390** The sqlite3_exec() interface is a convenience wrapper around
1391** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
1392** that allows an application to run multiple statements of SQL
1393** without having to use a lot of C code.
1394**
1395** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
1396** semicolon-separate SQL statements passed into its 2nd argument,
1397** in the context of the [database connection] passed in as its 1st
1398** argument.  ^If the callback function of the 3rd argument to
1399** sqlite3_exec() is not NULL, then it is invoked for each result row
1400** coming out of the evaluated SQL statements.  ^The 4th argument to
1401** sqlite3_exec() is relayed through to the 1st argument of each
1402** callback invocation.  ^If the callback pointer to sqlite3_exec()
1403** is NULL, then no callback is ever invoked and result rows are
1404** ignored.
1405**
1406** ^If an error occurs while evaluating the SQL statements passed into
1407** sqlite3_exec(), then execution of the current statement stops and
1408** subsequent statements are skipped.  ^If the 5th parameter to sqlite3_exec()
1409** is not NULL then any error message is written into memory obtained
1410** from [sqlite3_malloc()] and passed back through the 5th parameter.
1411** To avoid memory leaks, the application should invoke [sqlite3_free()]
1412** on error message strings returned through the 5th parameter of
1413** sqlite3_exec() after the error message string is no longer needed.
1414** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
1415** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
1416** NULL before returning.
1417**
1418** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
1419** routine returns SQLITE_ABORT without invoking the callback again and
1420** without running any subsequent SQL statements.
1421**
1422** ^The 2nd argument to the sqlite3_exec() callback function is the
1423** number of columns in the result.  ^The 3rd argument to the sqlite3_exec()
1424** callback is an array of pointers to strings obtained as if from
1425** [sqlite3_column_text()], one for each column.  ^If an element of a
1426** result row is NULL then the corresponding string pointer for the
1427** sqlite3_exec() callback is a NULL pointer.  ^The 4th argument to the
1428** sqlite3_exec() callback is an array of pointers to strings where each
1429** entry represents the name of corresponding result column as obtained
1430** from [sqlite3_column_name()].
1431**
1432** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
1433** to an empty string, or a pointer that contains only whitespace and/or
1434** SQL comments, then no SQL statements are evaluated and the database
1435** is not changed.
1436**
1437** Restrictions:
1438**
1439** <ul>
1440** <li> The application must ensure that the 1st parameter to sqlite3_exec()
1441**      is a valid and open [database connection].
1442** <li> The application must not close the [database connection] specified by
1443**      the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
1444** <li> The application must not modify the SQL statement text passed into
1445**      the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
1446** </ul>
1447*/
1448SQLITE_API int sqlite3_exec(
1449  sqlite3*,                                  /* An open database */
1450  const char *sql,                           /* SQL to be evaluated */
1451  int (*callback)(void*,int,char**,char**),  /* Callback function */
1452  void *,                                    /* 1st argument to callback */
1453  char **errmsg                              /* Error msg written here */
1454);
1455
1456/*
1457** CAPI3REF: Result Codes
1458** KEYWORDS: {result code definitions}
1459**
1460** Many SQLite functions return an integer result code from the set shown
1461** here in order to indicate success or failure.
1462**
1463** New error codes may be added in future versions of SQLite.
1464**
1465** See also: [extended result code definitions]
1466*/
1467#define SQLITE_OK           0   /* Successful result */
1468/* beginning-of-error-codes */
1469#define SQLITE_ERROR        1   /* Generic error */
1470#define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
1471#define SQLITE_PERM         3   /* Access permission denied */
1472#define SQLITE_ABORT        4   /* Callback routine requested an abort */
1473#define SQLITE_BUSY         5   /* The database file is locked */
1474#define SQLITE_LOCKED       6   /* A table in the database is locked */
1475#define SQLITE_NOMEM        7   /* A malloc() failed */
1476#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
1477#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
1478#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
1479#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
1480#define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */
1481#define SQLITE_FULL        13   /* Insertion failed because database is full */
1482#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
1483#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
1484#define SQLITE_EMPTY       16   /* Internal use only */
1485#define SQLITE_SCHEMA      17   /* The database schema changed */
1486#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
1487#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
1488#define SQLITE_MISMATCH    20   /* Data type mismatch */
1489#define SQLITE_MISUSE      21   /* Library used incorrectly */
1490#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
1491#define SQLITE_AUTH        23   /* Authorization denied */
1492#define SQLITE_FORMAT      24   /* Not used */
1493#define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
1494#define SQLITE_NOTADB      26   /* File opened that is not a database file */
1495#define SQLITE_NOTICE      27   /* Notifications from sqlite3_log() */
1496#define SQLITE_WARNING     28   /* Warnings from sqlite3_log() */
1497#define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
1498#define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
1499/* end-of-error-codes */
1500
1501/*
1502** CAPI3REF: Extended Result Codes
1503** KEYWORDS: {extended result code definitions}
1504**
1505** In its default configuration, SQLite API routines return one of 30 integer
1506** [result codes].  However, experience has shown that many of
1507** these result codes are too coarse-grained.  They do not provide as
1508** much information about problems as programmers might like.  In an effort to
1509** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8]
1510** and later) include
1511** support for additional result codes that provide more detailed information
1512** about errors. These [extended result codes] are enabled or disabled
1513** on a per database connection basis using the
1514** [sqlite3_extended_result_codes()] API.  Or, the extended code for
1515** the most recent error can be obtained using
1516** [sqlite3_extended_errcode()].
1517*/
1518#define SQLITE_ERROR_MISSING_COLLSEQ   (SQLITE_ERROR | (1<<8))
1519#define SQLITE_ERROR_RETRY             (SQLITE_ERROR | (2<<8))
1520#define SQLITE_ERROR_SNAPSHOT          (SQLITE_ERROR | (3<<8))
1521#define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
1522#define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
1523#define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
1524#define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
1525#define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
1526#define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
1527#define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
1528#define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))
1529#define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))
1530#define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))
1531#define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))
1532#define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))
1533#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
1534#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
1535#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
1536#define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
1537#define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
1538#define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18<<8))
1539#define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19<<8))
1540#define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20<<8))
1541#define SQLITE_IOERR_SHMMAP            (SQLITE_IOERR | (21<<8))
1542#define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22<<8))
1543#define SQLITE_IOERR_DELETE_NOENT      (SQLITE_IOERR | (23<<8))
1544#define SQLITE_IOERR_MMAP              (SQLITE_IOERR | (24<<8))
1545#define SQLITE_IOERR_GETTEMPPATH       (SQLITE_IOERR | (25<<8))
1546#define SQLITE_IOERR_CONVPATH          (SQLITE_IOERR | (26<<8))
1547#define SQLITE_IOERR_VNODE             (SQLITE_IOERR | (27<<8))
1548#define SQLITE_IOERR_AUTH              (SQLITE_IOERR | (28<<8))
1549#define SQLITE_IOERR_BEGIN_ATOMIC      (SQLITE_IOERR | (29<<8))
1550#define SQLITE_IOERR_COMMIT_ATOMIC     (SQLITE_IOERR | (30<<8))
1551#define SQLITE_IOERR_ROLLBACK_ATOMIC   (SQLITE_IOERR | (31<<8))
1552#define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))
1553#define SQLITE_LOCKED_VTAB             (SQLITE_LOCKED |  (2<<8))
1554#define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))
1555#define SQLITE_BUSY_SNAPSHOT           (SQLITE_BUSY   |  (2<<8))
1556#define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))
1557#define SQLITE_CANTOPEN_ISDIR          (SQLITE_CANTOPEN | (2<<8))
1558#define SQLITE_CANTOPEN_FULLPATH       (SQLITE_CANTOPEN | (3<<8))
1559#define SQLITE_CANTOPEN_CONVPATH       (SQLITE_CANTOPEN | (4<<8))
1560#define SQLITE_CANTOPEN_DIRTYWAL       (SQLITE_CANTOPEN | (5<<8)) /* Not Used */
1561#define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1<<8))
1562#define SQLITE_CORRUPT_SEQUENCE        (SQLITE_CORRUPT | (2<<8))
1563#define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1<<8))
1564#define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2<<8))
1565#define SQLITE_READONLY_ROLLBACK       (SQLITE_READONLY | (3<<8))
1566#define SQLITE_READONLY_DBMOVED        (SQLITE_READONLY | (4<<8))
1567#define SQLITE_READONLY_CANTINIT       (SQLITE_READONLY | (5<<8))
1568#define SQLITE_READONLY_DIRECTORY      (SQLITE_READONLY | (6<<8))
1569#define SQLITE_ABORT_ROLLBACK          (SQLITE_ABORT | (2<<8))
1570#define SQLITE_CONSTRAINT_CHECK        (SQLITE_CONSTRAINT | (1<<8))
1571#define SQLITE_CONSTRAINT_COMMITHOOK   (SQLITE_CONSTRAINT | (2<<8))
1572#define SQLITE_CONSTRAINT_FOREIGNKEY   (SQLITE_CONSTRAINT | (3<<8))
1573#define SQLITE_CONSTRAINT_FUNCTION     (SQLITE_CONSTRAINT | (4<<8))
1574#define SQLITE_CONSTRAINT_NOTNULL      (SQLITE_CONSTRAINT | (5<<8))
1575#define SQLITE_CONSTRAINT_PRIMARYKEY   (SQLITE_CONSTRAINT | (6<<8))
1576#define SQLITE_CONSTRAINT_TRIGGER      (SQLITE_CONSTRAINT | (7<<8))
1577#define SQLITE_CONSTRAINT_UNIQUE       (SQLITE_CONSTRAINT | (8<<8))
1578#define SQLITE_CONSTRAINT_VTAB         (SQLITE_CONSTRAINT | (9<<8))
1579#define SQLITE_CONSTRAINT_ROWID        (SQLITE_CONSTRAINT |(10<<8))
1580#define SQLITE_NOTICE_RECOVER_WAL      (SQLITE_NOTICE | (1<<8))
1581#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
1582#define SQLITE_WARNING_AUTOINDEX       (SQLITE_WARNING | (1<<8))
1583#define SQLITE_AUTH_USER               (SQLITE_AUTH | (1<<8))
1584#define SQLITE_OK_LOAD_PERMANENTLY     (SQLITE_OK | (1<<8))
1585
1586/*
1587** CAPI3REF: Flags For File Open Operations
1588**
1589** These bit values are intended for use in the
1590** 3rd parameter to the [sqlite3_open_v2()] interface and
1591** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
1592*/
1593#define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */
1594#define SQLITE_OPEN_READWRITE        0x00000002  /* Ok for sqlite3_open_v2() */
1595#define SQLITE_OPEN_CREATE           0x00000004  /* Ok for sqlite3_open_v2() */
1596#define SQLITE_OPEN_DELETEONCLOSE    0x00000008  /* VFS only */
1597#define SQLITE_OPEN_EXCLUSIVE        0x00000010  /* VFS only */
1598#define SQLITE_OPEN_AUTOPROXY        0x00000020  /* VFS only */
1599#define SQLITE_OPEN_URI              0x00000040  /* Ok for sqlite3_open_v2() */
1600#define SQLITE_OPEN_MEMORY           0x00000080  /* Ok for sqlite3_open_v2() */
1601#define SQLITE_OPEN_MAIN_DB          0x00000100  /* VFS only */
1602#define SQLITE_OPEN_TEMP_DB          0x00000200  /* VFS only */
1603#define SQLITE_OPEN_TRANSIENT_DB     0x00000400  /* VFS only */
1604#define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  /* VFS only */
1605#define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  /* VFS only */
1606#define SQLITE_OPEN_SUBJOURNAL       0x00002000  /* VFS only */
1607#define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */
1608#define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
1609#define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
1610#define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */
1611#define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */
1612#define SQLITE_OPEN_WAL              0x00080000  /* VFS only */
1613
1614/* Reserved:                         0x00F00000 */
1615
1616/*
1617** CAPI3REF: Device Characteristics
1618**
1619** The xDeviceCharacteristics method of the [sqlite3_io_methods]
1620** object returns an integer which is a vector of these
1621** bit values expressing I/O characteristics of the mass storage
1622** device that holds the file that the [sqlite3_io_methods]
1623** refers to.
1624**
1625** The SQLITE_IOCAP_ATOMIC property means that all writes of
1626** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
1627** mean that writes of blocks that are nnn bytes in size and
1628** are aligned to an address which is an integer multiple of
1629** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
1630** that when data is appended to a file, the data is appended
1631** first then the size of the file is extended, never the other
1632** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
1633** information is written to disk in the same order as calls
1634** to xWrite().  The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
1635** after reboot following a crash or power loss, the only bytes in a
1636** file that were written at the application level might have changed
1637** and that adjacent bytes, even bytes within the same sector are
1638** guaranteed to be unchanged.  The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
1639** flag indicates that a file cannot be deleted when open.  The
1640** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
1641** read-only media and cannot be changed even by processes with
1642** elevated privileges.
1643**
1644** The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying
1645** filesystem supports doing multiple write operations atomically when those
1646** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and
1647** [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].
1648*/
1649#define SQLITE_IOCAP_ATOMIC                 0x00000001
1650#define SQLITE_IOCAP_ATOMIC512              0x00000002
1651#define SQLITE_IOCAP_ATOMIC1K               0x00000004
1652#define SQLITE_IOCAP_ATOMIC2K               0x00000008
1653#define SQLITE_IOCAP_ATOMIC4K               0x00000010
1654#define SQLITE_IOCAP_ATOMIC8K               0x00000020
1655#define SQLITE_IOCAP_ATOMIC16K              0x00000040
1656#define SQLITE_IOCAP_ATOMIC32K              0x00000080
1657#define SQLITE_IOCAP_ATOMIC64K              0x00000100
1658#define SQLITE_IOCAP_SAFE_APPEND            0x00000200
1659#define SQLITE_IOCAP_SEQUENTIAL             0x00000400
1660#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800
1661#define SQLITE_IOCAP_POWERSAFE_OVERWRITE    0x00001000
1662#define SQLITE_IOCAP_IMMUTABLE              0x00002000
1663#define SQLITE_IOCAP_BATCH_ATOMIC           0x00004000
1664
1665/*
1666** CAPI3REF: File Locking Levels
1667**
1668** SQLite uses one of these integer values as the second
1669** argument to calls it makes to the xLock() and xUnlock() methods
1670** of an [sqlite3_io_methods] object.
1671*/
1672#define SQLITE_LOCK_NONE          0
1673#define SQLITE_LOCK_SHARED        1
1674#define SQLITE_LOCK_RESERVED      2
1675#define SQLITE_LOCK_PENDING       3
1676#define SQLITE_LOCK_EXCLUSIVE     4
1677
1678/*
1679** CAPI3REF: Synchronization Type Flags
1680**
1681** When SQLite invokes the xSync() method of an
1682** [sqlite3_io_methods] object it uses a combination of
1683** these integer values as the second argument.
1684**
1685** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
1686** sync operation only needs to flush data to mass storage.  Inode
1687** information need not be flushed. If the lower four bits of the flag
1688** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
1689** If the lower four bits equal SQLITE_SYNC_FULL, that means
1690** to use Mac OS X style fullsync instead of fsync().
1691**
1692** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
1693** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
1694** settings.  The [synchronous pragma] determines when calls to the
1695** xSync VFS method occur and applies uniformly across all platforms.
1696** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
1697** energetic or rigorous or forceful the sync operations are and
1698** only make a difference on Mac OSX for the default SQLite code.
1699** (Third-party VFS implementations might also make the distinction
1700** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
1701** operating systems natively supported by SQLite, only Mac OSX
1702** cares about the difference.)
1703*/
1704#define SQLITE_SYNC_NORMAL        0x00002
1705#define SQLITE_SYNC_FULL          0x00003
1706#define SQLITE_SYNC_DATAONLY      0x00010
1707
1708/*
1709** CAPI3REF: OS Interface Open File Handle
1710**
1711** An [sqlite3_file] object represents an open file in the
1712** [sqlite3_vfs | OS interface layer].  Individual OS interface
1713** implementations will
1714** want to subclass this object by appending additional fields
1715** for their own use.  The pMethods entry is a pointer to an
1716** [sqlite3_io_methods] object that defines methods for performing
1717** I/O operations on the open file.
1718*/
1719typedef struct sqlite3_file sqlite3_file;
1720struct sqlite3_file {
1721  const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
1722};
1723
1724/*
1725** CAPI3REF: OS Interface File Virtual Methods Object
1726**
1727** Every file opened by the [sqlite3_vfs.xOpen] method populates an
1728** [sqlite3_file] object (or, more commonly, a subclass of the
1729** [sqlite3_file] object) with a pointer to an instance of this object.
1730** This object defines the methods used to perform various operations
1731** against the open file represented by the [sqlite3_file] object.
1732**
1733** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element
1734** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
1735** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed.  The
1736** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
1737** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
1738** to NULL.
1739**
1740** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
1741** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().
1742** The second choice is a Mac OS X style fullsync.  The [SQLITE_SYNC_DATAONLY]
1743** flag may be ORed in to indicate that only the data of the file
1744** and not its inode needs to be synced.
1745**
1746** The integer values to xLock() and xUnlock() are one of
1747** <ul>
1748** <li> [SQLITE_LOCK_NONE],
1749** <li> [SQLITE_LOCK_SHARED],
1750** <li> [SQLITE_LOCK_RESERVED],
1751** <li> [SQLITE_LOCK_PENDING], or
1752** <li> [SQLITE_LOCK_EXCLUSIVE].
1753** </ul>
1754** xLock() increases the lock. xUnlock() decreases the lock.
1755** The xCheckReservedLock() method checks whether any database connection,
1756** either in this process or in some other process, is holding a RESERVED,
1757** PENDING, or EXCLUSIVE lock on the file.  It returns true
1758** if such a lock exists and false otherwise.
1759**
1760** The xFileControl() method is a generic interface that allows custom
1761** VFS implementations to directly control an open file using the
1762** [sqlite3_file_control()] interface.  The second "op" argument is an
1763** integer opcode.  The third argument is a generic pointer intended to
1764** point to a structure that may contain arguments or space in which to
1765** write return values.  Potential uses for xFileControl() might be
1766** functions to enable blocking locks with timeouts, to change the
1767** locking strategy (for example to use dot-file locks), to inquire
1768** about the status of a lock, or to break stale locks.  The SQLite
1769** core reserves all opcodes less than 100 for its own use.
1770** A [file control opcodes | list of opcodes] less than 100 is available.
1771** Applications that define a custom xFileControl method should use opcodes
1772** greater than 100 to avoid conflicts.  VFS implementations should
1773** return [SQLITE_NOTFOUND] for file control opcodes that they do not
1774** recognize.
1775**
1776** The xSectorSize() method returns the sector size of the
1777** device that underlies the file.  The sector size is the
1778** minimum write that can be performed without disturbing
1779** other bytes in the file.  The xDeviceCharacteristics()
1780** method returns a bit vector describing behaviors of the
1781** underlying device:
1782**
1783** <ul>
1784** <li> [SQLITE_IOCAP_ATOMIC]
1785** <li> [SQLITE_IOCAP_ATOMIC512]
1786** <li> [SQLITE_IOCAP_ATOMIC1K]
1787** <li> [SQLITE_IOCAP_ATOMIC2K]
1788** <li> [SQLITE_IOCAP_ATOMIC4K]
1789** <li> [SQLITE_IOCAP_ATOMIC8K]
1790** <li> [SQLITE_IOCAP_ATOMIC16K]
1791** <li> [SQLITE_IOCAP_ATOMIC32K]
1792** <li> [SQLITE_IOCAP_ATOMIC64K]
1793** <li> [SQLITE_IOCAP_SAFE_APPEND]
1794** <li> [SQLITE_IOCAP_SEQUENTIAL]
1795** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN]
1796** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE]
1797** <li> [SQLITE_IOCAP_IMMUTABLE]
1798** <li> [SQLITE_IOCAP_BATCH_ATOMIC]
1799** </ul>
1800**
1801** The SQLITE_IOCAP_ATOMIC property means that all writes of
1802** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
1803** mean that writes of blocks that are nnn bytes in size and
1804** are aligned to an address which is an integer multiple of
1805** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
1806** that when data is appended to a file, the data is appended
1807** first then the size of the file is extended, never the other
1808** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
1809** information is written to disk in the same order as calls
1810** to xWrite().
1811**
1812** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
1813** in the unread portions of the buffer with zeros.  A VFS that
1814** fails to zero-fill short reads might seem to work.  However,
1815** failure to zero-fill short reads will eventually lead to
1816** database corruption.
1817*/
1818typedef struct sqlite3_io_methods sqlite3_io_methods;
1819struct sqlite3_io_methods {
1820  int iVersion;
1821  int (*xClose)(sqlite3_file*);
1822  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
1823  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
1824  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
1825  int (*xSync)(sqlite3_file*, int flags);
1826  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
1827  int (*xLock)(sqlite3_file*, int);
1828  int (*xUnlock)(sqlite3_file*, int);
1829  int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
1830  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
1831  int (*xSectorSize)(sqlite3_file*);
1832  int (*xDeviceCharacteristics)(sqlite3_file*);
1833  /* Methods above are valid for version 1 */
1834  int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
1835  int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
1836  void (*xShmBarrier)(sqlite3_file*);
1837  int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
1838  /* Methods above are valid for version 2 */
1839  int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
1840  int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
1841  /* Methods above are valid for version 3 */
1842  /* Additional methods may be added in future releases */
1843};
1844
1845/*
1846** CAPI3REF: Standard File Control Opcodes
1847** KEYWORDS: {file control opcodes} {file control opcode}
1848**
1849** These integer constants are opcodes for the xFileControl method
1850** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
1851** interface.
1852**
1853** <ul>
1854** <li>[[SQLITE_FCNTL_LOCKSTATE]]
1855** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
1856** opcode causes the xFileControl method to write the current state of
1857** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
1858** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
1859** into an integer that the pArg argument points to. This capability
1860** is used during testing and is only available when the SQLITE_TEST
1861** compile-time option is used.
1862**
1863** <li>[[SQLITE_FCNTL_SIZE_HINT]]
1864** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
1865** layer a hint of how large the database file will grow to be during the
1866** current transaction.  This hint is not guaranteed to be accurate but it
1867** is often close.  The underlying VFS might choose to preallocate database
1868** file space based on this hint in order to help writes to the database
1869** file run faster.
1870**
1871** <li>[[SQLITE_FCNTL_SIZE_LIMIT]]
1872** The [SQLITE_FCNTL_SIZE_LIMIT] opcode is used by in-memory VFS that
1873** implements [sqlite3_deserialize()] to set an upper bound on the size
1874** of the in-memory database.  The argument is a pointer to a [sqlite3_int64].
1875** If the integer pointed to is negative, then it is filled in with the
1876** current limit.  Otherwise the limit is set to the larger of the value
1877** of the integer pointed to and the current database size.  The integer
1878** pointed to is set to the new limit.
1879**
1880** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]
1881** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
1882** extends and truncates the database file in chunks of a size specified
1883** by the user. The fourth argument to [sqlite3_file_control()] should
1884** point to an integer (type int) containing the new chunk-size to use
1885** for the nominated database. Allocating database file space in large
1886** chunks (say 1MB at a time), may reduce file-system fragmentation and
1887** improve performance on some systems.
1888**
1889** <li>[[SQLITE_FCNTL_FILE_POINTER]]
1890** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
1891** to the [sqlite3_file] object associated with a particular database
1892** connection.  See also [SQLITE_FCNTL_JOURNAL_POINTER].
1893**
1894** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]
1895** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
1896** to the [sqlite3_file] object associated with the journal file (either
1897** the [rollback journal] or the [write-ahead log]) for a particular database
1898** connection.  See also [SQLITE_FCNTL_FILE_POINTER].
1899**
1900** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
1901** No longer in use.
1902**
1903** <li>[[SQLITE_FCNTL_SYNC]]
1904** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
1905** sent to the VFS immediately before the xSync method is invoked on a
1906** database file descriptor. Or, if the xSync method is not invoked
1907** because the user has configured SQLite with
1908** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place
1909** of the xSync method. In most cases, the pointer argument passed with
1910** this file-control is NULL. However, if the database file is being synced
1911** as part of a multi-database commit, the argument points to a nul-terminated
1912** string containing the transactions master-journal file name. VFSes that
1913** do not need this signal should silently ignore this opcode. Applications
1914** should not call [sqlite3_file_control()] with this opcode as doing so may
1915** disrupt the operation of the specialized VFSes that do require it.
1916**
1917** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]
1918** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
1919** and sent to the VFS after a transaction has been committed immediately
1920** but before the database is unlocked. VFSes that do not need this signal
1921** should silently ignore this opcode. Applications should not call
1922** [sqlite3_file_control()] with this opcode as doing so may disrupt the
1923** operation of the specialized VFSes that do require it.
1924**
1925** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
1926** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
1927** retry counts and intervals for certain disk I/O operations for the
1928** windows [VFS] in order to provide robustness in the presence of
1929** anti-virus programs.  By default, the windows VFS will retry file read,
1930** file write, and file delete operations up to 10 times, with a delay
1931** of 25 milliseconds before the first retry and with the delay increasing
1932** by an additional 25 milliseconds with each subsequent retry.  This
1933** opcode allows these two values (10 retries and 25 milliseconds of delay)
1934** to be adjusted.  The values are changed for all database connections
1935** within the same process.  The argument is a pointer to an array of two
1936** integers where the first integer is the new retry count and the second
1937** integer is the delay.  If either integer is negative, then the setting
1938** is not changed but instead the prior value of that setting is written
1939** into the array entry, allowing the current retry settings to be
1940** interrogated.  The zDbName parameter is ignored.
1941**
1942** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
1943** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
1944** persistent [WAL | Write Ahead Log] setting.  By default, the auxiliary
1945** write ahead log ([WAL file]) and shared memory
1946** files used for transaction control
1947** are automatically deleted when the latest connection to the database
1948** closes.  Setting persistent WAL mode causes those files to persist after
1949** close.  Persisting the files is useful when other processes that do not
1950** have write permission on the directory containing the database file want
1951** to read the database file, as the WAL and shared memory files must exist
1952** in order for the database to be readable.  The fourth parameter to
1953** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
1954** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
1955** WAL mode.  If the integer is -1, then it is overwritten with the current
1956** WAL persistence setting.
1957**
1958** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]
1959** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
1960** persistent "powersafe-overwrite" or "PSOW" setting.  The PSOW setting
1961** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the
1962** xDeviceCharacteristics methods. The fourth parameter to
1963** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
1964** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
1965** mode.  If the integer is -1, then it is overwritten with the current
1966** zero-damage mode setting.
1967**
1968** <li>[[SQLITE_FCNTL_OVERWRITE]]
1969** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
1970** a write transaction to indicate that, unless it is rolled back for some
1971** reason, the entire database file will be overwritten by the current
1972** transaction. This is used by VACUUM operations.
1973**
1974** <li>[[SQLITE_FCNTL_VFSNAME]]
1975** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
1976** all [VFSes] in the VFS stack.  The names are of all VFS shims and the
1977** final bottom-level VFS are written into memory obtained from
1978** [sqlite3_malloc()] and the result is stored in the char* variable
1979** that the fourth parameter of [sqlite3_file_control()] points to.
1980** The caller is responsible for freeing the memory when done.  As with
1981** all file-control actions, there is no guarantee that this will actually
1982** do anything.  Callers should initialize the char* variable to a NULL
1983** pointer in case this file-control is not implemented.  This file-control
1984** is intended for diagnostic use only.
1985**
1986** <li>[[SQLITE_FCNTL_VFS_POINTER]]
1987** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
1988** [VFSes] currently in use.  ^(The argument X in
1989** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
1990** of type "[sqlite3_vfs] **".  This opcodes will set *X
1991** to a pointer to the top-level VFS.)^
1992** ^When there are multiple VFS shims in the stack, this opcode finds the
1993** upper-most shim only.
1994**
1995** <li>[[SQLITE_FCNTL_PRAGMA]]
1996** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
1997** file control is sent to the open [sqlite3_file] object corresponding
1998** to the database file to which the pragma statement refers. ^The argument
1999** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
2000** pointers to strings (char**) in which the second element of the array
2001** is the name of the pragma and the third element is the argument to the
2002** pragma or NULL if the pragma has no argument.  ^The handler for an
2003** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element
2004** of the char** argument point to a string obtained from [sqlite3_mprintf()]
2005** or the equivalent and that string will become the result of the pragma or
2006** the error message if the pragma fails. ^If the
2007** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal
2008** [PRAGMA] processing continues.  ^If the [SQLITE_FCNTL_PRAGMA]
2009** file control returns [SQLITE_OK], then the parser assumes that the
2010** VFS has handled the PRAGMA itself and the parser generates a no-op
2011** prepared statement if result string is NULL, or that returns a copy
2012** of the result string if the string is non-NULL.
2013** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
2014** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
2015** that the VFS encountered an error while handling the [PRAGMA] and the
2016** compilation of the PRAGMA fails with an error.  ^The [SQLITE_FCNTL_PRAGMA]
2017** file control occurs at the beginning of pragma statement analysis and so
2018** it is able to override built-in [PRAGMA] statements.
2019**
2020** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
2021** ^The [SQLITE_FCNTL_BUSYHANDLER]
2022** file-control may be invoked by SQLite on the database file handle
2023** shortly after it is opened in order to provide a custom VFS with access
2024** to the connections busy-handler callback. The argument is of type (void **)
2025** - an array of two (void *) values. The first (void *) actually points
2026** to a function of type (int (*)(void *)). In order to invoke the connections
2027** busy-handler, this function should be invoked with the second (void *) in
2028** the array as the only argument. If it returns non-zero, then the operation
2029** should be retried. If it returns zero, the custom VFS should abandon the
2030** current operation.
2031**
2032** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
2033** ^Application can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
2034** to have SQLite generate a
2035** temporary filename using the same algorithm that is followed to generate
2036** temporary filenames for TEMP tables and other internal uses.  The
2037** argument should be a char** which will be filled with the filename
2038** written into memory obtained from [sqlite3_malloc()].  The caller should
2039** invoke [sqlite3_free()] on the result to avoid a memory leak.
2040**
2041** <li>[[SQLITE_FCNTL_MMAP_SIZE]]
2042** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
2043** maximum number of bytes that will be used for memory-mapped I/O.
2044** The argument is a pointer to a value of type sqlite3_int64 that
2045** is an advisory maximum number of bytes in the file to memory map.  The
2046** pointer is overwritten with the old value.  The limit is not changed if
2047** the value originally pointed to is negative, and so the current limit
2048** can be queried by passing in a pointer to a negative number.  This
2049** file-control is used internally to implement [PRAGMA mmap_size].
2050**
2051** <li>[[SQLITE_FCNTL_TRACE]]
2052** The [SQLITE_FCNTL_TRACE] file control provides advisory information
2053** to the VFS about what the higher layers of the SQLite stack are doing.
2054** This file control is used by some VFS activity tracing [shims].
2055** The argument is a zero-terminated string.  Higher layers in the
2056** SQLite stack may generate instances of this file control if
2057** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
2058**
2059** <li>[[SQLITE_FCNTL_HAS_MOVED]]
2060** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
2061** pointer to an integer and it writes a boolean into that integer depending
2062** on whether or not the file has been renamed, moved, or deleted since it
2063** was first opened.
2064**
2065** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]]
2066** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the
2067** underlying native file handle associated with a file handle.  This file
2068** control interprets its argument as a pointer to a native file handle and
2069** writes the resulting value there.
2070**
2071** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
2072** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging.  This
2073** opcode causes the xFileControl method to swap the file handle with the one
2074** pointed to by the pArg argument.  This capability is used during testing
2075** and only needs to be supported when SQLITE_TEST is defined.
2076**
2077** <li>[[SQLITE_FCNTL_WAL_BLOCK]]
2078** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
2079** be advantageous to block on the next WAL lock if the lock is not immediately
2080** available.  The WAL subsystem issues this signal during rare
2081** circumstances in order to fix a problem with priority inversion.
2082** Applications should <em>not</em> use this file-control.
2083**
2084** <li>[[SQLITE_FCNTL_ZIPVFS]]
2085** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
2086** VFS should return SQLITE_NOTFOUND for this opcode.
2087**
2088** <li>[[SQLITE_FCNTL_RBU]]
2089** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
2090** the RBU extension only.  All other VFS should return SQLITE_NOTFOUND for
2091** this opcode.
2092**
2093** <li>[[SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]]
2094** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, then
2095** the file descriptor is placed in "batch write mode", which
2096** means all subsequent write operations will be deferred and done
2097** atomically at the next [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].  Systems
2098** that do not support batch atomic writes will return SQLITE_NOTFOUND.
2099** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
2100** the closing [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] or
2101** [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE], SQLite will make
2102** no VFS interface calls on the same [sqlite3_file] file descriptor
2103** except for calls to the xWrite method and the xFileControl method
2104** with [SQLITE_FCNTL_SIZE_HINT].
2105**
2106** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]
2107** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write
2108** operations since the previous successful call to
2109** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.
2110** This file control returns [SQLITE_OK] if and only if the writes were
2111** all performed successfully and have been committed to persistent storage.
2112** ^Regardless of whether or not it is successful, this file control takes
2113** the file descriptor out of batch write mode so that all subsequent
2114** write operations are independent.
2115** ^SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
2116** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
2117**
2118** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]
2119** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write
2120** operations since the previous successful call to
2121** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.
2122** ^This file control takes the file descriptor out of batch write mode
2123** so that all subsequent write operations are independent.
2124** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
2125** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
2126**
2127** <li>[[SQLITE_FCNTL_LOCK_TIMEOUT]]
2128** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode causes attempts to obtain
2129** a file lock using the xLock or xShmLock methods of the VFS to wait
2130** for up to M milliseconds before failing, where M is the single
2131** unsigned integer parameter.
2132**
2133** <li>[[SQLITE_FCNTL_DATA_VERSION]]
2134** The [SQLITE_FCNTL_DATA_VERSION] opcode is used to detect changes to
2135** a database file.  The argument is a pointer to a 32-bit unsigned integer.
2136** The "data version" for the pager is written into the pointer.  The
2137** "data version" changes whenever any change occurs to the corresponding
2138** database file, either through SQL statements on the same database
2139** connection or through transactions committed by separate database
2140** connections possibly in other processes. The [sqlite3_total_changes()]
2141** interface can be used to find if any database on the connection has changed,
2142** but that interface responds to changes on TEMP as well as MAIN and does
2143** not provide a mechanism to detect changes to MAIN only.  Also, the
2144** [sqlite3_total_changes()] interface responds to internal changes only and
2145** omits changes made by other database connections.  The
2146** [PRAGMA data_version] command provide a mechanism to detect changes to
2147** a single attached database that occur due to other database connections,
2148** but omits changes implemented by the database connection on which it is
2149** called.  This file control is the only mechanism to detect changes that
2150** happen either internally or externally and that are associated with
2151** a particular attached database.
2152** </ul>
2153*/
2154#define SQLITE_FCNTL_LOCKSTATE               1
2155#define SQLITE_FCNTL_GET_LOCKPROXYFILE       2
2156#define SQLITE_FCNTL_SET_LOCKPROXYFILE       3
2157#define SQLITE_FCNTL_LAST_ERRNO              4
2158#define SQLITE_FCNTL_SIZE_HINT               5
2159#define SQLITE_FCNTL_CHUNK_SIZE              6
2160#define SQLITE_FCNTL_FILE_POINTER            7
2161#define SQLITE_FCNTL_SYNC_OMITTED            8
2162#define SQLITE_FCNTL_WIN32_AV_RETRY          9
2163#define SQLITE_FCNTL_PERSIST_WAL            10
2164#define SQLITE_FCNTL_OVERWRITE              11
2165#define SQLITE_FCNTL_VFSNAME                12
2166#define SQLITE_FCNTL_POWERSAFE_OVERWRITE    13
2167#define SQLITE_FCNTL_PRAGMA                 14
2168#define SQLITE_FCNTL_BUSYHANDLER            15
2169#define SQLITE_FCNTL_TEMPFILENAME           16
2170#define SQLITE_FCNTL_MMAP_SIZE              18
2171#define SQLITE_FCNTL_TRACE                  19
2172#define SQLITE_FCNTL_HAS_MOVED              20
2173#define SQLITE_FCNTL_SYNC                   21
2174#define SQLITE_FCNTL_COMMIT_PHASETWO        22
2175#define SQLITE_FCNTL_WIN32_SET_HANDLE       23
2176#define SQLITE_FCNTL_WAL_BLOCK              24
2177#define SQLITE_FCNTL_ZIPVFS                 25
2178#define SQLITE_FCNTL_RBU                    26
2179#define SQLITE_FCNTL_VFS_POINTER            27
2180#define SQLITE_FCNTL_JOURNAL_POINTER        28
2181#define SQLITE_FCNTL_WIN32_GET_HANDLE       29
2182#define SQLITE_FCNTL_PDB                    30
2183#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE     31
2184#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE    32
2185#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE  33
2186#define SQLITE_FCNTL_LOCK_TIMEOUT           34
2187#define SQLITE_FCNTL_DATA_VERSION           35
2188#define SQLITE_FCNTL_SIZE_LIMIT             36
2189
2190/* deprecated names */
2191#define SQLITE_GET_LOCKPROXYFILE      SQLITE_FCNTL_GET_LOCKPROXYFILE
2192#define SQLITE_SET_LOCKPROXYFILE      SQLITE_FCNTL_SET_LOCKPROXYFILE
2193#define SQLITE_LAST_ERRNO             SQLITE_FCNTL_LAST_ERRNO
2194
2195
2196/*
2197** CAPI3REF: Mutex Handle
2198**
2199** The mutex module within SQLite defines [sqlite3_mutex] to be an
2200** abstract type for a mutex object.  The SQLite core never looks
2201** at the internal representation of an [sqlite3_mutex].  It only
2202** deals with pointers to the [sqlite3_mutex] object.
2203**
2204** Mutexes are created using [sqlite3_mutex_alloc()].
2205*/
2206typedef struct sqlite3_mutex sqlite3_mutex;
2207
2208/*
2209** CAPI3REF: Loadable Extension Thunk
2210**
2211** A pointer to the opaque sqlite3_api_routines structure is passed as
2212** the third parameter to entry points of [loadable extensions].  This
2213** structure must be typedefed in order to work around compiler warnings
2214** on some platforms.
2215*/
2216typedef struct sqlite3_api_routines sqlite3_api_routines;
2217
2218/*
2219** CAPI3REF: OS Interface Object
2220**
2221** An instance of the sqlite3_vfs object defines the interface between
2222** the SQLite core and the underlying operating system.  The "vfs"
2223** in the name of the object stands for "virtual file system".  See
2224** the [VFS | VFS documentation] for further information.
2225**
2226** The VFS interface is sometimes extended by adding new methods onto
2227** the end.  Each time such an extension occurs, the iVersion field
2228** is incremented.  The iVersion value started out as 1 in
2229** SQLite [version 3.5.0] on [dateof:3.5.0], then increased to 2
2230** with SQLite [version 3.7.0] on [dateof:3.7.0], and then increased
2231** to 3 with SQLite [version 3.7.6] on [dateof:3.7.6].  Additional fields
2232** may be appended to the sqlite3_vfs object and the iVersion value
2233** may increase again in future versions of SQLite.
2234** Note that the structure
2235** of the sqlite3_vfs object changes in the transition from
2236** SQLite [version 3.5.9] to [version 3.6.0] on [dateof:3.6.0]
2237** and yet the iVersion field was not modified.
2238**
2239** The szOsFile field is the size of the subclassed [sqlite3_file]
2240** structure used by this VFS.  mxPathname is the maximum length of
2241** a pathname in this VFS.
2242**
2243** Registered sqlite3_vfs objects are kept on a linked list formed by
2244** the pNext pointer.  The [sqlite3_vfs_register()]
2245** and [sqlite3_vfs_unregister()] interfaces manage this list
2246** in a thread-safe way.  The [sqlite3_vfs_find()] interface
2247** searches the list.  Neither the application code nor the VFS
2248** implementation should use the pNext pointer.
2249**
2250** The pNext field is the only field in the sqlite3_vfs
2251** structure that SQLite will ever modify.  SQLite will only access
2252** or modify this field while holding a particular static mutex.
2253** The application should never modify anything within the sqlite3_vfs
2254** object once the object has been registered.
2255**
2256** The zName field holds the name of the VFS module.  The name must
2257** be unique across all VFS modules.
2258**
2259** [[sqlite3_vfs.xOpen]]
2260** ^SQLite guarantees that the zFilename parameter to xOpen
2261** is either a NULL pointer or string obtained
2262** from xFullPathname() with an optional suffix added.
2263** ^If a suffix is added to the zFilename parameter, it will
2264** consist of a single "-" character followed by no more than
2265** 11 alphanumeric and/or "-" characters.
2266** ^SQLite further guarantees that
2267** the string will be valid and unchanged until xClose() is
2268** called. Because of the previous sentence,
2269** the [sqlite3_file] can safely store a pointer to the
2270** filename if it needs to remember the filename for some reason.
2271** If the zFilename parameter to xOpen is a NULL pointer then xOpen
2272** must invent its own temporary name for the file.  ^Whenever the
2273** xFilename parameter is NULL it will also be the case that the
2274** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
2275**
2276** The flags argument to xOpen() includes all bits set in
2277** the flags argument to [sqlite3_open_v2()].  Or if [sqlite3_open()]
2278** or [sqlite3_open16()] is used, then flags includes at least
2279** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
2280** If xOpen() opens a file read-only then it sets *pOutFlags to
2281** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be set.
2282**
2283** ^(SQLite will also add one of the following flags to the xOpen()
2284** call, depending on the object being opened:
2285**
2286** <ul>
2287** <li>  [SQLITE_OPEN_MAIN_DB]
2288** <li>  [SQLITE_OPEN_MAIN_JOURNAL]
2289** <li>  [SQLITE_OPEN_TEMP_DB]
2290** <li>  [SQLITE_OPEN_TEMP_JOURNAL]
2291** <li>  [SQLITE_OPEN_TRANSIENT_DB]
2292** <li>  [SQLITE_OPEN_SUBJOURNAL]
2293** <li>  [SQLITE_OPEN_MASTER_JOURNAL]
2294** <li>  [SQLITE_OPEN_WAL]
2295** </ul>)^
2296**
2297** The file I/O implementation can use the object type flags to
2298** change the way it deals with files.  For example, an application
2299** that does not care about crash recovery or rollback might make
2300** the open of a journal file a no-op.  Writes to this journal would
2301** also be no-ops, and any attempt to read the journal would return
2302** SQLITE_IOERR.  Or the implementation might recognize that a database
2303** file will be doing page-aligned sector reads and writes in a random
2304** order and set up its I/O subsystem accordingly.
2305**
2306** SQLite might also add one of the following flags to the xOpen method:
2307**
2308** <ul>
2309** <li> [SQLITE_OPEN_DELETEONCLOSE]
2310** <li> [SQLITE_OPEN_EXCLUSIVE]
2311** </ul>
2312**
2313** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
2314** deleted when it is closed.  ^The [SQLITE_OPEN_DELETEONCLOSE]
2315** will be set for TEMP databases and their journals, transient
2316** databases, and subjournals.
2317**
2318** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
2319** with the [SQLITE_OPEN_CREATE] flag, which are both directly
2320** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
2321** API.  The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
2322** SQLITE_OPEN_CREATE, is used to indicate that file should always
2323** be created, and that it is an error if it already exists.
2324** It is <i>not</i> used to indicate the file should be opened
2325** for exclusive access.
2326**
2327** ^At least szOsFile bytes of memory are allocated by SQLite
2328** to hold the  [sqlite3_file] structure passed as the third
2329** argument to xOpen.  The xOpen method does not have to
2330** allocate the structure; it should just fill it in.  Note that
2331** the xOpen method must set the sqlite3_file.pMethods to either
2332** a valid [sqlite3_io_methods] object or to NULL.  xOpen must do
2333** this even if the open fails.  SQLite expects that the sqlite3_file.pMethods
2334** element will be valid after xOpen returns regardless of the success
2335** or failure of the xOpen call.
2336**
2337** [[sqlite3_vfs.xAccess]]
2338** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
2339** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
2340** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
2341** to test whether a file is at least readable.  The SQLITE_ACCESS_READ
2342** flag is never actually used and is not implemented in the built-in
2343** VFSes of SQLite.  The file is named by the second argument and can be a
2344** directory. The xAccess method returns [SQLITE_OK] on success or some
2345** non-zero error code if there is an I/O error or if the name of
2346** the file given in the second argument is illegal.  If SQLITE_OK
2347** is returned, then non-zero or zero is written into *pResOut to indicate
2348** whether or not the file is accessible.
2349**
2350** ^SQLite will always allocate at least mxPathname+1 bytes for the
2351** output buffer xFullPathname.  The exact size of the output buffer
2352** is also passed as a parameter to both  methods. If the output buffer
2353** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
2354** handled as a fatal error by SQLite, vfs implementations should endeavor
2355** to prevent this by setting mxPathname to a sufficiently large value.
2356**
2357** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
2358** interfaces are not strictly a part of the filesystem, but they are
2359** included in the VFS structure for completeness.
2360** The xRandomness() function attempts to return nBytes bytes
2361** of good-quality randomness into zOut.  The return value is
2362** the actual number of bytes of randomness obtained.
2363** The xSleep() method causes the calling thread to sleep for at
2364** least the number of microseconds given.  ^The xCurrentTime()
2365** method returns a Julian Day Number for the current date and time as
2366** a floating point value.
2367** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
2368** Day Number multiplied by 86400000 (the number of milliseconds in
2369** a 24-hour day).
2370** ^SQLite will use the xCurrentTimeInt64() method to get the current
2371** date and time if that method is available (if iVersion is 2 or
2372** greater and the function pointer is not NULL) and will fall back
2373** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
2374**
2375** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
2376** are not used by the SQLite core.  These optional interfaces are provided
2377** by some VFSes to facilitate testing of the VFS code. By overriding
2378** system calls with functions under its control, a test program can
2379** simulate faults and error conditions that would otherwise be difficult
2380** or impossible to induce.  The set of system calls that can be overridden
2381** varies from one VFS to another, and from one version of the same VFS to the
2382** next.  Applications that use these interfaces must be prepared for any
2383** or all of these interfaces to be NULL or for their behavior to change
2384** from one release to the next.  Applications must not attempt to access
2385** any of these methods if the iVersion of the VFS is less than 3.
2386*/
2387typedef struct sqlite3_vfs sqlite3_vfs;
2388typedef void (*sqlite3_syscall_ptr)(void);
2389struct sqlite3_vfs {
2390  int iVersion;            /* Structure version number (currently 3) */
2391  int szOsFile;            /* Size of subclassed sqlite3_file */
2392  int mxPathname;          /* Maximum file pathname length */
2393  sqlite3_vfs *pNext;      /* Next registered VFS */
2394  const char *zName;       /* Name of this virtual file system */
2395  void *pAppData;          /* Pointer to application-specific data */
2396  int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
2397               int flags, int *pOutFlags);
2398  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
2399  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
2400  int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
2401  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
2402  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
2403  void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
2404  void (*xDlClose)(sqlite3_vfs*, void*);
2405  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
2406  int (*xSleep)(sqlite3_vfs*, int microseconds);
2407  int (*xCurrentTime)(sqlite3_vfs*, double*);
2408  int (*xGetLastError)(sqlite3_vfs*, int, char *);
2409  /*
2410  ** The methods above are in version 1 of the sqlite_vfs object
2411  ** definition.  Those that follow are added in version 2 or later
2412  */
2413  int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
2414  /*
2415  ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
2416  ** Those below are for version 3 and greater.
2417  */
2418  int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
2419  sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
2420  const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
2421  /*
2422  ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
2423  ** New fields may be appended in future versions.  The iVersion
2424  ** value will increment whenever this happens.
2425  */
2426};
2427
2428/*
2429** CAPI3REF: Flags for the xAccess VFS method
2430**
2431** These integer constants can be used as the third parameter to
2432** the xAccess method of an [sqlite3_vfs] object.  They determine
2433** what kind of permissions the xAccess method is looking for.
2434** With SQLITE_ACCESS_EXISTS, the xAccess method
2435** simply checks whether the file exists.
2436** With SQLITE_ACCESS_READWRITE, the xAccess method
2437** checks whether the named directory is both readable and writable
2438** (in other words, if files can be added, removed, and renamed within
2439** the directory).
2440** The SQLITE_ACCESS_READWRITE constant is currently used only by the
2441** [temp_store_directory pragma], though this could change in a future
2442** release of SQLite.
2443** With SQLITE_ACCESS_READ, the xAccess method
2444** checks whether the file is readable.  The SQLITE_ACCESS_READ constant is
2445** currently unused, though it might be used in a future release of
2446** SQLite.
2447*/
2448#define SQLITE_ACCESS_EXISTS    0
2449#define SQLITE_ACCESS_READWRITE 1   /* Used by PRAGMA temp_store_directory */
2450#define SQLITE_ACCESS_READ      2   /* Unused */
2451
2452/*
2453** CAPI3REF: Flags for the xShmLock VFS method
2454**
2455** These integer constants define the various locking operations
2456** allowed by the xShmLock method of [sqlite3_io_methods].  The
2457** following are the only legal combinations of flags to the
2458** xShmLock method:
2459**
2460** <ul>
2461** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
2462** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
2463** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
2464** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
2465** </ul>
2466**
2467** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
2468** was given on the corresponding lock.
2469**
2470** The xShmLock method can transition between unlocked and SHARED or
2471** between unlocked and EXCLUSIVE.  It cannot transition between SHARED
2472** and EXCLUSIVE.
2473*/
2474#define SQLITE_SHM_UNLOCK       1
2475#define SQLITE_SHM_LOCK         2
2476#define SQLITE_SHM_SHARED       4
2477#define SQLITE_SHM_EXCLUSIVE    8
2478
2479/*
2480** CAPI3REF: Maximum xShmLock index
2481**
2482** The xShmLock method on [sqlite3_io_methods] may use values
2483** between 0 and this upper bound as its "offset" argument.
2484** The SQLite core will never attempt to acquire or release a
2485** lock outside of this range
2486*/
2487#define SQLITE_SHM_NLOCK        8
2488
2489
2490/*
2491** CAPI3REF: Initialize The SQLite Library
2492**
2493** ^The sqlite3_initialize() routine initializes the
2494** SQLite library.  ^The sqlite3_shutdown() routine
2495** deallocates any resources that were allocated by sqlite3_initialize().
2496** These routines are designed to aid in process initialization and
2497** shutdown on embedded systems.  Workstation applications using
2498** SQLite normally do not need to invoke either of these routines.
2499**
2500** A call to sqlite3_initialize() is an "effective" call if it is
2501** the first time sqlite3_initialize() is invoked during the lifetime of
2502** the process, or if it is the first time sqlite3_initialize() is invoked
2503** following a call to sqlite3_shutdown().  ^(Only an effective call
2504** of sqlite3_initialize() does any initialization.  All other calls
2505** are harmless no-ops.)^
2506**
2507** A call to sqlite3_shutdown() is an "effective" call if it is the first
2508** call to sqlite3_shutdown() since the last sqlite3_initialize().  ^(Only
2509** an effective call to sqlite3_shutdown() does any deinitialization.
2510** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
2511**
2512** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
2513** is not.  The sqlite3_shutdown() interface must only be called from a
2514** single thread.  All open [database connections] must be closed and all
2515** other SQLite resources must be deallocated prior to invoking
2516** sqlite3_shutdown().
2517**
2518** Among other things, ^sqlite3_initialize() will invoke
2519** sqlite3_os_init().  Similarly, ^sqlite3_shutdown()
2520** will invoke sqlite3_os_end().
2521**
2522** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
2523** ^If for some reason, sqlite3_initialize() is unable to initialize
2524** the library (perhaps it is unable to allocate a needed resource such
2525** as a mutex) it returns an [error code] other than [SQLITE_OK].
2526**
2527** ^The sqlite3_initialize() routine is called internally by many other
2528** SQLite interfaces so that an application usually does not need to
2529** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]
2530** calls sqlite3_initialize() so the SQLite library will be automatically
2531** initialized when [sqlite3_open()] is called if it has not be initialized
2532** already.  ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
2533** compile-time option, then the automatic calls to sqlite3_initialize()
2534** are omitted and the application must call sqlite3_initialize() directly
2535** prior to using any other SQLite interface.  For maximum portability,
2536** it is recommended that applications always invoke sqlite3_initialize()
2537** directly prior to using any other SQLite interface.  Future releases
2538** of SQLite may require this.  In other words, the behavior exhibited
2539** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
2540** default behavior in some future release of SQLite.
2541**
2542** The sqlite3_os_init() routine does operating-system specific
2543** initialization of the SQLite library.  The sqlite3_os_end()
2544** routine undoes the effect of sqlite3_os_init().  Typical tasks
2545** performed by these routines include allocation or deallocation
2546** of static resources, initialization of global variables,
2547** setting up a default [sqlite3_vfs] module, or setting up
2548** a default configuration using [sqlite3_config()].
2549**
2550** The application should never invoke either sqlite3_os_init()
2551** or sqlite3_os_end() directly.  The application should only invoke
2552** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()
2553** interface is called automatically by sqlite3_initialize() and
2554** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate
2555** implementations for sqlite3_os_init() and sqlite3_os_end()
2556** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
2557** When [custom builds | built for other platforms]
2558** (using the [SQLITE_OS_OTHER=1] compile-time
2559** option) the application must supply a suitable implementation for
2560** sqlite3_os_init() and sqlite3_os_end().  An application-supplied
2561** implementation of sqlite3_os_init() or sqlite3_os_end()
2562** must return [SQLITE_OK] on success and some other [error code] upon
2563** failure.
2564*/
2565SQLITE_API int sqlite3_initialize(void);
2566SQLITE_API int sqlite3_shutdown(void);
2567SQLITE_API int sqlite3_os_init(void);
2568SQLITE_API int sqlite3_os_end(void);
2569
2570/*
2571** CAPI3REF: Configuring The SQLite Library
2572**
2573** The sqlite3_config() interface is used to make global configuration
2574** changes to SQLite in order to tune SQLite to the specific needs of
2575** the application.  The default configuration is recommended for most
2576** applications and so this routine is usually not necessary.  It is
2577** provided to support rare applications with unusual needs.
2578**
2579** <b>The sqlite3_config() interface is not threadsafe. The application
2580** must ensure that no other SQLite interfaces are invoked by other
2581** threads while sqlite3_config() is running.</b>
2582**
2583** The sqlite3_config() interface
2584** may only be invoked prior to library initialization using
2585** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
2586** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
2587** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
2588** Note, however, that ^sqlite3_config() can be called as part of the
2589** implementation of an application-defined [sqlite3_os_init()].
2590**
2591** The first argument to sqlite3_config() is an integer
2592** [configuration option] that determines
2593** what property of SQLite is to be configured.  Subsequent arguments
2594** vary depending on the [configuration option]
2595** in the first argument.
2596**
2597** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
2598** ^If the option is unknown or SQLite is unable to set the option
2599** then this routine returns a non-zero [error code].
2600*/
2601SQLITE_API int sqlite3_config(int, ...);
2602
2603/*
2604** CAPI3REF: Configure database connections
2605** METHOD: sqlite3
2606**
2607** The sqlite3_db_config() interface is used to make configuration
2608** changes to a [database connection].  The interface is similar to
2609** [sqlite3_config()] except that the changes apply to a single
2610** [database connection] (specified in the first argument).
2611**
2612** The second argument to sqlite3_db_config(D,V,...)  is the
2613** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code
2614** that indicates what aspect of the [database connection] is being configured.
2615** Subsequent arguments vary depending on the configuration verb.
2616**
2617** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
2618** the call is considered successful.
2619*/
2620SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
2621
2622/*
2623** CAPI3REF: Memory Allocation Routines
2624**
2625** An instance of this object defines the interface between SQLite
2626** and low-level memory allocation routines.
2627**
2628** This object is used in only one place in the SQLite interface.
2629** A pointer to an instance of this object is the argument to
2630** [sqlite3_config()] when the configuration option is
2631** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
2632** By creating an instance of this object
2633** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
2634** during configuration, an application can specify an alternative
2635** memory allocation subsystem for SQLite to use for all of its
2636** dynamic memory needs.
2637**
2638** Note that SQLite comes with several [built-in memory allocators]
2639** that are perfectly adequate for the overwhelming majority of applications
2640** and that this object is only useful to a tiny minority of applications
2641** with specialized memory allocation requirements.  This object is
2642** also used during testing of SQLite in order to specify an alternative
2643** memory allocator that simulates memory out-of-memory conditions in
2644** order to verify that SQLite recovers gracefully from such
2645** conditions.
2646**
2647** The xMalloc, xRealloc, and xFree methods must work like the
2648** malloc(), realloc() and free() functions from the standard C library.
2649** ^SQLite guarantees that the second argument to
2650** xRealloc is always a value returned by a prior call to xRoundup.
2651**
2652** xSize should return the allocated size of a memory allocation
2653** previously obtained from xMalloc or xRealloc.  The allocated size
2654** is always at least as big as the requested size but may be larger.
2655**
2656** The xRoundup method returns what would be the allocated size of
2657** a memory allocation given a particular requested size.  Most memory
2658** allocators round up memory allocations at least to the next multiple
2659** of 8.  Some allocators round up to a larger multiple or to a power of 2.
2660** Every memory allocation request coming in through [sqlite3_malloc()]
2661** or [sqlite3_realloc()] first calls xRoundup.  If xRoundup returns 0,
2662** that causes the corresponding memory allocation to fail.
2663**
2664** The xInit method initializes the memory allocator.  For example,
2665** it might allocate any require mutexes or initialize internal data
2666** structures.  The xShutdown method is invoked (indirectly) by
2667** [sqlite3_shutdown()] and should deallocate any resources acquired
2668** by xInit.  The pAppData pointer is used as the only parameter to
2669** xInit and xShutdown.
2670**
2671** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
2672** the xInit method, so the xInit method need not be threadsafe.  The
2673** xShutdown method is only called from [sqlite3_shutdown()] so it does
2674** not need to be threadsafe either.  For all other methods, SQLite
2675** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
2676** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
2677** it is by default) and so the methods are automatically serialized.
2678** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
2679** methods must be threadsafe or else make their own arrangements for
2680** serialization.
2681**
2682** SQLite will never invoke xInit() more than once without an intervening
2683** call to xShutdown().
2684*/
2685typedef struct sqlite3_mem_methods sqlite3_mem_methods;
2686struct sqlite3_mem_methods {
2687  void *(*xMalloc)(int);         /* Memory allocation function */
2688  void (*xFree)(void*);          /* Free a prior allocation */
2689  void *(*xRealloc)(void*,int);  /* Resize an allocation */
2690  int (*xSize)(void*);           /* Return the size of an allocation */
2691  int (*xRoundup)(int);          /* Round up request size to allocation size */
2692  int (*xInit)(void*);           /* Initialize the memory allocator */
2693  void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
2694  void *pAppData;                /* Argument to xInit() and xShutdown() */
2695};
2696
2697/*
2698** CAPI3REF: Configuration Options
2699** KEYWORDS: {configuration option}
2700**
2701** These constants are the available integer configuration options that
2702** can be passed as the first argument to the [sqlite3_config()] interface.
2703**
2704** New configuration options may be added in future releases of SQLite.
2705** Existing configuration options might be discontinued.  Applications
2706** should check the return code from [sqlite3_config()] to make sure that
2707** the call worked.  The [sqlite3_config()] interface will return a
2708** non-zero [error code] if a discontinued or unsupported configuration option
2709** is invoked.
2710**
2711** <dl>
2712** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
2713** <dd>There are no arguments to this option.  ^This option sets the
2714** [threading mode] to Single-thread.  In other words, it disables
2715** all mutexing and puts SQLite into a mode where it can only be used
2716** by a single thread.   ^If SQLite is compiled with
2717** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
2718** it is not possible to change the [threading mode] from its default
2719** value of Single-thread and so [sqlite3_config()] will return
2720** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
2721** configuration option.</dd>
2722**
2723** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
2724** <dd>There are no arguments to this option.  ^This option sets the
2725** [threading mode] to Multi-thread.  In other words, it disables
2726** mutexing on [database connection] and [prepared statement] objects.
2727** The application is responsible for serializing access to
2728** [database connections] and [prepared statements].  But other mutexes
2729** are enabled so that SQLite will be safe to use in a multi-threaded
2730** environment as long as no two threads attempt to use the same
2731** [database connection] at the same time.  ^If SQLite is compiled with
2732** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
2733** it is not possible to set the Multi-thread [threading mode] and
2734** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
2735** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
2736**
2737** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
2738** <dd>There are no arguments to this option.  ^This option sets the
2739** [threading mode] to Serialized. In other words, this option enables
2740** all mutexes including the recursive
2741** mutexes on [database connection] and [prepared statement] objects.
2742** In this mode (which is the default when SQLite is compiled with
2743** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
2744** to [database connections] and [prepared statements] so that the
2745** application is free to use the same [database connection] or the
2746** same [prepared statement] in different threads at the same time.
2747** ^If SQLite is compiled with
2748** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
2749** it is not possible to set the Serialized [threading mode] and
2750** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
2751** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
2752**
2753** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
2754** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is
2755** a pointer to an instance of the [sqlite3_mem_methods] structure.
2756** The argument specifies
2757** alternative low-level memory allocation routines to be used in place of
2758** the memory allocation routines built into SQLite.)^ ^SQLite makes
2759** its own private copy of the content of the [sqlite3_mem_methods] structure
2760** before the [sqlite3_config()] call returns.</dd>
2761**
2762** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
2763** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which
2764** is a pointer to an instance of the [sqlite3_mem_methods] structure.
2765** The [sqlite3_mem_methods]
2766** structure is filled with the currently defined memory allocation routines.)^
2767** This option can be used to overload the default memory allocation
2768** routines with a wrapper that simulations memory allocation failure or
2769** tracks memory usage, for example. </dd>
2770**
2771** [[SQLITE_CONFIG_SMALL_MALLOC]] <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>
2772** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of
2773** type int, interpreted as a boolean, which if true provides a hint to
2774** SQLite that it should avoid large memory allocations if possible.
2775** SQLite will run faster if it is free to make large memory allocations,
2776** but some application might prefer to run slower in exchange for
2777** guarantees about memory fragmentation that are possible if large
2778** allocations are avoided.  This hint is normally off.
2779** </dd>
2780**
2781** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
2782** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
2783** interpreted as a boolean, which enables or disables the collection of
2784** memory allocation statistics. ^(When memory allocation statistics are
2785** disabled, the following SQLite interfaces become non-operational:
2786**   <ul>
2787**   <li> [sqlite3_memory_used()]
2788**   <li> [sqlite3_memory_highwater()]
2789**   <li> [sqlite3_soft_heap_limit64()]
2790**   <li> [sqlite3_status64()]
2791**   </ul>)^
2792** ^Memory allocation statistics are enabled by default unless SQLite is
2793** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
2794** allocation statistics are disabled by default.
2795** </dd>
2796**
2797** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
2798** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
2799** </dd>
2800**
2801** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
2802** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
2803** that SQLite can use for the database page cache with the default page
2804** cache implementation.
2805** This configuration option is a no-op if an application-define page
2806** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
2807** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
2808** 8-byte aligned memory (pMem), the size of each page cache line (sz),
2809** and the number of cache lines (N).
2810** The sz argument should be the size of the largest database page
2811** (a power of two between 512 and 65536) plus some extra bytes for each
2812** page header.  ^The number of extra bytes needed by the page header
2813** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
2814** ^It is harmless, apart from the wasted memory,
2815** for the sz parameter to be larger than necessary.  The pMem
2816** argument must be either a NULL pointer or a pointer to an 8-byte
2817** aligned block of memory of at least sz*N bytes, otherwise
2818** subsequent behavior is undefined.
2819** ^When pMem is not NULL, SQLite will strive to use the memory provided
2820** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
2821** a page cache line is larger than sz bytes or if all of the pMem buffer
2822** is exhausted.
2823** ^If pMem is NULL and N is non-zero, then each database connection
2824** does an initial bulk allocation for page cache memory
2825** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
2826** of -1024*N bytes if N is negative, . ^If additional
2827** page cache memory is needed beyond what is provided by the initial
2828** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
2829** additional cache line. </dd>
2830**
2831** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
2832** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer
2833** that SQLite will use for all of its dynamic memory allocation needs
2834** beyond those provided for by [SQLITE_CONFIG_PAGECACHE].
2835** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
2836** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
2837** [SQLITE_ERROR] if invoked otherwise.
2838** ^There are three arguments to SQLITE_CONFIG_HEAP:
2839** An 8-byte aligned pointer to the memory,
2840** the number of bytes in the memory buffer, and the minimum allocation size.
2841** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
2842** to using its default memory allocator (the system malloc() implementation),
2843** undoing any prior invocation of [SQLITE_CONFIG_MALLOC].  ^If the
2844** memory pointer is not NULL then the alternative memory
2845** allocator is engaged to handle all of SQLites memory allocation needs.
2846** The first pointer (the memory pointer) must be aligned to an 8-byte
2847** boundary or subsequent behavior of SQLite will be undefined.
2848** The minimum allocation size is capped at 2**12. Reasonable values
2849** for the minimum allocation size are 2**5 through 2**8.</dd>
2850**
2851** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
2852** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
2853** pointer to an instance of the [sqlite3_mutex_methods] structure.
2854** The argument specifies alternative low-level mutex routines to be used
2855** in place the mutex routines built into SQLite.)^  ^SQLite makes a copy of
2856** the content of the [sqlite3_mutex_methods] structure before the call to
2857** [sqlite3_config()] returns. ^If SQLite is compiled with
2858** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
2859** the entire mutexing subsystem is omitted from the build and hence calls to
2860** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
2861** return [SQLITE_ERROR].</dd>
2862**
2863** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
2864** <dd> ^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which
2865** is a pointer to an instance of the [sqlite3_mutex_methods] structure.  The
2866** [sqlite3_mutex_methods]
2867** structure is filled with the currently defined mutex routines.)^
2868** This option can be used to overload the default mutex allocation
2869** routines with a wrapper used to track mutex usage for performance
2870** profiling or testing, for example.   ^If SQLite is compiled with
2871** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
2872** the entire mutexing subsystem is omitted from the build and hence calls to
2873** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
2874** return [SQLITE_ERROR].</dd>
2875**
2876** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
2877** <dd> ^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
2878** the default size of lookaside memory on each [database connection].
2879** The first argument is the
2880** size of each lookaside buffer slot and the second is the number of
2881** slots allocated to each database connection.)^  ^(SQLITE_CONFIG_LOOKASIDE
2882** sets the <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
2883** option to [sqlite3_db_config()] can be used to change the lookaside
2884** configuration on individual connections.)^ </dd>
2885**
2886** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
2887** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
2888** a pointer to an [sqlite3_pcache_methods2] object.  This object specifies
2889** the interface to a custom page cache implementation.)^
2890** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
2891**
2892** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
2893** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
2894** is a pointer to an [sqlite3_pcache_methods2] object.  SQLite copies of
2895** the current page cache implementation into that object.)^ </dd>
2896**
2897** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
2898** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
2899** global [error log].
2900** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
2901** function with a call signature of void(*)(void*,int,const char*),
2902** and a pointer to void. ^If the function pointer is not NULL, it is
2903** invoked by [sqlite3_log()] to process each logging event.  ^If the
2904** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
2905** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
2906** passed through as the first parameter to the application-defined logger
2907** function whenever that function is invoked.  ^The second parameter to
2908** the logger function is a copy of the first parameter to the corresponding
2909** [sqlite3_log()] call and is intended to be a [result code] or an
2910** [extended result code].  ^The third parameter passed to the logger is
2911** log message after formatting via [sqlite3_snprintf()].
2912** The SQLite logging interface is not reentrant; the logger function
2913** supplied by the application must not invoke any SQLite interface.
2914** In a multi-threaded application, the application-defined logger
2915** function must be threadsafe. </dd>
2916**
2917** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
2918** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
2919** If non-zero, then URI handling is globally enabled. If the parameter is zero,
2920** then URI handling is globally disabled.)^ ^If URI handling is globally
2921** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
2922** [sqlite3_open16()] or
2923** specified as part of [ATTACH] commands are interpreted as URIs, regardless
2924** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
2925** connection is opened. ^If it is globally disabled, filenames are
2926** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
2927** database connection is opened. ^(By default, URI handling is globally
2928** disabled. The default value may be changed by compiling with the
2929** [SQLITE_USE_URI] symbol defined.)^
2930**
2931** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
2932** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
2933** argument which is interpreted as a boolean in order to enable or disable
2934** the use of covering indices for full table scans in the query optimizer.
2935** ^The default setting is determined
2936** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
2937** if that compile-time option is omitted.
2938** The ability to disable the use of covering indices for full table scans
2939** is because some incorrectly coded legacy applications might malfunction
2940** when the optimization is enabled.  Providing the ability to
2941** disable the optimization allows the older, buggy application code to work
2942** without change even with newer versions of SQLite.
2943**
2944** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
2945** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
2946** <dd> These options are obsolete and should not be used by new code.
2947** They are retained for backwards compatibility but are now no-ops.
2948** </dd>
2949**
2950** [[SQLITE_CONFIG_SQLLOG]]
2951** <dt>SQLITE_CONFIG_SQLLOG
2952** <dd>This option is only available if sqlite is compiled with the
2953** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
2954** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
2955** The second should be of type (void*). The callback is invoked by the library
2956** in three separate circumstances, identified by the value passed as the
2957** fourth parameter. If the fourth parameter is 0, then the database connection
2958** passed as the second argument has just been opened. The third argument
2959** points to a buffer containing the name of the main database file. If the
2960** fourth parameter is 1, then the SQL statement that the third parameter
2961** points to has just been executed. Or, if the fourth parameter is 2, then
2962** the connection being passed as the second parameter is being closed. The
2963** third parameter is passed NULL In this case.  An example of using this
2964** configuration option can be seen in the "test_sqllog.c" source file in
2965** the canonical SQLite source tree.</dd>
2966**
2967** [[SQLITE_CONFIG_MMAP_SIZE]]
2968** <dt>SQLITE_CONFIG_MMAP_SIZE
2969** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
2970** that are the default mmap size limit (the default setting for
2971** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
2972** ^The default setting can be overridden by each database connection using
2973** either the [PRAGMA mmap_size] command, or by using the
2974** [SQLITE_FCNTL_MMAP_SIZE] file control.  ^(The maximum allowed mmap size
2975** will be silently truncated if necessary so that it does not exceed the
2976** compile-time maximum mmap size set by the
2977** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
2978** ^If either argument to this option is negative, then that argument is
2979** changed to its compile-time default.
2980**
2981** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
2982** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
2983** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
2984** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
2985** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
2986** that specifies the maximum size of the created heap.
2987**
2988** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
2989** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
2990** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
2991** is a pointer to an integer and writes into that integer the number of extra
2992** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].
2993** The amount of extra space required can change depending on the compiler,
2994** target platform, and SQLite version.
2995**
2996** [[SQLITE_CONFIG_PMASZ]]
2997** <dt>SQLITE_CONFIG_PMASZ
2998** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which
2999** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
3000** sorter to that integer.  The default minimum PMA Size is set by the
3001** [SQLITE_SORTER_PMASZ] compile-time option.  New threads are launched
3002** to help with sort operations when multithreaded sorting
3003** is enabled (using the [PRAGMA threads] command) and the amount of content
3004** to be sorted exceeds the page size times the minimum of the
3005** [PRAGMA cache_size] setting and this value.
3006**
3007** [[SQLITE_CONFIG_STMTJRNL_SPILL]]
3008** <dt>SQLITE_CONFIG_STMTJRNL_SPILL
3009** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
3010** becomes the [statement journal] spill-to-disk threshold.
3011** [Statement journals] are held in memory until their size (in bytes)
3012** exceeds this threshold, at which point they are written to disk.
3013** Or if the threshold is -1, statement journals are always held
3014** exclusively in memory.
3015** Since many statement journals never become large, setting the spill
3016** threshold to a value such as 64KiB can greatly reduce the amount of
3017** I/O required to support statement rollback.
3018** The default value for this setting is controlled by the
3019** [SQLITE_STMTJRNL_SPILL] compile-time option.
3020**
3021** [[SQLITE_CONFIG_SORTERREF_SIZE]]
3022** <dt>SQLITE_CONFIG_SORTERREF_SIZE
3023** <dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter
3024** of type (int) - the new value of the sorter-reference size threshold.
3025** Usually, when SQLite uses an external sort to order records according
3026** to an ORDER BY clause, all fields required by the caller are present in the
3027** sorted records. However, if SQLite determines based on the declared type
3028** of a table column that its values are likely to be very large - larger
3029** than the configured sorter-reference size threshold - then a reference
3030** is stored in each sorted record and the required column values loaded
3031** from the database as records are returned in sorted order. The default
3032** value for this option is to never use this optimization. Specifying a
3033** negative value for this option restores the default behaviour.
3034** This option is only available if SQLite is compiled with the
3035** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option.
3036**
3037** [[SQLITE_CONFIG_MEMDB_MAXSIZE]]
3038** <dt>SQLITE_CONFIG_MEMDB_MAXSIZE
3039** <dd>The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter
3040** [sqlite3_int64] parameter which is the default maximum size for an in-memory
3041** database created using [sqlite3_deserialize()].  This default maximum
3042** size can be adjusted up or down for individual databases using the
3043** [SQLITE_FCNTL_SIZE_LIMIT] [sqlite3_file_control|file-control].  If this
3044** configuration setting is never used, then the default maximum is determined
3045** by the [SQLITE_MEMDB_DEFAULT_MAXSIZE] compile-time option.  If that
3046** compile-time option is not set, then the default maximum is 1073741824.
3047** </dl>
3048*/
3049#define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
3050#define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
3051#define SQLITE_CONFIG_SERIALIZED    3  /* nil */
3052#define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
3053#define SQLITE_CONFIG_GETMALLOC     5  /* sqlite3_mem_methods* */
3054#define SQLITE_CONFIG_SCRATCH       6  /* No longer used */
3055#define SQLITE_CONFIG_PAGECACHE     7  /* void*, int sz, int N */
3056#define SQLITE_CONFIG_HEAP          8  /* void*, int nByte, int min */
3057#define SQLITE_CONFIG_MEMSTATUS     9  /* boolean */
3058#define SQLITE_CONFIG_MUTEX        10  /* sqlite3_mutex_methods* */
3059#define SQLITE_CONFIG_GETMUTEX     11  /* sqlite3_mutex_methods* */
3060/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
3061#define SQLITE_CONFIG_LOOKASIDE    13  /* int int */
3062#define SQLITE_CONFIG_PCACHE       14  /* no-op */
3063#define SQLITE_CONFIG_GETPCACHE    15  /* no-op */
3064#define SQLITE_CONFIG_LOG          16  /* xFunc, void* */
3065#define SQLITE_CONFIG_URI          17  /* int */
3066#define SQLITE_CONFIG_PCACHE2      18  /* sqlite3_pcache_methods2* */
3067#define SQLITE_CONFIG_GETPCACHE2   19  /* sqlite3_pcache_methods2* */
3068#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20  /* int */
3069#define SQLITE_CONFIG_SQLLOG       21  /* xSqllog, void* */
3070#define SQLITE_CONFIG_MMAP_SIZE    22  /* sqlite3_int64, sqlite3_int64 */
3071#define SQLITE_CONFIG_WIN32_HEAPSIZE      23  /* int nByte */
3072#define SQLITE_CONFIG_PCACHE_HDRSZ        24  /* int *psz */
3073#define SQLITE_CONFIG_PMASZ               25  /* unsigned int szPma */
3074#define SQLITE_CONFIG_STMTJRNL_SPILL      26  /* int nByte */
3075#define SQLITE_CONFIG_SMALL_MALLOC        27  /* boolean */
3076#define SQLITE_CONFIG_SORTERREF_SIZE      28  /* int nByte */
3077#define SQLITE_CONFIG_MEMDB_MAXSIZE       29  /* sqlite3_int64 */
3078
3079/*
3080** CAPI3REF: Database Connection Configuration Options
3081**
3082** These constants are the available integer configuration options that
3083** can be passed as the second argument to the [sqlite3_db_config()] interface.
3084**
3085** New configuration options may be added in future releases of SQLite.
3086** Existing configuration options might be discontinued.  Applications
3087** should check the return code from [sqlite3_db_config()] to make sure that
3088** the call worked.  ^The [sqlite3_db_config()] interface will return a
3089** non-zero [error code] if a discontinued or unsupported configuration option
3090** is invoked.
3091**
3092** <dl>
3093** [[SQLITE_DBCONFIG_LOOKASIDE]]
3094** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
3095** <dd> ^This option takes three additional arguments that determine the
3096** [lookaside memory allocator] configuration for the [database connection].
3097** ^The first argument (the third parameter to [sqlite3_db_config()] is a
3098** pointer to a memory buffer to use for lookaside memory.
3099** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
3100** may be NULL in which case SQLite will allocate the
3101** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
3102** size of each lookaside buffer slot.  ^The third argument is the number of
3103** slots.  The size of the buffer in the first argument must be greater than
3104** or equal to the product of the second and third arguments.  The buffer
3105** must be aligned to an 8-byte boundary.  ^If the second argument to
3106** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
3107** rounded down to the next smaller multiple of 8.  ^(The lookaside memory
3108** configuration for a database connection can only be changed when that
3109** connection is not currently using lookaside memory, or in other words
3110** when the "current value" returned by
3111** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
3112** Any attempt to change the lookaside memory configuration when lookaside
3113** memory is in use leaves the configuration unchanged and returns
3114** [SQLITE_BUSY].)^</dd>
3115**
3116** [[SQLITE_DBCONFIG_ENABLE_FKEY]]
3117** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
3118** <dd> ^This option is used to enable or disable the enforcement of
3119** [foreign key constraints].  There should be two additional arguments.
3120** The first argument is an integer which is 0 to disable FK enforcement,
3121** positive to enable FK enforcement or negative to leave FK enforcement
3122** unchanged.  The second parameter is a pointer to an integer into which
3123** is written 0 or 1 to indicate whether FK enforcement is off or on
3124** following this call.  The second parameter may be a NULL pointer, in
3125** which case the FK enforcement setting is not reported back. </dd>
3126**
3127** [[SQLITE_DBCONFIG_ENABLE_TRIGGER]]
3128** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
3129** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
3130** There should be two additional arguments.
3131** The first argument is an integer which is 0 to disable triggers,
3132** positive to enable triggers or negative to leave the setting unchanged.
3133** The second parameter is a pointer to an integer into which
3134** is written 0 or 1 to indicate whether triggers are disabled or enabled
3135** following this call.  The second parameter may be a NULL pointer, in
3136** which case the trigger setting is not reported back. </dd>
3137**
3138** [[SQLITE_DBCONFIG_ENABLE_VIEW]]
3139** <dt>SQLITE_DBCONFIG_ENABLE_VIEW</dt>
3140** <dd> ^This option is used to enable or disable [CREATE VIEW | views].
3141** There should be two additional arguments.
3142** The first argument is an integer which is 0 to disable views,
3143** positive to enable views or negative to leave the setting unchanged.
3144** The second parameter is a pointer to an integer into which
3145** is written 0 or 1 to indicate whether views are disabled or enabled
3146** following this call.  The second parameter may be a NULL pointer, in
3147** which case the view setting is not reported back. </dd>
3148**
3149** [[SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER]]
3150** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
3151** <dd> ^This option is used to enable or disable the
3152** [fts3_tokenizer()] function which is part of the
3153** [FTS3] full-text search engine extension.
3154** There should be two additional arguments.
3155** The first argument is an integer which is 0 to disable fts3_tokenizer() or
3156** positive to enable fts3_tokenizer() or negative to leave the setting
3157** unchanged.
3158** The second parameter is a pointer to an integer into which
3159** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
3160** following this call.  The second parameter may be a NULL pointer, in
3161** which case the new setting is not reported back. </dd>
3162**
3163** [[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION]]
3164** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt>
3165** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
3166** interface independently of the [load_extension()] SQL function.
3167** The [sqlite3_enable_load_extension()] API enables or disables both the
3168** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].
3169** There should be two additional arguments.
3170** When the first argument to this interface is 1, then only the C-API is
3171** enabled and the SQL function remains disabled.  If the first argument to
3172** this interface is 0, then both the C-API and the SQL function are disabled.
3173** If the first argument is -1, then no changes are made to state of either the
3174** C-API or the SQL function.
3175** The second parameter is a pointer to an integer into which
3176** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface
3177** is disabled or enabled following this call.  The second parameter may
3178** be a NULL pointer, in which case the new setting is not reported back.
3179** </dd>
3180**
3181** [[SQLITE_DBCONFIG_MAINDBNAME]] <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>
3182** <dd> ^This option is used to change the name of the "main" database
3183** schema.  ^The sole argument is a pointer to a constant UTF8 string
3184** which will become the new schema name in place of "main".  ^SQLite
3185** does not make a copy of the new main schema name string, so the application
3186** must ensure that the argument passed into this DBCONFIG option is unchanged
3187** until after the database connection closes.
3188** </dd>
3189**
3190** [[SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE]]
3191** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>
3192** <dd> Usually, when a database in wal mode is closed or detached from a
3193** database handle, SQLite checks if this will mean that there are now no
3194** connections at all to the database. If so, it performs a checkpoint
3195** operation before closing the connection. This option may be used to
3196** override this behaviour. The first parameter passed to this operation
3197** is an integer - positive to disable checkpoints-on-close, or zero (the
3198** default) to enable them, and negative to leave the setting unchanged.
3199** The second parameter is a pointer to an integer
3200** into which is written 0 or 1 to indicate whether checkpoints-on-close
3201** have been disabled - 0 if they are not disabled, 1 if they are.
3202** </dd>
3203**
3204** [[SQLITE_DBCONFIG_ENABLE_QPSG]] <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>
3205** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates
3206** the [query planner stability guarantee] (QPSG).  When the QPSG is active,
3207** a single SQL query statement will always use the same algorithm regardless
3208** of values of [bound parameters].)^ The QPSG disables some query optimizations
3209** that look at the values of bound parameters, which can make some queries
3210** slower.  But the QPSG has the advantage of more predictable behavior.  With
3211** the QPSG active, SQLite will always use the same query plan in the field as
3212** was used during testing in the lab.
3213** The first argument to this setting is an integer which is 0 to disable
3214** the QPSG, positive to enable QPSG, or negative to leave the setting
3215** unchanged. The second parameter is a pointer to an integer into which
3216** is written 0 or 1 to indicate whether the QPSG is disabled or enabled
3217** following this call.
3218** </dd>
3219**
3220** [[SQLITE_DBCONFIG_TRIGGER_EQP]] <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt>
3221** <dd> By default, the output of EXPLAIN QUERY PLAN commands does not
3222** include output for any operations performed by trigger programs. This
3223** option is used to set or clear (the default) a flag that governs this
3224** behavior. The first parameter passed to this operation is an integer -
3225** positive to enable output for trigger programs, or zero to disable it,
3226** or negative to leave the setting unchanged.
3227** The second parameter is a pointer to an integer into which is written
3228** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if
3229** it is not disabled, 1 if it is.
3230** </dd>
3231**
3232** [[SQLITE_DBCONFIG_RESET_DATABASE]] <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt>
3233** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run
3234** [VACUUM] in order to reset a database back to an empty database
3235** with no schema and no content. The following process works even for
3236** a badly corrupted database file:
3237** <ol>
3238** <li> If the database connection is newly opened, make sure it has read the
3239**      database schema by preparing then discarding some query against the
3240**      database, or calling sqlite3_table_column_metadata(), ignoring any
3241**      errors.  This step is only necessary if the application desires to keep
3242**      the database in WAL mode after the reset if it was in WAL mode before
3243**      the reset.
3244** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);
3245** <li> [sqlite3_exec](db, "[VACUUM]", 0, 0, 0);
3246** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);
3247** </ol>
3248** Because resetting a database is destructive and irreversible, the
3249** process requires the use of this obscure API and multiple steps to help
3250** ensure that it does not happen by accident.
3251**
3252** [[SQLITE_DBCONFIG_DEFENSIVE]] <dt>SQLITE_DBCONFIG_DEFENSIVE</dt>
3253** <dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the
3254** "defensive" flag for a database connection.  When the defensive
3255** flag is enabled, language features that allow ordinary SQL to
3256** deliberately corrupt the database file are disabled.  The disabled
3257** features include but are not limited to the following:
3258** <ul>
3259** <li> The [PRAGMA writable_schema=ON] statement.
3260** <li> The [PRAGMA journal_mode=OFF] statement.
3261** <li> Writes to the [sqlite_dbpage] virtual table.
3262** <li> Direct writes to [shadow tables].
3263** </ul>
3264** </dd>
3265**
3266** [[SQLITE_DBCONFIG_WRITABLE_SCHEMA]] <dt>SQLITE_DBCONFIG_WRITABLE_SCHEMA</dt>
3267** <dd>The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the
3268** "writable_schema" flag. This has the same effect and is logically equivalent
3269** to setting [PRAGMA writable_schema=ON] or [PRAGMA writable_schema=OFF].
3270** The first argument to this setting is an integer which is 0 to disable
3271** the writable_schema, positive to enable writable_schema, or negative to
3272** leave the setting unchanged. The second parameter is a pointer to an
3273** integer into which is written 0 or 1 to indicate whether the writable_schema
3274** is enabled or disabled following this call.
3275** </dd>
3276**
3277** [[SQLITE_DBCONFIG_LEGACY_ALTER_TABLE]]
3278** <dt>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</dt>
3279** <dd>The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates
3280** the legacy behavior of the [ALTER TABLE RENAME] command such it
3281** behaves as it did prior to [version 3.24.0] (2018-06-04).  See the
3282** "Compatibility Notice" on the [ALTER TABLE RENAME documentation] for
3283** additional information. This feature can also be turned on and off
3284** using the [PRAGMA legacy_alter_table] statement.
3285** </dd>
3286**
3287** [[SQLITE_DBCONFIG_DQS_DML]]
3288** <dt>SQLITE_DBCONFIG_DQS_DML</td>
3289** <dd>The SQLITE_DBCONFIG_DQS_DML option activates or deactivates
3290** the legacy [double-quoted string literal] misfeature for DML statement
3291** only, that is DELETE, INSERT, SELECT, and UPDATE statements. The
3292** default value of this setting is determined by the [-DSQLITE_DQS]
3293** compile-time option.
3294** </dd>
3295**
3296** [[SQLITE_DBCONFIG_DQS_DDL]]
3297** <dt>SQLITE_DBCONFIG_DQS_DDL</td>
3298** <dd>The SQLITE_DBCONFIG_DQS option activates or deactivates
3299** the legacy [double-quoted string literal] misfeature for DDL statements,
3300** such as CREATE TABLE and CREATE INDEX. The
3301** default value of this setting is determined by the [-DSQLITE_DQS]
3302** compile-time option.
3303** </dd>
3304** </dl>
3305*/
3306#define SQLITE_DBCONFIG_MAINDBNAME            1000 /* const char* */
3307#define SQLITE_DBCONFIG_LOOKASIDE             1001 /* void* int int */
3308#define SQLITE_DBCONFIG_ENABLE_FKEY           1002 /* int int* */
3309#define SQLITE_DBCONFIG_ENABLE_TRIGGER        1003 /* int int* */
3310#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
3311#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
3312#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE      1006 /* int int* */
3313#define SQLITE_DBCONFIG_ENABLE_QPSG           1007 /* int int* */
3314#define SQLITE_DBCONFIG_TRIGGER_EQP           1008 /* int int* */
3315#define SQLITE_DBCONFIG_RESET_DATABASE        1009 /* int int* */
3316#define SQLITE_DBCONFIG_DEFENSIVE             1010 /* int int* */
3317#define SQLITE_DBCONFIG_WRITABLE_SCHEMA       1011 /* int int* */
3318#define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE    1012 /* int int* */
3319#define SQLITE_DBCONFIG_DQS_DML               1013 /* int int* */
3320#define SQLITE_DBCONFIG_DQS_DDL               1014 /* int int* */
3321#define SQLITE_DBCONFIG_ENABLE_VIEW           1015 /* int int* */
3322#define SQLITE_DBCONFIG_MAX                   1015 /* Largest DBCONFIG */
3323
3324/*
3325** CAPI3REF: Enable Or Disable Extended Result Codes
3326** METHOD: sqlite3
3327**
3328** ^The sqlite3_extended_result_codes() routine enables or disables the
3329** [extended result codes] feature of SQLite. ^The extended result
3330** codes are disabled by default for historical compatibility.
3331*/
3332SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
3333
3334/*
3335** CAPI3REF: Last Insert Rowid
3336** METHOD: sqlite3
3337**
3338** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
3339** has a unique 64-bit signed
3340** integer key called the [ROWID | "rowid"]. ^The rowid is always available
3341** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
3342** names are not also used by explicitly declared columns. ^If
3343** the table has a column of type [INTEGER PRIMARY KEY] then that column
3344** is another alias for the rowid.
3345**
3346** ^The sqlite3_last_insert_rowid(D) interface usually returns the [rowid] of
3347** the most recent successful [INSERT] into a rowid table or [virtual table]
3348** on database connection D. ^Inserts into [WITHOUT ROWID] tables are not
3349** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred
3350** on the database connection D, then sqlite3_last_insert_rowid(D) returns
3351** zero.
3352**
3353** As well as being set automatically as rows are inserted into database
3354** tables, the value returned by this function may be set explicitly by
3355** [sqlite3_set_last_insert_rowid()]
3356**
3357** Some virtual table implementations may INSERT rows into rowid tables as
3358** part of committing a transaction (e.g. to flush data accumulated in memory
3359** to disk). In this case subsequent calls to this function return the rowid
3360** associated with these internal INSERT operations, which leads to
3361** unintuitive results. Virtual table implementations that do write to rowid
3362** tables in this way can avoid this problem by restoring the original
3363** rowid value using [sqlite3_set_last_insert_rowid()] before returning
3364** control to the user.
3365**
3366** ^(If an [INSERT] occurs within a trigger then this routine will
3367** return the [rowid] of the inserted row as long as the trigger is
3368** running. Once the trigger program ends, the value returned
3369** by this routine reverts to what it was before the trigger was fired.)^
3370**
3371** ^An [INSERT] that fails due to a constraint violation is not a
3372** successful [INSERT] and does not change the value returned by this
3373** routine.  ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
3374** and INSERT OR ABORT make no changes to the return value of this
3375** routine when their insertion fails.  ^(When INSERT OR REPLACE
3376** encounters a constraint violation, it does not fail.  The
3377** INSERT continues to completion after deleting rows that caused
3378** the constraint problem so INSERT OR REPLACE will always change
3379** the return value of this interface.)^
3380**
3381** ^For the purposes of this routine, an [INSERT] is considered to
3382** be successful even if it is subsequently rolled back.
3383**
3384** This function is accessible to SQL statements via the
3385** [last_insert_rowid() SQL function].
3386**
3387** If a separate thread performs a new [INSERT] on the same
3388** database connection while the [sqlite3_last_insert_rowid()]
3389** function is running and thus changes the last insert [rowid],
3390** then the value returned by [sqlite3_last_insert_rowid()] is
3391** unpredictable and might not equal either the old or the new
3392** last insert [rowid].
3393*/
3394SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
3395
3396/*
3397** CAPI3REF: Set the Last Insert Rowid value.
3398** METHOD: sqlite3
3399**
3400** The sqlite3_set_last_insert_rowid(D, R) method allows the application to
3401** set the value returned by calling sqlite3_last_insert_rowid(D) to R
3402** without inserting a row into the database.
3403*/
3404SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
3405
3406/*
3407** CAPI3REF: Count The Number Of Rows Modified
3408** METHOD: sqlite3
3409**
3410** ^This function returns the number of rows modified, inserted or
3411** deleted by the most recently completed INSERT, UPDATE or DELETE
3412** statement on the database connection specified by the only parameter.
3413** ^Executing any other type of SQL statement does not modify the value
3414** returned by this function.
3415**
3416** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
3417** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
3418** [foreign key actions] or [REPLACE] constraint resolution are not counted.
3419**
3420** Changes to a view that are intercepted by
3421** [INSTEAD OF trigger | INSTEAD OF triggers] are not counted. ^The value
3422** returned by sqlite3_changes() immediately after an INSERT, UPDATE or
3423** DELETE statement run on a view is always zero. Only changes made to real
3424** tables are counted.
3425**
3426** Things are more complicated if the sqlite3_changes() function is
3427** executed while a trigger program is running. This may happen if the
3428** program uses the [changes() SQL function], or if some other callback
3429** function invokes sqlite3_changes() directly. Essentially:
3430**
3431** <ul>
3432**   <li> ^(Before entering a trigger program the value returned by
3433**        sqlite3_changes() function is saved. After the trigger program
3434**        has finished, the original value is restored.)^
3435**
3436**   <li> ^(Within a trigger program each INSERT, UPDATE and DELETE
3437**        statement sets the value returned by sqlite3_changes()
3438**        upon completion as normal. Of course, this value will not include
3439**        any changes performed by sub-triggers, as the sqlite3_changes()
3440**        value will be saved and restored after each sub-trigger has run.)^
3441** </ul>
3442**
3443** ^This means that if the changes() SQL function (or similar) is used
3444** by the first INSERT, UPDATE or DELETE statement within a trigger, it
3445** returns the value as set when the calling statement began executing.
3446** ^If it is used by the second or subsequent such statement within a trigger
3447** program, the value returned reflects the number of rows modified by the
3448** previous INSERT, UPDATE or DELETE statement within the same trigger.
3449**
3450** If a separate thread makes changes on the same database connection
3451** while [sqlite3_changes()] is running then the value returned
3452** is unpredictable and not meaningful.
3453**
3454** See also:
3455** <ul>
3456** <li> the [sqlite3_total_changes()] interface
3457** <li> the [count_changes pragma]
3458** <li> the [changes() SQL function]
3459** <li> the [data_version pragma]
3460** </ul>
3461*/
3462SQLITE_API int sqlite3_changes(sqlite3*);
3463
3464/*
3465** CAPI3REF: Total Number Of Rows Modified
3466** METHOD: sqlite3
3467**
3468** ^This function returns the total number of rows inserted, modified or
3469** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed
3470** since the database connection was opened, including those executed as
3471** part of trigger programs. ^Executing any other type of SQL statement
3472** does not affect the value returned by sqlite3_total_changes().
3473**
3474** ^Changes made as part of [foreign key actions] are included in the
3475** count, but those made as part of REPLACE constraint resolution are
3476** not. ^Changes to a view that are intercepted by INSTEAD OF triggers
3477** are not counted.
3478**
3479** The [sqlite3_total_changes(D)] interface only reports the number
3480** of rows that changed due to SQL statement run against database
3481** connection D.  Any changes by other database connections are ignored.
3482** To detect changes against a database file from other database
3483** connections use the [PRAGMA data_version] command or the
3484** [SQLITE_FCNTL_DATA_VERSION] [file control].
3485**
3486** If a separate thread makes changes on the same database connection
3487** while [sqlite3_total_changes()] is running then the value
3488** returned is unpredictable and not meaningful.
3489**
3490** See also:
3491** <ul>
3492** <li> the [sqlite3_changes()] interface
3493** <li> the [count_changes pragma]
3494** <li> the [changes() SQL function]
3495** <li> the [data_version pragma]
3496** <li> the [SQLITE_FCNTL_DATA_VERSION] [file control]
3497** </ul>
3498*/
3499SQLITE_API int sqlite3_total_changes(sqlite3*);
3500
3501/*
3502** CAPI3REF: Interrupt A Long-Running Query
3503** METHOD: sqlite3
3504**
3505** ^This function causes any pending database operation to abort and
3506** return at its earliest opportunity. This routine is typically
3507** called in response to a user action such as pressing "Cancel"
3508** or Ctrl-C where the user wants a long query operation to halt
3509** immediately.
3510**
3511** ^It is safe to call this routine from a thread different from the
3512** thread that is currently running the database operation.  But it
3513** is not safe to call this routine with a [database connection] that
3514** is closed or might close before sqlite3_interrupt() returns.
3515**
3516** ^If an SQL operation is very nearly finished at the time when
3517** sqlite3_interrupt() is called, then it might not have an opportunity
3518** to be interrupted and might continue to completion.
3519**
3520** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
3521** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
3522** that is inside an explicit transaction, then the entire transaction
3523** will be rolled back automatically.
3524**
3525** ^The sqlite3_interrupt(D) call is in effect until all currently running
3526** SQL statements on [database connection] D complete.  ^Any new SQL statements
3527** that are started after the sqlite3_interrupt() call and before the
3528** running statements reaches zero are interrupted as if they had been
3529** running prior to the sqlite3_interrupt() call.  ^New SQL statements
3530** that are started after the running statement count reaches zero are
3531** not effected by the sqlite3_interrupt().
3532** ^A call to sqlite3_interrupt(D) that occurs when there are no running
3533** SQL statements is a no-op and has no effect on SQL statements
3534** that are started after the sqlite3_interrupt() call returns.
3535*/
3536SQLITE_API void sqlite3_interrupt(sqlite3*);
3537
3538/*
3539** CAPI3REF: Determine If An SQL Statement Is Complete
3540**
3541** These routines are useful during command-line input to determine if the
3542** currently entered text seems to form a complete SQL statement or
3543** if additional input is needed before sending the text into
3544** SQLite for parsing.  ^These routines return 1 if the input string
3545** appears to be a complete SQL statement.  ^A statement is judged to be
3546** complete if it ends with a semicolon token and is not a prefix of a
3547** well-formed CREATE TRIGGER statement.  ^Semicolons that are embedded within
3548** string literals or quoted identifier names or comments are not
3549** independent tokens (they are part of the token in which they are
3550** embedded) and thus do not count as a statement terminator.  ^Whitespace
3551** and comments that follow the final semicolon are ignored.
3552**
3553** ^These routines return 0 if the statement is incomplete.  ^If a
3554** memory allocation fails, then SQLITE_NOMEM is returned.
3555**
3556** ^These routines do not parse the SQL statements thus
3557** will not detect syntactically incorrect SQL.
3558**
3559** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior
3560** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
3561** automatically by sqlite3_complete16().  If that initialization fails,
3562** then the return value from sqlite3_complete16() will be non-zero
3563** regardless of whether or not the input SQL is complete.)^
3564**
3565** The input to [sqlite3_complete()] must be a zero-terminated
3566** UTF-8 string.
3567**
3568** The input to [sqlite3_complete16()] must be a zero-terminated
3569** UTF-16 string in native byte order.
3570*/
3571SQLITE_API int sqlite3_complete(const char *sql);
3572SQLITE_API int sqlite3_complete16(const void *sql);
3573
3574/*
3575** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
3576** KEYWORDS: {busy-handler callback} {busy handler}
3577** METHOD: sqlite3
3578**
3579** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
3580** that might be invoked with argument P whenever
3581** an attempt is made to access a database table associated with
3582** [database connection] D when another thread
3583** or process has the table locked.
3584** The sqlite3_busy_handler() interface is used to implement
3585** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
3586**
3587** ^If the busy callback is NULL, then [SQLITE_BUSY]
3588** is returned immediately upon encountering the lock.  ^If the busy callback
3589** is not NULL, then the callback might be invoked with two arguments.
3590**
3591** ^The first argument to the busy handler is a copy of the void* pointer which
3592** is the third argument to sqlite3_busy_handler().  ^The second argument to
3593** the busy handler callback is the number of times that the busy handler has
3594** been invoked previously for the same locking event.  ^If the
3595** busy callback returns 0, then no additional attempts are made to
3596** access the database and [SQLITE_BUSY] is returned
3597** to the application.
3598** ^If the callback returns non-zero, then another attempt
3599** is made to access the database and the cycle repeats.
3600**
3601** The presence of a busy handler does not guarantee that it will be invoked
3602** when there is lock contention. ^If SQLite determines that invoking the busy
3603** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
3604** to the application instead of invoking the
3605** busy handler.
3606** Consider a scenario where one process is holding a read lock that
3607** it is trying to promote to a reserved lock and
3608** a second process is holding a reserved lock that it is trying
3609** to promote to an exclusive lock.  The first process cannot proceed
3610** because it is blocked by the second and the second process cannot
3611** proceed because it is blocked by the first.  If both processes
3612** invoke the busy handlers, neither will make any progress.  Therefore,
3613** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
3614** will induce the first process to release its read lock and allow
3615** the second process to proceed.
3616**
3617** ^The default busy callback is NULL.
3618**
3619** ^(There can only be a single busy handler defined for each
3620** [database connection].  Setting a new busy handler clears any
3621** previously set handler.)^  ^Note that calling [sqlite3_busy_timeout()]
3622** or evaluating [PRAGMA busy_timeout=N] will change the
3623** busy handler and thus clear any previously set busy handler.
3624**
3625** The busy callback should not take any actions which modify the
3626** database connection that invoked the busy handler.  In other words,
3627** the busy handler is not reentrant.  Any such actions
3628** result in undefined behavior.
3629**
3630** A busy handler must not close the database connection
3631** or [prepared statement] that invoked the busy handler.
3632*/
3633SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);
3634
3635/*
3636** CAPI3REF: Set A Busy Timeout
3637** METHOD: sqlite3
3638**
3639** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
3640** for a specified amount of time when a table is locked.  ^The handler
3641** will sleep multiple times until at least "ms" milliseconds of sleeping
3642** have accumulated.  ^After at least "ms" milliseconds of sleeping,
3643** the handler returns 0 which causes [sqlite3_step()] to return
3644** [SQLITE_BUSY].
3645**
3646** ^Calling this routine with an argument less than or equal to zero
3647** turns off all busy handlers.
3648**
3649** ^(There can only be a single busy handler for a particular
3650** [database connection] at any given moment.  If another busy handler
3651** was defined  (using [sqlite3_busy_handler()]) prior to calling
3652** this routine, that other busy handler is cleared.)^
3653**
3654** See also:  [PRAGMA busy_timeout]
3655*/
3656SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
3657
3658/*
3659** CAPI3REF: Convenience Routines For Running Queries
3660** METHOD: sqlite3
3661**
3662** This is a legacy interface that is preserved for backwards compatibility.
3663** Use of this interface is not recommended.
3664**
3665** Definition: A <b>result table</b> is memory data structure created by the
3666** [sqlite3_get_table()] interface.  A result table records the
3667** complete query results from one or more queries.
3668**
3669** The table conceptually has a number of rows and columns.  But
3670** these numbers are not part of the result table itself.  These
3671** numbers are obtained separately.  Let N be the number of rows
3672** and M be the number of columns.
3673**
3674** A result table is an array of pointers to zero-terminated UTF-8 strings.
3675** There are (N+1)*M elements in the array.  The first M pointers point
3676** to zero-terminated strings that  contain the names of the columns.
3677** The remaining entries all point to query results.  NULL values result
3678** in NULL pointers.  All other values are in their UTF-8 zero-terminated
3679** string representation as returned by [sqlite3_column_text()].
3680**
3681** A result table might consist of one or more memory allocations.
3682** It is not safe to pass a result table directly to [sqlite3_free()].
3683** A result table should be deallocated using [sqlite3_free_table()].
3684**
3685** ^(As an example of the result table format, suppose a query result
3686** is as follows:
3687**
3688** <blockquote><pre>
3689**        Name        | Age
3690**        -----------------------
3691**        Alice       | 43
3692**        Bob         | 28
3693**        Cindy       | 21
3694** </pre></blockquote>
3695**
3696** There are two column (M==2) and three rows (N==3).  Thus the
3697** result table has 8 entries.  Suppose the result table is stored
3698** in an array names azResult.  Then azResult holds this content:
3699**
3700** <blockquote><pre>
3701**        azResult&#91;0] = "Name";
3702**        azResult&#91;1] = "Age";
3703**        azResult&#91;2] = "Alice";
3704**        azResult&#91;3] = "43";
3705**        azResult&#91;4] = "Bob";
3706**        azResult&#91;5] = "28";
3707**        azResult&#91;6] = "Cindy";
3708**        azResult&#91;7] = "21";
3709** </pre></blockquote>)^
3710**
3711** ^The sqlite3_get_table() function evaluates one or more
3712** semicolon-separated SQL statements in the zero-terminated UTF-8
3713** string of its 2nd parameter and returns a result table to the
3714** pointer given in its 3rd parameter.
3715**
3716** After the application has finished with the result from sqlite3_get_table(),
3717** it must pass the result table pointer to sqlite3_free_table() in order to
3718** release the memory that was malloced.  Because of the way the
3719** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
3720** function must not try to call [sqlite3_free()] directly.  Only
3721** [sqlite3_free_table()] is able to release the memory properly and safely.
3722**
3723** The sqlite3_get_table() interface is implemented as a wrapper around
3724** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access
3725** to any internal data structures of SQLite.  It uses only the public
3726** interface defined here.  As a consequence, errors that occur in the
3727** wrapper layer outside of the internal [sqlite3_exec()] call are not
3728** reflected in subsequent calls to [sqlite3_errcode()] or
3729** [sqlite3_errmsg()].
3730*/
3731SQLITE_API int sqlite3_get_table(
3732  sqlite3 *db,          /* An open database */
3733  const char *zSql,     /* SQL to be evaluated */
3734  char ***pazResult,    /* Results of the query */
3735  int *pnRow,           /* Number of result rows written here */
3736  int *pnColumn,        /* Number of result columns written here */
3737  char **pzErrmsg       /* Error msg written here */
3738);
3739SQLITE_API void sqlite3_free_table(char **result);
3740
3741/*
3742** CAPI3REF: Formatted String Printing Functions
3743**
3744** These routines are work-alikes of the "printf()" family of functions
3745** from the standard C library.
3746** These routines understand most of the common formatting options from
3747** the standard library printf()
3748** plus some additional non-standard formats ([%q], [%Q], [%w], and [%z]).
3749** See the [built-in printf()] documentation for details.
3750**
3751** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
3752** results into memory obtained from [sqlite3_malloc64()].
3753** The strings returned by these two routines should be
3754** released by [sqlite3_free()].  ^Both routines return a
3755** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough
3756** memory to hold the resulting string.
3757**
3758** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
3759** the standard C library.  The result is written into the
3760** buffer supplied as the second parameter whose size is given by
3761** the first parameter. Note that the order of the
3762** first two parameters is reversed from snprintf().)^  This is an
3763** historical accident that cannot be fixed without breaking
3764** backwards compatibility.  ^(Note also that sqlite3_snprintf()
3765** returns a pointer to its buffer instead of the number of
3766** characters actually written into the buffer.)^  We admit that
3767** the number of characters written would be a more useful return
3768** value but we cannot change the implementation of sqlite3_snprintf()
3769** now without breaking compatibility.
3770**
3771** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
3772** guarantees that the buffer is always zero-terminated.  ^The first
3773** parameter "n" is the total size of the buffer, including space for
3774** the zero terminator.  So the longest string that can be completely
3775** written will be n-1 characters.
3776**
3777** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
3778**
3779** See also:  [built-in printf()], [printf() SQL function]
3780*/
3781SQLITE_API char *sqlite3_mprintf(const char*,...);
3782SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
3783SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
3784SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
3785
3786/*
3787** CAPI3REF: Memory Allocation Subsystem
3788**
3789** The SQLite core uses these three routines for all of its own
3790** internal memory allocation needs. "Core" in the previous sentence
3791** does not include operating-system specific VFS implementation.  The
3792** Windows VFS uses native malloc() and free() for some operations.
3793**
3794** ^The sqlite3_malloc() routine returns a pointer to a block
3795** of memory at least N bytes in length, where N is the parameter.
3796** ^If sqlite3_malloc() is unable to obtain sufficient free
3797** memory, it returns a NULL pointer.  ^If the parameter N to
3798** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
3799** a NULL pointer.
3800**
3801** ^The sqlite3_malloc64(N) routine works just like
3802** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
3803** of a signed 32-bit integer.
3804**
3805** ^Calling sqlite3_free() with a pointer previously returned
3806** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
3807** that it might be reused.  ^The sqlite3_free() routine is
3808** a no-op if is called with a NULL pointer.  Passing a NULL pointer
3809** to sqlite3_free() is harmless.  After being freed, memory
3810** should neither be read nor written.  Even reading previously freed
3811** memory might result in a segmentation fault or other severe error.
3812** Memory corruption, a segmentation fault, or other severe error
3813** might result if sqlite3_free() is called with a non-NULL pointer that
3814** was not obtained from sqlite3_malloc() or sqlite3_realloc().
3815**
3816** ^The sqlite3_realloc(X,N) interface attempts to resize a
3817** prior memory allocation X to be at least N bytes.
3818** ^If the X parameter to sqlite3_realloc(X,N)
3819** is a NULL pointer then its behavior is identical to calling
3820** sqlite3_malloc(N).
3821** ^If the N parameter to sqlite3_realloc(X,N) is zero or
3822** negative then the behavior is exactly the same as calling
3823** sqlite3_free(X).
3824** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
3825** of at least N bytes in size or NULL if insufficient memory is available.
3826** ^If M is the size of the prior allocation, then min(N,M) bytes
3827** of the prior allocation are copied into the beginning of buffer returned
3828** by sqlite3_realloc(X,N) and the prior allocation is freed.
3829** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
3830** prior allocation is not freed.
3831**
3832** ^The sqlite3_realloc64(X,N) interfaces works the same as
3833** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
3834** of a 32-bit signed integer.
3835**
3836** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
3837** sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
3838** sqlite3_msize(X) returns the size of that memory allocation in bytes.
3839** ^The value returned by sqlite3_msize(X) might be larger than the number
3840** of bytes requested when X was allocated.  ^If X is a NULL pointer then
3841** sqlite3_msize(X) returns zero.  If X points to something that is not
3842** the beginning of memory allocation, or if it points to a formerly
3843** valid memory allocation that has now been freed, then the behavior
3844** of sqlite3_msize(X) is undefined and possibly harmful.
3845**
3846** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(),
3847** sqlite3_malloc64(), and sqlite3_realloc64()
3848** is always aligned to at least an 8 byte boundary, or to a
3849** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
3850** option is used.
3851**
3852** In SQLite version 3.5.0 and 3.5.1, it was possible to define
3853** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
3854** implementation of these routines to be omitted.  That capability
3855** is no longer provided.  Only built-in memory allocators can be used.
3856**
3857** Prior to SQLite version 3.7.10, the Windows OS interface layer called
3858** the system malloc() and free() directly when converting
3859** filenames between the UTF-8 encoding used by SQLite
3860** and whatever filename encoding is used by the particular Windows
3861** installation.  Memory allocation errors were detected, but
3862** they were reported back as [SQLITE_CANTOPEN] or
3863** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
3864**
3865** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
3866** must be either NULL or else pointers obtained from a prior
3867** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
3868** not yet been released.
3869**
3870** The application must not read or write any part of
3871** a block of memory after it has been released using
3872** [sqlite3_free()] or [sqlite3_realloc()].
3873*/
3874SQLITE_API void *sqlite3_malloc(int);
3875SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);
3876SQLITE_API void *sqlite3_realloc(void*, int);
3877SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64);
3878SQLITE_API void sqlite3_free(void*);
3879SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
3880
3881/*
3882** CAPI3REF: Memory Allocator Statistics
3883**
3884** SQLite provides these two interfaces for reporting on the status
3885** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
3886** routines, which form the built-in memory allocation subsystem.
3887**
3888** ^The [sqlite3_memory_used()] routine returns the number of bytes
3889** of memory currently outstanding (malloced but not freed).
3890** ^The [sqlite3_memory_highwater()] routine returns the maximum
3891** value of [sqlite3_memory_used()] since the high-water mark
3892** was last reset.  ^The values returned by [sqlite3_memory_used()] and
3893** [sqlite3_memory_highwater()] include any overhead
3894** added by SQLite in its implementation of [sqlite3_malloc()],
3895** but not overhead added by the any underlying system library
3896** routines that [sqlite3_malloc()] may call.
3897**
3898** ^The memory high-water mark is reset to the current value of
3899** [sqlite3_memory_used()] if and only if the parameter to
3900** [sqlite3_memory_highwater()] is true.  ^The value returned
3901** by [sqlite3_memory_highwater(1)] is the high-water mark
3902** prior to the reset.
3903*/
3904SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
3905SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
3906
3907/*
3908** CAPI3REF: Pseudo-Random Number Generator
3909**
3910** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
3911** select random [ROWID | ROWIDs] when inserting new records into a table that
3912** already uses the largest possible [ROWID].  The PRNG is also used for
3913** the build-in random() and randomblob() SQL functions.  This interface allows
3914** applications to access the same PRNG for other purposes.
3915**
3916** ^A call to this routine stores N bytes of randomness into buffer P.
3917** ^The P parameter can be a NULL pointer.
3918**
3919** ^If this routine has not been previously called or if the previous
3920** call had N less than one or a NULL pointer for P, then the PRNG is
3921** seeded using randomness obtained from the xRandomness method of
3922** the default [sqlite3_vfs] object.
3923** ^If the previous call to this routine had an N of 1 or more and a
3924** non-NULL P then the pseudo-randomness is generated
3925** internally and without recourse to the [sqlite3_vfs] xRandomness
3926** method.
3927*/
3928SQLITE_API void sqlite3_randomness(int N, void *P);
3929
3930/*
3931** CAPI3REF: Compile-Time Authorization Callbacks
3932** METHOD: sqlite3
3933** KEYWORDS: {authorizer callback}
3934**
3935** ^This routine registers an authorizer callback with a particular
3936** [database connection], supplied in the first argument.
3937** ^The authorizer callback is invoked as SQL statements are being compiled
3938** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
3939** [sqlite3_prepare_v3()], [sqlite3_prepare16()], [sqlite3_prepare16_v2()],
3940** and [sqlite3_prepare16_v3()].  ^At various
3941** points during the compilation process, as logic is being created
3942** to perform various actions, the authorizer callback is invoked to
3943** see if those actions are allowed.  ^The authorizer callback should
3944** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
3945** specific action but allow the SQL statement to continue to be
3946** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
3947** rejected with an error.  ^If the authorizer callback returns
3948** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
3949** then the [sqlite3_prepare_v2()] or equivalent call that triggered
3950** the authorizer will fail with an error message.
3951**
3952** When the callback returns [SQLITE_OK], that means the operation
3953** requested is ok.  ^When the callback returns [SQLITE_DENY], the
3954** [sqlite3_prepare_v2()] or equivalent call that triggered the
3955** authorizer will fail with an error message explaining that
3956** access is denied.
3957**
3958** ^The first parameter to the authorizer callback is a copy of the third
3959** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
3960** to the callback is an integer [SQLITE_COPY | action code] that specifies
3961** the particular action to be authorized. ^The third through sixth parameters
3962** to the callback are either NULL pointers or zero-terminated strings
3963** that contain additional details about the action to be authorized.
3964** Applications must always be prepared to encounter a NULL pointer in any
3965** of the third through the sixth parameters of the authorization callback.
3966**
3967** ^If the action code is [SQLITE_READ]
3968** and the callback returns [SQLITE_IGNORE] then the
3969** [prepared statement] statement is constructed to substitute
3970** a NULL value in place of the table column that would have
3971** been read if [SQLITE_OK] had been returned.  The [SQLITE_IGNORE]
3972** return can be used to deny an untrusted user access to individual
3973** columns of a table.
3974** ^When a table is referenced by a [SELECT] but no column values are
3975** extracted from that table (for example in a query like
3976** "SELECT count(*) FROM tab") then the [SQLITE_READ] authorizer callback
3977** is invoked once for that table with a column name that is an empty string.
3978** ^If the action code is [SQLITE_DELETE] and the callback returns
3979** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
3980** [truncate optimization] is disabled and all rows are deleted individually.
3981**
3982** An authorizer is used when [sqlite3_prepare | preparing]
3983** SQL statements from an untrusted source, to ensure that the SQL statements
3984** do not try to access data they are not allowed to see, or that they do not
3985** try to execute malicious statements that damage the database.  For
3986** example, an application may allow a user to enter arbitrary
3987** SQL queries for evaluation by a database.  But the application does
3988** not want the user to be able to make arbitrary changes to the
3989** database.  An authorizer could then be put in place while the
3990** user-entered SQL is being [sqlite3_prepare | prepared] that
3991** disallows everything except [SELECT] statements.
3992**
3993** Applications that need to process SQL from untrusted sources
3994** might also consider lowering resource limits using [sqlite3_limit()]
3995** and limiting database size using the [max_page_count] [PRAGMA]
3996** in addition to using an authorizer.
3997**
3998** ^(Only a single authorizer can be in place on a database connection
3999** at a time.  Each call to sqlite3_set_authorizer overrides the
4000** previous call.)^  ^Disable the authorizer by installing a NULL callback.
4001** The authorizer is disabled by default.
4002**
4003** The authorizer callback must not do anything that will modify
4004** the database connection that invoked the authorizer callback.
4005** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
4006** database connections for the meaning of "modify" in this paragraph.
4007**
4008** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
4009** statement might be re-prepared during [sqlite3_step()] due to a
4010** schema change.  Hence, the application should ensure that the
4011** correct authorizer callback remains in place during the [sqlite3_step()].
4012**
4013** ^Note that the authorizer callback is invoked only during
4014** [sqlite3_prepare()] or its variants.  Authorization is not
4015** performed during statement evaluation in [sqlite3_step()], unless
4016** as stated in the previous paragraph, sqlite3_step() invokes
4017** sqlite3_prepare_v2() to reprepare a statement after a schema change.
4018*/
4019SQLITE_API int sqlite3_set_authorizer(
4020  sqlite3*,
4021  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
4022  void *pUserData
4023);
4024
4025/*
4026** CAPI3REF: Authorizer Return Codes
4027**
4028** The [sqlite3_set_authorizer | authorizer callback function] must
4029** return either [SQLITE_OK] or one of these two constants in order
4030** to signal SQLite whether or not the action is permitted.  See the
4031** [sqlite3_set_authorizer | authorizer documentation] for additional
4032** information.
4033**
4034** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
4035** returned from the [sqlite3_vtab_on_conflict()] interface.
4036*/
4037#define SQLITE_DENY   1   /* Abort the SQL statement with an error */
4038#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
4039
4040/*
4041** CAPI3REF: Authorizer Action Codes
4042**
4043** The [sqlite3_set_authorizer()] interface registers a callback function
4044** that is invoked to authorize certain SQL statement actions.  The
4045** second parameter to the callback is an integer code that specifies
4046** what action is being authorized.  These are the integer action codes that
4047** the authorizer callback may be passed.
4048**
4049** These action code values signify what kind of operation is to be
4050** authorized.  The 3rd and 4th parameters to the authorization
4051** callback function will be parameters or NULL depending on which of these
4052** codes is used as the second parameter.  ^(The 5th parameter to the
4053** authorizer callback is the name of the database ("main", "temp",
4054** etc.) if applicable.)^  ^The 6th parameter to the authorizer callback
4055** is the name of the inner-most trigger or view that is responsible for
4056** the access attempt or NULL if this access attempt is directly from
4057** top-level SQL code.
4058*/
4059/******************************************* 3rd ************ 4th ***********/
4060#define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
4061#define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
4062#define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
4063#define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
4064#define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
4065#define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
4066#define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
4067#define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
4068#define SQLITE_DELETE                9   /* Table Name      NULL            */
4069#define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
4070#define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
4071#define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
4072#define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
4073#define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
4074#define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
4075#define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
4076#define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
4077#define SQLITE_INSERT               18   /* Table Name      NULL            */
4078#define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
4079#define SQLITE_READ                 20   /* Table Name      Column Name     */
4080#define SQLITE_SELECT               21   /* NULL            NULL            */
4081#define SQLITE_TRANSACTION          22   /* Operation       NULL            */
4082#define SQLITE_UPDATE               23   /* Table Name      Column Name     */
4083#define SQLITE_ATTACH               24   /* Filename        NULL            */
4084#define SQLITE_DETACH               25   /* Database Name   NULL            */
4085#define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
4086#define SQLITE_REINDEX              27   /* Index Name      NULL            */
4087#define SQLITE_ANALYZE              28   /* Table Name      NULL            */
4088#define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
4089#define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
4090#define SQLITE_FUNCTION             31   /* NULL            Function Name   */
4091#define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
4092#define SQLITE_COPY                  0   /* No longer used */
4093#define SQLITE_RECURSIVE            33   /* NULL            NULL            */
4094
4095/*
4096** CAPI3REF: Tracing And Profiling Functions
4097** METHOD: sqlite3
4098**
4099** These routines are deprecated. Use the [sqlite3_trace_v2()] interface
4100** instead of the routines described here.
4101**
4102** These routines register callback functions that can be used for
4103** tracing and profiling the execution of SQL statements.
4104**
4105** ^The callback function registered by sqlite3_trace() is invoked at
4106** various times when an SQL statement is being run by [sqlite3_step()].
4107** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
4108** SQL statement text as the statement first begins executing.
4109** ^(Additional sqlite3_trace() callbacks might occur
4110** as each triggered subprogram is entered.  The callbacks for triggers
4111** contain a UTF-8 SQL comment that identifies the trigger.)^
4112**
4113** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
4114** the length of [bound parameter] expansion in the output of sqlite3_trace().
4115**
4116** ^The callback function registered by sqlite3_profile() is invoked
4117** as each SQL statement finishes.  ^The profile callback contains
4118** the original statement text and an estimate of wall-clock time
4119** of how long that statement took to run.  ^The profile callback
4120** time is in units of nanoseconds, however the current implementation
4121** is only capable of millisecond resolution so the six least significant
4122** digits in the time are meaningless.  Future versions of SQLite
4123** might provide greater resolution on the profiler callback.  Invoking
4124** either [sqlite3_trace()] or [sqlite3_trace_v2()] will cancel the
4125** profile callback.
4126*/
4127SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*,
4128   void(*xTrace)(void*,const char*), void*);
4129SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
4130   void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
4131
4132/*
4133** CAPI3REF: SQL Trace Event Codes
4134** KEYWORDS: SQLITE_TRACE
4135**
4136** These constants identify classes of events that can be monitored
4137** using the [sqlite3_trace_v2()] tracing logic.  The M argument
4138** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
4139** the following constants.  ^The first argument to the trace callback
4140** is one of the following constants.
4141**
4142** New tracing constants may be added in future releases.
4143**
4144** ^A trace callback has four arguments: xCallback(T,C,P,X).
4145** ^The T argument is one of the integer type codes above.
4146** ^The C argument is a copy of the context pointer passed in as the
4147** fourth argument to [sqlite3_trace_v2()].
4148** The P and X arguments are pointers whose meanings depend on T.
4149**
4150** <dl>
4151** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt>
4152** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
4153** first begins running and possibly at other times during the
4154** execution of the prepared statement, such as at the start of each
4155** trigger subprogram. ^The P argument is a pointer to the
4156** [prepared statement]. ^The X argument is a pointer to a string which
4157** is the unexpanded SQL text of the prepared statement or an SQL comment
4158** that indicates the invocation of a trigger.  ^The callback can compute
4159** the same text that would have been returned by the legacy [sqlite3_trace()]
4160** interface by using the X argument when X begins with "--" and invoking
4161** [sqlite3_expanded_sql(P)] otherwise.
4162**
4163** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
4164** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
4165** information as is provided by the [sqlite3_profile()] callback.
4166** ^The P argument is a pointer to the [prepared statement] and the
4167** X argument points to a 64-bit integer which is the estimated of
4168** the number of nanosecond that the prepared statement took to run.
4169** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
4170**
4171** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
4172** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
4173** statement generates a single row of result.
4174** ^The P argument is a pointer to the [prepared statement] and the
4175** X argument is unused.
4176**
4177** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt>
4178** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
4179** connection closes.
4180** ^The P argument is a pointer to the [database connection] object
4181** and the X argument is unused.
4182** </dl>
4183*/
4184#define SQLITE_TRACE_STMT       0x01
4185#define SQLITE_TRACE_PROFILE    0x02
4186#define SQLITE_TRACE_ROW        0x04
4187#define SQLITE_TRACE_CLOSE      0x08
4188
4189/*
4190** CAPI3REF: SQL Trace Hook
4191** METHOD: sqlite3
4192**
4193** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
4194** function X against [database connection] D, using property mask M
4195** and context pointer P.  ^If the X callback is
4196** NULL or if the M mask is zero, then tracing is disabled.  The
4197** M argument should be the bitwise OR-ed combination of
4198** zero or more [SQLITE_TRACE] constants.
4199**
4200** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides
4201** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
4202**
4203** ^The X callback is invoked whenever any of the events identified by
4204** mask M occur.  ^The integer return value from the callback is currently
4205** ignored, though this may change in future releases.  Callback
4206** implementations should return zero to ensure future compatibility.
4207**
4208** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
4209** ^The T argument is one of the [SQLITE_TRACE]
4210** constants to indicate why the callback was invoked.
4211** ^The C argument is a copy of the context pointer.
4212** The P and X arguments are pointers whose meanings depend on T.
4213**
4214** The sqlite3_trace_v2() interface is intended to replace the legacy
4215** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which
4216** are deprecated.
4217*/
4218SQLITE_API int sqlite3_trace_v2(
4219  sqlite3*,
4220  unsigned uMask,
4221  int(*xCallback)(unsigned,void*,void*,void*),
4222  void *pCtx
4223);
4224
4225/*
4226** CAPI3REF: Query Progress Callbacks
4227** METHOD: sqlite3
4228**
4229** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
4230** function X to be invoked periodically during long running calls to
4231** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
4232** database connection D.  An example use for this
4233** interface is to keep a GUI updated during a large query.
4234**
4235** ^The parameter P is passed through as the only parameter to the
4236** callback function X.  ^The parameter N is the approximate number of
4237** [virtual machine instructions] that are evaluated between successive
4238** invocations of the callback X.  ^If N is less than one then the progress
4239** handler is disabled.
4240**
4241** ^Only a single progress handler may be defined at one time per
4242** [database connection]; setting a new progress handler cancels the
4243** old one.  ^Setting parameter X to NULL disables the progress handler.
4244** ^The progress handler is also disabled by setting N to a value less
4245** than 1.
4246**
4247** ^If the progress callback returns non-zero, the operation is
4248** interrupted.  This feature can be used to implement a
4249** "Cancel" button on a GUI progress dialog box.
4250**
4251** The progress handler callback must not do anything that will modify
4252** the database connection that invoked the progress handler.
4253** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
4254** database connections for the meaning of "modify" in this paragraph.
4255**
4256*/
4257SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
4258
4259/*
4260** CAPI3REF: Opening A New Database Connection
4261** CONSTRUCTOR: sqlite3
4262**
4263** ^These routines open an SQLite database file as specified by the
4264** filename argument. ^The filename argument is interpreted as UTF-8 for
4265** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
4266** order for sqlite3_open16(). ^(A [database connection] handle is usually
4267** returned in *ppDb, even if an error occurs.  The only exception is that
4268** if SQLite is unable to allocate memory to hold the [sqlite3] object,
4269** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
4270** object.)^ ^(If the database is opened (and/or created) successfully, then
4271** [SQLITE_OK] is returned.  Otherwise an [error code] is returned.)^ ^The
4272** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
4273** an English language description of the error following a failure of any
4274** of the sqlite3_open() routines.
4275**
4276** ^The default encoding will be UTF-8 for databases created using
4277** sqlite3_open() or sqlite3_open_v2().  ^The default encoding for databases
4278** created using sqlite3_open16() will be UTF-16 in the native byte order.
4279**
4280** Whether or not an error occurs when it is opened, resources
4281** associated with the [database connection] handle should be released by
4282** passing it to [sqlite3_close()] when it is no longer required.
4283**
4284** The sqlite3_open_v2() interface works like sqlite3_open()
4285** except that it accepts two additional parameters for additional control
4286** over the new database connection.  ^(The flags parameter to
4287** sqlite3_open_v2() can take one of
4288** the following three values, optionally combined with the
4289** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
4290** [SQLITE_OPEN_PRIVATECACHE], and/or [SQLITE_OPEN_URI] flags:)^
4291**
4292** <dl>
4293** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
4294** <dd>The database is opened in read-only mode.  If the database does not
4295** already exist, an error is returned.</dd>)^
4296**
4297** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
4298** <dd>The database is opened for reading and writing if possible, or reading
4299** only if the file is write protected by the operating system.  In either
4300** case the database must already exist, otherwise an error is returned.</dd>)^
4301**
4302** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
4303** <dd>The database is opened for reading and writing, and is created if
4304** it does not already exist. This is the behavior that is always used for
4305** sqlite3_open() and sqlite3_open16().</dd>)^
4306** </dl>
4307**
4308** If the 3rd parameter to sqlite3_open_v2() is not one of the
4309** combinations shown above optionally combined with other
4310** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
4311** then the behavior is undefined.
4312**
4313** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
4314** opens in the multi-thread [threading mode] as long as the single-thread
4315** mode has not been set at compile-time or start-time.  ^If the
4316** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
4317** in the serialized [threading mode] unless single-thread was
4318** previously selected at compile-time or start-time.
4319** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
4320** eligible to use [shared cache mode], regardless of whether or not shared
4321** cache is enabled using [sqlite3_enable_shared_cache()].  ^The
4322** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
4323** participate in [shared cache mode] even if it is enabled.
4324**
4325** ^The fourth parameter to sqlite3_open_v2() is the name of the
4326** [sqlite3_vfs] object that defines the operating system interface that
4327** the new database connection should use.  ^If the fourth parameter is
4328** a NULL pointer then the default [sqlite3_vfs] object is used.
4329**
4330** ^If the filename is ":memory:", then a private, temporary in-memory database
4331** is created for the connection.  ^This in-memory database will vanish when
4332** the database connection is closed.  Future versions of SQLite might
4333** make use of additional special filenames that begin with the ":" character.
4334** It is recommended that when a database filename actually does begin with
4335** a ":" character you should prefix the filename with a pathname such as
4336** "./" to avoid ambiguity.
4337**
4338** ^If the filename is an empty string, then a private, temporary
4339** on-disk database will be created.  ^This private database will be
4340** automatically deleted as soon as the database connection is closed.
4341**
4342** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
4343**
4344** ^If [URI filename] interpretation is enabled, and the filename argument
4345** begins with "file:", then the filename is interpreted as a URI. ^URI
4346** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
4347** set in the third argument to sqlite3_open_v2(), or if it has
4348** been enabled globally using the [SQLITE_CONFIG_URI] option with the
4349** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
4350** URI filename interpretation is turned off
4351** by default, but future releases of SQLite might enable URI filename
4352** interpretation by default.  See "[URI filenames]" for additional
4353** information.
4354**
4355** URI filenames are parsed according to RFC 3986. ^If the URI contains an
4356** authority, then it must be either an empty string or the string
4357** "localhost". ^If the authority is not an empty string or "localhost", an
4358** error is returned to the caller. ^The fragment component of a URI, if
4359** present, is ignored.
4360**
4361** ^SQLite uses the path component of the URI as the name of the disk file
4362** which contains the database. ^If the path begins with a '/' character,
4363** then it is interpreted as an absolute path. ^If the path does not begin
4364** with a '/' (meaning that the authority section is omitted from the URI)
4365** then the path is interpreted as a relative path.
4366** ^(On windows, the first component of an absolute path
4367** is a drive specification (e.g. "C:").)^
4368**
4369** [[core URI query parameters]]
4370** The query component of a URI may contain parameters that are interpreted
4371** either by SQLite itself, or by a [VFS | custom VFS implementation].
4372** SQLite and its built-in [VFSes] interpret the
4373** following query parameters:
4374**
4375** <ul>
4376**   <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
4377**     a VFS object that provides the operating system interface that should
4378**     be used to access the database file on disk. ^If this option is set to
4379**     an empty string the default VFS object is used. ^Specifying an unknown
4380**     VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
4381**     present, then the VFS specified by the option takes precedence over
4382**     the value passed as the fourth parameter to sqlite3_open_v2().
4383**
4384**   <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
4385**     "rwc", or "memory". Attempting to set it to any other value is
4386**     an error)^.
4387**     ^If "ro" is specified, then the database is opened for read-only
4388**     access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the
4389**     third argument to sqlite3_open_v2(). ^If the mode option is set to
4390**     "rw", then the database is opened for read-write (but not create)
4391**     access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
4392**     been set. ^Value "rwc" is equivalent to setting both
4393**     SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE.  ^If the mode option is
4394**     set to "memory" then a pure [in-memory database] that never reads
4395**     or writes from disk is used. ^It is an error to specify a value for
4396**     the mode parameter that is less restrictive than that specified by
4397**     the flags passed in the third parameter to sqlite3_open_v2().
4398**
4399**   <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
4400**     "private". ^Setting it to "shared" is equivalent to setting the
4401**     SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
4402**     sqlite3_open_v2(). ^Setting the cache parameter to "private" is
4403**     equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
4404**     ^If sqlite3_open_v2() is used and the "cache" parameter is present in
4405**     a URI filename, its value overrides any behavior requested by setting
4406**     SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
4407**
4408**  <li> <b>psow</b>: ^The psow parameter indicates whether or not the
4409**     [powersafe overwrite] property does or does not apply to the
4410**     storage media on which the database file resides.
4411**
4412**  <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
4413**     which if set disables file locking in rollback journal modes.  This
4414**     is useful for accessing a database on a filesystem that does not
4415**     support locking.  Caution:  Database corruption might result if two
4416**     or more processes write to the same database and any one of those
4417**     processes uses nolock=1.
4418**
4419**  <li> <b>immutable</b>: ^The immutable parameter is a boolean query
4420**     parameter that indicates that the database file is stored on
4421**     read-only media.  ^When immutable is set, SQLite assumes that the
4422**     database file cannot be changed, even by a process with higher
4423**     privilege, and so the database is opened read-only and all locking
4424**     and change detection is disabled.  Caution: Setting the immutable
4425**     property on a database file that does in fact change can result
4426**     in incorrect query results and/or [SQLITE_CORRUPT] errors.
4427**     See also: [SQLITE_IOCAP_IMMUTABLE].
4428**
4429** </ul>
4430**
4431** ^Specifying an unknown parameter in the query component of a URI is not an
4432** error.  Future versions of SQLite might understand additional query
4433** parameters.  See "[query parameters with special meaning to SQLite]" for
4434** additional information.
4435**
4436** [[URI filename examples]] <h3>URI filename examples</h3>
4437**
4438** <table border="1" align=center cellpadding=5>
4439** <tr><th> URI filenames <th> Results
4440** <tr><td> file:data.db <td>
4441**          Open the file "data.db" in the current directory.
4442** <tr><td> file:/home/fred/data.db<br>
4443**          file:///home/fred/data.db <br>
4444**          file://localhost/home/fred/data.db <br> <td>
4445**          Open the database file "/home/fred/data.db".
4446** <tr><td> file://darkstar/home/fred/data.db <td>
4447**          An error. "darkstar" is not a recognized authority.
4448** <tr><td style="white-space:nowrap">
4449**          file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
4450**     <td> Windows only: Open the file "data.db" on fred's desktop on drive
4451**          C:. Note that the %20 escaping in this example is not strictly
4452**          necessary - space characters can be used literally
4453**          in URI filenames.
4454** <tr><td> file:data.db?mode=ro&cache=private <td>
4455**          Open file "data.db" in the current directory for read-only access.
4456**          Regardless of whether or not shared-cache mode is enabled by
4457**          default, use a private cache.
4458** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
4459**          Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
4460**          that uses dot-files in place of posix advisory locking.
4461** <tr><td> file:data.db?mode=readonly <td>
4462**          An error. "readonly" is not a valid option for the "mode" parameter.
4463** </table>
4464**
4465** ^URI hexadecimal escape sequences (%HH) are supported within the path and
4466** query components of a URI. A hexadecimal escape sequence consists of a
4467** percent sign - "%" - followed by exactly two hexadecimal digits
4468** specifying an octet value. ^Before the path or query components of a
4469** URI filename are interpreted, they are encoded using UTF-8 and all
4470** hexadecimal escape sequences replaced by a single byte containing the
4471** corresponding octet. If this process generates an invalid UTF-8 encoding,
4472** the results are undefined.
4473**
4474** <b>Note to Windows users:</b>  The encoding used for the filename argument
4475** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
4476** codepage is currently defined.  Filenames containing international
4477** characters must be converted to UTF-8 prior to passing them into
4478** sqlite3_open() or sqlite3_open_v2().
4479**
4480** <b>Note to Windows Runtime users:</b>  The temporary directory must be set
4481** prior to calling sqlite3_open() or sqlite3_open_v2().  Otherwise, various
4482** features that require the use of temporary files may fail.
4483**
4484** See also: [sqlite3_temp_directory]
4485*/
4486SQLITE_API int sqlite3_open(
4487  const char *filename,   /* Database filename (UTF-8) */
4488  sqlite3 **ppDb          /* OUT: SQLite db handle */
4489);
4490SQLITE_API int sqlite3_open16(
4491  const void *filename,   /* Database filename (UTF-16) */
4492  sqlite3 **ppDb          /* OUT: SQLite db handle */
4493);
4494SQLITE_API int sqlite3_open_v2(
4495  const char *filename,   /* Database filename (UTF-8) */
4496  sqlite3 **ppDb,         /* OUT: SQLite db handle */
4497  int flags,              /* Flags */
4498  const char *zVfs        /* Name of VFS module to use */
4499);
4500
4501/*
4502** CAPI3REF: Obtain Values For URI Parameters
4503**
4504** These are utility routines, useful to VFS implementations, that check
4505** to see if a database file was a URI that contained a specific query
4506** parameter, and if so obtains the value of that query parameter.
4507**
4508** If F is the database filename pointer passed into the xOpen() method of
4509** a VFS implementation when the flags parameter to xOpen() has one or
4510** more of the [SQLITE_OPEN_URI] or [SQLITE_OPEN_MAIN_DB] bits set and
4511** P is the name of the query parameter, then
4512** sqlite3_uri_parameter(F,P) returns the value of the P
4513** parameter if it exists or a NULL pointer if P does not appear as a
4514** query parameter on F.  If P is a query parameter of F
4515** has no explicit value, then sqlite3_uri_parameter(F,P) returns
4516** a pointer to an empty string.
4517**
4518** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
4519** parameter and returns true (1) or false (0) according to the value
4520** of P.  The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
4521** value of query parameter P is one of "yes", "true", or "on" in any
4522** case or if the value begins with a non-zero number.  The
4523** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
4524** query parameter P is one of "no", "false", or "off" in any case or
4525** if the value begins with a numeric zero.  If P is not a query
4526** parameter on F or if the value of P is does not match any of the
4527** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).
4528**
4529** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
4530** 64-bit signed integer and returns that integer, or D if P does not
4531** exist.  If the value of P is something other than an integer, then
4532** zero is returned.
4533**
4534** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
4535** sqlite3_uri_boolean(F,P,B) returns B.  If F is not a NULL pointer and
4536** is not a database file pathname pointer that SQLite passed into the xOpen
4537** VFS method, then the behavior of this routine is undefined and probably
4538** undesirable.
4539**
4540** See the [URI filename] documentation for additional information.
4541*/
4542SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
4543SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
4544SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
4545
4546
4547/*
4548** CAPI3REF: Error Codes And Messages
4549** METHOD: sqlite3
4550**
4551** ^If the most recent sqlite3_* API call associated with
4552** [database connection] D failed, then the sqlite3_errcode(D) interface
4553** returns the numeric [result code] or [extended result code] for that
4554** API call.
4555** ^The sqlite3_extended_errcode()
4556** interface is the same except that it always returns the
4557** [extended result code] even when extended result codes are
4558** disabled.
4559**
4560** The values returned by sqlite3_errcode() and/or
4561** sqlite3_extended_errcode() might change with each API call.
4562** Except, there are some interfaces that are guaranteed to never
4563** change the value of the error code.  The error-code preserving
4564** interfaces are:
4565**
4566** <ul>
4567** <li> sqlite3_errcode()
4568** <li> sqlite3_extended_errcode()
4569** <li> sqlite3_errmsg()
4570** <li> sqlite3_errmsg16()
4571** </ul>
4572**
4573** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
4574** text that describes the error, as either UTF-8 or UTF-16 respectively.
4575** ^(Memory to hold the error message string is managed internally.
4576** The application does not need to worry about freeing the result.
4577** However, the error string might be overwritten or deallocated by
4578** subsequent calls to other SQLite interface functions.)^
4579**
4580** ^The sqlite3_errstr() interface returns the English-language text
4581** that describes the [result code], as UTF-8.
4582** ^(Memory to hold the error message string is managed internally
4583** and must not be freed by the application)^.
4584**
4585** When the serialized [threading mode] is in use, it might be the
4586** case that a second error occurs on a separate thread in between
4587** the time of the first error and the call to these interfaces.
4588** When that happens, the second error will be reported since these
4589** interfaces always report the most recent result.  To avoid
4590** this, each thread can obtain exclusive use of the [database connection] D
4591** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
4592** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
4593** all calls to the interfaces listed here are completed.
4594**
4595** If an interface fails with SQLITE_MISUSE, that means the interface
4596** was invoked incorrectly by the application.  In that case, the
4597** error code and message may or may not be set.
4598*/
4599SQLITE_API int sqlite3_errcode(sqlite3 *db);
4600SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
4601SQLITE_API const char *sqlite3_errmsg(sqlite3*);
4602SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
4603SQLITE_API const char *sqlite3_errstr(int);
4604
4605/*
4606** CAPI3REF: Prepared Statement Object
4607** KEYWORDS: {prepared statement} {prepared statements}
4608**
4609** An instance of this object represents a single SQL statement that
4610** has been compiled into binary form and is ready to be evaluated.
4611**
4612** Think of each SQL statement as a separate computer program.  The
4613** original SQL text is source code.  A prepared statement object
4614** is the compiled object code.  All SQL must be converted into a
4615** prepared statement before it can be run.
4616**
4617** The life-cycle of a prepared statement object usually goes like this:
4618**
4619** <ol>
4620** <li> Create the prepared statement object using [sqlite3_prepare_v2()].
4621** <li> Bind values to [parameters] using the sqlite3_bind_*()
4622**      interfaces.
4623** <li> Run the SQL by calling [sqlite3_step()] one or more times.
4624** <li> Reset the prepared statement using [sqlite3_reset()] then go back
4625**      to step 2.  Do this zero or more times.
4626** <li> Destroy the object using [sqlite3_finalize()].
4627** </ol>
4628*/
4629typedef struct sqlite3_stmt sqlite3_stmt;
4630
4631/*
4632** CAPI3REF: Run-time Limits
4633** METHOD: sqlite3
4634**
4635** ^(This interface allows the size of various constructs to be limited
4636** on a connection by connection basis.  The first parameter is the
4637** [database connection] whose limit is to be set or queried.  The
4638** second parameter is one of the [limit categories] that define a
4639** class of constructs to be size limited.  The third parameter is the
4640** new limit for that construct.)^
4641**
4642** ^If the new limit is a negative number, the limit is unchanged.
4643** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
4644** [limits | hard upper bound]
4645** set at compile-time by a C preprocessor macro called
4646** [limits | SQLITE_MAX_<i>NAME</i>].
4647** (The "_LIMIT_" in the name is changed to "_MAX_".))^
4648** ^Attempts to increase a limit above its hard upper bound are
4649** silently truncated to the hard upper bound.
4650**
4651** ^Regardless of whether or not the limit was changed, the
4652** [sqlite3_limit()] interface returns the prior value of the limit.
4653** ^Hence, to find the current value of a limit without changing it,
4654** simply invoke this interface with the third parameter set to -1.
4655**
4656** Run-time limits are intended for use in applications that manage
4657** both their own internal database and also databases that are controlled
4658** by untrusted external sources.  An example application might be a
4659** web browser that has its own databases for storing history and
4660** separate databases controlled by JavaScript applications downloaded
4661** off the Internet.  The internal databases can be given the
4662** large, default limits.  Databases managed by external sources can
4663** be given much smaller limits designed to prevent a denial of service
4664** attack.  Developers might also want to use the [sqlite3_set_authorizer()]
4665** interface to further control untrusted SQL.  The size of the database
4666** created by an untrusted script can be contained using the
4667** [max_page_count] [PRAGMA].
4668**
4669** New run-time limit categories may be added in future releases.
4670*/
4671SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
4672
4673/*
4674** CAPI3REF: Run-Time Limit Categories
4675** KEYWORDS: {limit category} {*limit categories}
4676**
4677** These constants define various performance limits
4678** that can be lowered at run-time using [sqlite3_limit()].
4679** The synopsis of the meanings of the various limits is shown below.
4680** Additional information is available at [limits | Limits in SQLite].
4681**
4682** <dl>
4683** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
4684** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
4685**
4686** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
4687** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
4688**
4689** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
4690** <dd>The maximum number of columns in a table definition or in the
4691** result set of a [SELECT] or the maximum number of columns in an index
4692** or in an ORDER BY or GROUP BY clause.</dd>)^
4693**
4694** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
4695** <dd>The maximum depth of the parse tree on any expression.</dd>)^
4696**
4697** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
4698** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
4699**
4700** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
4701** <dd>The maximum number of instructions in a virtual machine program
4702** used to implement an SQL statement.  If [sqlite3_prepare_v2()] or
4703** the equivalent tries to allocate space for more than this many opcodes
4704** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^
4705**
4706** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
4707** <dd>The maximum number of arguments on a function.</dd>)^
4708**
4709** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
4710** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
4711**
4712** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
4713** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
4714** <dd>The maximum length of the pattern argument to the [LIKE] or
4715** [GLOB] operators.</dd>)^
4716**
4717** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
4718** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
4719** <dd>The maximum index number of any [parameter] in an SQL statement.)^
4720**
4721** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
4722** <dd>The maximum depth of recursion for triggers.</dd>)^
4723**
4724** [[SQLITE_LIMIT_WORKER_THREADS]] ^(<dt>SQLITE_LIMIT_WORKER_THREADS</dt>
4725** <dd>The maximum number of auxiliary worker threads that a single
4726** [prepared statement] may start.</dd>)^
4727** </dl>
4728*/
4729#define SQLITE_LIMIT_LENGTH                    0
4730#define SQLITE_LIMIT_SQL_LENGTH                1
4731#define SQLITE_LIMIT_COLUMN                    2
4732#define SQLITE_LIMIT_EXPR_DEPTH                3
4733#define SQLITE_LIMIT_COMPOUND_SELECT           4
4734#define SQLITE_LIMIT_VDBE_OP                   5
4735#define SQLITE_LIMIT_FUNCTION_ARG              6
4736#define SQLITE_LIMIT_ATTACHED                  7
4737#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
4738#define SQLITE_LIMIT_VARIABLE_NUMBER           9
4739#define SQLITE_LIMIT_TRIGGER_DEPTH            10
4740#define SQLITE_LIMIT_WORKER_THREADS           11
4741
4742/*
4743** CAPI3REF: Prepare Flags
4744**
4745** These constants define various flags that can be passed into
4746** "prepFlags" parameter of the [sqlite3_prepare_v3()] and
4747** [sqlite3_prepare16_v3()] interfaces.
4748**
4749** New flags may be added in future releases of SQLite.
4750**
4751** <dl>
4752** [[SQLITE_PREPARE_PERSISTENT]] ^(<dt>SQLITE_PREPARE_PERSISTENT</dt>
4753** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
4754** that the prepared statement will be retained for a long time and
4755** probably reused many times.)^ ^Without this flag, [sqlite3_prepare_v3()]
4756** and [sqlite3_prepare16_v3()] assume that the prepared statement will
4757** be used just once or at most a few times and then destroyed using
4758** [sqlite3_finalize()] relatively soon. The current implementation acts
4759** on this hint by avoiding the use of [lookaside memory] so as not to
4760** deplete the limited store of lookaside memory. Future versions of
4761** SQLite may act on this hint differently.
4762**
4763** [[SQLITE_PREPARE_NORMALIZE]] <dt>SQLITE_PREPARE_NORMALIZE</dt>
4764** <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used
4765** to be required for any prepared statement that wanted to use the
4766** [sqlite3_normalized_sql()] interface.  However, the
4767** [sqlite3_normalized_sql()] interface is now available to all
4768** prepared statements, regardless of whether or not they use this
4769** flag.
4770**
4771** [[SQLITE_PREPARE_NO_VTAB]] <dt>SQLITE_PREPARE_NO_VTAB</dt>
4772** <dd>The SQLITE_PREPARE_NO_VTAB flag causes the SQL compiler
4773** to return an error (error code SQLITE_ERROR) if the statement uses
4774** any virtual tables.
4775** </dl>
4776*/
4777#define SQLITE_PREPARE_PERSISTENT              0x01
4778#define SQLITE_PREPARE_NORMALIZE               0x02
4779#define SQLITE_PREPARE_NO_VTAB                 0x04
4780
4781/*
4782** CAPI3REF: Compiling An SQL Statement
4783** KEYWORDS: {SQL statement compiler}
4784** METHOD: sqlite3
4785** CONSTRUCTOR: sqlite3_stmt
4786**
4787** To execute an SQL statement, it must first be compiled into a byte-code
4788** program using one of these routines.  Or, in other words, these routines
4789** are constructors for the [prepared statement] object.
4790**
4791** The preferred routine to use is [sqlite3_prepare_v2()].  The
4792** [sqlite3_prepare()] interface is legacy and should be avoided.
4793** [sqlite3_prepare_v3()] has an extra "prepFlags" option that is used
4794** for special purposes.
4795**
4796** The use of the UTF-8 interfaces is preferred, as SQLite currently
4797** does all parsing using UTF-8.  The UTF-16 interfaces are provided
4798** as a convenience.  The UTF-16 interfaces work by converting the
4799** input text into UTF-8, then invoking the corresponding UTF-8 interface.
4800**
4801** The first argument, "db", is a [database connection] obtained from a
4802** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
4803** [sqlite3_open16()].  The database connection must not have been closed.
4804**
4805** The second argument, "zSql", is the statement to be compiled, encoded
4806** as either UTF-8 or UTF-16.  The sqlite3_prepare(), sqlite3_prepare_v2(),
4807** and sqlite3_prepare_v3()
4808** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
4809** and sqlite3_prepare16_v3() use UTF-16.
4810**
4811** ^If the nByte argument is negative, then zSql is read up to the
4812** first zero terminator. ^If nByte is positive, then it is the
4813** number of bytes read from zSql.  ^If nByte is zero, then no prepared
4814** statement is generated.
4815** If the caller knows that the supplied string is nul-terminated, then
4816** there is a small performance advantage to passing an nByte parameter that
4817** is the number of bytes in the input string <i>including</i>
4818** the nul-terminator.
4819**
4820** ^If pzTail is not NULL then *pzTail is made to point to the first byte
4821** past the end of the first SQL statement in zSql.  These routines only
4822** compile the first statement in zSql, so *pzTail is left pointing to
4823** what remains uncompiled.
4824**
4825** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
4826** executed using [sqlite3_step()].  ^If there is an error, *ppStmt is set
4827** to NULL.  ^If the input text contains no SQL (if the input is an empty
4828** string or a comment) then *ppStmt is set to NULL.
4829** The calling procedure is responsible for deleting the compiled
4830** SQL statement using [sqlite3_finalize()] after it has finished with it.
4831** ppStmt may not be NULL.
4832**
4833** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
4834** otherwise an [error code] is returned.
4835**
4836** The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),
4837** and sqlite3_prepare16_v3() interfaces are recommended for all new programs.
4838** The older interfaces (sqlite3_prepare() and sqlite3_prepare16())
4839** are retained for backwards compatibility, but their use is discouraged.
4840** ^In the "vX" interfaces, the prepared statement
4841** that is returned (the [sqlite3_stmt] object) contains a copy of the
4842** original SQL text. This causes the [sqlite3_step()] interface to
4843** behave differently in three ways:
4844**
4845** <ol>
4846** <li>
4847** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
4848** always used to do, [sqlite3_step()] will automatically recompile the SQL
4849** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
4850** retries will occur before sqlite3_step() gives up and returns an error.
4851** </li>
4852**
4853** <li>
4854** ^When an error occurs, [sqlite3_step()] will return one of the detailed
4855** [error codes] or [extended error codes].  ^The legacy behavior was that
4856** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
4857** and the application would have to make a second call to [sqlite3_reset()]
4858** in order to find the underlying cause of the problem. With the "v2" prepare
4859** interfaces, the underlying reason for the error is returned immediately.
4860** </li>
4861**
4862** <li>
4863** ^If the specific value bound to [parameter | host parameter] in the
4864** WHERE clause might influence the choice of query plan for a statement,
4865** then the statement will be automatically recompiled, as if there had been
4866** a schema change, on the first  [sqlite3_step()] call following any change
4867** to the [sqlite3_bind_text | bindings] of that [parameter].
4868** ^The specific value of WHERE-clause [parameter] might influence the
4869** choice of query plan if the parameter is the left-hand side of a [LIKE]
4870** or [GLOB] operator or if the parameter is compared to an indexed column
4871** and the [SQLITE_ENABLE_STAT4] compile-time option is enabled.
4872** </li>
4873** </ol>
4874**
4875** <p>^sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having
4876** the extra prepFlags parameter, which is a bit array consisting of zero or
4877** more of the [SQLITE_PREPARE_PERSISTENT|SQLITE_PREPARE_*] flags.  ^The
4878** sqlite3_prepare_v2() interface works exactly the same as
4879** sqlite3_prepare_v3() with a zero prepFlags parameter.
4880*/
4881SQLITE_API int sqlite3_prepare(
4882  sqlite3 *db,            /* Database handle */
4883  const char *zSql,       /* SQL statement, UTF-8 encoded */
4884  int nByte,              /* Maximum length of zSql in bytes. */
4885  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
4886  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
4887);
4888SQLITE_API int sqlite3_prepare_v2(
4889  sqlite3 *db,            /* Database handle */
4890  const char *zSql,       /* SQL statement, UTF-8 encoded */
4891  int nByte,              /* Maximum length of zSql in bytes. */
4892  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
4893  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
4894);
4895SQLITE_API int sqlite3_prepare_v3(
4896  sqlite3 *db,            /* Database handle */
4897  const char *zSql,       /* SQL statement, UTF-8 encoded */
4898  int nByte,              /* Maximum length of zSql in bytes. */
4899  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
4900  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
4901  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
4902);
4903SQLITE_API int sqlite3_prepare16(
4904  sqlite3 *db,            /* Database handle */
4905  const void *zSql,       /* SQL statement, UTF-16 encoded */
4906  int nByte,              /* Maximum length of zSql in bytes. */
4907  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
4908  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
4909);
4910SQLITE_API int sqlite3_prepare16_v2(
4911  sqlite3 *db,            /* Database handle */
4912  const void *zSql,       /* SQL statement, UTF-16 encoded */
4913  int nByte,              /* Maximum length of zSql in bytes. */
4914  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
4915  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
4916);
4917SQLITE_API int sqlite3_prepare16_v3(
4918  sqlite3 *db,            /* Database handle */
4919  const void *zSql,       /* SQL statement, UTF-16 encoded */
4920  int nByte,              /* Maximum length of zSql in bytes. */
4921  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
4922  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
4923  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
4924);
4925
4926/*
4927** CAPI3REF: Retrieving Statement SQL
4928** METHOD: sqlite3_stmt
4929**
4930** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
4931** SQL text used to create [prepared statement] P if P was
4932** created by [sqlite3_prepare_v2()], [sqlite3_prepare_v3()],
4933** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
4934** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
4935** string containing the SQL text of prepared statement P with
4936** [bound parameters] expanded.
4937** ^The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8
4938** string containing the normalized SQL text of prepared statement P.  The
4939** semantics used to normalize a SQL statement are unspecified and subject
4940** to change.  At a minimum, literal values will be replaced with suitable
4941** placeholders.
4942**
4943** ^(For example, if a prepared statement is created using the SQL
4944** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
4945** and parameter :xyz is unbound, then sqlite3_sql() will return
4946** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()
4947** will return "SELECT 2345,NULL".)^
4948**
4949** ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory
4950** is available to hold the result, or if the result would exceed the
4951** the maximum string length determined by the [SQLITE_LIMIT_LENGTH].
4952**
4953** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of
4954** bound parameter expansions.  ^The [SQLITE_OMIT_TRACE] compile-time
4955** option causes sqlite3_expanded_sql() to always return NULL.
4956**
4957** ^The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P)
4958** are managed by SQLite and are automatically freed when the prepared
4959** statement is finalized.
4960** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
4961** is obtained from [sqlite3_malloc()] and must be free by the application
4962** by passing it to [sqlite3_free()].
4963*/
4964SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
4965SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
4966SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
4967
4968/*
4969** CAPI3REF: Determine If An SQL Statement Writes The Database
4970** METHOD: sqlite3_stmt
4971**
4972** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
4973** and only if the [prepared statement] X makes no direct changes to
4974** the content of the database file.
4975**
4976** Note that [application-defined SQL functions] or
4977** [virtual tables] might change the database indirectly as a side effect.
4978** ^(For example, if an application defines a function "eval()" that
4979** calls [sqlite3_exec()], then the following SQL statement would
4980** change the database file through side-effects:
4981**
4982** <blockquote><pre>
4983**    SELECT eval('DELETE FROM t1') FROM t2;
4984** </pre></blockquote>
4985**
4986** But because the [SELECT] statement does not change the database file
4987** directly, sqlite3_stmt_readonly() would still return true.)^
4988**
4989** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
4990** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
4991** since the statements themselves do not actually modify the database but
4992** rather they control the timing of when other statements modify the
4993** database.  ^The [ATTACH] and [DETACH] statements also cause
4994** sqlite3_stmt_readonly() to return true since, while those statements
4995** change the configuration of a database connection, they do not make
4996** changes to the content of the database files on disk.
4997** ^The sqlite3_stmt_readonly() interface returns true for [BEGIN] since
4998** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and
4999** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so
5000** sqlite3_stmt_readonly() returns false for those commands.
5001*/
5002SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
5003
5004/*
5005** CAPI3REF: Query The EXPLAIN Setting For A Prepared Statement
5006** METHOD: sqlite3_stmt
5007**
5008** ^The sqlite3_stmt_isexplain(S) interface returns 1 if the
5009** prepared statement S is an EXPLAIN statement, or 2 if the
5010** statement S is an EXPLAIN QUERY PLAN.
5011** ^The sqlite3_stmt_isexplain(S) interface returns 0 if S is
5012** an ordinary statement or a NULL pointer.
5013*/
5014SQLITE_API int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt);
5015
5016/*
5017** CAPI3REF: Determine If A Prepared Statement Has Been Reset
5018** METHOD: sqlite3_stmt
5019**
5020** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
5021** [prepared statement] S has been stepped at least once using
5022** [sqlite3_step(S)] but has neither run to completion (returned
5023** [SQLITE_DONE] from [sqlite3_step(S)]) nor
5024** been reset using [sqlite3_reset(S)].  ^The sqlite3_stmt_busy(S)
5025** interface returns false if S is a NULL pointer.  If S is not a
5026** NULL pointer and is not a pointer to a valid [prepared statement]
5027** object, then the behavior is undefined and probably undesirable.
5028**
5029** This interface can be used in combination [sqlite3_next_stmt()]
5030** to locate all prepared statements associated with a database
5031** connection that are in need of being reset.  This can be used,
5032** for example, in diagnostic routines to search for prepared
5033** statements that are holding a transaction open.
5034*/
5035SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
5036
5037/*
5038** CAPI3REF: Dynamically Typed Value Object
5039** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
5040**
5041** SQLite uses the sqlite3_value object to represent all values
5042** that can be stored in a database table. SQLite uses dynamic typing
5043** for the values it stores.  ^Values stored in sqlite3_value objects
5044** can be integers, floating point values, strings, BLOBs, or NULL.
5045**
5046** An sqlite3_value object may be either "protected" or "unprotected".
5047** Some interfaces require a protected sqlite3_value.  Other interfaces
5048** will accept either a protected or an unprotected sqlite3_value.
5049** Every interface that accepts sqlite3_value arguments specifies
5050** whether or not it requires a protected sqlite3_value.  The
5051** [sqlite3_value_dup()] interface can be used to construct a new
5052** protected sqlite3_value from an unprotected sqlite3_value.
5053**
5054** The terms "protected" and "unprotected" refer to whether or not
5055** a mutex is held.  An internal mutex is held for a protected
5056** sqlite3_value object but no mutex is held for an unprotected
5057** sqlite3_value object.  If SQLite is compiled to be single-threaded
5058** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
5059** or if SQLite is run in one of reduced mutex modes
5060** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
5061** then there is no distinction between protected and unprotected
5062** sqlite3_value objects and they can be used interchangeably.  However,
5063** for maximum code portability it is recommended that applications
5064** still make the distinction between protected and unprotected
5065** sqlite3_value objects even when not strictly required.
5066**
5067** ^The sqlite3_value objects that are passed as parameters into the
5068** implementation of [application-defined SQL functions] are protected.
5069** ^The sqlite3_value object returned by
5070** [sqlite3_column_value()] is unprotected.
5071** Unprotected sqlite3_value objects may only be used as arguments
5072** to [sqlite3_result_value()], [sqlite3_bind_value()], and
5073** [sqlite3_value_dup()].
5074** The [sqlite3_value_blob | sqlite3_value_type()] family of
5075** interfaces require protected sqlite3_value objects.
5076*/
5077typedef struct sqlite3_value sqlite3_value;
5078
5079/*
5080** CAPI3REF: SQL Function Context Object
5081**
5082** The context in which an SQL function executes is stored in an
5083** sqlite3_context object.  ^A pointer to an sqlite3_context object
5084** is always first parameter to [application-defined SQL functions].
5085** The application-defined SQL function implementation will pass this
5086** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
5087** [sqlite3_aggregate_context()], [sqlite3_user_data()],
5088** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
5089** and/or [sqlite3_set_auxdata()].
5090*/
5091typedef struct sqlite3_context sqlite3_context;
5092
5093/*
5094** CAPI3REF: Binding Values To Prepared Statements
5095** KEYWORDS: {host parameter} {host parameters} {host parameter name}
5096** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
5097** METHOD: sqlite3_stmt
5098**
5099** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
5100** literals may be replaced by a [parameter] that matches one of following
5101** templates:
5102**
5103** <ul>
5104** <li>  ?
5105** <li>  ?NNN
5106** <li>  :VVV
5107** <li>  @VVV
5108** <li>  $VVV
5109** </ul>
5110**
5111** In the templates above, NNN represents an integer literal,
5112** and VVV represents an alphanumeric identifier.)^  ^The values of these
5113** parameters (also called "host parameter names" or "SQL parameters")
5114** can be set using the sqlite3_bind_*() routines defined here.
5115**
5116** ^The first argument to the sqlite3_bind_*() routines is always
5117** a pointer to the [sqlite3_stmt] object returned from
5118** [sqlite3_prepare_v2()] or its variants.
5119**
5120** ^The second argument is the index of the SQL parameter to be set.
5121** ^The leftmost SQL parameter has an index of 1.  ^When the same named
5122** SQL parameter is used more than once, second and subsequent
5123** occurrences have the same index as the first occurrence.
5124** ^The index for named parameters can be looked up using the
5125** [sqlite3_bind_parameter_index()] API if desired.  ^The index
5126** for "?NNN" parameters is the value of NNN.
5127** ^The NNN value must be between 1 and the [sqlite3_limit()]
5128** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
5129**
5130** ^The third argument is the value to bind to the parameter.
5131** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
5132** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
5133** is ignored and the end result is the same as sqlite3_bind_null().
5134**
5135** ^(In those routines that have a fourth argument, its value is the
5136** number of bytes in the parameter.  To be clear: the value is the
5137** number of <u>bytes</u> in the value, not the number of characters.)^
5138** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
5139** is negative, then the length of the string is
5140** the number of bytes up to the first zero terminator.
5141** If the fourth parameter to sqlite3_bind_blob() is negative, then
5142** the behavior is undefined.
5143** If a non-negative fourth parameter is provided to sqlite3_bind_text()
5144** or sqlite3_bind_text16() or sqlite3_bind_text64() then
5145** that parameter must be the byte offset
5146** where the NUL terminator would occur assuming the string were NUL
5147** terminated.  If any NUL characters occur at byte offsets less than
5148** the value of the fourth parameter then the resulting string value will
5149** contain embedded NULs.  The result of expressions involving strings
5150** with embedded NULs is undefined.
5151**
5152** ^The fifth argument to the BLOB and string binding interfaces
5153** is a destructor used to dispose of the BLOB or
5154** string after SQLite has finished with it.  ^The destructor is called
5155** to dispose of the BLOB or string even if the call to the bind API fails,
5156** except the destructor is not called if the third parameter is a NULL
5157** pointer or the fourth parameter is negative.
5158** ^If the fifth argument is
5159** the special value [SQLITE_STATIC], then SQLite assumes that the
5160** information is in static, unmanaged space and does not need to be freed.
5161** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
5162** SQLite makes its own private copy of the data immediately, before
5163** the sqlite3_bind_*() routine returns.
5164**
5165** ^The sixth argument to sqlite3_bind_text64() must be one of
5166** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]
5167** to specify the encoding of the text in the third parameter.  If
5168** the sixth argument to sqlite3_bind_text64() is not one of the
5169** allowed values shown above, or if the text encoding is different
5170** from the encoding specified by the sixth parameter, then the behavior
5171** is undefined.
5172**
5173** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
5174** is filled with zeroes.  ^A zeroblob uses a fixed amount of memory
5175** (just an integer to hold its size) while it is being processed.
5176** Zeroblobs are intended to serve as placeholders for BLOBs whose
5177** content is later written using
5178** [sqlite3_blob_open | incremental BLOB I/O] routines.
5179** ^A negative value for the zeroblob results in a zero-length BLOB.
5180**
5181** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
5182** [prepared statement] S to have an SQL value of NULL, but to also be
5183** associated with the pointer P of type T.  ^D is either a NULL pointer or
5184** a pointer to a destructor function for P. ^SQLite will invoke the
5185** destructor D with a single argument of P when it is finished using
5186** P.  The T parameter should be a static string, preferably a string
5187** literal. The sqlite3_bind_pointer() routine is part of the
5188** [pointer passing interface] added for SQLite 3.20.0.
5189**
5190** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
5191** for the [prepared statement] or with a prepared statement for which
5192** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
5193** then the call will return [SQLITE_MISUSE].  If any sqlite3_bind_()
5194** routine is passed a [prepared statement] that has been finalized, the
5195** result is undefined and probably harmful.
5196**
5197** ^Bindings are not cleared by the [sqlite3_reset()] routine.
5198** ^Unbound parameters are interpreted as NULL.
5199**
5200** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
5201** [error code] if anything goes wrong.
5202** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB
5203** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or
5204** [SQLITE_MAX_LENGTH].
5205** ^[SQLITE_RANGE] is returned if the parameter
5206** index is out of range.  ^[SQLITE_NOMEM] is returned if malloc() fails.
5207**
5208** See also: [sqlite3_bind_parameter_count()],
5209** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
5210*/
5211SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
5212SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
5213                        void(*)(void*));
5214SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
5215SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
5216SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
5217SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
5218SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
5219SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
5220SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
5221                         void(*)(void*), unsigned char encoding);
5222SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
5223SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
5224SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
5225SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
5226
5227/*
5228** CAPI3REF: Number Of SQL Parameters
5229** METHOD: sqlite3_stmt
5230**
5231** ^This routine can be used to find the number of [SQL parameters]
5232** in a [prepared statement].  SQL parameters are tokens of the
5233** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
5234** placeholders for values that are [sqlite3_bind_blob | bound]
5235** to the parameters at a later time.
5236**
5237** ^(This routine actually returns the index of the largest (rightmost)
5238** parameter. For all forms except ?NNN, this will correspond to the
5239** number of unique parameters.  If parameters of the ?NNN form are used,
5240** there may be gaps in the list.)^
5241**
5242** See also: [sqlite3_bind_blob|sqlite3_bind()],
5243** [sqlite3_bind_parameter_name()], and
5244** [sqlite3_bind_parameter_index()].
5245*/
5246SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
5247
5248/*
5249** CAPI3REF: Name Of A Host Parameter
5250** METHOD: sqlite3_stmt
5251**
5252** ^The sqlite3_bind_parameter_name(P,N) interface returns
5253** the name of the N-th [SQL parameter] in the [prepared statement] P.
5254** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
5255** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
5256** respectively.
5257** In other words, the initial ":" or "$" or "@" or "?"
5258** is included as part of the name.)^
5259** ^Parameters of the form "?" without a following integer have no name
5260** and are referred to as "nameless" or "anonymous parameters".
5261**
5262** ^The first host parameter has an index of 1, not 0.
5263**
5264** ^If the value N is out of range or if the N-th parameter is
5265** nameless, then NULL is returned.  ^The returned string is
5266** always in UTF-8 encoding even if the named parameter was
5267** originally specified as UTF-16 in [sqlite3_prepare16()],
5268** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
5269**
5270** See also: [sqlite3_bind_blob|sqlite3_bind()],
5271** [sqlite3_bind_parameter_count()], and
5272** [sqlite3_bind_parameter_index()].
5273*/
5274SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
5275
5276/*
5277** CAPI3REF: Index Of A Parameter With A Given Name
5278** METHOD: sqlite3_stmt
5279**
5280** ^Return the index of an SQL parameter given its name.  ^The
5281** index value returned is suitable for use as the second
5282** parameter to [sqlite3_bind_blob|sqlite3_bind()].  ^A zero
5283** is returned if no matching parameter is found.  ^The parameter
5284** name must be given in UTF-8 even if the original statement
5285** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or
5286** [sqlite3_prepare16_v3()].
5287**
5288** See also: [sqlite3_bind_blob|sqlite3_bind()],
5289** [sqlite3_bind_parameter_count()], and
5290** [sqlite3_bind_parameter_name()].
5291*/
5292SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
5293
5294/*
5295** CAPI3REF: Reset All Bindings On A Prepared Statement
5296** METHOD: sqlite3_stmt
5297**
5298** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
5299** the [sqlite3_bind_blob | bindings] on a [prepared statement].
5300** ^Use this routine to reset all host parameters to NULL.
5301*/
5302SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
5303
5304/*
5305** CAPI3REF: Number Of Columns In A Result Set
5306** METHOD: sqlite3_stmt
5307**
5308** ^Return the number of columns in the result set returned by the
5309** [prepared statement]. ^If this routine returns 0, that means the
5310** [prepared statement] returns no data (for example an [UPDATE]).
5311** ^However, just because this routine returns a positive number does not
5312** mean that one or more rows of data will be returned.  ^A SELECT statement
5313** will always have a positive sqlite3_column_count() but depending on the
5314** WHERE clause constraints and the table content, it might return no rows.
5315**
5316** See also: [sqlite3_data_count()]
5317*/
5318SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
5319
5320/*
5321** CAPI3REF: Column Names In A Result Set
5322** METHOD: sqlite3_stmt
5323**
5324** ^These routines return the name assigned to a particular column
5325** in the result set of a [SELECT] statement.  ^The sqlite3_column_name()
5326** interface returns a pointer to a zero-terminated UTF-8 string
5327** and sqlite3_column_name16() returns a pointer to a zero-terminated
5328** UTF-16 string.  ^The first parameter is the [prepared statement]
5329** that implements the [SELECT] statement. ^The second parameter is the
5330** column number.  ^The leftmost column is number 0.
5331**
5332** ^The returned string pointer is valid until either the [prepared statement]
5333** is destroyed by [sqlite3_finalize()] or until the statement is automatically
5334** reprepared by the first call to [sqlite3_step()] for a particular run
5335** or until the next call to
5336** sqlite3_column_name() or sqlite3_column_name16() on the same column.
5337**
5338** ^If sqlite3_malloc() fails during the processing of either routine
5339** (for example during a conversion from UTF-8 to UTF-16) then a
5340** NULL pointer is returned.
5341**
5342** ^The name of a result column is the value of the "AS" clause for
5343** that column, if there is an AS clause.  If there is no AS clause
5344** then the name of the column is unspecified and may change from
5345** one release of SQLite to the next.
5346*/
5347SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
5348SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
5349
5350/*
5351** CAPI3REF: Source Of Data In A Query Result
5352** METHOD: sqlite3_stmt
5353**
5354** ^These routines provide a means to determine the database, table, and
5355** table column that is the origin of a particular result column in
5356** [SELECT] statement.
5357** ^The name of the database or table or column can be returned as
5358** either a UTF-8 or UTF-16 string.  ^The _database_ routines return
5359** the database name, the _table_ routines return the table name, and
5360** the origin_ routines return the column name.
5361** ^The returned string is valid until the [prepared statement] is destroyed
5362** using [sqlite3_finalize()] or until the statement is automatically
5363** reprepared by the first call to [sqlite3_step()] for a particular run
5364** or until the same information is requested
5365** again in a different encoding.
5366**
5367** ^The names returned are the original un-aliased names of the
5368** database, table, and column.
5369**
5370** ^The first argument to these interfaces is a [prepared statement].
5371** ^These functions return information about the Nth result column returned by
5372** the statement, where N is the second function argument.
5373** ^The left-most column is column 0 for these routines.
5374**
5375** ^If the Nth column returned by the statement is an expression or
5376** subquery and is not a column value, then all of these functions return
5377** NULL.  ^These routine might also return NULL if a memory allocation error
5378** occurs.  ^Otherwise, they return the name of the attached database, table,
5379** or column that query result column was extracted from.
5380**
5381** ^As with all other SQLite APIs, those whose names end with "16" return
5382** UTF-16 encoded strings and the other functions return UTF-8.
5383**
5384** ^These APIs are only available if the library was compiled with the
5385** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
5386**
5387** If two or more threads call one or more of these routines against the same
5388** prepared statement and column at the same time then the results are
5389** undefined.
5390**
5391** If two or more threads call one or more
5392** [sqlite3_column_database_name | column metadata interfaces]
5393** for the same [prepared statement] and result column
5394** at the same time then the results are undefined.
5395*/
5396SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
5397SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
5398SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
5399SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
5400SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
5401SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
5402
5403/*
5404** CAPI3REF: Declared Datatype Of A Query Result
5405** METHOD: sqlite3_stmt
5406**
5407** ^(The first parameter is a [prepared statement].
5408** If this statement is a [SELECT] statement and the Nth column of the
5409** returned result set of that [SELECT] is a table column (not an
5410** expression or subquery) then the declared type of the table
5411** column is returned.)^  ^If the Nth column of the result set is an
5412** expression or subquery, then a NULL pointer is returned.
5413** ^The returned string is always UTF-8 encoded.
5414**
5415** ^(For example, given the database schema:
5416**
5417** CREATE TABLE t1(c1 VARIANT);
5418**
5419** and the following statement to be compiled:
5420**
5421** SELECT c1 + 1, c1 FROM t1;
5422**
5423** this routine would return the string "VARIANT" for the second result
5424** column (i==1), and a NULL pointer for the first result column (i==0).)^
5425**
5426** ^SQLite uses dynamic run-time typing.  ^So just because a column
5427** is declared to contain a particular type does not mean that the
5428** data stored in that column is of the declared type.  SQLite is
5429** strongly typed, but the typing is dynamic not static.  ^Type
5430** is associated with individual values, not with the containers
5431** used to hold those values.
5432*/
5433SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
5434SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
5435
5436/*
5437** CAPI3REF: Evaluate An SQL Statement
5438** METHOD: sqlite3_stmt
5439**
5440** After a [prepared statement] has been prepared using any of
5441** [sqlite3_prepare_v2()], [sqlite3_prepare_v3()], [sqlite3_prepare16_v2()],
5442** or [sqlite3_prepare16_v3()] or one of the legacy
5443** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
5444** must be called one or more times to evaluate the statement.
5445**
5446** The details of the behavior of the sqlite3_step() interface depend
5447** on whether the statement was prepared using the newer "vX" interfaces
5448** [sqlite3_prepare_v3()], [sqlite3_prepare_v2()], [sqlite3_prepare16_v3()],
5449** [sqlite3_prepare16_v2()] or the older legacy
5450** interfaces [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the
5451** new "vX" interface is recommended for new applications but the legacy
5452** interface will continue to be supported.
5453**
5454** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
5455** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
5456** ^With the "v2" interface, any of the other [result codes] or
5457** [extended result codes] might be returned as well.
5458**
5459** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
5460** database locks it needs to do its job.  ^If the statement is a [COMMIT]
5461** or occurs outside of an explicit transaction, then you can retry the
5462** statement.  If the statement is not a [COMMIT] and occurs within an
5463** explicit transaction then you should rollback the transaction before
5464** continuing.
5465**
5466** ^[SQLITE_DONE] means that the statement has finished executing
5467** successfully.  sqlite3_step() should not be called again on this virtual
5468** machine without first calling [sqlite3_reset()] to reset the virtual
5469** machine back to its initial state.
5470**
5471** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
5472** is returned each time a new row of data is ready for processing by the
5473** caller. The values may be accessed using the [column access functions].
5474** sqlite3_step() is called again to retrieve the next row of data.
5475**
5476** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
5477** violation) has occurred.  sqlite3_step() should not be called again on
5478** the VM. More information may be found by calling [sqlite3_errmsg()].
5479** ^With the legacy interface, a more specific error code (for example,
5480** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
5481** can be obtained by calling [sqlite3_reset()] on the
5482** [prepared statement].  ^In the "v2" interface,
5483** the more specific error code is returned directly by sqlite3_step().
5484**
5485** [SQLITE_MISUSE] means that the this routine was called inappropriately.
5486** Perhaps it was called on a [prepared statement] that has
5487** already been [sqlite3_finalize | finalized] or on one that had
5488** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
5489** be the case that the same database connection is being used by two or
5490** more threads at the same moment in time.
5491**
5492** For all versions of SQLite up to and including 3.6.23.1, a call to
5493** [sqlite3_reset()] was required after sqlite3_step() returned anything
5494** other than [SQLITE_ROW] before any subsequent invocation of
5495** sqlite3_step().  Failure to reset the prepared statement using
5496** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
5497** sqlite3_step().  But after [version 3.6.23.1] ([dateof:3.6.23.1],
5498** sqlite3_step() began
5499** calling [sqlite3_reset()] automatically in this circumstance rather
5500** than returning [SQLITE_MISUSE].  This is not considered a compatibility
5501** break because any application that ever receives an SQLITE_MISUSE error
5502** is broken by definition.  The [SQLITE_OMIT_AUTORESET] compile-time option
5503** can be used to restore the legacy behavior.
5504**
5505** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
5506** API always returns a generic error code, [SQLITE_ERROR], following any
5507** error other than [SQLITE_BUSY] and [SQLITE_MISUSE].  You must call
5508** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
5509** specific [error codes] that better describes the error.
5510** We admit that this is a goofy design.  The problem has been fixed
5511** with the "v2" interface.  If you prepare all of your SQL statements
5512** using [sqlite3_prepare_v3()] or [sqlite3_prepare_v2()]
5513** or [sqlite3_prepare16_v2()] or [sqlite3_prepare16_v3()] instead
5514** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
5515** then the more specific [error codes] are returned directly
5516** by sqlite3_step().  The use of the "vX" interfaces is recommended.
5517*/
5518SQLITE_API int sqlite3_step(sqlite3_stmt*);
5519
5520/*
5521** CAPI3REF: Number of columns in a result set
5522** METHOD: sqlite3_stmt
5523**
5524** ^The sqlite3_data_count(P) interface returns the number of columns in the
5525** current row of the result set of [prepared statement] P.
5526** ^If prepared statement P does not have results ready to return
5527** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of
5528** interfaces) then sqlite3_data_count(P) returns 0.
5529** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
5530** ^The sqlite3_data_count(P) routine returns 0 if the previous call to
5531** [sqlite3_step](P) returned [SQLITE_DONE].  ^The sqlite3_data_count(P)
5532** will return non-zero if previous call to [sqlite3_step](P) returned
5533** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum]
5534** where it always returns zero since each step of that multi-step
5535** pragma returns 0 columns of data.
5536**
5537** See also: [sqlite3_column_count()]
5538*/
5539SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
5540
5541/*
5542** CAPI3REF: Fundamental Datatypes
5543** KEYWORDS: SQLITE_TEXT
5544**
5545** ^(Every value in SQLite has one of five fundamental datatypes:
5546**
5547** <ul>
5548** <li> 64-bit signed integer
5549** <li> 64-bit IEEE floating point number
5550** <li> string
5551** <li> BLOB
5552** <li> NULL
5553** </ul>)^
5554**
5555** These constants are codes for each of those types.
5556**
5557** Note that the SQLITE_TEXT constant was also used in SQLite version 2
5558** for a completely different meaning.  Software that links against both
5559** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
5560** SQLITE_TEXT.
5561*/
5562#define SQLITE_INTEGER  1
5563#define SQLITE_FLOAT    2
5564#define SQLITE_BLOB     4
5565#define SQLITE_NULL     5
5566#ifdef SQLITE_TEXT
5567# undef SQLITE_TEXT
5568#else
5569# define SQLITE_TEXT     3
5570#endif
5571#define SQLITE3_TEXT     3
5572
5573/*
5574** CAPI3REF: Result Values From A Query
5575** KEYWORDS: {column access functions}
5576** METHOD: sqlite3_stmt
5577**
5578** <b>Summary:</b>
5579** <blockquote><table border=0 cellpadding=0 cellspacing=0>
5580** <tr><td><b>sqlite3_column_blob</b><td>&rarr;<td>BLOB result
5581** <tr><td><b>sqlite3_column_double</b><td>&rarr;<td>REAL result
5582** <tr><td><b>sqlite3_column_int</b><td>&rarr;<td>32-bit INTEGER result
5583** <tr><td><b>sqlite3_column_int64</b><td>&rarr;<td>64-bit INTEGER result
5584** <tr><td><b>sqlite3_column_text</b><td>&rarr;<td>UTF-8 TEXT result
5585** <tr><td><b>sqlite3_column_text16</b><td>&rarr;<td>UTF-16 TEXT result
5586** <tr><td><b>sqlite3_column_value</b><td>&rarr;<td>The result as an
5587** [sqlite3_value|unprotected sqlite3_value] object.
5588** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
5589** <tr><td><b>sqlite3_column_bytes</b><td>&rarr;<td>Size of a BLOB
5590** or a UTF-8 TEXT result in bytes
5591** <tr><td><b>sqlite3_column_bytes16&nbsp;&nbsp;</b>
5592** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
5593** TEXT in bytes
5594** <tr><td><b>sqlite3_column_type</b><td>&rarr;<td>Default
5595** datatype of the result
5596** </table></blockquote>
5597**
5598** <b>Details:</b>
5599**
5600** ^These routines return information about a single column of the current
5601** result row of a query.  ^In every case the first argument is a pointer
5602** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
5603** that was returned from [sqlite3_prepare_v2()] or one of its variants)
5604** and the second argument is the index of the column for which information
5605** should be returned. ^The leftmost column of the result set has the index 0.
5606** ^The number of columns in the result can be determined using
5607** [sqlite3_column_count()].
5608**
5609** If the SQL statement does not currently point to a valid row, or if the
5610** column index is out of range, the result is undefined.
5611** These routines may only be called when the most recent call to
5612** [sqlite3_step()] has returned [SQLITE_ROW] and neither
5613** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
5614** If any of these routines are called after [sqlite3_reset()] or
5615** [sqlite3_finalize()] or after [sqlite3_step()] has returned
5616** something other than [SQLITE_ROW], the results are undefined.
5617** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
5618** are called from a different thread while any of these routines
5619** are pending, then the results are undefined.
5620**
5621** The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
5622** each return the value of a result column in a specific data format.  If
5623** the result column is not initially in the requested format (for example,
5624** if the query returns an integer but the sqlite3_column_text() interface
5625** is used to extract the value) then an automatic type conversion is performed.
5626**
5627** ^The sqlite3_column_type() routine returns the
5628** [SQLITE_INTEGER | datatype code] for the initial data type
5629** of the result column.  ^The returned value is one of [SQLITE_INTEGER],
5630** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].
5631** The return value of sqlite3_column_type() can be used to decide which
5632** of the first six interface should be used to extract the column value.
5633** The value returned by sqlite3_column_type() is only meaningful if no
5634** automatic type conversions have occurred for the value in question.
5635** After a type conversion, the result of calling sqlite3_column_type()
5636** is undefined, though harmless.  Future
5637** versions of SQLite may change the behavior of sqlite3_column_type()
5638** following a type conversion.
5639**
5640** If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
5641** or sqlite3_column_bytes16() interfaces can be used to determine the size
5642** of that BLOB or string.
5643**
5644** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
5645** routine returns the number of bytes in that BLOB or string.
5646** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
5647** the string to UTF-8 and then returns the number of bytes.
5648** ^If the result is a numeric value then sqlite3_column_bytes() uses
5649** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
5650** the number of bytes in that string.
5651** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
5652**
5653** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
5654** routine returns the number of bytes in that BLOB or string.
5655** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
5656** the string to UTF-16 and then returns the number of bytes.
5657** ^If the result is a numeric value then sqlite3_column_bytes16() uses
5658** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
5659** the number of bytes in that string.
5660** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
5661**
5662** ^The values returned by [sqlite3_column_bytes()] and
5663** [sqlite3_column_bytes16()] do not include the zero terminators at the end
5664** of the string.  ^For clarity: the values returned by
5665** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
5666** bytes in the string, not the number of characters.
5667**
5668** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
5669** even empty strings, are always zero-terminated.  ^The return
5670** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
5671**
5672** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
5673** [unprotected sqlite3_value] object.  In a multithreaded environment,
5674** an unprotected sqlite3_value object may only be used safely with
5675** [sqlite3_bind_value()] and [sqlite3_result_value()].
5676** If the [unprotected sqlite3_value] object returned by
5677** [sqlite3_column_value()] is used in any other way, including calls
5678** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
5679** or [sqlite3_value_bytes()], the behavior is not threadsafe.
5680** Hence, the sqlite3_column_value() interface
5681** is normally only useful within the implementation of
5682** [application-defined SQL functions] or [virtual tables], not within
5683** top-level application code.
5684**
5685** The these routines may attempt to convert the datatype of the result.
5686** ^For example, if the internal representation is FLOAT and a text result
5687** is requested, [sqlite3_snprintf()] is used internally to perform the
5688** conversion automatically.  ^(The following table details the conversions
5689** that are applied:
5690**
5691** <blockquote>
5692** <table border="1">
5693** <tr><th> Internal<br>Type <th> Requested<br>Type <th>  Conversion
5694**
5695** <tr><td>  NULL    <td> INTEGER   <td> Result is 0
5696** <tr><td>  NULL    <td>  FLOAT    <td> Result is 0.0
5697** <tr><td>  NULL    <td>   TEXT    <td> Result is a NULL pointer
5698** <tr><td>  NULL    <td>   BLOB    <td> Result is a NULL pointer
5699** <tr><td> INTEGER  <td>  FLOAT    <td> Convert from integer to float
5700** <tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering of the integer
5701** <tr><td> INTEGER  <td>   BLOB    <td> Same as INTEGER->TEXT
5702** <tr><td>  FLOAT   <td> INTEGER   <td> [CAST] to INTEGER
5703** <tr><td>  FLOAT   <td>   TEXT    <td> ASCII rendering of the float
5704** <tr><td>  FLOAT   <td>   BLOB    <td> [CAST] to BLOB
5705** <tr><td>  TEXT    <td> INTEGER   <td> [CAST] to INTEGER
5706** <tr><td>  TEXT    <td>  FLOAT    <td> [CAST] to REAL
5707** <tr><td>  TEXT    <td>   BLOB    <td> No change
5708** <tr><td>  BLOB    <td> INTEGER   <td> [CAST] to INTEGER
5709** <tr><td>  BLOB    <td>  FLOAT    <td> [CAST] to REAL
5710** <tr><td>  BLOB    <td>   TEXT    <td> Add a zero terminator if needed
5711** </table>
5712** </blockquote>)^
5713**
5714** Note that when type conversions occur, pointers returned by prior
5715** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
5716** sqlite3_column_text16() may be invalidated.
5717** Type conversions and pointer invalidations might occur
5718** in the following cases:
5719**
5720** <ul>
5721** <li> The initial content is a BLOB and sqlite3_column_text() or
5722**      sqlite3_column_text16() is called.  A zero-terminator might
5723**      need to be added to the string.</li>
5724** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
5725**      sqlite3_column_text16() is called.  The content must be converted
5726**      to UTF-16.</li>
5727** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
5728**      sqlite3_column_text() is called.  The content must be converted
5729**      to UTF-8.</li>
5730** </ul>
5731**
5732** ^Conversions between UTF-16be and UTF-16le are always done in place and do
5733** not invalidate a prior pointer, though of course the content of the buffer
5734** that the prior pointer references will have been modified.  Other kinds
5735** of conversion are done in place when it is possible, but sometimes they
5736** are not possible and in those cases prior pointers are invalidated.
5737**
5738** The safest policy is to invoke these routines
5739** in one of the following ways:
5740**
5741** <ul>
5742**  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
5743**  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
5744**  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
5745** </ul>
5746**
5747** In other words, you should call sqlite3_column_text(),
5748** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
5749** into the desired format, then invoke sqlite3_column_bytes() or
5750** sqlite3_column_bytes16() to find the size of the result.  Do not mix calls
5751** to sqlite3_column_text() or sqlite3_column_blob() with calls to
5752** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
5753** with calls to sqlite3_column_bytes().
5754**
5755** ^The pointers returned are valid until a type conversion occurs as
5756** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
5757** [sqlite3_finalize()] is called.  ^The memory space used to hold strings
5758** and BLOBs is freed automatically.  Do not pass the pointers returned
5759** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
5760** [sqlite3_free()].
5761**
5762** As long as the input parameters are correct, these routines will only
5763** fail if an out-of-memory error occurs during a format conversion.
5764** Only the following subset of interfaces are subject to out-of-memory
5765** errors:
5766**
5767** <ul>
5768** <li> sqlite3_column_blob()
5769** <li> sqlite3_column_text()
5770** <li> sqlite3_column_text16()
5771** <li> sqlite3_column_bytes()
5772** <li> sqlite3_column_bytes16()
5773** </ul>
5774**
5775** If an out-of-memory error occurs, then the return value from these
5776** routines is the same as if the column had contained an SQL NULL value.
5777** Valid SQL NULL returns can be distinguished from out-of-memory errors
5778** by invoking the [sqlite3_errcode()] immediately after the suspect
5779** return value is obtained and before any
5780** other SQLite interface is called on the same [database connection].
5781*/
5782SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
5783SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
5784SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
5785SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
5786SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
5787SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
5788SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
5789SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
5790SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
5791SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
5792
5793/*
5794** CAPI3REF: Destroy A Prepared Statement Object
5795** DESTRUCTOR: sqlite3_stmt
5796**
5797** ^The sqlite3_finalize() function is called to delete a [prepared statement].
5798** ^If the most recent evaluation of the statement encountered no errors
5799** or if the statement is never been evaluated, then sqlite3_finalize() returns
5800** SQLITE_OK.  ^If the most recent evaluation of statement S failed, then
5801** sqlite3_finalize(S) returns the appropriate [error code] or
5802** [extended error code].
5803**
5804** ^The sqlite3_finalize(S) routine can be called at any point during
5805** the life cycle of [prepared statement] S:
5806** before statement S is ever evaluated, after
5807** one or more calls to [sqlite3_reset()], or after any call
5808** to [sqlite3_step()] regardless of whether or not the statement has
5809** completed execution.
5810**
5811** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
5812**
5813** The application must finalize every [prepared statement] in order to avoid
5814** resource leaks.  It is a grievous error for the application to try to use
5815** a prepared statement after it has been finalized.  Any use of a prepared
5816** statement after it has been finalized can result in undefined and
5817** undesirable behavior such as segfaults and heap corruption.
5818*/
5819SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
5820
5821/*
5822** CAPI3REF: Reset A Prepared Statement Object
5823** METHOD: sqlite3_stmt
5824**
5825** The sqlite3_reset() function is called to reset a [prepared statement]
5826** object back to its initial state, ready to be re-executed.
5827** ^Any SQL statement variables that had values bound to them using
5828** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
5829** Use [sqlite3_clear_bindings()] to reset the bindings.
5830**
5831** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
5832** back to the beginning of its program.
5833**
5834** ^If the most recent call to [sqlite3_step(S)] for the
5835** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
5836** or if [sqlite3_step(S)] has never before been called on S,
5837** then [sqlite3_reset(S)] returns [SQLITE_OK].
5838**
5839** ^If the most recent call to [sqlite3_step(S)] for the
5840** [prepared statement] S indicated an error, then
5841** [sqlite3_reset(S)] returns an appropriate [error code].
5842**
5843** ^The [sqlite3_reset(S)] interface does not change the values
5844** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
5845*/
5846SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
5847
5848/*
5849** CAPI3REF: Create Or Redefine SQL Functions
5850** KEYWORDS: {function creation routines}
5851** KEYWORDS: {application-defined SQL function}
5852** KEYWORDS: {application-defined SQL functions}
5853** METHOD: sqlite3
5854**
5855** ^These functions (collectively known as "function creation routines")
5856** are used to add SQL functions or aggregates or to redefine the behavior
5857** of existing SQL functions or aggregates. The only differences between
5858** the three "sqlite3_create_function*" routines are the text encoding
5859** expected for the second parameter (the name of the function being
5860** created) and the presence or absence of a destructor callback for
5861** the application data pointer. Function sqlite3_create_window_function()
5862** is similar, but allows the user to supply the extra callback functions
5863** needed by [aggregate window functions].
5864**
5865** ^The first parameter is the [database connection] to which the SQL
5866** function is to be added.  ^If an application uses more than one database
5867** connection then application-defined SQL functions must be added
5868** to each database connection separately.
5869**
5870** ^The second parameter is the name of the SQL function to be created or
5871** redefined.  ^The length of the name is limited to 255 bytes in a UTF-8
5872** representation, exclusive of the zero-terminator.  ^Note that the name
5873** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
5874** ^Any attempt to create a function with a longer name
5875** will result in [SQLITE_MISUSE] being returned.
5876**
5877** ^The third parameter (nArg)
5878** is the number of arguments that the SQL function or
5879** aggregate takes. ^If this parameter is -1, then the SQL function or
5880** aggregate may take any number of arguments between 0 and the limit
5881** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]).  If the third
5882** parameter is less than -1 or greater than 127 then the behavior is
5883** undefined.
5884**
5885** ^The fourth parameter, eTextRep, specifies what
5886** [SQLITE_UTF8 | text encoding] this SQL function prefers for
5887** its parameters.  The application should set this parameter to
5888** [SQLITE_UTF16LE] if the function implementation invokes
5889** [sqlite3_value_text16le()] on an input, or [SQLITE_UTF16BE] if the
5890** implementation invokes [sqlite3_value_text16be()] on an input, or
5891** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8]
5892** otherwise.  ^The same SQL function may be registered multiple times using
5893** different preferred text encodings, with different implementations for
5894** each encoding.
5895** ^When multiple implementations of the same function are available, SQLite
5896** will pick the one that involves the least amount of data conversion.
5897**
5898** ^The fourth parameter may optionally be ORed with [SQLITE_DETERMINISTIC]
5899** to signal that the function will always return the same result given
5900** the same inputs within a single SQL statement.  Most SQL functions are
5901** deterministic.  The built-in [random()] SQL function is an example of a
5902** function that is not deterministic.  The SQLite query planner is able to
5903** perform additional optimizations on deterministic functions, so use
5904** of the [SQLITE_DETERMINISTIC] flag is recommended where possible.
5905**
5906** ^The fourth parameter may also optionally include the [SQLITE_DIRECTONLY]
5907** flag, which if present prevents the function from being invoked from
5908** within VIEWs or TRIGGERs.  For security reasons, the [SQLITE_DIRECTONLY]
5909** flag is recommended for any application-defined SQL function that has
5910** side-effects.
5911**
5912** ^(The fifth parameter is an arbitrary pointer.  The implementation of the
5913** function can gain access to this pointer using [sqlite3_user_data()].)^
5914**
5915** ^The sixth, seventh and eighth parameters passed to the three
5916** "sqlite3_create_function*" functions, xFunc, xStep and xFinal, are
5917** pointers to C-language functions that implement the SQL function or
5918** aggregate. ^A scalar SQL function requires an implementation of the xFunc
5919** callback only; NULL pointers must be passed as the xStep and xFinal
5920** parameters. ^An aggregate SQL function requires an implementation of xStep
5921** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
5922** SQL function or aggregate, pass NULL pointers for all three function
5923** callbacks.
5924**
5925** ^The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue
5926** and xInverse) passed to sqlite3_create_window_function are pointers to
5927** C-language callbacks that implement the new function. xStep and xFinal
5928** must both be non-NULL. xValue and xInverse may either both be NULL, in
5929** which case a regular aggregate function is created, or must both be
5930** non-NULL, in which case the new function may be used as either an aggregate
5931** or aggregate window function. More details regarding the implementation
5932** of aggregate window functions are
5933** [user-defined window functions|available here].
5934**
5935** ^(If the final parameter to sqlite3_create_function_v2() or
5936** sqlite3_create_window_function() is not NULL, then it is destructor for
5937** the application data pointer. The destructor is invoked when the function
5938** is deleted, either by being overloaded or when the database connection
5939** closes.)^ ^The destructor is also invoked if the call to
5940** sqlite3_create_function_v2() fails.  ^When the destructor callback is
5941** invoked, it is passed a single argument which is a copy of the application
5942** data pointer which was the fifth parameter to sqlite3_create_function_v2().
5943**
5944** ^It is permitted to register multiple implementations of the same
5945** functions with the same name but with either differing numbers of
5946** arguments or differing preferred text encodings.  ^SQLite will use
5947** the implementation that most closely matches the way in which the
5948** SQL function is used.  ^A function implementation with a non-negative
5949** nArg parameter is a better match than a function implementation with
5950** a negative nArg.  ^A function where the preferred text encoding
5951** matches the database encoding is a better
5952** match than a function where the encoding is different.
5953** ^A function where the encoding difference is between UTF16le and UTF16be
5954** is a closer match than a function where the encoding difference is
5955** between UTF8 and UTF16.
5956**
5957** ^Built-in functions may be overloaded by new application-defined functions.
5958**
5959** ^An application-defined function is permitted to call other
5960** SQLite interfaces.  However, such calls must not
5961** close the database connection nor finalize or reset the prepared
5962** statement in which the function is running.
5963*/
5964SQLITE_API int sqlite3_create_function(
5965  sqlite3 *db,
5966  const char *zFunctionName,
5967  int nArg,
5968  int eTextRep,
5969  void *pApp,
5970  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
5971  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
5972  void (*xFinal)(sqlite3_context*)
5973);
5974SQLITE_API int sqlite3_create_function16(
5975  sqlite3 *db,
5976  const void *zFunctionName,
5977  int nArg,
5978  int eTextRep,
5979  void *pApp,
5980  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
5981  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
5982  void (*xFinal)(sqlite3_context*)
5983);
5984SQLITE_API int sqlite3_create_function_v2(
5985  sqlite3 *db,
5986  const char *zFunctionName,
5987  int nArg,
5988  int eTextRep,
5989  void *pApp,
5990  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
5991  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
5992  void (*xFinal)(sqlite3_context*),
5993  void(*xDestroy)(void*)
5994);
5995SQLITE_API int sqlite3_create_window_function(
5996  sqlite3 *db,
5997  const char *zFunctionName,
5998  int nArg,
5999  int eTextRep,
6000  void *pApp,
6001  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
6002  void (*xFinal)(sqlite3_context*),
6003  void (*xValue)(sqlite3_context*),
6004  void (*xInverse)(sqlite3_context*,int,sqlite3_value**),
6005  void(*xDestroy)(void*)
6006);
6007
6008/*
6009** CAPI3REF: Text Encodings
6010**
6011** These constant define integer codes that represent the various
6012** text encodings supported by SQLite.
6013*/
6014#define SQLITE_UTF8           1    /* IMP: R-37514-35566 */
6015#define SQLITE_UTF16LE        2    /* IMP: R-03371-37637 */
6016#define SQLITE_UTF16BE        3    /* IMP: R-51971-34154 */
6017#define SQLITE_UTF16          4    /* Use native byte order */
6018#define SQLITE_ANY            5    /* Deprecated */
6019#define SQLITE_UTF16_ALIGNED  8    /* sqlite3_create_collation only */
6020
6021/*
6022** CAPI3REF: Function Flags
6023**
6024** These constants may be ORed together with the
6025** [SQLITE_UTF8 | preferred text encoding] as the fourth argument
6026** to [sqlite3_create_function()], [sqlite3_create_function16()], or
6027** [sqlite3_create_function_v2()].
6028**
6029** The SQLITE_DETERMINISTIC flag means that the new function will always
6030** maps the same inputs into the same output.  The abs() function is
6031** deterministic, for example, but randomblob() is not.
6032**
6033** The SQLITE_DIRECTONLY flag means that the function may only be invoked
6034** from top-level SQL, and cannot be used in VIEWs or TRIGGERs.  This is
6035** a security feature which is recommended for all
6036** [application-defined SQL functions] that have side-effects.  This flag
6037** prevents an attacker from adding triggers and views to a schema then
6038** tricking a high-privilege application into causing unintended side-effects
6039** while performing ordinary queries.
6040**
6041** The SQLITE_SUBTYPE flag indicates to SQLite that a function may call
6042** [sqlite3_value_subtype()] to inspect the sub-types of its arguments.
6043** Specifying this flag makes no difference for scalar or aggregate user
6044** functions. However, if it is not specified for a user-defined window
6045** function, then any sub-types belonging to arguments passed to the window
6046** function may be discarded before the window function is called (i.e.
6047** sqlite3_value_subtype() will always return 0).
6048*/
6049#define SQLITE_DETERMINISTIC    0x000000800
6050#define SQLITE_DIRECTONLY       0x000080000
6051#define SQLITE_SUBTYPE          0x000100000
6052
6053/*
6054** CAPI3REF: Deprecated Functions
6055** DEPRECATED
6056**
6057** These functions are [deprecated].  In order to maintain
6058** backwards compatibility with older code, these functions continue
6059** to be supported.  However, new applications should avoid
6060** the use of these functions.  To encourage programmers to avoid
6061** these functions, we will not explain what they do.
6062*/
6063#ifndef SQLITE_OMIT_DEPRECATED
6064SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
6065SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
6066SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
6067SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
6068SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
6069SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
6070                      void*,sqlite3_int64);
6071#endif
6072
6073/*
6074** CAPI3REF: Obtaining SQL Values
6075** METHOD: sqlite3_value
6076**
6077** <b>Summary:</b>
6078** <blockquote><table border=0 cellpadding=0 cellspacing=0>
6079** <tr><td><b>sqlite3_value_blob</b><td>&rarr;<td>BLOB value
6080** <tr><td><b>sqlite3_value_double</b><td>&rarr;<td>REAL value
6081** <tr><td><b>sqlite3_value_int</b><td>&rarr;<td>32-bit INTEGER value
6082** <tr><td><b>sqlite3_value_int64</b><td>&rarr;<td>64-bit INTEGER value
6083** <tr><td><b>sqlite3_value_pointer</b><td>&rarr;<td>Pointer value
6084** <tr><td><b>sqlite3_value_text</b><td>&rarr;<td>UTF-8 TEXT value
6085** <tr><td><b>sqlite3_value_text16</b><td>&rarr;<td>UTF-16 TEXT value in
6086** the native byteorder
6087** <tr><td><b>sqlite3_value_text16be</b><td>&rarr;<td>UTF-16be TEXT value
6088** <tr><td><b>sqlite3_value_text16le</b><td>&rarr;<td>UTF-16le TEXT value
6089** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
6090** <tr><td><b>sqlite3_value_bytes</b><td>&rarr;<td>Size of a BLOB
6091** or a UTF-8 TEXT in bytes
6092** <tr><td><b>sqlite3_value_bytes16&nbsp;&nbsp;</b>
6093** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
6094** TEXT in bytes
6095** <tr><td><b>sqlite3_value_type</b><td>&rarr;<td>Default
6096** datatype of the value
6097** <tr><td><b>sqlite3_value_numeric_type&nbsp;&nbsp;</b>
6098** <td>&rarr;&nbsp;&nbsp;<td>Best numeric datatype of the value
6099** <tr><td><b>sqlite3_value_nochange&nbsp;&nbsp;</b>
6100** <td>&rarr;&nbsp;&nbsp;<td>True if the column is unchanged in an UPDATE
6101** against a virtual table.
6102** <tr><td><b>sqlite3_value_frombind&nbsp;&nbsp;</b>
6103** <td>&rarr;&nbsp;&nbsp;<td>True if value originated from a [bound parameter]
6104** </table></blockquote>
6105**
6106** <b>Details:</b>
6107**
6108** These routines extract type, size, and content information from
6109** [protected sqlite3_value] objects.  Protected sqlite3_value objects
6110** are used to pass parameter information into implementation of
6111** [application-defined SQL functions] and [virtual tables].
6112**
6113** These routines work only with [protected sqlite3_value] objects.
6114** Any attempt to use these routines on an [unprotected sqlite3_value]
6115** is not threadsafe.
6116**
6117** ^These routines work just like the corresponding [column access functions]
6118** except that these routines take a single [protected sqlite3_value] object
6119** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
6120**
6121** ^The sqlite3_value_text16() interface extracts a UTF-16 string
6122** in the native byte-order of the host machine.  ^The
6123** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
6124** extract UTF-16 strings as big-endian and little-endian respectively.
6125**
6126** ^If [sqlite3_value] object V was initialized
6127** using [sqlite3_bind_pointer(S,I,P,X,D)] or [sqlite3_result_pointer(C,P,X,D)]
6128** and if X and Y are strings that compare equal according to strcmp(X,Y),
6129** then sqlite3_value_pointer(V,Y) will return the pointer P.  ^Otherwise,
6130** sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer()
6131** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
6132**
6133** ^(The sqlite3_value_type(V) interface returns the
6134** [SQLITE_INTEGER | datatype code] for the initial datatype of the
6135** [sqlite3_value] object V. The returned value is one of [SQLITE_INTEGER],
6136** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].)^
6137** Other interfaces might change the datatype for an sqlite3_value object.
6138** For example, if the datatype is initially SQLITE_INTEGER and
6139** sqlite3_value_text(V) is called to extract a text value for that
6140** integer, then subsequent calls to sqlite3_value_type(V) might return
6141** SQLITE_TEXT.  Whether or not a persistent internal datatype conversion
6142** occurs is undefined and may change from one release of SQLite to the next.
6143**
6144** ^(The sqlite3_value_numeric_type() interface attempts to apply
6145** numeric affinity to the value.  This means that an attempt is
6146** made to convert the value to an integer or floating point.  If
6147** such a conversion is possible without loss of information (in other
6148** words, if the value is a string that looks like a number)
6149** then the conversion is performed.  Otherwise no conversion occurs.
6150** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
6151**
6152** ^Within the [xUpdate] method of a [virtual table], the
6153** sqlite3_value_nochange(X) interface returns true if and only if
6154** the column corresponding to X is unchanged by the UPDATE operation
6155** that the xUpdate method call was invoked to implement and if
6156** and the prior [xColumn] method call that was invoked to extracted
6157** the value for that column returned without setting a result (probably
6158** because it queried [sqlite3_vtab_nochange()] and found that the column
6159** was unchanging).  ^Within an [xUpdate] method, any value for which
6160** sqlite3_value_nochange(X) is true will in all other respects appear
6161** to be a NULL value.  If sqlite3_value_nochange(X) is invoked anywhere other
6162** than within an [xUpdate] method call for an UPDATE statement, then
6163** the return value is arbitrary and meaningless.
6164**
6165** ^The sqlite3_value_frombind(X) interface returns non-zero if the
6166** value X originated from one of the [sqlite3_bind_int|sqlite3_bind()]
6167** interfaces.  ^If X comes from an SQL literal value, or a table column,
6168** and expression, then sqlite3_value_frombind(X) returns zero.
6169**
6170** Please pay particular attention to the fact that the pointer returned
6171** from [sqlite3_value_blob()], [sqlite3_value_text()], or
6172** [sqlite3_value_text16()] can be invalidated by a subsequent call to
6173** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
6174** or [sqlite3_value_text16()].
6175**
6176** These routines must be called from the same thread as
6177** the SQL function that supplied the [sqlite3_value*] parameters.
6178**
6179** As long as the input parameter is correct, these routines can only
6180** fail if an out-of-memory error occurs during a format conversion.
6181** Only the following subset of interfaces are subject to out-of-memory
6182** errors:
6183**
6184** <ul>
6185** <li> sqlite3_value_blob()
6186** <li> sqlite3_value_text()
6187** <li> sqlite3_value_text16()
6188** <li> sqlite3_value_text16le()
6189** <li> sqlite3_value_text16be()
6190** <li> sqlite3_value_bytes()
6191** <li> sqlite3_value_bytes16()
6192** </ul>
6193**
6194** If an out-of-memory error occurs, then the return value from these
6195** routines is the same as if the column had contained an SQL NULL value.
6196** Valid SQL NULL returns can be distinguished from out-of-memory errors
6197** by invoking the [sqlite3_errcode()] immediately after the suspect
6198** return value is obtained and before any
6199** other SQLite interface is called on the same [database connection].
6200*/
6201SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
6202SQLITE_API double sqlite3_value_double(sqlite3_value*);
6203SQLITE_API int sqlite3_value_int(sqlite3_value*);
6204SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
6205SQLITE_API void *sqlite3_value_pointer(sqlite3_value*, const char*);
6206SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
6207SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
6208SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
6209SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
6210SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
6211SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
6212SQLITE_API int sqlite3_value_type(sqlite3_value*);
6213SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
6214SQLITE_API int sqlite3_value_nochange(sqlite3_value*);
6215SQLITE_API int sqlite3_value_frombind(sqlite3_value*);
6216
6217/*
6218** CAPI3REF: Finding The Subtype Of SQL Values
6219** METHOD: sqlite3_value
6220**
6221** The sqlite3_value_subtype(V) function returns the subtype for
6222** an [application-defined SQL function] argument V.  The subtype
6223** information can be used to pass a limited amount of context from
6224** one SQL function to another.  Use the [sqlite3_result_subtype()]
6225** routine to set the subtype for the return value of an SQL function.
6226*/
6227SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*);
6228
6229/*
6230** CAPI3REF: Copy And Free SQL Values
6231** METHOD: sqlite3_value
6232**
6233** ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value]
6234** object D and returns a pointer to that copy.  ^The [sqlite3_value] returned
6235** is a [protected sqlite3_value] object even if the input is not.
6236** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
6237** memory allocation fails.
6238**
6239** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object
6240** previously obtained from [sqlite3_value_dup()].  ^If V is a NULL pointer
6241** then sqlite3_value_free(V) is a harmless no-op.
6242*/
6243SQLITE_API sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
6244SQLITE_API void sqlite3_value_free(sqlite3_value*);
6245
6246/*
6247** CAPI3REF: Obtain Aggregate Function Context
6248** METHOD: sqlite3_context
6249**
6250** Implementations of aggregate SQL functions use this
6251** routine to allocate memory for storing their state.
6252**
6253** ^The first time the sqlite3_aggregate_context(C,N) routine is called
6254** for a particular aggregate function, SQLite
6255** allocates N of memory, zeroes out that memory, and returns a pointer
6256** to the new memory. ^On second and subsequent calls to
6257** sqlite3_aggregate_context() for the same aggregate function instance,
6258** the same buffer is returned.  Sqlite3_aggregate_context() is normally
6259** called once for each invocation of the xStep callback and then one
6260** last time when the xFinal callback is invoked.  ^(When no rows match
6261** an aggregate query, the xStep() callback of the aggregate function
6262** implementation is never called and xFinal() is called exactly once.
6263** In those cases, sqlite3_aggregate_context() might be called for the
6264** first time from within xFinal().)^
6265**
6266** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer
6267** when first called if N is less than or equal to zero or if a memory
6268** allocate error occurs.
6269**
6270** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
6271** determined by the N parameter on first successful call.  Changing the
6272** value of N in subsequent call to sqlite3_aggregate_context() within
6273** the same aggregate function instance will not resize the memory
6274** allocation.)^  Within the xFinal callback, it is customary to set
6275** N=0 in calls to sqlite3_aggregate_context(C,N) so that no
6276** pointless memory allocations occur.
6277**
6278** ^SQLite automatically frees the memory allocated by
6279** sqlite3_aggregate_context() when the aggregate query concludes.
6280**
6281** The first parameter must be a copy of the
6282** [sqlite3_context | SQL function context] that is the first parameter
6283** to the xStep or xFinal callback routine that implements the aggregate
6284** function.
6285**
6286** This routine must be called from the same thread in which
6287** the aggregate SQL function is running.
6288*/
6289SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
6290
6291/*
6292** CAPI3REF: User Data For Functions
6293** METHOD: sqlite3_context
6294**
6295** ^The sqlite3_user_data() interface returns a copy of
6296** the pointer that was the pUserData parameter (the 5th parameter)
6297** of the [sqlite3_create_function()]
6298** and [sqlite3_create_function16()] routines that originally
6299** registered the application defined function.
6300**
6301** This routine must be called from the same thread in which
6302** the application-defined function is running.
6303*/
6304SQLITE_API void *sqlite3_user_data(sqlite3_context*);
6305
6306/*
6307** CAPI3REF: Database Connection For Functions
6308** METHOD: sqlite3_context
6309**
6310** ^The sqlite3_context_db_handle() interface returns a copy of
6311** the pointer to the [database connection] (the 1st parameter)
6312** of the [sqlite3_create_function()]
6313** and [sqlite3_create_function16()] routines that originally
6314** registered the application defined function.
6315*/
6316SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
6317
6318/*
6319** CAPI3REF: Function Auxiliary Data
6320** METHOD: sqlite3_context
6321**
6322** These functions may be used by (non-aggregate) SQL functions to
6323** associate metadata with argument values. If the same value is passed to
6324** multiple invocations of the same SQL function during query execution, under
6325** some circumstances the associated metadata may be preserved.  An example
6326** of where this might be useful is in a regular-expression matching
6327** function. The compiled version of the regular expression can be stored as
6328** metadata associated with the pattern string.
6329** Then as long as the pattern string remains the same,
6330** the compiled regular expression can be reused on multiple
6331** invocations of the same function.
6332**
6333** ^The sqlite3_get_auxdata(C,N) interface returns a pointer to the metadata
6334** associated by the sqlite3_set_auxdata(C,N,P,X) function with the Nth argument
6335** value to the application-defined function.  ^N is zero for the left-most
6336** function argument.  ^If there is no metadata
6337** associated with the function argument, the sqlite3_get_auxdata(C,N) interface
6338** returns a NULL pointer.
6339**
6340** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th
6341** argument of the application-defined function.  ^Subsequent
6342** calls to sqlite3_get_auxdata(C,N) return P from the most recent
6343** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or
6344** NULL if the metadata has been discarded.
6345** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
6346** SQLite will invoke the destructor function X with parameter P exactly
6347** once, when the metadata is discarded.
6348** SQLite is free to discard the metadata at any time, including: <ul>
6349** <li> ^(when the corresponding function parameter changes)^, or
6350** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
6351**      SQL statement)^, or
6352** <li> ^(when sqlite3_set_auxdata() is invoked again on the same
6353**       parameter)^, or
6354** <li> ^(during the original sqlite3_set_auxdata() call when a memory
6355**      allocation error occurs.)^ </ul>
6356**
6357** Note the last bullet in particular.  The destructor X in
6358** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
6359** sqlite3_set_auxdata() interface even returns.  Hence sqlite3_set_auxdata()
6360** should be called near the end of the function implementation and the
6361** function implementation should not make any use of P after
6362** sqlite3_set_auxdata() has been called.
6363**
6364** ^(In practice, metadata is preserved between function calls for
6365** function parameters that are compile-time constants, including literal
6366** values and [parameters] and expressions composed from the same.)^
6367**
6368** The value of the N parameter to these interfaces should be non-negative.
6369** Future enhancements may make use of negative N values to define new
6370** kinds of function caching behavior.
6371**
6372** These routines must be called from the same thread in which
6373** the SQL function is running.
6374*/
6375SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
6376SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
6377
6378
6379/*
6380** CAPI3REF: Constants Defining Special Destructor Behavior
6381**
6382** These are special values for the destructor that is passed in as the
6383** final argument to routines like [sqlite3_result_blob()].  ^If the destructor
6384** argument is SQLITE_STATIC, it means that the content pointer is constant
6385** and will never change.  It does not need to be destroyed.  ^The
6386** SQLITE_TRANSIENT value means that the content will likely change in
6387** the near future and that SQLite should make its own private copy of
6388** the content before returning.
6389**
6390** The typedef is necessary to work around problems in certain
6391** C++ compilers.
6392*/
6393typedef void (*sqlite3_destructor_type)(void*);
6394#define SQLITE_STATIC      ((sqlite3_destructor_type)0)
6395#define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)
6396
6397/*
6398** CAPI3REF: Setting The Result Of An SQL Function
6399** METHOD: sqlite3_context
6400**
6401** These routines are used by the xFunc or xFinal callbacks that
6402** implement SQL functions and aggregates.  See
6403** [sqlite3_create_function()] and [sqlite3_create_function16()]
6404** for additional information.
6405**
6406** These functions work very much like the [parameter binding] family of
6407** functions used to bind values to host parameters in prepared statements.
6408** Refer to the [SQL parameter] documentation for additional information.
6409**
6410** ^The sqlite3_result_blob() interface sets the result from
6411** an application-defined function to be the BLOB whose content is pointed
6412** to by the second parameter and which is N bytes long where N is the
6413** third parameter.
6414**
6415** ^The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
6416** interfaces set the result of the application-defined function to be
6417** a BLOB containing all zero bytes and N bytes in size.
6418**
6419** ^The sqlite3_result_double() interface sets the result from
6420** an application-defined function to be a floating point value specified
6421** by its 2nd argument.
6422**
6423** ^The sqlite3_result_error() and sqlite3_result_error16() functions
6424** cause the implemented SQL function to throw an exception.
6425** ^SQLite uses the string pointed to by the
6426** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
6427** as the text of an error message.  ^SQLite interprets the error
6428** message string from sqlite3_result_error() as UTF-8. ^SQLite
6429** interprets the string from sqlite3_result_error16() as UTF-16 in native
6430** byte order.  ^If the third parameter to sqlite3_result_error()
6431** or sqlite3_result_error16() is negative then SQLite takes as the error
6432** message all text up through the first zero character.
6433** ^If the third parameter to sqlite3_result_error() or
6434** sqlite3_result_error16() is non-negative then SQLite takes that many
6435** bytes (not characters) from the 2nd parameter as the error message.
6436** ^The sqlite3_result_error() and sqlite3_result_error16()
6437** routines make a private copy of the error message text before
6438** they return.  Hence, the calling function can deallocate or
6439** modify the text after they return without harm.
6440** ^The sqlite3_result_error_code() function changes the error code
6441** returned by SQLite as a result of an error in a function.  ^By default,
6442** the error code is SQLITE_ERROR.  ^A subsequent call to sqlite3_result_error()
6443** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
6444**
6445** ^The sqlite3_result_error_toobig() interface causes SQLite to throw an
6446** error indicating that a string or BLOB is too long to represent.
6447**
6448** ^The sqlite3_result_error_nomem() interface causes SQLite to throw an
6449** error indicating that a memory allocation failed.
6450**
6451** ^The sqlite3_result_int() interface sets the return value
6452** of the application-defined function to be the 32-bit signed integer
6453** value given in the 2nd argument.
6454** ^The sqlite3_result_int64() interface sets the return value
6455** of the application-defined function to be the 64-bit signed integer
6456** value given in the 2nd argument.
6457**
6458** ^The sqlite3_result_null() interface sets the return value
6459** of the application-defined function to be NULL.
6460**
6461** ^The sqlite3_result_text(), sqlite3_result_text16(),
6462** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
6463** set the return value of the application-defined function to be
6464** a text string which is represented as UTF-8, UTF-16 native byte order,
6465** UTF-16 little endian, or UTF-16 big endian, respectively.
6466** ^The sqlite3_result_text64() interface sets the return value of an
6467** application-defined function to be a text string in an encoding
6468** specified by the fifth (and last) parameter, which must be one
6469** of [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE].
6470** ^SQLite takes the text result from the application from
6471** the 2nd parameter of the sqlite3_result_text* interfaces.
6472** ^If the 3rd parameter to the sqlite3_result_text* interfaces
6473** is negative, then SQLite takes result text from the 2nd parameter
6474** through the first zero character.
6475** ^If the 3rd parameter to the sqlite3_result_text* interfaces
6476** is non-negative, then as many bytes (not characters) of the text
6477** pointed to by the 2nd parameter are taken as the application-defined
6478** function result.  If the 3rd parameter is non-negative, then it
6479** must be the byte offset into the string where the NUL terminator would
6480** appear if the string where NUL terminated.  If any NUL characters occur
6481** in the string at a byte offset that is less than the value of the 3rd
6482** parameter, then the resulting string will contain embedded NULs and the
6483** result of expressions operating on strings with embedded NULs is undefined.
6484** ^If the 4th parameter to the sqlite3_result_text* interfaces
6485** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
6486** function as the destructor on the text or BLOB result when it has
6487** finished using that result.
6488** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
6489** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
6490** assumes that the text or BLOB result is in constant space and does not
6491** copy the content of the parameter nor call a destructor on the content
6492** when it has finished using that result.
6493** ^If the 4th parameter to the sqlite3_result_text* interfaces
6494** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
6495** then SQLite makes a copy of the result into space obtained
6496** from [sqlite3_malloc()] before it returns.
6497**
6498** ^The sqlite3_result_value() interface sets the result of
6499** the application-defined function to be a copy of the
6500** [unprotected sqlite3_value] object specified by the 2nd parameter.  ^The
6501** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
6502** so that the [sqlite3_value] specified in the parameter may change or
6503** be deallocated after sqlite3_result_value() returns without harm.
6504** ^A [protected sqlite3_value] object may always be used where an
6505** [unprotected sqlite3_value] object is required, so either
6506** kind of [sqlite3_value] object can be used with this interface.
6507**
6508** ^The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
6509** SQL NULL value, just like [sqlite3_result_null(C)], except that it
6510** also associates the host-language pointer P or type T with that
6511** NULL value such that the pointer can be retrieved within an
6512** [application-defined SQL function] using [sqlite3_value_pointer()].
6513** ^If the D parameter is not NULL, then it is a pointer to a destructor
6514** for the P parameter.  ^SQLite invokes D with P as its only argument
6515** when SQLite is finished with P.  The T parameter should be a static
6516** string and preferably a string literal. The sqlite3_result_pointer()
6517** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
6518**
6519** If these routines are called from within the different thread
6520** than the one containing the application-defined function that received
6521** the [sqlite3_context] pointer, the results are undefined.
6522*/
6523SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
6524SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*,
6525                           sqlite3_uint64,void(*)(void*));
6526SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
6527SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
6528SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
6529SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
6530SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
6531SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
6532SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
6533SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
6534SQLITE_API void sqlite3_result_null(sqlite3_context*);
6535SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
6536SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64,
6537                           void(*)(void*), unsigned char encoding);
6538SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
6539SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
6540SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
6541SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
6542SQLITE_API void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*));
6543SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
6544SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
6545
6546
6547/*
6548** CAPI3REF: Setting The Subtype Of An SQL Function
6549** METHOD: sqlite3_context
6550**
6551** The sqlite3_result_subtype(C,T) function causes the subtype of
6552** the result from the [application-defined SQL function] with
6553** [sqlite3_context] C to be the value T.  Only the lower 8 bits
6554** of the subtype T are preserved in current versions of SQLite;
6555** higher order bits are discarded.
6556** The number of subtype bytes preserved by SQLite might increase
6557** in future releases of SQLite.
6558*/
6559SQLITE_API void sqlite3_result_subtype(sqlite3_context*,unsigned int);
6560
6561/*
6562** CAPI3REF: Define New Collating Sequences
6563** METHOD: sqlite3
6564**
6565** ^These functions add, remove, or modify a [collation] associated
6566** with the [database connection] specified as the first argument.
6567**
6568** ^The name of the collation is a UTF-8 string
6569** for sqlite3_create_collation() and sqlite3_create_collation_v2()
6570** and a UTF-16 string in native byte order for sqlite3_create_collation16().
6571** ^Collation names that compare equal according to [sqlite3_strnicmp()] are
6572** considered to be the same name.
6573**
6574** ^(The third argument (eTextRep) must be one of the constants:
6575** <ul>
6576** <li> [SQLITE_UTF8],
6577** <li> [SQLITE_UTF16LE],
6578** <li> [SQLITE_UTF16BE],
6579** <li> [SQLITE_UTF16], or
6580** <li> [SQLITE_UTF16_ALIGNED].
6581** </ul>)^
6582** ^The eTextRep argument determines the encoding of strings passed
6583** to the collating function callback, xCallback.
6584** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep
6585** force strings to be UTF16 with native byte order.
6586** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin
6587** on an even byte address.
6588**
6589** ^The fourth argument, pArg, is an application data pointer that is passed
6590** through as the first argument to the collating function callback.
6591**
6592** ^The fifth argument, xCallback, is a pointer to the collating function.
6593** ^Multiple collating functions can be registered using the same name but
6594** with different eTextRep parameters and SQLite will use whichever
6595** function requires the least amount of data transformation.
6596** ^If the xCallback argument is NULL then the collating function is
6597** deleted.  ^When all collating functions having the same name are deleted,
6598** that collation is no longer usable.
6599**
6600** ^The collating function callback is invoked with a copy of the pArg
6601** application data pointer and with two strings in the encoding specified
6602** by the eTextRep argument.  The collating function must return an
6603** integer that is negative, zero, or positive
6604** if the first string is less than, equal to, or greater than the second,
6605** respectively.  A collating function must always return the same answer
6606** given the same inputs.  If two or more collating functions are registered
6607** to the same collation name (using different eTextRep values) then all
6608** must give an equivalent answer when invoked with equivalent strings.
6609** The collating function must obey the following properties for all
6610** strings A, B, and C:
6611**
6612** <ol>
6613** <li> If A==B then B==A.
6614** <li> If A==B and B==C then A==C.
6615** <li> If A&lt;B THEN B&gt;A.
6616** <li> If A&lt;B and B&lt;C then A&lt;C.
6617** </ol>
6618**
6619** If a collating function fails any of the above constraints and that
6620** collating function is  registered and used, then the behavior of SQLite
6621** is undefined.
6622**
6623** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
6624** with the addition that the xDestroy callback is invoked on pArg when
6625** the collating function is deleted.
6626** ^Collating functions are deleted when they are overridden by later
6627** calls to the collation creation functions or when the
6628** [database connection] is closed using [sqlite3_close()].
6629**
6630** ^The xDestroy callback is <u>not</u> called if the
6631** sqlite3_create_collation_v2() function fails.  Applications that invoke
6632** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
6633** check the return code and dispose of the application data pointer
6634** themselves rather than expecting SQLite to deal with it for them.
6635** This is different from every other SQLite interface.  The inconsistency
6636** is unfortunate but cannot be changed without breaking backwards
6637** compatibility.
6638**
6639** See also:  [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
6640*/
6641SQLITE_API int sqlite3_create_collation(
6642  sqlite3*,
6643  const char *zName,
6644  int eTextRep,
6645  void *pArg,
6646  int(*xCompare)(void*,int,const void*,int,const void*)
6647);
6648SQLITE_API int sqlite3_create_collation_v2(
6649  sqlite3*,
6650  const char *zName,
6651  int eTextRep,
6652  void *pArg,
6653  int(*xCompare)(void*,int,const void*,int,const void*),
6654  void(*xDestroy)(void*)
6655);
6656SQLITE_API int sqlite3_create_collation16(
6657  sqlite3*,
6658  const void *zName,
6659  int eTextRep,
6660  void *pArg,
6661  int(*xCompare)(void*,int,const void*,int,const void*)
6662);
6663
6664/*
6665** CAPI3REF: Collation Needed Callbacks
6666** METHOD: sqlite3
6667**
6668** ^To avoid having to register all collation sequences before a database
6669** can be used, a single callback function may be registered with the
6670** [database connection] to be invoked whenever an undefined collation
6671** sequence is required.
6672**
6673** ^If the function is registered using the sqlite3_collation_needed() API,
6674** then it is passed the names of undefined collation sequences as strings
6675** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
6676** the names are passed as UTF-16 in machine native byte order.
6677** ^A call to either function replaces the existing collation-needed callback.
6678**
6679** ^(When the callback is invoked, the first argument passed is a copy
6680** of the second argument to sqlite3_collation_needed() or
6681** sqlite3_collation_needed16().  The second argument is the database
6682** connection.  The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
6683** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
6684** sequence function required.  The fourth parameter is the name of the
6685** required collation sequence.)^
6686**
6687** The callback function should register the desired collation using
6688** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
6689** [sqlite3_create_collation_v2()].
6690*/
6691SQLITE_API int sqlite3_collation_needed(
6692  sqlite3*,
6693  void*,
6694  void(*)(void*,sqlite3*,int eTextRep,const char*)
6695);
6696SQLITE_API int sqlite3_collation_needed16(
6697  sqlite3*,
6698  void*,
6699  void(*)(void*,sqlite3*,int eTextRep,const void*)
6700);
6701
6702#ifdef SQLITE_HAS_CODEC
6703/*
6704** Specify the key for an encrypted database.  This routine should be
6705** called right after sqlite3_open().
6706**
6707** The code to implement this API is not available in the public release
6708** of SQLite.
6709*/
6710SQLITE_API int sqlite3_key(
6711  sqlite3 *db,                   /* Database to be rekeyed */
6712  const void *pKey, int nKey     /* The key */
6713);
6714SQLITE_API int sqlite3_key_v2(
6715  sqlite3 *db,                   /* Database to be rekeyed */
6716  const char *zDbName,           /* Name of the database */
6717  const void *pKey, int nKey     /* The key */
6718);
6719
6720/*
6721** Change the key on an open database.  If the current database is not
6722** encrypted, this routine will encrypt it.  If pNew==0 or nNew==0, the
6723** database is decrypted.
6724**
6725** The code to implement this API is not available in the public release
6726** of SQLite.
6727*/
6728SQLITE_API int sqlite3_rekey(
6729  sqlite3 *db,                   /* Database to be rekeyed */
6730  const void *pKey, int nKey     /* The new key */
6731);
6732SQLITE_API int sqlite3_rekey_v2(
6733  sqlite3 *db,                   /* Database to be rekeyed */
6734  const char *zDbName,           /* Name of the database */
6735  const void *pKey, int nKey     /* The new key */
6736);
6737
6738/*
6739** Specify the activation key for a SEE database.  Unless
6740** activated, none of the SEE routines will work.
6741*/
6742SQLITE_API void sqlite3_activate_see(
6743  const char *zPassPhrase        /* Activation phrase */
6744);
6745#endif
6746
6747#ifdef SQLITE_ENABLE_CEROD
6748/*
6749** Specify the activation key for a CEROD database.  Unless
6750** activated, none of the CEROD routines will work.
6751*/
6752SQLITE_API void sqlite3_activate_cerod(
6753  const char *zPassPhrase        /* Activation phrase */
6754);
6755#endif
6756
6757/*
6758** CAPI3REF: Suspend Execution For A Short Time
6759**
6760** The sqlite3_sleep() function causes the current thread to suspend execution
6761** for at least a number of milliseconds specified in its parameter.
6762**
6763** If the operating system does not support sleep requests with
6764** millisecond time resolution, then the time will be rounded up to
6765** the nearest second. The number of milliseconds of sleep actually
6766** requested from the operating system is returned.
6767**
6768** ^SQLite implements this interface by calling the xSleep()
6769** method of the default [sqlite3_vfs] object.  If the xSleep() method
6770** of the default VFS is not implemented correctly, or not implemented at
6771** all, then the behavior of sqlite3_sleep() may deviate from the description
6772** in the previous paragraphs.
6773*/
6774SQLITE_API int sqlite3_sleep(int);
6775
6776/*
6777** CAPI3REF: Name Of The Folder Holding Temporary Files
6778**
6779** ^(If this global variable is made to point to a string which is
6780** the name of a folder (a.k.a. directory), then all temporary files
6781** created by SQLite when using a built-in [sqlite3_vfs | VFS]
6782** will be placed in that directory.)^  ^If this variable
6783** is a NULL pointer, then SQLite performs a search for an appropriate
6784** temporary file directory.
6785**
6786** Applications are strongly discouraged from using this global variable.
6787** It is required to set a temporary folder on Windows Runtime (WinRT).
6788** But for all other platforms, it is highly recommended that applications
6789** neither read nor write this variable.  This global variable is a relic
6790** that exists for backwards compatibility of legacy applications and should
6791** be avoided in new projects.
6792**
6793** It is not safe to read or modify this variable in more than one
6794** thread at a time.  It is not safe to read or modify this variable
6795** if a [database connection] is being used at the same time in a separate
6796** thread.
6797** It is intended that this variable be set once
6798** as part of process initialization and before any SQLite interface
6799** routines have been called and that this variable remain unchanged
6800** thereafter.
6801**
6802** ^The [temp_store_directory pragma] may modify this variable and cause
6803** it to point to memory obtained from [sqlite3_malloc].  ^Furthermore,
6804** the [temp_store_directory pragma] always assumes that any string
6805** that this variable points to is held in memory obtained from
6806** [sqlite3_malloc] and the pragma may attempt to free that memory
6807** using [sqlite3_free].
6808** Hence, if this variable is modified directly, either it should be
6809** made NULL or made to point to memory obtained from [sqlite3_malloc]
6810** or else the use of the [temp_store_directory pragma] should be avoided.
6811** Except when requested by the [temp_store_directory pragma], SQLite
6812** does not free the memory that sqlite3_temp_directory points to.  If
6813** the application wants that memory to be freed, it must do
6814** so itself, taking care to only do so after all [database connection]
6815** objects have been destroyed.
6816**
6817** <b>Note to Windows Runtime users:</b>  The temporary directory must be set
6818** prior to calling [sqlite3_open] or [sqlite3_open_v2].  Otherwise, various
6819** features that require the use of temporary files may fail.  Here is an
6820** example of how to do this using C++ with the Windows Runtime:
6821**
6822** <blockquote><pre>
6823** LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
6824** &nbsp;     TemporaryFolder->Path->Data();
6825** char zPathBuf&#91;MAX_PATH + 1&#93;;
6826** memset(zPathBuf, 0, sizeof(zPathBuf));
6827** WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
6828** &nbsp;     NULL, NULL);
6829** sqlite3_temp_directory = sqlite3_mprintf("%s", zPathBuf);
6830** </pre></blockquote>
6831*/
6832SQLITE_API char *sqlite3_temp_directory;
6833
6834/*
6835** CAPI3REF: Name Of The Folder Holding Database Files
6836**
6837** ^(If this global variable is made to point to a string which is
6838** the name of a folder (a.k.a. directory), then all database files
6839** specified with a relative pathname and created or accessed by
6840** SQLite when using a built-in windows [sqlite3_vfs | VFS] will be assumed
6841** to be relative to that directory.)^ ^If this variable is a NULL
6842** pointer, then SQLite assumes that all database files specified
6843** with a relative pathname are relative to the current directory
6844** for the process.  Only the windows VFS makes use of this global
6845** variable; it is ignored by the unix VFS.
6846**
6847** Changing the value of this variable while a database connection is
6848** open can result in a corrupt database.
6849**
6850** It is not safe to read or modify this variable in more than one
6851** thread at a time.  It is not safe to read or modify this variable
6852** if a [database connection] is being used at the same time in a separate
6853** thread.
6854** It is intended that this variable be set once
6855** as part of process initialization and before any SQLite interface
6856** routines have been called and that this variable remain unchanged
6857** thereafter.
6858**
6859** ^The [data_store_directory pragma] may modify this variable and cause
6860** it to point to memory obtained from [sqlite3_malloc].  ^Furthermore,
6861** the [data_store_directory pragma] always assumes that any string
6862** that this variable points to is held in memory obtained from
6863** [sqlite3_malloc] and the pragma may attempt to free that memory
6864** using [sqlite3_free].
6865** Hence, if this variable is modified directly, either it should be
6866** made NULL or made to point to memory obtained from [sqlite3_malloc]
6867** or else the use of the [data_store_directory pragma] should be avoided.
6868*/
6869SQLITE_API char *sqlite3_data_directory;
6870
6871/*
6872** CAPI3REF: Win32 Specific Interface
6873**
6874** These interfaces are available only on Windows.  The
6875** [sqlite3_win32_set_directory] interface is used to set the value associated
6876** with the [sqlite3_temp_directory] or [sqlite3_data_directory] variable, to
6877** zValue, depending on the value of the type parameter.  The zValue parameter
6878** should be NULL to cause the previous value to be freed via [sqlite3_free];
6879** a non-NULL value will be copied into memory obtained from [sqlite3_malloc]
6880** prior to being used.  The [sqlite3_win32_set_directory] interface returns
6881** [SQLITE_OK] to indicate success, [SQLITE_ERROR] if the type is unsupported,
6882** or [SQLITE_NOMEM] if memory could not be allocated.  The value of the
6883** [sqlite3_data_directory] variable is intended to act as a replacement for
6884** the current directory on the sub-platforms of Win32 where that concept is
6885** not present, e.g. WinRT and UWP.  The [sqlite3_win32_set_directory8] and
6886** [sqlite3_win32_set_directory16] interfaces behave exactly the same as the
6887** sqlite3_win32_set_directory interface except the string parameter must be
6888** UTF-8 or UTF-16, respectively.
6889*/
6890SQLITE_API int sqlite3_win32_set_directory(
6891  unsigned long type, /* Identifier for directory being set or reset */
6892  void *zValue        /* New value for directory being set or reset */
6893);
6894SQLITE_API int sqlite3_win32_set_directory8(unsigned long type, const char *zValue);
6895SQLITE_API int sqlite3_win32_set_directory16(unsigned long type, const void *zValue);
6896
6897/*
6898** CAPI3REF: Win32 Directory Types
6899**
6900** These macros are only available on Windows.  They define the allowed values
6901** for the type argument to the [sqlite3_win32_set_directory] interface.
6902*/
6903#define SQLITE_WIN32_DATA_DIRECTORY_TYPE  1
6904#define SQLITE_WIN32_TEMP_DIRECTORY_TYPE  2
6905
6906/*
6907** CAPI3REF: Test For Auto-Commit Mode
6908** KEYWORDS: {autocommit mode}
6909** METHOD: sqlite3
6910**
6911** ^The sqlite3_get_autocommit() interface returns non-zero or
6912** zero if the given database connection is or is not in autocommit mode,
6913** respectively.  ^Autocommit mode is on by default.
6914** ^Autocommit mode is disabled by a [BEGIN] statement.
6915** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
6916**
6917** If certain kinds of errors occur on a statement within a multi-statement
6918** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],
6919** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
6920** transaction might be rolled back automatically.  The only way to
6921** find out whether SQLite automatically rolled back the transaction after
6922** an error is to use this function.
6923**
6924** If another thread changes the autocommit status of the database
6925** connection while this routine is running, then the return value
6926** is undefined.
6927*/
6928SQLITE_API int sqlite3_get_autocommit(sqlite3*);
6929
6930/*
6931** CAPI3REF: Find The Database Handle Of A Prepared Statement
6932** METHOD: sqlite3_stmt
6933**
6934** ^The sqlite3_db_handle interface returns the [database connection] handle
6935** to which a [prepared statement] belongs.  ^The [database connection]
6936** returned by sqlite3_db_handle is the same [database connection]
6937** that was the first argument
6938** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
6939** create the statement in the first place.
6940*/
6941SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
6942
6943/*
6944** CAPI3REF: Return The Filename For A Database Connection
6945** METHOD: sqlite3
6946**
6947** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename
6948** associated with database N of connection D.  ^The main database file
6949** has the name "main".  If there is no attached database N on the database
6950** connection D, or if database N is a temporary or in-memory database, then
6951** this function will return either a NULL pointer or an empty string.
6952**
6953** ^The filename returned by this function is the output of the
6954** xFullPathname method of the [VFS].  ^In other words, the filename
6955** will be an absolute pathname, even if the filename used
6956** to open the database originally was a URI or relative pathname.
6957*/
6958SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName);
6959
6960/*
6961** CAPI3REF: Determine if a database is read-only
6962** METHOD: sqlite3
6963**
6964** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N
6965** of connection D is read-only, 0 if it is read/write, or -1 if N is not
6966** the name of a database on connection D.
6967*/
6968SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
6969
6970/*
6971** CAPI3REF: Find the next prepared statement
6972** METHOD: sqlite3
6973**
6974** ^This interface returns a pointer to the next [prepared statement] after
6975** pStmt associated with the [database connection] pDb.  ^If pStmt is NULL
6976** then this interface returns a pointer to the first prepared statement
6977** associated with the database connection pDb.  ^If no prepared statement
6978** satisfies the conditions of this routine, it returns NULL.
6979**
6980** The [database connection] pointer D in a call to
6981** [sqlite3_next_stmt(D,S)] must refer to an open database
6982** connection and in particular must not be a NULL pointer.
6983*/
6984SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
6985
6986/*
6987** CAPI3REF: Commit And Rollback Notification Callbacks
6988** METHOD: sqlite3
6989**
6990** ^The sqlite3_commit_hook() interface registers a callback
6991** function to be invoked whenever a transaction is [COMMIT | committed].
6992** ^Any callback set by a previous call to sqlite3_commit_hook()
6993** for the same database connection is overridden.
6994** ^The sqlite3_rollback_hook() interface registers a callback
6995** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
6996** ^Any callback set by a previous call to sqlite3_rollback_hook()
6997** for the same database connection is overridden.
6998** ^The pArg argument is passed through to the callback.
6999** ^If the callback on a commit hook function returns non-zero,
7000** then the commit is converted into a rollback.
7001**
7002** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
7003** return the P argument from the previous call of the same function
7004** on the same [database connection] D, or NULL for
7005** the first call for each function on D.
7006**
7007** The commit and rollback hook callbacks are not reentrant.
7008** The callback implementation must not do anything that will modify
7009** the database connection that invoked the callback.  Any actions
7010** to modify the database connection must be deferred until after the
7011** completion of the [sqlite3_step()] call that triggered the commit
7012** or rollback hook in the first place.
7013** Note that running any other SQL statements, including SELECT statements,
7014** or merely calling [sqlite3_prepare_v2()] and [sqlite3_step()] will modify
7015** the database connections for the meaning of "modify" in this paragraph.
7016**
7017** ^Registering a NULL function disables the callback.
7018**
7019** ^When the commit hook callback routine returns zero, the [COMMIT]
7020** operation is allowed to continue normally.  ^If the commit hook
7021** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
7022** ^The rollback hook is invoked on a rollback that results from a commit
7023** hook returning non-zero, just as it would be with any other rollback.
7024**
7025** ^For the purposes of this API, a transaction is said to have been
7026** rolled back if an explicit "ROLLBACK" statement is executed, or
7027** an error or constraint causes an implicit rollback to occur.
7028** ^The rollback callback is not invoked if a transaction is
7029** automatically rolled back because the database connection is closed.
7030**
7031** See also the [sqlite3_update_hook()] interface.
7032*/
7033SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
7034SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
7035
7036/*
7037** CAPI3REF: Data Change Notification Callbacks
7038** METHOD: sqlite3
7039**
7040** ^The sqlite3_update_hook() interface registers a callback function
7041** with the [database connection] identified by the first argument
7042** to be invoked whenever a row is updated, inserted or deleted in
7043** a [rowid table].
7044** ^Any callback set by a previous call to this function
7045** for the same database connection is overridden.
7046**
7047** ^The second argument is a pointer to the function to invoke when a
7048** row is updated, inserted or deleted in a rowid table.
7049** ^The first argument to the callback is a copy of the third argument
7050** to sqlite3_update_hook().
7051** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
7052** or [SQLITE_UPDATE], depending on the operation that caused the callback
7053** to be invoked.
7054** ^The third and fourth arguments to the callback contain pointers to the
7055** database and table name containing the affected row.
7056** ^The final callback parameter is the [rowid] of the row.
7057** ^In the case of an update, this is the [rowid] after the update takes place.
7058**
7059** ^(The update hook is not invoked when internal system tables are
7060** modified (i.e. sqlite_master and sqlite_sequence).)^
7061** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.
7062**
7063** ^In the current implementation, the update hook
7064** is not invoked when conflicting rows are deleted because of an
7065** [ON CONFLICT | ON CONFLICT REPLACE] clause.  ^Nor is the update hook
7066** invoked when rows are deleted using the [truncate optimization].
7067** The exceptions defined in this paragraph might change in a future
7068** release of SQLite.
7069**
7070** The update hook implementation must not do anything that will modify
7071** the database connection that invoked the update hook.  Any actions
7072** to modify the database connection must be deferred until after the
7073** completion of the [sqlite3_step()] call that triggered the update hook.
7074** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
7075** database connections for the meaning of "modify" in this paragraph.
7076**
7077** ^The sqlite3_update_hook(D,C,P) function
7078** returns the P argument from the previous call
7079** on the same [database connection] D, or NULL for
7080** the first call on D.
7081**
7082** See also the [sqlite3_commit_hook()], [sqlite3_rollback_hook()],
7083** and [sqlite3_preupdate_hook()] interfaces.
7084*/
7085SQLITE_API void *sqlite3_update_hook(
7086  sqlite3*,
7087  void(*)(void *,int ,char const *,char const *,sqlite3_int64),
7088  void*
7089);
7090
7091/*
7092** CAPI3REF: Enable Or Disable Shared Pager Cache
7093**
7094** ^(This routine enables or disables the sharing of the database cache
7095** and schema data structures between [database connection | connections]
7096** to the same database. Sharing is enabled if the argument is true
7097** and disabled if the argument is false.)^
7098**
7099** ^Cache sharing is enabled and disabled for an entire process.
7100** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).
7101** In prior versions of SQLite,
7102** sharing was enabled or disabled for each thread separately.
7103**
7104** ^(The cache sharing mode set by this interface effects all subsequent
7105** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
7106** Existing database connections continue use the sharing mode
7107** that was in effect at the time they were opened.)^
7108**
7109** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled
7110** successfully.  An [error code] is returned otherwise.)^
7111**
7112** ^Shared cache is disabled by default. But this might change in
7113** future releases of SQLite.  Applications that care about shared
7114** cache setting should set it explicitly.
7115**
7116** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0
7117** and will always return SQLITE_MISUSE. On those systems,
7118** shared cache mode should be enabled per-database connection via
7119** [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE].
7120**
7121** This interface is threadsafe on processors where writing a
7122** 32-bit integer is atomic.
7123**
7124** See Also:  [SQLite Shared-Cache Mode]
7125*/
7126SQLITE_API int sqlite3_enable_shared_cache(int);
7127
7128/*
7129** CAPI3REF: Attempt To Free Heap Memory
7130**
7131** ^The sqlite3_release_memory() interface attempts to free N bytes
7132** of heap memory by deallocating non-essential memory allocations
7133** held by the database library.   Memory used to cache database
7134** pages to improve performance is an example of non-essential memory.
7135** ^sqlite3_release_memory() returns the number of bytes actually freed,
7136** which might be more or less than the amount requested.
7137** ^The sqlite3_release_memory() routine is a no-op returning zero
7138** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].
7139**
7140** See also: [sqlite3_db_release_memory()]
7141*/
7142SQLITE_API int sqlite3_release_memory(int);
7143
7144/*
7145** CAPI3REF: Free Memory Used By A Database Connection
7146** METHOD: sqlite3
7147**
7148** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap
7149** memory as possible from database connection D. Unlike the
7150** [sqlite3_release_memory()] interface, this interface is in effect even
7151** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
7152** omitted.
7153**
7154** See also: [sqlite3_release_memory()]
7155*/
7156SQLITE_API int sqlite3_db_release_memory(sqlite3*);
7157
7158/*
7159** CAPI3REF: Impose A Limit On Heap Size
7160**
7161** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the