Bug Summary

File:3rdparty/sqlite3/sqlite3.c
Warning:line 111893, column 19
Although the value stored to 'rc' is used in the enclosing expression, the value is never actually read from 'rc'

Annotated Source Code

Press '?' to see keyboard shortcuts

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