Bug Summary

File:3rdparty/sqlite3/sqlite3.c
Warning:line 138372, column 19
The result of the left shift is undefined due to shifting by '2147483647', which is greater or equal to the width of type 'Bitmask'

Annotated Source Code

Press '?' to see keyboard shortcuts

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