Bug Summary

File:3rdparty/sqlite3/sqlite3.c
Warning:line 194394, column 28
The left operand of '<' is a garbage value

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-10-22-202332-1210664-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